baldart 4.18.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

@@ -39,7 +39,7 @@ message. You ask questions, wait for answers, and iterate.
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
 | 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
-| 2 | Discovery Question Loop | [discovery-phase.md](references/discovery-phase.md) |
+| 2 | Discovery Question Loop (+ Codex completeness cross-check at exit, v4.19.0) | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | the canonical **`prd-add` skill** ([../prd-add/SKILL.md](../prd-add/SKILL.md)) — worktree-aware (`references/prd-add-phase.md` is a redirect stub, not the implementation) |
 | 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
 | 3 | UI Design (3a-3d) | [ui-design-phase.md](references/ui-design-phase.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").
@@ -928,6 +927,81 @@ appendix or extended context, not for the signal table):
    If yes, launch in foreground and process. If no, mark skipped.
 4. **No research needed** → exit normally.
 
+**Before exiting, run the Discovery Completeness Cross-Check (Codex — since v4.19.0):**
+
+This is the **final, single cross-model sweep** of discovery, run ONLY once all the
+gates above pass (99% comprehension OR user-proceed, mockup gaps resolved, research
+resolved) and BEFORE flipping the status to `ui-design`. Its purpose is the one thing
+the 99% formula structurally cannot do: catch the questions that *should* have been
+asked but weren't. The formula measures coverage of the **predefined** dimensions; a
+different model reading the discovery transcript catches the **questioner's own blind
+spots** — latent ambiguities, missing NFRs, unhandled error/edge paths, data lifecycle,
+permission boundaries, integration touchpoints that no dimension modelled. Catching a
+requirements gap HERE (pre-design) is far cheaper than at the Step 6.6d plan audit
+(post-PRD, post-cards). [DESIGN-CHOICE: cross-model diversity has its highest marginal
+value against the blind spots of the model that conducted the interview]
+
+**Once-per-session guard (MUST — prevents a re-sweep loop).** The exit condition is
+re-evaluated every time the loop tries to exit; addressing a surfaced gap re-enters the
+question loop and then re-reaches this point. So FIRST: if the Discovery Log already
+contains a `discovery-completeness:` entry (from a prior pass this session), **skip this
+block entirely and proceed to exit** — the cross-check is run AT MOST ONCE per discovery
+session, never re-run after its gaps have been processed. Only if no such entry exists do
+you run the sweep below.
+
+**This check is NEVER a hard block** (unlike the mockup-gap check, which gates on physical
+screens). It surfaces gaps and lets the user decide; it never STOPs the exit on its own.
+
+```bash
+SESSION_ID="${SESSION_ID:-$(date +%s%N | md5sum | head -c8)}" && \
+CHECK_FILE="/tmp/codex-discovery-check-<slug>-${SESSION_ID}.md" && \
+CODEX_SCRIPT="$(ls -d ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)" && \
+[ -z "$CODEX_SCRIPT" ] && echo "CODEX_NOT_FOUND" && exit 1; \
+node "$CODEX_SCRIPT" task --wait "
+<task>
+Adversarial DISCOVERY-completeness review — a pre-design quality gate (review-only, DO NOT edit).
+Claude has just finished interviewing the user to scope a feature. Your job is to find the
+questions that SHOULD have been asked but were NOT, and the requirements that remain ambiguous —
+the blind spots of the interviewer. Default to skepticism; assume the interview missed something.
+
+Read the discovery state file below — it contains the dimensions, the answers, the Discovery Log,
+AND the original kickoff brief in its '## Kickoff' section (everything you need is in this one file):
+  ${STATE_FILE_PATH}
+</task>
+
+<attack_surface>
+- Unasked questions: a concern specific to THIS feature that none of the standard dimensions captured.
+- Latent ambiguity: an answer marked 'covered' that is actually vague, shallow, or under-specified.
+- Non-functional requirements never raised: performance budgets, scale/limits, concurrency, auth/permission boundaries, data retention/lifecycle, privacy/PII, observability.
+- Missing error/edge/failure paths (the interview only covered the happy path).
+- Integration touchpoints not discussed: external systems, webhooks, third-party APIs, downstream consumers.
+- Conflicting or unbounded requirements ('all', 'every', no limit) accepted without a boundary.
+</attack_surface>
+
+<grounding_rules>
+Every finding MUST quote the exact dimension/answer (or note its absence) from the state file.
+Do not invent gaps without evidence. Prefer a few strong, high-cost gaps over many weak ones.
+Suppress a finding when the strongest argument that it is already covered is convincing.
+</grounding_rules>
+
+<structured_output_contract>
+For each genuine gap, one line:
+- **Gap title** — what is missing/ambiguous. (Severity: HIGH/MEDIUM/LOW) [Target: <dimension or topic>]
+  > Evidence: exact state-file quote or 'no dimension covers X'
+  > Suggested question: the discovery question that closes it
+End with: 'COMPLETE — no material gaps' if the discovery is genuinely sufficient.
+</structured_output_contract>
+" 2>&1 | tee "$CHECK_FILE"
+```
+
+- `${STATE_FILE_PATH}` = `$WORKTREE_PATH/${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md` (the single artifact Codex reads — it already embeds the kickoff brief in its `## Kickoff` section, so no separate brief file is passed). **Timeout**: `timeout: 300000` (5 min).
+- **Present + process the findings (ONE pass):**
+  - **Presentation is ONE message** (an explicit, documented exception to HARD RULE 6's one-question-per-turn, exactly like the mockup-gap presentation): show the gaps as a single concise completeness summary, grouped by severity. This summary is a *report*, not a discovery question, so it does not violate the one-question rule.
+  - For each HIGH/MEDIUM gap the user chooses to address, it becomes the **next Discovery question** and follows the **normal per-iteration flow** — asked one-per-turn (HARD RULE 6), its answer folded into the state file, and run through the **Scope Expansion Check** like any other answer (so a gap whose answer reveals new scope routes to `/prd-add` exactly as a normal answer would — no special-casing, no double-trigger). Any gap the user declines → record in the Discovery Log as `"skipped — <reason>"`. LOW gaps are advisory: log them, never block.
+  - **Respect explicit user intent**: if the user reached this point by explicitly saying *proceed* / *basta domande* (the OR-branch of the 99% gate), keep the check **advisory-only** — present the one summary, default to recording every gap as `skipped — user proceeded`, and do NOT re-open the interrogation unless the user opts in. Do not turn an explicit "proceed" into a fresh question loop.
+  - **After processing (whatever the outcome), write ONE `discovery-completeness:` entry to the Discovery Log** (e.g. `discovery-completeness: 2 gaps asked, 1 skipped` / `COMPLETE — no material gaps`). This entry is the once-per-session guard above — its presence means the sweep has run and MUST NOT run again this session.
+- **Fallback (Codex unavailable — `$CHECK_FILE` empty, contains `CODEX_NOT_FOUND`, or holds no parseable findings)**: **skip the cross-check** and log `discovery-completeness: SKIPPED (Codex unavailable)` in the Discovery Log (this also satisfies the once-per-session guard). This gate is **additive** — the 99% formula + mockup + research gates already gate exit. Do NOT fall back to a same-model Claude pass: the entire value here is cross-model diversity, and Claude just conducted the interview (it carries the very blind spot this check exists to catch), so a Claude self-review adds little and is not worth the spawn. Proceed to exit.
+
 When loop exits: mark task 1 as `completed`. Update state file status to
 `ui-design` (or `specs-confirmed` if UI is N/A).
 

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