baldart 4.19.0 → 4.21.0

package/framework/.claude/skills/new/references/implement.md

@@ -10,7 +10,7 @@
    - If `DONE` (or the user chose "proceed anyway") → continue.
 2b. **Claim** — only now set the card status to `IN_PROGRESS` and assign yourself. **→ Visibility**: TaskUpdate this card's spine task → `in_progress`, and emit a Progress Bar (card change) per § "Progress Visibility".
 2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
-3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. The orchestrator does NOT propagate the flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.)
+3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.)
 3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.
 4. **Plan-auditor grounding check** — but first, a **provenance skip (since v4.7.0 — mirror of Step 3d)**: the `/prd` Step 6.6 holistic audit already ran a per-card grounding pass when the card was authored. Re-grounding here is only worth a plan-auditor spawn if something changed since. Skip the plan-auditor when **BOTH** hold:
    - **P1 — provenance present**: the card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, `audited_set`.

package/framework/.claude/skills/prd/SKILL.md

@@ -299,16 +299,17 @@ Before entering the discovery loop, load codebase context using the **context-pr
 1. Extract 2-4 keywords from the user's feature description.
 2. Invoke the `Skill` tool with `skill: "context-primer"` passing the keywords
    (e.g., `args: "prize scanning scratch card wheel"`).
