Add ADR + concept content types to Knowledge Base substrate

Context

Operator-prompted 2026-05-14 (post-ADR-0004 + ADR-0005 graduation session):

"kb should get new types for ADR and for concept too. concept: still early. current descriptions just inside a json file, most likely needs to become markdown files too. quick win. ticket or sandbox"

After this session graduated ADR 0004 + ADR 0005 (which themselves codified single-source-of-truth substrate to prevent the #11362 substrate-bypass), the Knowledge Base lacks first-class type filters for the two highest-authority substrate kinds:

• 'adr' — load-bearing architectural decisions in learn/agentos/decisions/0NNN-*.md
• 'concept' — conceptual primitives that connect source files + guides (operator framing for v13 graph extension)

Current KB filters: 'all', 'blog', 'guide', 'src', 'example', 'ticket', 'release', 'test', 'skill'. ADRs currently fall through to 'guide' or get mixed across types; concepts have no markdown substrate at all.

The Problem

ADR retrievability — future agents executing V-B-A against authority artifacts need ask_knowledge_base(query='archive chunking', type='adr') to return ONLY the 5 ADR files semantically ranked, not fragments mixed across guides + source + skills. The substrate-bypass that caused #11362 was substantially an execution-time consultation gap; a clean type='adr' filter is the V-B-A primitive that makes the consultation cheap.

Concept substrate gap — operator-noted: concepts currently live in a JSON file. Need migration to markdown files (one file per concept) so:

1. They become KB-indexable as type='concept'
2. They become git-history-trackable (concepts evolve; JSON-blob churn hides evolution)
3. They become consumable by Dream Service / Native Edge Graph as substrate nodes (orthogonal Ideation Sandbox pending on graph-entity shape — see follow-up Discussion to be filed)

The Architectural Reality

Files touched:

Source-of-authority for type classification: path-based first (ADRs at learn/agentos/decisions/0NNN-*.md, concepts at resources/content/concepts/*.md), frontmatter-based as override (e.g., type: adr in frontmatter for edge cases).

The Fix

Single-PR (or sibling-PR pair if migration scope grows) implementation:

1. Migrate concept-JSON → markdown files — one .md per concept with frontmatter (name, connects: [...], original-JSON-derived fields)
2. Create AdrSource.mjs mirroring existing TicketSource.mjs / PullRequestSource.mjs pattern; indexes learn/agentos/decisions/0NNN-*.md
3. Create ConceptSource.mjs indexing the new resources/content/concepts/*.md files
4. Extend OpenAPI type enum with 'adr' + 'concept' for both ask_knowledge_base + query_documents
5. Update tool descriptions to document the new filters (per pr-review §5.3 MCP-Tool-Description Budget Audit — keep concise)
6. Unit tests for both new sources mirroring PullRequestSource.spec.mjs / SkillSource.spec.mjs patterns

Acceptance Criteria

• ai/services/knowledge-base/source/AdrSource.mjs exists with unit-test coverage; indexes learn/agentos/decisions/0NNN-*.md as type='adr'
• ai/services/knowledge-base/source/ConceptSource.mjs exists with unit-test coverage; indexes resources/content/concepts/*.md as type='concept'
• Existing concept-JSON migrated to per-file markdown; original JSON either retired or marked build-artifact-only
• ai/mcp/server/knowledge-base/openapi.yaml type enum includes 'adr' + 'concept' on both ask_knowledge_base + query_documents
• Tool descriptions updated per MCP-tool-description budget (single-line preferred; describe call-site usage not architectural narrative)
• ask_knowledge_base(query='archive chunking architecture', type='adr') returns ADR 0004 as top-ranked hit (regression test)
• ask_knowledge_base(query='<concept-name>', type='concept') returns the matching concept (regression test)
• ai:sync-kb build script picks up the new sources without manual configuration (auto-discovery via DatabaseService source registry)

Out of Scope

• Promoting ADRs / concepts to first-class graph entities (orthogonal Ideation Sandbox — TBD #)
• Bird's-eye strategic-awareness synthesis over the new types (separate Ideation Sandbox — TBD #)
• Restructuring the existing concept-JSON's data model — assume direct field-to-frontmatter migration unless evolution surfaces gaps mid-implementation
• ADR template standardization (ADRs 0001-0005 already follow a shape; not forcing rigid template here)
• Extending the type filter mechanism to add other authority-tier candidates (e.g., 'feedback-memory', 'session-transcript') — those need their own substrate-tier justification per the "first-class authority artifact" boundary

Avoided Traps

• Bundling graph-entity work into this ticket: rejected — ADR-as-graph-entity is N-to-N schema design + DreamService LLM extraction prompt update + cross-substrate consumers. Different scope, different Sandbox arc.
• Type-categorization explosion: explicitly rejected the slippery-slope pattern. The boundary is "first-class authority artifact" — adding new types requires substrate-tier justification, not just "another content category".
• Hardcoded path matching: ADR / concept classification should be path-first + frontmatter-override, not pure path-matching (allows edge-case overrides like an ADR draft in a sub-folder).
• Manual KB sync invocation: ticket-pickup should validate auto-discovery via DatabaseService source registry; no manual ai:sync-kb invocation required for the new sources to land.

Related

• Operator framing 2026-05-14 brainstorming: "kb should get new types for ADR and for concept too"
• ADR 0004 — the authority artifact this ticket makes semantically-filterable
• ADR 0005 — the workflow that produces future ADRs (and thus motivates this ticket's growth trajectory)
• PR #11362 substrate-bypass empirical anchor — the failure this ticket's 'adr' filter mitigates
• ai/services/knowledge-base/source/ — existing source pattern (TicketSource, PullRequestSource, DiscussionSource, SkillSource)
• Orthogonal Ideation Sandboxes (to be filed in parallel): ADR-as-graph-entity + Bird's-eye strategic-awareness layer

Origin Session ID

cf76b29a-9cf5-4c35-a415-37d631a8a755

Handoff Retrieval Hints

• query_raw_memories("KB ADR concept type filter post-ADR-0004-0005-session")
• Operator quote anchor: "kb should get new types for ADR and for concept too. concept: still early. current descriptions just inside a json file, most likely needs to become markdown files too. quick win." (2026-05-14)
• Related session work: ADR 0004 + ADR 0005 graduation arc, this session