baldart 4.19.0 → 4.21.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.21.0] - 2026-06-09
+
+**Code knowledge graph layer (Graphify) + Karpathy wiki rebind + nightly doc-alignment command.** Introduce [Graphify](https://github.com/safishamsi/graphify) as the new retrieval engine replacing the removed RAG (v4.20.0): a single language-agnostic tool (tree-sitter, 28 langs, local/offline, native Leiden communities; pip `graphifyy`, CLI `graphify` + `graphify-mcp`). Opt-in, runtime-detected, silent fallback to LSP→Grep→Git. **MINOR** (additive; new agent + 2 skills + 1 routine + 1 protocol module; new config key `features.has_code_graph` + `graph.*` propagated end-to-end per the schema-change rule).
+
+### Added
+
+- **`features.has_code_graph` + `graph:` block** (`framework/templates/baldart.config.template.yml`) — `graph.{output_dir, auto_rebuild_hook, register_mcp}` (scalars only). Propagated: configure autodetect + prompt + interactive install (`src/commands/configure.js`), update schema-drift detector **extended to diff nested top-level blocks** like `graph:` (`src/commands/update.js`), doctor diagnostic + actions (`src/commands/doctor.js`).
+- **`src/utils/graphify-installer.js`** — thin wrapper over Graphify's NATIVE commands (no per-language adapter registry): `detect/install/verify/buildGraph/installGitHook/installAlwaysOn/registerMcp/isStale`. Composes `pipx install graphifyy`, `graphify update` (offline build), `graphify hook install` (auto-rebuild), `graphify <tool> install` (always-on), `graphify-mcp` (MCP).
+- **`framework/agents/code-graph-protocol.md`** — new protocol module: when to prefer the graph (structural/relational) vs LSP (symbol) vs Grep (text) vs Git; CLI-first, MCP optional; budget; silent fallback. Wired into `code-search-protocol.md`, `index.md`, `codebase-architect`, and the exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) — all gated on `has_code_graph`.
+- **Karpathy wiki rebind** — the LLM-wiki auto-learning loop (removed with RAG in v4.20.0) is re-activated on Graphify's native `GRAPH_REPORT.md` (god nodes / Leiden communities / suggested questions → synthesis candidates), offline. Updated `llm-wiki-methodology.md`, `wiki-curator.md`, `wiki-review.routine.yml`, `capture/SKILL.md`. Gated; dormant when `has_code_graph: false` (no regression).
+- **Nightly doc-alignment command** — new agent `doc-graph-aligner` (rebuild graph → cross-check graph vs docs: uncovered core code, stale docs, registry drift → report + synthesis candidates; propose-only), routine `doc-graph-align.routine.yml` (+ `routines/index.yml`, `optional: true`), interactive skill `/graph-align`, and install skill `/graphify-bootstrap`.
+- **`framework/docs/CODE-GRAPH-LAYER.md`** — operator guide (lifecycle, schema, native commands, invariants, CI behavior). MCP-INTEGRATION.md + PROJECT-CONFIGURATION.md updated.
+
+### Notes
+
+- **CI install is deliberate**: a Python tool is never installed silently in `--yes`/non-interactive runs — `configure` writes the flag, `baldart doctor` (`graph-install`/`graph-rebuild`/`graph-hook`) and `/graphify-bootstrap` backfill.
+- **`graphify-out/`** added to `.gitignore` (generated artifact). **`package.json`** version is unrelated drift (tracked separately from `VERSION`).
+
+## [4.20.0] - 2026-06-09
+
+**Rimozione del motore RAG (strato A); wiki overlay preservato dormiente.** Il layer RAG (`doc-rag` MCP, `search_docs`, loop auto-learning con tap-point `wiki_log`) non era attivo in nessun consumer ed era un costo di istruzioni morto in ~20 file tra agenti, skill e moduli protocollo. Rimosso completamente; il retrieval del codice si riduce a **LSP → Grep → Git**. Il wiki overlay (loop di Karpathy: `/capture`, `wiki-curator`, `paths.wiki_dir`, `has_wiki_overlay`) resta nel framework ma **dormiente**, scollegato dal motore — engine-agnostic e riutilizzabile in futuro su un nuovo motore di retrieval. **MINOR** (nessun agente/skill/comando rimosso, nessun cambio di layout d'install; rimossa la sola chiave config `paths.wiki_log`, non usata da alcun consumer).
+
+### Removed
+
+- **Motore RAG (strato A) da tutti gli agenti, skill e moduli protocollo.** `mcp__doc-rag__search_docs` / `search_docs` / `mode:"hybrid"`, i verdetti `rag_telemetry` (`useful/weak/empty/fallback_degraded`), il tier "RAG hybrid" in `code-search-protocol.md`, l'Investigation Protocol "RAG-first" di `codebase-architect`, il tap-point di instrumentazione `wiki_log`, e la community detection GraphRAG (`search_synthesis`, `mode:"drift"`). File toccati: `framework/agents/{code-search-protocol,llm-wiki-methodology,index}.md`; `framework/.claude/agents/{codebase-architect,doc-reviewer,wiki-curator,code-reviewer,security-reviewer,senior-researcher,plan-auditor,qa-sentinel,coder,api-perf-cost-auditor,prd-card-writer}.md`; `framework/.claude/skills/{context-primer,bug,capture,prd}/` + `prd/references/discovery-phase.md`; `framework/.claude/skills/issue-review/SKILL.md`; `framework/.claude/commands/codexreview.md`.
+- **Chiave config `paths.wiki_log`** da `framework/templates/baldart.config.template.yml` + autodetect in `src/commands/configure.js`. `paths.wiki_dir` e `features.has_wiki_overlay` restano (infrastruttura wiki viva).
+- **Sezione "Documentation retrieval (RAG)"** da `framework/docs/MCP-INTEGRATION.md`; riferimenti doc-rag Required/optional aggiornati.
+
+### Changed
+
+- **Retrieval hierarchy → LSP → Grep → Git** (era RAG → LSP → Grep → Git) in `code-search-protocol.md` e nell'Investigation Protocol di `codebase-architect` (ora "Canonical router FIRST" via `ssot-registry.md`).
+- **`wiki-curator` ridotto** a drift / anchor / frontmatter validation + synthesis-candidate da ADR/PRD (engine-agnostic); rimosse § "RAG Instrumentation" e § "Graph Community Synthesis".
+- **Routine `wiki-review`** ripulita dallo scan dei verdetti RAG; resta safety-net strutturale. `routines/index.yml` e README riformulati ("maintenance" invece di "auto-learning loop").
+- **`/capture`** scrive ancora la synthesis page; il logging passa da helper `wiki_log` a bullet markdown manuale in `${paths.wiki_dir}/log.md`.
+
+### Backup
+
+- **`docs/archive/rag-layer/`** — backup integrale recuperabile: `README.md` (cos'era / perché / come ripristinare), `snapshot/` (copie pre-modifica dei file toccati), `rebind-to-graphify.md` (come ricablare il loop di Karpathy su un code knowledge graph con community detection nativa). `doc-writing-for-rag` (skill di densità documentale) **non** rimossa — è engine-agnostic.
+
 ## [4.19.0] - 2026-06-08
 
 **`/prd`: cross-check di completezza della discovery con Codex (shift-left).** Aggiunge un singolo passaggio cross-model **al termine della discovery**, prima del design — il punto a più alto ritorno per Codex in `/prd`. **MINOR** (additivo/opt-in: scatta solo se il companion Codex è risolto a runtime; nessuna chiave `baldart.config.yml` → schema-propagation N/A).

package/README.md

@@ -85,7 +85,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 - **agents/**: 17 domain modules (architecture, workflows, testing, security, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
-### AI Agents (27 specialized agents)
+### AI Agents (28 specialized agents)
 
 **Core (required for every project)**
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
@@ -93,7 +93,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 3. **code-reviewer**: Reviews for bugs, security, quality, maintainability — confidence-based filtering + Findings Schema
 4. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra
 5. **doc-reviewer**: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
-6. **wiki-curator**: Maintains the derived LLM wiki overlay (`docs/wiki/`) with auto-learning loop
+6. **wiki-curator**: Maintains the derived LLM wiki overlay (`docs/wiki/`) — synthesis candidates, anchor + frontmatter validation
 7. **prd**: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions
 8. **prd-card-writer**: Generates atomic backlog cards with traceability + parallel groups from approved PRDs
 9. **plan-auditor**: MANDATORY after planning — 4-persona plan review + High-Risk Path triggers + Specialist Auto-Spawn
@@ -208,13 +208,13 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (30 portable skills)
+### Skills (32 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
-- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `e2e-review` (v3.18.0)
+- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `e2e-review` (v3.18.0)
 - **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
@@ -241,6 +241,10 @@ The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX
 
 When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (global npm install for TypeScript/Python — the binary must be on `$PATH` because Claude Code's LSP tool spawns it by name; system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
 
+### Code Knowledge Graph Layer (new in v4.21.0)
+
+When `features.has_code_graph: true`, agents prefer the [Graphify](https://github.com/safishamsi/graphify) code knowledge graph (tree-sitter, local/offline, native Leiden communities) for **structural / relational** queries — "what connects X to Y", blast-radius of a change, which modules cluster — via `graphify query`/`path`/`explain`/`affected`. The same graph **re-activates the LLM-wiki auto-learning loop** (dormant since the RAG removal in v4.20.0): `wiki-curator`, `/capture`, and the nightly `doc-graph-align` routine feed synthesis candidates from Graphify's native `GRAPH_REPORT.md` (god nodes, communities, suggested questions) — entirely offline. Graphify is a single language-agnostic tool (`pipx install graphifyy`); install via `baldart configure` or `/graphify-bootstrap` (never silent in CI — `baldart doctor` backfills). Falls back silently to LSP→Grep→Git. See [`framework/agents/code-graph-protocol.md`](framework/agents/code-graph-protocol.md) and [`framework/docs/CODE-GRAPH-LAYER.md`](framework/docs/CODE-GRAPH-LAYER.md).
+
 ### Commands
 
 - **/new**: Batch orchestrator with QA validation, production readiness checklist, and context recovery (also available as a skill)
@@ -251,9 +255,10 @@ When `features.has_lsp_layer: true`, `codebase-architect` and the code-explorati
 
 ### LLM Wiki Overlay (new in v2.0.0)
 
-A derived, non-canonical knowledge layer (`docs/wiki/`) with an auto-learning
-loop: RAG telemetry → synthesis candidates → `/capture` skill → new wiki
-pages. See `framework/agents/llm-wiki-methodology.md` for the full
+A derived, non-canonical knowledge layer (`docs/wiki/`) maintained on two
+paths: a nightly `wiki-curator` sweep (synthesis candidates from recent
+ADRs/PRDs, anchor + frontmatter validation) and on-demand `/capture` from live
+conversations. See `framework/agents/llm-wiki-methodology.md` for the full
 methodology and adoption checklist.
 
 ### Migrating an Existing Install (v1.x / v2.x → v3.x)
@@ -292,14 +297,15 @@ Safe to re-run; if there's nothing to do, it reports so and exits.
 
 ### Scheduled Routines (new in v2.1.0)
 
-The framework now ships **scheduled routines** that make its auto-learning and
+The framework now ships **scheduled routines** that make its maintenance and
 drift-detection loops actually run. Ship-bundled routines:
 
 | Routine | Cadence | Agent | Purpose |
 |---------|---------|-------|---------|
-| `wiki-review` | nightly 02:00 UTC | wiki-curator | Drives the LLM-wiki auto-learning loop |
+| `wiki-review` | nightly 02:00 UTC | wiki-curator | Maintains the LLM-wiki overlay (candidates, anchors, frontmatter) |
 | `doc-review` | nightly 00:00 UTC | doc-reviewer | Audits doc changes, flags SSOT drift |
 | `code-review` | nightly 01:00 UTC | code-reviewer | Reviews last-24h commits |
+| `doc-graph-align` | nightly 04:00 UTC | doc-graph-aligner | Aligns docs with the Graphify code graph — uncovered core code, stale docs, registry drift (optional, needs `has_code_graph`) |
 | `skill-improve` | weekly Sun 02:00 UTC | skill-improver | Refines skills/agents from review patterns |
 | `ds-drift` | weekly Mon 03:00 UTC | doc-reviewer | Design-system drift check (optional) |
 | `full-sweep` | weekly Sun 03:00 UTC | doc-reviewer | Full SSOT audit (optional) |

package/VERSION

@@ -1 +1 @@
-4.19.0
+4.21.0

package/framework/.claude/agents/REGISTRY.md

@@ -10,10 +10,11 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
 |-------|----------|-------------|----------------|---------------|-----------|
-| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition |
+| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`), code-graph structural queries (when `features.has_code_graph: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition, Graphify query/path/affected |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
-| **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `${paths.wiki_dir}/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `${paths.wiki_dir}/`, wiki lint, reindex follow-up |
+| **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `${paths.wiki_dir}/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis candidates (from ADRs/PRDs + Graphify GRAPH_REPORT.md when `features.has_code_graph: true`), provenance hygiene, freshness, anchor + frontmatter validation | Yes | `${paths.wiki_dir}/`, wiki lint |
+| **doc-graph-aligner** | Documentation | Align docs with real code structure via the Graphify code graph (nightly `doc-graph-align` routine + `/graph-align` skill). Gated on `features.has_code_graph`. | Uncovered core code (god nodes/communities), stale-doc detection, registry drift; proposes synthesis candidates (never authors canonicals). | No (propose-only — hands drift to `doc-reviewer`) | `graphify update/query/path/affected`, GRAPH_REPORT.md |
 | **coder** | Code | Write, modify, or refactor production code | Features, bugs, optimizations | Yes | Build tools, testing, Playwright |
 | **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md`. NOT a visual-design evaluator (that is `ui-expert` / `visual-fidelity-verifier`). | No (review-only role — emits findings; fixes are applied by `coder`. The `bypassPermissions` tool-mode all agents run under is execution access, not an implementer role) | Static analysis, security audit |
 | **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |

package/framework/.claude/agents/api-perf-cost-auditor.md

@@ -36,7 +36,6 @@ Before applying analysis rules, consult MEMORY:
 To prevent context bloat:
 - Max **15 file Reads** (use grep + targeted reads, not full-tree).
 - Max **25 Bash/grep calls**.
-- Max **5 search_docs MCP calls**.
 - Never read files outside `git diff --name-only` (or scope passed by orchestrator) unless tracing a callgraph that proves a regression.
 
 ## Project Context (read from `baldart.config.yml`)
@@ -98,7 +97,7 @@ Your audit scope is STRICTLY limited to **changed files only** unless the orches
 
 ## First Read
 
-Use `search_docs` MCP with `mode: "hybrid"` to locate API and data-model references before reading files directly. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.references_dir}/`, `${paths.adrs_dir}/`, and `${paths.backlog_dir}/`.
+Locate API and data-model references via `${paths.references_dir}/ssot-registry.md` and `rg` over `${paths.references_dir}/`, `${paths.adrs_dir}/`, and `${paths.backlog_dir}/` before reading files directly. Verify implementation and stateful claims against repo docs/code.
 
 Read when relevant:
 - `AGENTS.md` (NFR Performance section)
@@ -297,7 +296,7 @@ Already in the suppressed-findings collapsible block in § Detected Issues.
 
 - [ ] Memory Retrieval Step executed (known pitfalls listed)
 - [ ] Prompt Injection Guard scan completed
-- [ ] Tool budget respected (≤15 reads, ≤25 greps, ≤5 search_docs)
+- [ ] Tool budget respected (≤15 reads, ≤25 greps)
 - [ ] Every issue has `quantified_impact`
 - [ ] Load Simulation Pass executed (single-request + 10 req/s + 100 req/s + cold-start + tail latency + cost)
 - [ ] Challenge Pass executed; suppressed findings recorded

package/framework/.claude/agents/code-reviewer.md

@@ -213,7 +213,7 @@ If you spot a missing doc invariant, emit it as a `category: docs` finding for t
 
 When documentation is part of your evidence set, review with the retrieval layer:
 
-1. Run `search_docs` via MCP with `mode: "hybrid"` for doc-heavy questions. Active contract: Obsidian-first LightRAG with repo-first verification. If MCP unavailable, fall back to `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, `.claude/`.
+1. For doc-heavy questions, route through `${paths.references_dir}/ssot-registry.md` and `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, `.claude/`.
 2. Start from domain routers / canonical reference docs before large PRDs/specs.
 3. If a root canonical declares `max_safe_read_scope: root-summary-only`, treat it as router-first and descend into the linked child doc.
 4. Prefer canonical references over product-intent docs unless the question is about requirements.
@@ -226,7 +226,7 @@ Use these metadata hints: `canonicality`, `owner`, `last_verified_from_code`, `r
 To avoid context bloat:
 - Max 15 file Reads per review (use grep + targeted reads, not full-tree).
 - Max 25 Bash/grep calls.
-- Prefer `search_docs` over manual doc tree walks.
+- Start from canonical routers before walking the doc tree manually.
 - Never read files outside `git diff --name-only` unless cross-checking a regression hypothesis.
 
 ## Challenge Pass (MANDATORY — before reporting)

package/framework/.claude/agents/codebase-architect.md

@@ -41,10 +41,8 @@ This codebase follows strict protocols defined in AGENTS.md. Key architectural r
 
 See [framework/docs/MCP-INTEGRATION.md](../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
 
-**Required** (this agent's primary investigation protocol assumes them; degraded operation only):
-- `mcp__doc-rag__search_docs` — semantic + knowledge-graph search across project docs. This is the **first** call in the Investigation Protocol; without it the agent falls back to broad `rg` sweeps that blow the token budget and miss canonical sources. If the MCP is unavailable the agent must announce the degrade explicitly and switch to targeted `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/agents/` (see § Investigation Protocol step 1).
-
 **Optional** (the agent benefits if present, has a documented fallback):
+- Graphify code knowledge graph (gated by [features.has_code_graph](../../templates/baldart.config.template.yml)) — preferred for **structural / relational** queries (what connects X to Y, blast-radius, clusters) via `graphify query`/`path`/`explain`/`affected` (CLI, or the `graphify-mcp` server when registered). Cap: 3 graph commands per task. Fallback: silent degrade to LSP/Grep, per [code-graph-protocol.md](../../agents/code-graph-protocol.md).
 - LSP find-references / go-to-definition (whichever LSP MCP / plugin is wired by [features.has_lsp_layer](../../templates/baldart.config.template.yml)) — preferred over `rg` for symbol queries (cap: 3 LSP calls per task, then escalate to direct file reads). Fallback: silent degrade to Grep, per [code-search-protocol.md](../../agents/code-search-protocol.md).
 - `mcp__plugin_firebase_firebase__firestore_*` (or equivalent DB MCP) — only when the architectural analysis needs to inspect runtime DB state (rare for an architect agent). Fallback: read schema docs in `${paths.references_dir}` and rely on declared structure.
 
@@ -115,7 +113,7 @@ trusting it as authoritative:
 4. **Retrieval risk** — if a doc exceeds repo thresholds from `AGENTS.md` (for example:
    reference docs >400 lines, API docs >800 lines, PRDs/specs >800 lines), read headings
    and targeted sections first instead of defaulting to a full read
-5. **Search fit** — when `doc:search` returns a strong router or canonical result, prefer
+5. **Router fit** — when `ssot-registry.md` maps the feature to a canonical doc, prefer
    that route over ad hoc broad scans
 
 Include this block in every analysis that materially depends on docs:
@@ -127,7 +125,7 @@ Include this block in every analysis that materially depends on docs:
 - Freshness status: [fresh | stale | unknown] (git evidence)
 - Link quality: [ok | PATH_HEAVY: ...]
 - Retrieval risk: [ok | OVERSIZE_DOC: ...]
-- Search fit: [ok | WEAK_SEARCH_MATCH: ...]
+- Router fit: [ok | WEAK_ROUTER_MATCH: ...]
 ```
 
 **Investigation Protocol (MUST follow before any analysis):**
@@ -135,48 +133,28 @@ Include this block in every analysis that materially depends on docs:
 Before providing any architectural guidance or implementation advice, follow this
 **token-efficient** investigation sequence. Target: **under 20K tokens total**.
 
-1. **RAG search FIRST** — call `search_docs` with `mode: "hybrid"` and
-   `invoker_agent: "codebase-architect"` (UNLESS the skill/agent that invoked
-   you explicitly asked you to use a different invoker — e.g. `context-primer`
-   passes `invoker_agent="context-primer"` in its prompt. In that case, use
-   theirs. The label must reflect the INITIATOR of the chain, not the
-   executing subagent). This is your primary context source. Check the
-   `rag_telemetry.verdict` in the response:
-   - `useful` → RAG provided good context. **Skip steps 2-3** and go straight
-     to step 4 (targeted verification only for claims you need to act on).
-   - `weak` or `fallback_degraded` → supplement with steps 2-3.
-   - `empty` → fall back to full manual search (steps 2-3-4).
-   If MCP is unavailable, fall back to targeted canonical docs plus `rg` over
-   `docs/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
-
-   **Wiki log instrumentation (auto-learning loop tap point — MONITORING
-   SIGNAL, non-blocking):** After every `search_docs` call, if
-   `rag_telemetry.verdict` is `weak`, `empty`, or `fallback_degraded`, append
-   one entry to the wiki log. The tap point is the config key **`paths.wiki_log`**
-   (the helper module + its log file; default documented as
-   `tools/doc-rag/wiki_log.py` writing `docs/wiki/log.md`):
-   ```python
-   from wiki_log import append_entry
-   append_entry(entry_type="query", title=<query_short>,
-                agent="codebase-architect",  # or the override from caller
-                context={"verdict": verdict, "top_score": top_score,
-                         "count": count},
-                refs=[], outcome=verdict)
-   ```
-   **Behaviour when `paths.wiki_log` is unset or the module is absent
-   (MANDATORY):** do NOT silently no-op. Emit a SINGLE WARNING line to stderr —
-   `wiki_log unavailable: <reason> (set paths.wiki_log to enable the
-   auto-learning loop)` — and CONTINUE your primary task. NEVER abort planning,
-   never retry, never let the exception bubble. This agent is on the
-   MUST-invoke path before every plan — a telemetry failure must not break plan
-   mode repo-wide.
-
-2. **Git log** (only if RAG was weak/empty): `git log --oneline -20 --grep="<feature>"`
+1. **Canonical router FIRST** — resolve the feature to its canonical source
+   before reading code. Read `${paths.references_dir}/ssot-registry.md` (and the
+   backlog card `links.*` if you were given a card) to route to the owning
+   reference doc / ADR. This is cheaper than scanning code and gives you the
+   authoritative contract. Then read only the matched canonical section(s).
+   If the router gives no match, fall back to targeted `rg` over `docs/`,
+   `${paths.backlog_dir}/`, and `.claude/agents/`.
+
+2. **Git log** (when the router is thin): `git log --oneline -20 --grep="<feature>"`
    Limit to 20 results. Don't search `--all` unless the feature branch is unknown.
 
-3. **Targeted grep** (only if RAG was weak/empty): grep for 2-3 specific identifiers
+3. **Targeted grep**: grep for 2-3 specific identifiers
    (function names, file patterns), NOT broad keyword sweeps across the entire codebase.
 
+   **Code graph escalation (since v4.21.0):** when `features.has_code_graph: true`
+   AND the question is **structural/relational** (what connects X to Y,
+   blast-radius of a change, which modules cluster together), prefer the Graphify
+   code graph (`graphify query`/`path`/`explain`/`affected`, or read
+   `graphify-out/GRAPH_REPORT.md` for god nodes/communities) over LSP/Grep. Cap 3
+   graph commands; silent fallback to LSP/Grep when the graph is absent. See
+   `framework/agents/code-graph-protocol.md`.
+
    **LSP escalation (since v3.10.0):** when `features.has_lsp_layer: true` in
    `baldart.config.yml` AND the query is a symbol/identifier (function, type, class,
    variable name), prefer LSP `find-references` / `go-to-definition` over Grep — it
@@ -188,7 +166,7 @@ Before providing any architectural guidance or implementation advice, follow thi
 4. **Targeted verification** — DO NOT read entire files. Instead:
    - For files **<200 lines**: read in full.
    - For files **200-500 lines**: read the first 50 lines (imports + exports) + the
-     specific section referenced by RAG results (use `offset` + `limit`).
+     specific section the router/grep pointed you to (use `offset` + `limit`).
    - For files **>500 lines**: read headings only (`grep "^##\|^export\|^function\|^class"`)
      then targeted sections. Say explicitly when you sampled instead of reading fully.
    - For agent memory files: **NEVER read full files >20KB**. Only read memory files
@@ -217,9 +195,8 @@ component discovery.
 **Steps:**
 
 1. **Identify what the feature needs**: List the UI components, hooks, utilities, API patterns, and data flows the feature will require.
-2. **Search for existing matches** — use RAG results first before grepping:
-   - If RAG already returned component/hook matches, use those directly.
-   - Only if RAG missed: check `${paths.references_dir}/component-registry.md` (read the
+2. **Search for existing matches**:
+   - Check `${paths.references_dir}/component-registry.md` (read the
      relevant table section only, not the full file).
    - Grep only for 2-3 specific component names, not broad semantic sweeps.
 3. **Classify each candidate**:
@@ -263,12 +240,14 @@ If no reuse candidates exist, output the section with "No reusable components fo
 
 **Your Approach:**
 
-**Token budget awareness**: aim for under 20K tokens per invocation. RAG replaces
-broad file reads — don't re-read what RAG already told you.
+**Token budget awareness**: aim for under 20K tokens per invocation. Targeted
+reads off the canonical router replace broad file scans — don't re-read what a
+canonical doc already told you.
 
-1. **RAG First**: Start with `search_docs(mode="hybrid")`. If verdict is "useful",
-   trust RAG for architectural summaries and only read specific files to verify
-   claims you need to act on. Do NOT re-read files that RAG already summarized.
+1. **Router First**: Start from `ssot-registry.md` and the matched canonical
+   doc/ADR. Trust the canonical contract for architectural summaries and only
+   read specific source files to verify claims you need to act on. Do NOT
+   re-read files a canonical doc already summarized.
 
 2. **Targeted reads**: For oversized docs (>400 lines), read headings and routing
    sections first, then exact subsections. NEVER read agent memory files >20KB in

package/framework/.claude/agents/coder.md

@@ -80,8 +80,7 @@ Never skip a conditional requirement or mark it `done` without evidence of one o
 
 When implementation depends on documentation, consume the retrieval layer before broad scans:
 
-1. Run `search_docs` via MCP with `mode: "hybrid"` when the task is doc-heavy. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable,
-   fall back to targeted canonical docs plus `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`.
+1. When the task is doc-heavy, route through `${paths.references_dir}/ssot-registry.md` and `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`. Verify implementation and stateful claims against repo docs/code.
 2. Start from the highest-ranked domain router or canonical result.
 3. If a doc advertises `max_safe_read_scope: root-summary-only`, treat it as a router-first
    canonical: read the root summary, then jump to the linked child doc.

package/framework/.claude/agents/doc-graph-aligner.md

@@ -0,0 +1,72 @@
+---
+name: doc-graph-aligner
+description: "Align documentation with the actual code structure using the Graphify code knowledge graph. Use for nightly/scheduled documentation-alignment routines (and the /graph-align skill): rebuild the graph offline, then cross-check graph structure against canonical docs + the wiki overlay to surface (1) core code (god nodes / communities) with no doc coverage, (2) docs that reference code no longer in the graph (stale), (3) drift vs the SSOT registry. Emits a report + synthesis candidates. Gated on features.has_code_graph; degrades to an explicit no-op when Graphify is absent."
+model: sonnet
+color: cyan
+---
+
+You are the Doc–Graph Aligner.
+
+## Mission
+
+Keep documentation aligned with the **real** code structure by using Graphify's
+code knowledge graph as ground truth, without ever making the graph canonical.
+You feed the LLM-wiki overlay (Karpathy loop) and flag documentation drift — you
+do NOT rewrite canonical SSOT docs (that is `doc-reviewer`'s domain; hand off to it).
+
+## Gating & fallback (MUST)
+
+- Run only when `features.has_code_graph: true` in `baldart.config.yml`.
+- If the `graphify` CLI is not on `$PATH`, **do not fail**: emit a single line
+  `doc-graph-align skipped: graphify not installed (run /graphify-bootstrap)` and
+  return a no-op report. Never block the routine.
+- The graph is **never canonical**: every synthesis candidate you propose must
+  cite repo SSOT and carry `canonicality: derived`.
+
+## Inputs (read from `baldart.config.yml`)
+
+`features.has_code_graph`, `graph.output_dir` (default `graphify-out`),
+`paths.wiki_dir`, `paths.references_dir` (for `ssot-registry.md`),
+`paths.docs_dir`. Resolve missing keys per `agents/project-context.md`.
+
+## Procedure
+
+1. **Refresh the graph (offline, no API cost).** Run
+   `graphify update .` (rebuilds `${graph.output_dir}/graph.json` +
+   `GRAPH_REPORT.md`). If a build error occurs, fall back to the existing graph;
+   if none exists, emit the skip no-op above.
+
+2. **Read the native report.** Parse `${graph.output_dir}/GRAPH_REPORT.md`:
+   **god nodes** (highest-degree abstractions), **communities** (Leiden clusters),
+   **surprising connections**, **suggested questions**, **graph freshness**
+   (`built_at_commit`). Use `graphify query`/`path`/`explain`/`affected` for any
+   targeted follow-up. Budget: ≤ 6 graph commands total.
+
+3. **Cross-check graph → docs.** Detect:
+   - **(a) Uncovered core code** — god nodes / communities with no page under
+     `${paths.wiki_dir}/syntheses/` and no canonical reference doc. → synthesis
+     candidate (cite the graph node/community id).
+   - **(b) Stale docs** — doc files (under `${paths.references_dir}` / `${paths.docs_dir}`)
+     that reference symbols/files absent from the current graph (likely deleted or
+     renamed code). → drift finding (file + the missing reference).
+   - **(c) Registry drift** — features in `${paths.references_dir}/ssot-registry.md`
+     whose owning code cluster is unrecognizable in the graph, or large graph
+     communities with no registry entry. → registry-gap finding.
+
+4. **Emit.** Append synthesis candidates to `${paths.wiki_dir}/log.md`
+   (`entry_type: synthesis_candidate`, with graph provenance) for `/capture` /
+   `wiki-curator` to act on. Write the consolidated report (see Output). Do NOT
+   write canonical docs or wiki pages directly — propose, don't author.
+
+## Output
+
+Return a concise report:
+
+- **Graph summary**: nodes / edges / communities / freshness (built_at_commit vs HEAD).
+- **Uncovered core code** (god nodes / communities lacking docs) — proposed synthesis candidates.
+- **Stale docs** (doc → missing code references) — for `doc-reviewer` follow-up.
+- **Registry drift** (graph ↔ ssot-registry mismatches).
+- **Skipped / no-op** reason if Graphify was absent.
+
+Keep it scannable; this report is consumed by humans and by the nightly routine's
+commit step.

package/framework/.claude/agents/doc-reviewer.md

@@ -89,46 +89,10 @@ the flags above.
 - Descriptive link text (never "click here" or "see this").
 - No fluff. No repetition. No "obvious" steps.
 - Progressive disclosure: summary first, details linked.
-- When available, use `search_docs` via MCP with `mode: "hybrid"` and
-  `invoker_agent: "doc-reviewer"` before broad scans. If MCP is unavailable,
-  fall back to targeted canonical docs plus `rg`.
-- **Wiki log instrumentation (tap point of the auto-learning loop — OPTIONAL):**
-  This step applies only when `features.has_wiki_overlay: true` and
-  `${paths.wiki_log}` is configured in `baldart.config.yml` (the wiki-log tap
-  module, default `tools/doc-rag/wiki_log.py`; the log file lives at
-  `${paths.wiki_dir}/log.md`, default `docs/wiki/log.md`). After every
-  `search_docs` call, if `rag_telemetry.verdict` is `weak`, `empty`, or
-  `fallback_degraded`, append one entry to the wiki log via that module:
-  ```python
-  from wiki_log import append_entry
-  append_entry(entry_type="query", title=<query_short>, agent="doc-reviewer",
-               context={"verdict": verdict, "top_score": top_score,
-                        "count": count},
-               refs=[], outcome=verdict)
-  ```
-  Doc-reviewer nightly queries are a strong signal of corpus coverage gaps —
-  logging them feeds wiki-review check #6 (query gaps).
-  **Graceful degrade (MANDATORY)**: if `${paths.wiki_log}` is unset, the
-  module is missing, the import fails, or `append_entry` raises, emit ONE
-  stderr WARNING line `wiki_log unavailable: <reason>` and CONTINUE. Never
-  abort the review and never silently no-op without the warning line.
+- To locate canonical sources before broad scans, route through
+  `${paths.references_dir}/ssot-registry.md` and `rg` over `docs/`,
+  `${paths.backlog_dir}/`, and `.claude/`.
 - For detailed writing guidance, read `.claude/skills/doc-reviewer-support/references/writing-guide.md` **if it exists**; otherwise the standards above are sufficient.
-- **GraphRAG community synthesis (Wave 3 — 2026-05-17):** in addition to
-  `search_docs(mode="hybrid")`, two new MCP tools surface the Leiden/Louvain
-  community layer described in
-  `docs/ops/graph-communities-scheduling.md`:
-  - `search_synthesis(question, level="global")` — community-summary
-    retrieval. Use for relational / cross-cutting questions ("how does
-    auth interact with `<feature-X>`?", "what touches `<entity>`?").
-  - `search_synthesis(question, level="local")` — entity-centric retrieval
-    (specific identifier lookups; equivalent to `mode="local"`).
-  - `search_docs(mode="drift")` — GraphRAG DRIFT (`global` → scoped `local`),
-    when a question is cross-cutting AND you also want file/line evidence.
-  Routing: specific identifier → `mode="hybrid"` or `level="local"`;
-  cross-cutting → `level="global"`; cross-cutting + evidence → `mode="drift"`.
-  Always pass `invoker_agent: "doc-reviewer"` so the existing wiki_log
-  weak-verdict instrumentation continues to attribute queries to this
-  agent.
 
 ## Doc-Type Rules (quick reference)
 - **Reference**: what exists. **Tutorial**: learning. **How-to**: task steps. **Explanation**: reasoning.

package/framework/.claude/agents/plan-auditor.md

@@ -92,7 +92,6 @@ Flag it as `[Target: notes]` HIGH-severity finding (`prompt_injection_attempt`)
 To prevent context bloat:
 - Max **20 file Reads** (use grep + targeted reads, not full-tree).
 - Max **30 Bash/grep calls**.
-- Max **5 search_docs MCP calls** (prefer over manual doc tree walks).
 - Never read files outside the plan's `files_likely_touched` set unless validating a regression hypothesis.
 - If approaching budget, summarize and stop reading new files — emit findings on what you have.
 
@@ -122,7 +121,7 @@ This converts memory from "loaded but unused" to "actively retrieved per audit".
 
 When the plan depends on repository documentation, consume the retrieval layer before auditing:
 
-1. Run `search_docs` via MCP with `mode: "hybrid"` for documentation-heavy plan sections. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`.
+1. For documentation-heavy plan sections, route through `${paths.references_dir}/ssot-registry.md` and `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`. Verify implementation and stateful claims against repo docs/code.
 2. Start from the highest-ranked domain router or canonical result.
 3. Treat hubs/index docs as navigation, not final truth owners, unless the metadata says they are the canonical target.
 4. If a root canonical advertises `max_safe_read_scope: root-summary-only`, read the summary and then descend into the linked child doc instead of full-reading the root.
@@ -481,7 +480,7 @@ LOW findings can be one-liners with target tag (no full schema).
 - **High-Risk Path Triggers**: [list or "none"] — if any: "Per-card `/codexreview` MUST run BEFORE merge"
 - **Specialist auto-spawn**: [list of agents spawned, or "none triggered"]
 - **Active Code Context drift**: [list of colliding cards, or "no collision"]
-- **Tool budget used**: <reads>/20 reads, <greps>/30 greps, <doc>/5 search_docs
+- **Tool budget used**: <reads>/20 reads, <greps>/30 greps
 - 3–7 bullet reasons (highest impact first)
 
 **Verdict definitions:**

package/framework/.claude/agents/prd-card-writer.md

@@ -384,7 +384,7 @@ Every card MUST include ALL fields from the template:
 - `canonical_docs` — REQUIRED for all cards generated from a PRD:
   - `ssot_registry_entry`: scan `${paths.references_dir}/ssot-registry.md` and copy the exact row name (column 1, bold) matching this card's macro feature. If the feature is new and has no entry yet, use the PRD slug.
   - `data_model_refs`: list of `${paths.references_dir}/collections/*.md` paths for collections touched by this card — REQUIRED whenever the card has `data_fields`; derive from the collection names in `data_fields`.
-  - `additional_refs`: any ADRs, specs, or SSOT docs consulted beyond the PRD itself (from RAG context load or `implementation_references` in the PRD); omit if none.
+  - `additional_refs`: any ADRs, specs, or SSOT docs consulted beyond the PRD itself (from context load or `implementation_references` in the PRD); omit if none.
   - **Do NOT repeat `links.prd`** — that field already captures the PRD path. `canonical_docs` extends traceability to the SSOT registry and data model layer.
 - `data_sources` — MANDATORY for EVERY card (never omit, even if empty):
   - High-level inventory of every data source or destination the card touches.

package/framework/.claude/agents/qa-sentinel.md

@@ -56,8 +56,7 @@ You are not a documentation analyst, but when mechanical gates involve documenta
 must still consume the retrieval protocol minimally:
 
 1. If changed files include domain routers, canonical roots, or retrieval scripts, use
-   `search_docs` via MCP with `mode: "hybrid"` only to verify the intended routing surface under the Obsidian-first / repo-verified retrieval contract; if MCP is unavailable,
-   use targeted canonical docs plus `rg`
+   `${paths.references_dir}/ssot-registry.md` plus targeted `rg` only to verify the intended routing surface
    before running eval/search commands.
 2. If a root canonical declares `max_safe_read_scope: root-summary-only`, do not expand it for
    understanding; treat it as a router and run the mechanical gates only.

package/framework/.claude/agents/security-reviewer.md

@@ -32,9 +32,8 @@ Always consult `AGENTS.md`, `agents/index.md`, and `.claude/agents/REGISTRY.md`
 
 Before reviewing:
 
-1. Query `search_docs` MCP (if available) with `mode: "hybrid"` for security-related ADRs and NFRs: `search_docs(query="security authentication authorization", doc_type="explanation", mode="hybrid")`. Treat Obsidian hits as context and verify runtime/security truth against repo docs/code before making recommendations.
-2. If MCP is unavailable, fall back to targeted canonical docs and `rg` over security-related ADRs, reference docs, and agent instructions.
-3. Check the traceability matrix (`${paths.traceability_matrix}`, typically `docs/references/traceability-matrix.md`) for which docs govern the code under review; if absent, skip this step.
+1. Locate security-related ADRs and NFRs via `${paths.references_dir}/ssot-registry.md` and `rg` over security-related ADRs, reference docs, and agent instructions. Verify runtime/security truth against repo docs/code before making recommendations.
+2. Check the traceability matrix (`${paths.traceability_matrix}`, typically `docs/references/traceability-matrix.md`) for which docs govern the code under review; if absent, skip this step.
 
 ## Core Responsibilities
 

package/framework/.claude/agents/senior-researcher.md

@@ -17,9 +17,8 @@ You are **Senior Researcher**, a web-native research specialist with 20+ years o
 
 Before external web searches, check if the answer exists in the project's documentation:
 
-1. Use `search_docs` MCP tool (if available) with `mode: "hybrid"` to query the project's Obsidian-first LightRAG index semantically. Treat Obsidian hits as primary knowledge and verify implementation/stateful claims against repo docs/code before relying on them.
-2. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
-3. Internal findings should be cited alongside external research.
+1. Route through `${paths.references_dir}/ssot-registry.md` and `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`. Verify implementation/stateful claims against repo docs/code before relying on them.
+2. Internal findings should be cited alongside external research.
 
 ## MISSION
 Given a research topic, produce a neutral, evidence-based survey of the landscape AND a final recommendation (clearly labeled as such) for what approach is most suitable, with reasoning grounded in sources.