-3. The context-primer launches `codebase-architect` which searches RAG, docs,
-   backlog, source code, and git history — returning a compact summary. When
-   `features.has_lsp_layer: true`, the symbol-lookup tier is automatically used
-   for identifier-shaped queries (transitive via `agents/code-search-protocol.md`).
-4. Additionally, use `search_docs` MCP tool (if available) with `mode: "hybrid"` for the feature domain
-   to surface related PRDs, ADRs, and specs not covered by context-primer. The
-   active retrieval layer is Obsidian-first LightRAG; use Obsidian hits for
-   concept and decision context, then verify implementation and stateful claims
-   against repo docs/code. If MCP is unavailable, fall back to targeted
-   canonical docs plus `rg` over `${paths.references_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
+3. The context-primer launches `codebase-architect` which routes through the
+   canonical registry, docs, backlog, source code, and git history — returning a
+   compact summary. When `features.has_lsp_layer: true`, the symbol-lookup tier is
+   automatically used for identifier-shaped queries (transitive via
+   `agents/code-search-protocol.md`); when `features.has_code_graph: true`, the
+   architect uses the Graphify code graph for structural/relational queries
+   (transitive via `agents/code-graph-protocol.md`).
+4. Additionally, route through `${paths.references_dir}/ssot-registry.md` and `rg`
+   over `${paths.references_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`
+   for the feature domain to surface related PRDs, ADRs, and specs not covered by
+   context-primer. Verify implementation and stateful claims against repo docs/code.
 5. Check `${paths.references_dir}/traceability-matrix.md` for source-to-doc mappings (if the project maintains one — skip when absent).
 
 The loaded context lives in conversation history and informs ALL subsequent

package/framework/.claude/skills/prd/references/discovery-phase.md

@@ -106,12 +106,11 @@ this is a fresh session (no existing state file).
    2-4 keywords extracted from the user's feature description and
    `task_type: "new-feature"` (always explicit — do NOT let context-primer
    default to `"query"` for domain keywords, which produces a narrower
-   RAG-only context). context-primer internally calls `codebase-architect`
-   which runs `search_docs mode: hybrid`, checks docs, backlog, source code,
+   context). context-primer internally calls `codebase-architect`
+   which routes through the canonical registry, checks docs, backlog, source code,
    and git history. The returned context informs all subsequent discovery
-   dimensions. **Do NOT issue a separate `search_docs` call** — context-primer
-   already covers it, and a second call with the same query wastes context
-   window and doubles wiki_log telemetry entries.
+   dimensions. **Do NOT issue a separate redundant retrieval pass** — context-primer
+   already covers it, and a second pass with the same query wastes context window.
 8. Mark clearly irrelevant dimensions as "N/A" with reason
    (e.g., backend-only -> UI impact = N/A).
    If UI impact is N/A, immediately mark task 2 as `completed` ("Skipped — no UI").

package/framework/.claude/skills/simplify/SKILL.md

@@ -55,6 +55,9 @@ For each new piece of code in the diff:
    names overcounts because of collisions). See `framework/agents/code-search-protocol.md`.
    Also use LSP `find-references` on candidate "existing" utilities to confirm they're
    really in use and not abandoned dead code before recommending them as the canonical version.
+   When `features.has_code_graph: true`, `graphify affected "<symbol>"` gives the same
+   reverse-impact set from the graph (and `graphify-out/GRAPH_REPORT.md` surfaces
+   duplicated god-node clusters) — see `framework/agents/code-graph-protocol.md`.
 4. **Flag components that wrap the same underlying element** with minor style/prop differences.
 
 Classify each finding as:

package/framework/agents/code-graph-protocol.md

@@ -0,0 +1,108 @@
+# Code Graph Protocol
+
+## Purpose
+
+Define when and how agents/skills use the **code knowledge graph** (Graphify)
+for **structural / relational** code questions — the kind Grep and even LSP
+answer poorly: "what connects auth to the database", "what breaks if I change
+this", "which modules form a cluster", "show the path between these two pieces".
+The graph filters the codebase to the relevant *subgraph* before Claude reads
+anything, the same economy principle as the LSP and (former) RAG tiers.
+
+## Scope
+
+**In**: choosing the graph vs LSP vs Grep vs Git for code retrieval; the native
+Graphify commands to call; fallback rules.
+**Out**: single-symbol reference/definition lookups (see
+`agents/code-search-protocol.md` → LSP tier); documentation synthesis (see
+`agents/llm-wiki-methodology.md`).
+
+## Gating
+
+Conditional on `features.has_code_graph: true` in `baldart.config.yml`. When the
+flag is `false`/missing **or** the `graphify` CLI is not installed, agents **fall
+back silently** to the LSP → Grep → Git hierarchy. Never block a task on the
+graph being absent — surface setup gaps through `baldart doctor`
+(`Code graph` line + `graph-install` / `graph-rebuild` actions), not mid-task.
+
+Graphify is a single language-agnostic tool (tree-sitter, 28 languages,
+local/offline). The graph lives at `${graph.output_dir}/graph.json` (default
+`graphify-out/graph.json`); a stale graph (built from an older commit than HEAD)
+is rebuilt by doctor / the native post-commit hook, not by the querying agent.
+
+## Composition with Graphify's native always-on mode
+
+Graphify ships its **own** Claude/Codex integration: `graphify <platform> install`
+writes a graph-first section to the tool's instruction file + a pre-tool hook
+that nudges the assistant to query the graph before grepping, and a native
+`/graphify` skill. **This protocol does not duplicate that** — it tells BALDART's
+own agents *when* the graph is the right tier and *which* native command to run.
+Prefer the native skill / MCP when present; the CLI commands below always work
+post-install with no registration.
+
+## Retrieval hierarchy (relational queries first)
+
+For a **structural / relational** query, the order is:
+
+1. **Code graph** — `graphify query`/`path`/`explain`/`affected` (or the
+   `graphify-mcp` MCP tools when registered). Best for multi-hop relationships,
+   blast-radius, clustering, "how do these connect".
+2. **LSP** — when it collapses to a single symbol's references/definition
+   (`features.has_lsp_layer: true`). See `agents/code-search-protocol.md`.
+3. **Grep** — textual patterns (comments, magic strings, config keys).
+4. **Git log** — when/why something changed.
+
+For a **symbol or textual** query, skip the graph and start at LSP/Grep per the
+code-search-protocol — the graph adds nothing there.
+
+## Native commands (all offline, 0 API cost)
+
+Run via Bash (the CLI is on `$PATH` once installed); `--graph` defaults to
+`graphify-out/graph.json`:
+
+| Need | Command |
+|------|---------|
+| Free-text traversal for a question | `graphify query "how does auth reach the DB"` |
+| Path between two nodes | `graphify path "LoginController" "UserRepository"` |
+| Explain a node + its neighbours | `graphify explain "SessionService"` |
+| Blast radius (reverse impact) | `graphify affected "computeBaseFileSha"` |
+| Cluster / hub overview | read `graphify-out/GRAPH_REPORT.md` (god nodes, communities) |
+
+`graphify query` accepts `--budget N` (token cap, default 2000) and `--dfs`.
+`graphify affected` accepts `--depth N` and `--relation R`.
+
+## Query-type discrimination
+
+| Query shape | Start with |
+|-------------|------------|
+| "what connects X to Y" / "path from X to Y" | code graph (`path`/`query`) |
+| "what breaks if I change X" / impact | code graph (`affected`) |
+| "which parts form a cluster / the core abstractions" | code graph (`GRAPH_REPORT.md`) |
+| `handleSubmit`, `UserSchema` (single symbol refs/def) | LSP |
+| `"TODO: …"`, a config key, a regex | Grep |
+| "when did X change" | Git log |
+
+## Budget
+
+- **Graph**: up to **3 graph commands per task** for a relational question. If
+  still unclear, read the specific files the graph pointed to — don't keep
+  traversing. `--budget` caps `query` output.
+- Falls back to the existing LSP/Grep budgets when the graph is unavailable.
+
+## Fallback rules
+
+- `graphify` not installed / `has_code_graph: false` → silent fallback to
+  LSP → Grep → Git. No prompt mid-task.
+- `graph.json` missing or stale → still usable; note the staleness in reasoning
+  and let doctor/the hook rebuild it. Don't rebuild inline during a read task
+  (rebuild is a side effect owned by `doctor` / `graphify-bootstrap` / the
+  nightly `doc-graph-align` routine).
+- A graph command errors / returns nothing → fall back to LSP/Grep for that query.
+
+## See also
+
+- `framework/.claude/skills/graphify-bootstrap/SKILL.md` — install + verify + build.
+- `framework/.claude/skills/graph-align/SKILL.md` — on-demand doc/graph alignment.
+- `framework/agents/code-search-protocol.md` — LSP/Grep/Git hierarchy.
+- `framework/agents/llm-wiki-methodology.md` — how `GRAPH_REPORT.md` feeds the wiki.
+- `framework/docs/CODE-GRAPH-LAYER.md` — install lifecycle, schema, invariants.

package/framework/agents/code-search-protocol.md

@@ -10,7 +10,7 @@ burns context; LSP returns only the references that point to the same symbol.
 
 ## Scope
 
-**In**: How agents/skills should choose between RAG, LSP, Grep, and Git when
+**In**: How agents/skills should choose between LSP, Grep, and Git when
 searching for code. Fallback rules when a tier is unavailable.
 **Out**: Documentation search (see `agents/llm-wiki-methodology.md`), test
 discovery (see `agents/testing.md`).
@@ -19,7 +19,7 @@ discovery (see `agents/testing.md`).
 
 This protocol is **conditional** on `features.has_lsp_layer: true` in
 `baldart.config.yml`. When the flag is `false` or missing, agents fall back to
-the legacy RAG → Grep → Git flow and skip the LSP tier entirely.
+the Grep → Git flow and skip the LSP tier entirely.
 
 Adapters for installed servers live under `src/utils/lsp-adapters/`; the
 current set of servers BALDART has wired in this project is recorded at
@@ -27,20 +27,27 @@ current set of servers BALDART has wired in this project is recorded at
 
 ## Retrieval Hierarchy (in order)
 
-1. **RAG hybrid** — `search_docs(query, mode: "hybrid")` via the doc-rag MCP if
-   available. Best for free-text and conceptual queries ("how does session
-   token storage work").
-2. **LSP symbol search** — when the query is an identifier (function, type,
+0. **Code graph (Graphify)** — when the query is **structural / relational**
+   ("what connects X to Y", impact/blast-radius, clusters) and
+   `features.has_code_graph: true`. This tier sits *above* LSP for relationship
+   questions only; for a single-symbol or textual query, skip it and start at
+   LSP/Grep below. Full contract in `agents/code-graph-protocol.md`. Falls back
+   silently to the tiers below when the graph is unavailable.
+1. **LSP symbol search** — when the query is an identifier (function, type,
    class, variable name) and `features.has_lsp_layer: true`. Use the LSP tool
    (`ToolSearch("LSP")` in Claude Code) for:
    - **find references**: every callsite of a symbol across the project.
    - **go to definition**: the single authoritative declaration.
    - **type info / hover**: signature, parameters, return type.
    - **document/workspace symbols**: enumerate top-level symbols.
-3. **Grep** — for textual patterns that aren't symbols (a comment, a magic
+2. **Grep** — for textual patterns that aren't symbols (a comment, a magic
    string, a regex match, a config key, a TODO marker). Also the fallback when
    LSP is unavailable or returns nothing for a symbol that clearly exists.
-4. **Git log** — `git log --oneline -20 --grep="keyword"` to find when and why
+   For free-text / conceptual questions ("how does session token storage
+   work"), start from the canonical docs router (`ssot-registry.md` →
+   reference docs / ADRs) and Grep over `docs/`, then read the matched
+   sections.
+3. **Git log** — `git log --oneline -20 --grep="keyword"` to find when and why
    code changed. Last resort, but cheap when you suspect a regression.
 
 ## Query-type discrimination
@@ -49,21 +56,21 @@ Before picking a tier, classify the query:
 
 | Query shape                            | Start with |
 |----------------------------------------|------------|
+| "what connects X to Y" / impact / clusters | code graph (if `has_code_graph`) — see `code-graph-protocol.md` |
 | `handleSubmit`, `UserSchema`, `useAuth`| LSP        |
 | `"TODO: encrypt tokens"`               | Grep       |
 | `/api/v1/users` route handler          | Grep then LSP on the handler name |
-| "how is auth wired"                    | RAG hybrid |
+| "how is auth wired"                    | canonical docs router + Grep over `docs/` |
 | "when did we change session storage"   | Git log    |
-| Mixed (refactor a function used in 5 places) | RAG → LSP find-references |
+| Mixed (refactor a function used in 5 places) | Grep to disambiguate, then LSP find-references |
 
 ## Budget
 
 - **LSP**: up to **3 calls per task** for symbol resolution. If after 3 calls
-  the picture is still unclear, escalate to RAG or read the file directly —
+  the picture is still unclear, escalate to a direct file read —
   don't keep ping-ponging through references.
 - **Grep**: existing project budget (typically 15–25 calls per agent).
-- **RAG / Git**: no hard budget, but verify the verdict (`rag_telemetry.verdict`
-  for RAG) before relying on it.
+- **Git**: no hard budget.
 
 ## Fallback rules
 
@@ -88,21 +95,20 @@ Before picking a tier, classify the query:
 
 ### Refactor: rename a function used across the repo
 
-1. RAG hybrid: confirm the function is the right one and not a name collision.
+1. Grep to confirm the function is the right one and not a name collision.
 2. LSP find-references on the symbol → exact callsite list (file + line +
    column).
 3. Read each callsite, propose the rename, apply edits.
 
-Why this beats Grep: a project with both `handleSubmit` in a form component
-and `handleSubmit` in a CLI utility gets two semantically distinct sets from
-LSP, but a single conflated list from Grep.
+Why this beats Grep alone: a project with both `handleSubmit` in a form
+component and `handleSubmit` in a CLI utility gets two semantically distinct
+sets from LSP, but a single conflated list from Grep.
 
 ### Bug: trace where a value originates
 
-1. RAG hybrid on the symptom (free text).
-2. LSP go-to-definition on the suspect variable → authoritative source.
-3. LSP find-references back from the definition → call graph upstream.
-4. Grep only if LSP cannot resolve (e.g. the value passes through a
+1. LSP go-to-definition on the suspect variable → authoritative source.
+2. LSP find-references back from the definition → call graph upstream.
+3. Grep only if LSP cannot resolve (e.g. the value passes through a
    dynamically-typed boundary).
 
 ### Cleanup: remove a deprecated helper

package/framework/agents/index.md

@@ -15,6 +15,7 @@ Route agents to the right module with minimal reading.
 - **MANDATORY pre-read for any skill/agent that touches project-specific paths, identity, stack, or feature toggles** -> read `agents/project-context.md`. Skills consult `baldart.config.yml` + `.baldart/overlays/<skill>.md` instead of hard-coded paths; missing keys MUST be asked, never assumed.
 - If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first; do not proceed without architectural understanding.
 - If searching for a function/type/symbol (identifier-shaped query, not free text) and `features.has_lsp_layer: true` -> read `agents/code-search-protocol.md` and prefer LSP `find-references` / `go-to-definition` over Grep. Falls back to Grep when LSP is unavailable or the query is textual.
+- If the question is STRUCTURAL / RELATIONAL (what connects X to Y, blast-radius/impact, clusters) and `features.has_code_graph: true` -> read `agents/code-graph-protocol.md` and prefer the Graphify code graph (`graphify query`/`path`/`explain`/`affected`) over LSP/Grep. Falls back silently to LSP -> Grep -> Git when the graph is unavailable.
 - If touching API endpoints or request/response shape -> read `agents/api-contracts.md` and `${paths.references_dir}/api/index.md` (then specific API module for your domain).
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
@@ -59,9 +60,10 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/github-issue-subagent.md`
 - `agents/design-review.md`
 - `agents/skills-mapping.md`
-- `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology + auto-learning loop (since v2.0.0)
+- `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology (manual + scheduled maintenance; since v2.0.0)
 - `agents/project-context.md` — Project context protocol: `baldart.config.yml` + overlays + missing-key handling (since v3.0.0)
-- `agents/code-search-protocol.md` — Retrieval hierarchy for code search: RAG → LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
+- `agents/code-search-protocol.md` — Retrieval hierarchy for code search: LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
+- `agents/code-graph-protocol.md` — Structural/relational retrieval via the Graphify code knowledge graph (since v4.21.0, gated on `features.has_code_graph`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 
 ## Where to Document (Decision Tree)

package/framework/agents/llm-wiki-methodology.md

@@ -8,9 +8,9 @@ layer of compiled pages (concepts, syntheses, dashboards, reading guides) that
 makes retrieval cheaper and reasoning more stable, **without ever becoming
 source-of-truth**.
 
-This module describes the contract, file layout, lifecycle, and auto-learning
-loop. The agent that maintains the overlay is `wiki-curator`. The skill that
-captures synthesis pages from live conversations is `/capture`.
+This module describes the contract, file layout, and lifecycle of the overlay.
+The agent that maintains it is `wiki-curator`. The skill that captures synthesis
+pages from live conversations is `/capture`.
 
 ## Layered Knowledge Stack
 
@@ -20,7 +20,6 @@ The wiki overlay sits on top of an existing retrieval stack. A typical layout:
 |-------|------|-----------|
 | Canonical SSOT (`${paths.references_dir}/**`, `${paths.adrs_dir}/**`, code itself) | Source of truth | **Canonical** — never override from below |
 | External human knowledge (Obsidian vault, Notion, Confluence) | Human-readable narrative; optional | Mirrors canonical with extra context |
-| RAG / search layer (e.g. LightRAG, vector DB, full-text index) | Recall + cross-document discovery | Operational, not canonical |
 | **Wiki overlay** (`${paths.wiki_dir}/**`) | Compiled, navigable, stable | **Derived** — always cites canonical refs |
 
 Rules:
@@ -29,9 +28,6 @@ Rules:
 2. SSOT changes propagate down; wiki pages must be recompiled when canonicals
    change.
 3. If a wiki page conflicts with SSOT, SSOT wins and the wiki page is rewritten.
-4. The RAG layer is fed both canonicals and wiki pages, but query verdicts
-   reveal **gaps** in the canonical layer, which become candidates for new
-   wiki syntheses (see § Auto-Learning Loop).
 
 ## Page Types
 
@@ -45,8 +41,8 @@ A complete overlay typically contains five page types:
 | **Reading Guide** | `${paths.wiki_dir}/reading-guides/` | Ordered paths into the corpus for specific tasks (onboarding, incident response) |
 | **Index** | `${paths.wiki_dir}/index.md` | Single navigation entry point listing the other pages |
 
-The `${paths.wiki_dir}/log.md` file is the **append-only event log** used by the
-auto-learning loop (see below).
+The `${paths.wiki_dir}/log.md` file is an **append-only event log** recording
+synthesis candidates and captures (see § Maintenance & Capture).
 
 ## Frontmatter Discipline (MANDATORY)
 
@@ -86,61 +82,10 @@ equivalent) before committing wiki edits.
 - The `wiki-curator` agent flags `WIKI_ANCHOR_BROKEN` on mismatch and fixes
   it in the same invocation when possible.
 
-## Auto-Learning Loop (the core idea)
+## Maintenance & Capture
 
-The overlay is not static. It feeds itself from agent activity, closing a loop
-that surfaces documentation gaps and turns them into stable pages.
-
-```
-        ┌──────────────┐
-        │ Agents query │
-        │ RAG / search │
-        └──────┬───────┘
-               │  (instrumented: every search_docs call tags the invoker)
-               ▼
-        ┌──────────────┐
-        │ Telemetry log│  (${paths.wiki_dir}/log.md — append-only)
-        └──────┬───────┘
-               │  (verdicts: useful | weak | empty | fallback_degraded)
-               ▼
-   ┌────────────────────────────┐
-   │ Nightly wiki-review job    │
-   │ runs `wiki-curator` agent  │
-   └──────┬─────────────────────┘
-          │  (proposes synthesis candidates from weak/empty verdicts)
-          ▼
-   ┌────────────────────────────┐
-   │ /capture skill writes      │
-   │ a new synthesis page after │
-   │ user approval              │
-   └──────┬─────────────────────┘
-          │
-          ▼
-        New wiki page → next RAG query gets a strong verdict.
-```
-
-### Tap points (instrumentation)
-
-Every agent that queries the RAG layer MUST pass an `invoker_agent` tag on its
-search calls, so telemetry attributes the query to the right agent. After each
-call, the agent inspects the telemetry verdict and — if it is `weak`, `empty`,
-or `fallback_degraded` — appends one entry to `${paths.wiki_dir}/log.md` via the
-project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
-
-```python
-from wiki_log import append_entry  # project-specific helper
-append_entry(
-  entry_type="query",
-  title=<query_short>,
-  agent=<invoker>,
-  context={"verdict": verdict, "top_score": top_score, "count": count},
-  refs=[],
-  outcome=verdict,
-)
-```
-
-**Graceful degrade**: if the helper fails or is missing, emit one stderr line
-and continue. Telemetry must never block real work.
+The overlay is maintained on two paths — a scheduled structural sweep and an
+on-demand capture from live conversations.
 
 ### Synthesis candidates (nightly review)
 
@@ -151,8 +96,12 @@ The `wiki-curator` agent, running on a schedule (typically nightly), scans:
   contract) → propose a synthesis page.
 - PRD-led multi-card epics (≥4 cards in same parent epic) → propose an
   overview synthesis.
-- RAG queries with `verdict=weak|empty` repeated ≥3 times in
-  `${paths.wiki_dir}/log.md` → the topic is a documentation gap, propose synthesis.
+- **(when `features.has_code_graph: true`)** Graphify's native
+  `${graph.output_dir}/GRAPH_REPORT.md` — **god nodes** (highest-degree core
+  abstractions), **communities** (Leiden clusters), and the auto-generated
+  **suggested questions** — cross-checked against existing synthesis pages.
+  A god node or community with no corresponding wiki page → propose a synthesis
+  (this is the auto-learning signal, replacing the removed RAG verdicts).
 
 Candidates are appended to `${paths.wiki_dir}/log.md` with
 `entry_type: synthesis_candidate` and a small payload (title, source refs,
@@ -175,12 +124,32 @@ disable with a kill-switch file (`touch .claude/capture-queue/.disabled`).
 The skill requires explicit user approval before writing. Acceptance and
 rejection are both logged.
 
-## Graph Community Synthesis (optional, advanced)
+### Auto-learning loop (Graphify-fed, when `has_code_graph: true`)
+
+The original RAG-fed loop (weak/empty search verdicts → gap → synthesis) was
+removed in v4.20.0. It is now **re-activated on the code graph** (v4.21.0): the
+gap signal is structural, not retrieval-telemetry, and entirely **offline**
+(no API cost).
+
+```
+graphify update .  (native, on commit via `graphify hook install`)
+        │
+        ▼
+graphify-out/GRAPH_REPORT.md  (god nodes · Leiden communities · suggested questions)
+        │   (cross-check vs ${paths.wiki_dir}/syntheses/*)
+        ▼
+wiki-curator / doc-graph-align  → propose synthesis for uncovered god nodes/communities
+        │
+        ▼
+/capture writes the page  → next graph review finds it covered
+```
 
-If the project's RAG layer ships a community-detection layer (e.g.
-Leiden/Louvain) on top of the entity graph, cluster summaries can be produced
-weekly and exposed via dedicated MCP tools. These cluster summaries are
-candidate inputs to `concept` pages.
+The graph never becomes canonical — synthesis pages still cite repo SSOT and the
+`canonicality: derived` contract holds. When `has_code_graph: false` or Graphify
+is absent, the loop is simply inactive and the overlay runs on the manual +
+ADR/PRD-scheduled paths above (no regression). Engine details:
+`docs/archive/rag-layer/rebind-to-graphify.md` and
+`framework/agents/code-graph-protocol.md`.
 
 ## Roles & Responsibilities
 
@@ -198,15 +167,10 @@ To install the LLM wiki overlay in a new project:
 1. Create `${paths.wiki_dir}/` with the five page-type folders and an `index.md`.
 2. Add the frontmatter validator (or adapt your existing one) to check
    wiki frontmatter compliance.
-3. Decide on a RAG layer (LightRAG, vector DB, or full-text). If using one,
-   instrument every `search_docs` call with `invoker_agent` and a `wiki_log`
-   append helper.
-4. Schedule the `wiki-curator` agent to run on a nightly cadence
+3. Schedule the `wiki-curator` agent to run on a nightly cadence
    (cron / Claude Code remote agent / GitHub Action).
-5. Enable the `/capture` skill for users and (optionally) the proactive hook.
-6. Add `${paths.wiki_dir}/log.md` as an append-only log file under version control,
-   with rotation rules if it grows large.
-7. Document the overlay in your repo README so contributors know it exists
+4. Enable the `/capture` skill for users and (optionally) the proactive hook.
+5. Document the overlay in your repo README so contributors know it exists
    and is non-canonical.
 
 ## Related

package/framework/docs/CODE-GRAPH-LAYER.md

@@ -0,0 +1,104 @@
+# Code Graph Layer (Graphify) — Operator Guide
+
+> Since v4.21.0. Opt-in, gated on `features.has_code_graph`. The **runtime**
+> protocol (when to use the graph vs LSP vs Grep) lives in
+> [`framework/agents/code-graph-protocol.md`](../agents/code-graph-protocol.md);
+> this document covers the *plumbing* — install, config, lifecycle, fallback.
+
+## 1. Why this exists
+
+After removing the (unused, costly) RAG engine in v4.20.0, BALDART needed a
+retrieval tier for **structural / relational** code questions — "what connects X
+to Y", blast-radius of a change, which modules cluster — that Grep and even LSP
+answer poorly. [Graphify](https://github.com/safishamsi/graphify) builds a code
+knowledge graph (tree-sitter, 28 languages, **local/offline**) with native Leiden
+community detection. The same graph also **re-activates the Karpathy LLM-wiki
+auto-learning loop**: its native `GRAPH_REPORT.md` (god nodes, communities,
+suggested questions) is the gap signal that feeds synthesis candidates.
+
+## 2. What BALDART adds vs what Graphify already ships
+
+Graphify is a complete tool on its own — it installs its **own** skill, an
+always-on pre-tool hook, a post-commit git hook, and an MCP server. BALDART does
+**not** reimplement any of that. It adds only:
+
+- **Gating + config** (`features.has_code_graph` + `graph:` block).
+- **Opt-in install** (`configure` interactive branch, `/graphify-bootstrap`, `doctor` backfill).
+- **A retrieval protocol** telling BALDART's own agents *when* the graph is the right tier.
+- **The wiki rebind** (wiki-curator / capture / `doc-graph-align` consume `GRAPH_REPORT.md`).
+- **Fallback discipline** (silent degrade to LSP→Grep→Git).
+
+Everything mutating is a thin wrapper over Graphify's native commands in
+[`src/utils/graphify-installer.js`](../../src/utils/graphify-installer.js).
+There is **no per-language adapter registry** (unlike LSP) — Graphify is one
+language-agnostic tool.
+
+## 3. The moving parts
+
+| Part | Where | Role |
+|------|-------|------|
+| Config flag + block | `framework/templates/baldart.config.template.yml` | `features.has_code_graph` + `graph.{output_dir,auto_rebuild_hook,register_mcp}` |
+| Installer wrapper | `src/utils/graphify-installer.js` | `detect/install/verify/buildGraph/installGitHook/installAlwaysOn/registerMcp/isStale` |
+| Configure | `src/commands/configure.js` | autodetect (binary on PATH) + prompt + interactive install/build/wire |
+| Update detector | `src/commands/update.js` | diffs the `graph:` block → offers `configure` (extended to diff nested top-level blocks) |
+| Doctor | `src/commands/doctor.js` | `Code graph` line + `graph-install` / `graph-rebuild` / `graph-hook` actions |
+| Retrieval protocol | `framework/agents/code-graph-protocol.md` | when to use the graph; budget; fallback |
+| Wiki rebind | `llm-wiki-methodology.md`, `wiki-curator.md`, `wiki-review.routine.yml`, `capture` | GRAPH_REPORT.md → synthesis candidates |
+| Nightly command | agent `doc-graph-aligner` + routine `doc-graph-align` + skill `/graph-align` | doc↔graph alignment |
+| Bootstrap skill | `/graphify-bootstrap` | explicit install path (CI-safe backfill) |
+
+## 4. Install lifecycle
+
+```
+features.has_code_graph: true
+        │
+        ├─ baldart configure (INTERACTIVE) ─→ pipx install graphifyy
+        │      → graphify update .          (build, offline)
+        │      → graphify <tool> install    (always-on per tools.enabled)
+        │      → graphify hook install       (auto-rebuild, if auto_rebuild_hook)
+        │      → claude mcp add … graphify-mcp (if register_mcp)
+        │
+        ├─ baldart configure --yes / CI ──→ writes the flag ONLY (no silent
+        │      Python install) → doctor backfills
+        │
+        ├─ /graphify-bootstrap ───────────→ the explicit, full install path
+        │
+        └─ baldart doctor ────────────────→ graph-install (binary missing)
+               graph-rebuild (stale: built_at_commit ≠ HEAD) · graph-hook (hook missing)
+```
+
+**CI behavior is deliberate**: a Python tool is never installed silently in
+`--yes`/non-interactive runs. The flag is written from autodetect; `doctor` and
+`/graphify-bootstrap` own the actual install.
+
+## 5. Native commands BALDART relies on (all offline, 0 API cost)
+
+| Purpose | Command |
+|---------|---------|
+| Build / refresh graph | `graphify update <root>` → `<root>/graphify-out/{graph.json, GRAPH_REPORT.md, graph.html}` |
+| Auto-rebuild on commit | `graphify hook install` (post-commit + graph.json union merge-driver) |
+| Always-on per tool | `graphify claude install` / `graphify codex install` / … |
+| Query (relational) | `graphify query "…"`, `graphify path "A" "B"`, `graphify explain "X"`, `graphify affected "X"` |
+| MCP server | `graphify-mcp [graph.json]` (stdio default; `--transport http` available) |
+| Staleness (cron-safe) | `graphify check-update <root>`, or compare `graph.json.built_at_commit` to `git rev-parse HEAD` |
+
+LLM API keys are needed **only** for `--wiki` / community naming (`graphify label`)
+/ URL & vision ingestion — all optional. The structural graph + report are free.
+
+## 6. Invariants
+
+- **The graph is never canonical.** Synthesis candidates it produces cite repo
+  SSOT and carry `canonicality: derived`.
+- **Silent fallback.** No task aborts because the graph is missing — degrade to
+  LSP→Grep→Git; surface setup gaps via `baldart doctor`, never mid-task.
+- **`graphify-out/` is generated** — must be in `.gitignore`, never versioned.
+- **No per-language registry.** Add nothing per language; Graphify handles 28 via
+  tree-sitter. The wrapper composes native commands, never reimplements them.
+- **Schema-change propagation** applies to `features.has_code_graph` + `graph.*`.
+
+## 7. Adding capability later
+
+The retrieval tier ships CLI-first; the MCP path is opt-in. To deepen the
+integration (e.g. wire `graphify-mcp` as a first-class MCP tool, or use `--wiki`
+community pages directly as wiki concept pages), extend `graphify-installer.js`
+and the protocol module — do not fork Graphify's native behavior.