baldart 4.19.0 → 4.21.0

package/framework/.claude/agents/wiki-curator.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-curator
-description: "Maintain the derived LLM wiki surface under ${paths.wiki_dir}/. Use when the team needs compiled concept pages, synthesis pages, dashboards, or reading guides that sit on top of canonical SSOT docs (and optionally an Obsidian vault + RAG layer) without becoming canonical themselves."
+description: "Maintain the derived LLM wiki surface under ${paths.wiki_dir}/. Use when the team needs compiled concept pages, synthesis pages, dashboards, or reading guides that sit on top of canonical SSOT docs (and optionally an Obsidian vault) without becoming canonical themselves."
 model: sonnet
 color: blue
 ---
@@ -18,7 +18,6 @@ Maintain the derived wiki overlay without weakening SSOT discipline.
 - Prefer compact synthesis over duplication.
 - Preserve explicit provenance and canonical references on every page.
 - Keep pages small enough to recompile quickly.
-- Mark wiki changes for the project's RAG layer (e.g. LightRAG) reindex after edits, if any.
 
 ## Rules
 
@@ -28,34 +27,6 @@ Maintain the derived wiki overlay without weakening SSOT discipline.
 4. If a wiki page conflicts with SSOT, the SSOT wins and the wiki must be rewritten.
 5. If a topic needs human vault visibility, coordinate with an external knowledge-sync agent (if the project ships one) after the derived repo page is stable.
 
-## RAG Instrumentation (tap point of the auto-learning loop)
-
-If the project ships a RAG/search layer with telemetry, every call you make to
-the project's `search_docs` (or equivalent) MUST pass an invoker tag so
-telemetry attributes wiki-curation queries to this agent. After each call,
-inspect the telemetry verdict: if it is `weak`, `empty`, or `fallback_degraded`,
-append one entry to a log file under your wiki overlay (typically
-`${paths.wiki_dir}/log.md`) via the project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
-
-Example call shape:
-
-```python
-from wiki_log import append_entry  # project-specific helper
-append_entry(entry_type="query", title=<query_short>, agent="wiki-curator",
-             context={"verdict": verdict, "top_score": top_score,
-                      "count": count},
-             refs=[], outcome=verdict)
-```
-
-This is the feedback loop the wiki overlay depends on: weak queries become
-candidates for new synthesis pages in the nightly wiki-review. If the project
-has no RAG layer or no telemetry, skip this section.
-
-**Graceful degrade (MANDATORY)**: if the log helper import fails, the module
-is missing, or `append_entry` raises for any reason, emit ONE stderr line
-`wiki_log unavailable: <reason>` and CONTINUE. Never abort curation work —
-observational telemetry failures must not block wiki page writes.
-
 ## Anchor Slug Validation
 
 For every wiki page you create or edit, validate internal anchor links against heading slugs:
@@ -71,9 +42,25 @@ During nightly wiki-review, scan recent ADRs and PRDs (last 14 days):
 
 - For ADRs with significant architectural impact (touches >3 modules, marked as architectural pivot, or under categories: provider swap / DB schema / auth / API contract) → propose a synthesis page candidate.
 - For PRD-led multi-card epics (≥4 cards in same parent epic) → propose an overview synthesis.
-- For RAG queries with `verdict=weak|empty` repeated ≥3 times in `${paths.wiki_dir}/log.md` → the topic is a documentation gap, propose synthesis.
 - Output candidates by appending to `${paths.wiki_dir}/log.md` with `entry_type: synthesis_candidate` and including: title, source refs, expected scope, agent who triggered.
 
+### Graph-fed candidates (Graphify — when `features.has_code_graph: true`)
+
+If the project has the code graph layer, read Graphify's native
+`${graph.output_dir}/GRAPH_REPORT.md` (default `graphify-out/GRAPH_REPORT.md`)
+and cross-check against existing pages under `${paths.wiki_dir}/syntheses/`:
+
+- **God nodes** (highest-degree core abstractions) with no synthesis/concept page
+  → propose one (these are the architecture's load-bearing pieces).
+- **Communities** (Leiden clusters) with no overview page → propose a cluster synthesis.
+- **Suggested questions** (auto-generated in the report) that no page answers →
+  candidate concept pages.
+
+This is the auto-learning gap signal (offline, replaces the removed RAG verdicts).
+The graph is **never canonical** — proposed pages must still cite repo SSOT and
+carry `canonicality: derived`. If Graphify is absent, skip this section silently.
+Provenance: cite the graph node/community id in the candidate payload.
+
 ## Frontmatter Discipline
 
 All wiki pages MUST have:
@@ -92,46 +79,6 @@ When invoked for a nightly wiki-review, also run the project's drift validators
 (typically `npm run validate:frontmatter`, `npm run audit:full-sweep`, or
 equivalent). Include any findings in your output's `unresolved drift` section.
 
-## Graph Community Synthesis (optional layer)
-
-If the project has a community-detection layer (e.g. Leiden/Louvain) on top of
-the RAG entity graph, clusters and their summaries are typically produced
-weekly (e.g. `python -m tools.<rag-impl>.graph_communities --rebuild`) and
-exposed via dedicated MCP tools alongside `search_docs`:
-
-- `search_synthesis(question, level="global")` — community-summary retrieval.
-  Use for **relational / cross-cutting** questions where the answer involves
-  multiple modules at once. Examples:
-  - "How does auth interact with `<feature-X>`?"
-  - "What touches the `<entity>` collection/table?"
-  - "Which areas share the `<shared-pattern>` (e.g. a theming/layout) pattern?"
-- `search_synthesis(question, level="local")` — entity-centric retrieval
-  (delegates to the existing `local` mode). Use for **specific lookups** —
-  "what is `<authWrapper>`?", "show me the `<DomainType>` type definition".
-- `search_docs(query, mode="drift")` (or the dedicated `search_drift` tool) —
-  the GraphRAG DRIFT pattern: first pick candidate communities via `global`,
-  then run a scoped `local` retrieval for each. Use when a question is both
-  cross-cutting AND you want concrete chunks (file/line evidence) back.
-
-Routing heuristic (apply in order):
-
-1. Specific identifier in the query (function name, file path, type
-   name) → `search_docs(mode="hybrid")` or `search_synthesis(level="local")`.
-2. Cross-cutting "how does X interact with Y?" / "what touches Z?" /
-   "which areas share pattern P?" → `search_synthesis(level="global")`.
-3. Cross-cutting **and** evidence-seeking → `search_docs(mode="drift")` or
-   `search_drift(...)`.
-4. When `level="global"` returns `verdict: weak` or `verdict: empty`, escalate
-   to `mode="drift"` before falling back to `mode="hybrid"`.
-
-Telemetry parity: pass `invoker_agent: "wiki-curator"` on every call; the
-existing `wiki_log` weak-verdict instrumentation applies unchanged.
-
-The community detector also appends `entry_type: graph_community_candidate`
-entries to `${paths.wiki_dir}/log.md` for newly-detected clusters (≥10 entities) that
-do not yet have a synthesis page. These are first-class candidates for the
-next nightly wiki-review.
-
 ## Output
 
 Return:
@@ -140,6 +87,4 @@ Return:
 - pages updated
 - source references used
 - unresolved drift (including any anchor slug or frontmatter issues)
-- synthesis candidates identified (including any from
-  `graph_community_candidate` log entries you acted on)
-- reindex follow-up
+- synthesis candidates identified

package/framework/.claude/commands/codexreview.md

@@ -137,7 +137,6 @@ Every Task tool invocation in this Step MUST include this exact block at the end
 ## Budget for this run
 - file_reads: <N>
 - bash_calls: <N>
-- search_docs: <N>
 - scope: <list of files passed by orchestrator (review_scope_files)>
 
 Respect this budget strictly. If approaching limits, summarize and emit findings on what you have rather than reading new files.
@@ -145,11 +144,11 @@ Respect this budget strictly. If approaching limits, summarize and emit findings
 
 Defaults per agent (override only if scope is unusually small/large):
 
-| Agent | file_reads | bash_calls | search_docs |
-|---|---|---|---|
-| `code-reviewer` | 15 | 25 | 5 |
-| `api-perf-cost-auditor` | 15 | 25 | 5 |
-| `doc-reviewer` | 20 | 25 | 8 |
+| Agent | file_reads | bash_calls |
+|---|---|---|
+| `code-reviewer` | 15 | 25 |
+| `api-perf-cost-auditor` | 15 | 25 |
+| `doc-reviewer` | 20 | 25 |
 
 Codex (agent #4, via Bash + companion script) does NOT receive this block — it manages its own context.
 

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

@@ -8,7 +8,7 @@ description: >
   Enforces a disciplined 5-phase debugging protocol that prevents blind guessing:
   (1) Reproduce & observe, (2) Enhanced logging if stuck, (3) Data-driven analysis,
   (4) Hypothesis & minimal fix, (5) Verify. Leverages Playwright MCP for browser capture,
-  codebase-architect for code path tracing, doc-rag for known patterns, git bisect for regressions.
+  codebase-architect for code path tracing, `rg` over docs for known patterns, git bisect for regressions.
 ---
 
 # /bug — Structured Bug Investigation
@@ -17,7 +17,7 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.references_dir`, `paths.wiki_dir` (Phase 0 doc-rag `rg` fallback target).
+**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.references_dir`, `paths.wiki_dir` (Phase 0 `rg` lookup target).
 **Gated by features:** `features.has_design_system` (when `true`, Phase 4's design-system reads become BLOCKING for UI-touching bugs).
 **Overlay:** loads `.baldart/overlays/bug.md` if present — project-specific debug entry points (e.g. SWR debug switches, env summary helpers, error-code modules). The base skill stays generic; project-specific code paths live in the overlay.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -39,7 +39,6 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 - `mcp__playwright__browser_*` (`browser_navigate`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`, `browser_evaluate`) — Phase 1 reproduction for **UI/Client** bugs. Without it the skill cannot capture deterministic state and Phase 1 degrades to "ask the user to reproduce manually and paste console logs". Phase 2's client-side `window.fetch` interception is impossible without `browser_evaluate`.
 
 **Optional** (the skill benefits if present, has a documented fallback):
-- `mcp__doc-rag__search_docs` — Phase 0 lookup for known patterns and error codes. Fallback: targeted `rg` over the project's error-code module (path listed in `.baldart/overlays/bug.md`) and `${paths.wiki_dir}/`.
 - `mcp__plugin_firebase_firebase__firestore_*` (or the project's DB MCP, when `stack.database.primary` is set) — Phase 1 inspection of runtime data state for **Data** bugs. Fallback: ask the user for a document export, or read the relevant code path and infer.
 - `codebase-architect` agent (always available, listed for completeness) — Phase 0 code-path mapping. Not an MCP per se but is treated as a required dependency by this skill.
 
@@ -64,10 +63,12 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
    When `features.has_lsp_layer: true` and the symptom names a concrete symbol
    (function/type/handler), `codebase-architect` will use LSP find-references /
    go-to-definition to locate the exact callsites instead of grepping. See
-   `framework/agents/code-search-protocol.md`.
-4. Search doc-rag for related patterns: `mcp__doc-rag__search_docs` with bug keywords
-   - always use `mode="hybrid"` (vector + knowledge graph) for richer context retrieval
-   - if results come from Obsidian, treat them as context only and verify runtime behavior against repo docs/code before fixing
+   `framework/agents/code-search-protocol.md`. When `features.has_code_graph: true`,
+   it can also trace blast-radius with `graphify affected "<symbol>"` (what breaks
+   if this changes) — see `framework/agents/code-graph-protocol.md`.
+4. Search for related patterns: `rg` over the project's error-code module (path
+   listed in `.baldart/overlays/bug.md`) and `${paths.wiki_dir}/` with bug keywords.
+   Verify any doc hit against repo docs/code before fixing.
 5. Check git history for recent changes in affected area:
    ```
    git log --oneline -20 --all -- <affected-files>
@@ -217,7 +218,7 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
 | Tool | When | Purpose |
 |------|------|---------|
 | `codebase-architect` agent | Phase 0 | Map affected code paths |
-| `mcp__doc-rag__search_docs` | Phase 0 | Search known patterns/errors (`hybrid` mode — vector + knowledge graph; if MCP available) |
+| `rg` over docs / error-code module | Phase 0 | Search known patterns/errors |
 | `mcp__playwright__browser_*` | Phase 1-5 | Navigate, screenshot, console, network |
 | Project DB MCP (if available) | Phase 1 | Inspect storage state (e.g. firestore/postgres tools) |
 | `git log/blame/bisect` | Phase 0, 3 | Find regression commits |

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

@@ -7,7 +7,7 @@ version: 0.1.0
 
 # /capture — Synthesis Capture Skill
 
-Turns a recent multi-turn synthesis (cross-document reasoning done by the assistant) into a durable **synthesis page** under `${paths.wiki_dir}/syntheses/<slug>.md`. Part of the LLM wiki auto-learning loop — weak RAG queries and recurring synthesis patterns feed back into stable wiki pages so future agents can retrieve consolidated context instead of re-deriving it every time.
+Turns a recent multi-turn synthesis (cross-document reasoning done by the assistant) into a durable **synthesis page** under `${paths.wiki_dir}/syntheses/<slug>.md`. Recurring cross-document reasoning is captured into stable wiki pages so future agents can retrieve consolidated context instead of re-deriving it every time.
 
 ## Project Context
 
@@ -100,25 +100,18 @@ reason.
 
 ### Step 5 — Write + log (accepted)
 
-If the project ships a wiki-log helper, call it with an `entry_type='capture'` entry referencing the new synthesis file and the source refs. The exact import path is listed in `.baldart/overlays/capture.md` (typically `tools/<rag-impl>/wiki_log.py`). If no helper exists, append a markdown bullet to `${paths.wiki_dir}/log.md` by hand. Example:
-
-```bash
-python3 -c "import sys; sys.path.insert(0, 'tools/<rag-impl>'); \
-  from wiki_log import append_entry; \
-  append_entry(entry_type='capture', title='<slug>', \
-    agent='capture-skill', \
-    context={'mode': '<manual|proactive>', 'confidence': '<low|medium|high>'}, \
-    refs=['${paths.wiki_dir}/syntheses/<slug>.md', '<source ref 1>', '<source ref 2>'], \
-    outcome='created')"
-```
+After writing the synthesis page, append a markdown bullet to
+`${paths.wiki_dir}/log.md` by hand recording the capture: the new synthesis file
+path, the source refs, the mode (manual/proactive), and `outcome=created`.
 
 If the synthesis was surfaced from the queue, delete (or move to
 `.processed/`) the candidate file after write.
 
 ### Step 6 — Rejection
 
-Log the rejection (same helper as Step 5 with `outcome='rejected'`). Also
-delete the candidate file from the queue so it does not resurface.
+Log the rejection (a markdown bullet in `${paths.wiki_dir}/log.md` with
+`outcome='rejected'`). Also delete the candidate file from the queue so it does
+not resurface.
 
 ## Notes
 
@@ -128,6 +121,11 @@ delete the candidate file from the queue so it does not resurface.
   See `.claude/capture-queue/.disabled.example`.
 - **Anti-spam**: the detection hook refuses to write when ≥10 unprocessed
   candidates already exist. See `.claude/hooks/capture-detect.sh`.
+- **Graph-fed candidates** (when `features.has_code_graph: true`): the nightly
+  `wiki-review` / `doc-graph-align` routines surface synthesis candidates from
+  Graphify's `GRAPH_REPORT.md` (god nodes / communities without a page). When
+  one is queued, `/capture` distils it into a synthesis page like any other
+  candidate. See `framework/agents/code-graph-protocol.md`.
 
 ## Related
 

package/framework/.claude/skills/context-primer/SKILL.md

@@ -16,7 +16,7 @@ Load structured, task-adaptive context about a topic into the conversation befor
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`, `paths.wiki_log`.
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`.
 **Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search AND the wiki-log instrumentation tap), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
 **Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -61,64 +61,50 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 Load context about: {keywords}
 Task type: {task_type}
 
-TOKEN BUDGET: stay under 15K tokens total. Prefer RAG over file reads.
+TOKEN BUDGET: stay under 15K tokens total. Prefer the canonical router + targeted reads over broad file scans.
 
-SEARCH STRATEGY — RAG-first, verify-only-if-needed:
+SEARCH STRATEGY — canonical-router-first, verify-only-if-needed:
 
-1. Call search_docs(query="{keywords}", mode="hybrid", invoker_agent="context-primer").
-   Pass invoker_agent="context-primer" — this OVERRIDES your own default
-   (codebase-architect) for every call you make on behalf of this skill,
-   so telemetry attributes the query to the initiating skill, not the subagent.
+1. Resolve the topic to its canonical source. Read `${paths.references_dir}/ssot-registry.md`
+   to route `{keywords}` to the owning reference doc / ADR, then read only the matched
+   section(s). If the topic is documentation-heavy and `features.has_wiki_overlay: true`,
+   also consult `${paths.wiki_dir}/index.md` and any must-include docs listed in
+   `.baldart/overlays/context-primer.md` (verify wiki claims against canonical docs).
 
-   NOTE: the search_docs MCP tool and its rag_telemetry.verdict field only
-   exist when a RAG/Obsidian doc-search layer is connected. If search_docs is
-   NOT available (no MCP tool), or it returns no rag_telemetry block, treat the
-   verdict as "empty" and go straight to the full manual search (steps 2-3) —
-   do NOT fabricate a verdict or stall waiting for a field that will never
-   appear. Emit no error; this is the normal no-RAG path.
-
-   When the field IS present, check rag_telemetry.verdict in the response:
-   - "useful" → RAG is your PRIMARY source. Go to step 4.
-   - "weak"/"fallback_degraded" → supplement with steps 2-3.
-   - "empty" → full manual search (steps 2-3).
-
-   If the topic is documentation-heavy and `features.has_wiki_overlay: true`,
-   include `${paths.wiki_dir}/index.md` and the project's wiki-overlay ADR
-   (in `${paths.adrs_dir}/`) in the search set, plus any must-include docs
-   listed in `.baldart/overlays/context-primer.md`.
-
-2. ONLY IF RAG was weak/empty — targeted searches:
+2. Targeted searches:
    a. Agent memory: grep MEMORY.md index for topic match, read ONLY
       matching files (skip files >20KB unless filename matches keywords).
    b. Backlog (when `features.has_backlog: true`): grep `${paths.backlog_dir}/*.yml` for card titles matching keywords.
       Read only the matching cards, not all cards.
    c. Git: `git log --oneline -10 --grep="{keywords}"` (10 results max).
 
-3. ONLY IF RAG was empty — broader search:
+3. Broader search (when steps 1-2 are thin):
    a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
       When `features.has_lsp_layer: true` AND the identifier is a symbol (function /
       type / class name, not a free-text phrase), prefer LSP `find-references` /
       `go-to-definition` over Grep — it filters textual collisions before any file
       read. Cap at 3 LSP calls, then fall back. See `framework/agents/code-search-protocol.md`.
+      When `features.has_code_graph: true` AND the question is structural/relational
+      (how X connects to Y, impact, clusters), prefer the Graphify code graph
+      (`graphify query`/`path`/`affected`) — see `framework/agents/code-graph-protocol.md`.
    b. Read key file headers (first 50 lines) to identify structure.
    DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
-   RAG already indexes them. Only read a specific doc section if RAG
-   pointed to it but the preview was insufficient.
+   route via the registry and read only the specific section you need.
 
 4. Targeted verification (ALL cases):
-   - Verify ONLY runtime-sensitive claims from Obsidian results (auth
-     patterns, API contracts, current schema) against actual code.
+   - Verify ONLY runtime-sensitive claims (auth patterns, API contracts,
+     current schema) against actual code.
    - Files <200 lines: read in full.
    - Files 200-500 lines: read first 50 lines + specific section.
    - Files >500 lines: grep for key exports/functions, read only those.
    - NEVER read agent memory files >20KB in full.
 
 TASK-ADAPTIVE RULES:
-- "query": RAG + memory only. Skip source code unless code-specific.
-- "bug-fix": RAG + recent git changes + error-related code. Skip arch docs.
-- "new-feature": RAG + patterns in same domain + ADRs. Skip unrelated areas.
-- "refactor": RAG + affected files + dependency refs. Skip design rationale.
-- "doc-update": RAG + SSOT registry. Skip source code.
+- "query": canonical docs + memory only. Skip source code unless code-specific.
+- "bug-fix": canonical docs + recent git changes + error-related code. Skip arch docs.
+- "new-feature": canonical docs + patterns in same domain + ADRs. Skip unrelated areas.
+- "refactor": canonical docs + affected files + dependency refs. Skip design rationale.
+- "doc-update": SSOT registry. Skip source code.
 
 WIKI OVERLAY ROUTING:
 - If the topic is about synthesized knowledge, dashboards, reading guides, or
@@ -150,45 +136,11 @@ Return output in this EXACT XML format (30-50 lines max):
     <note acquired="YYYY-MM-DD">Note content</note>
     <note acquired="YYYY-MM-DD" stale="true">Old note [STALE — verify]</note>
   </memory_notes>
-  <!-- If no RAG layer was available, set verdict="unavailable" count="0" mode="none" -->
-  <rag_quality verdict="{rag_telemetry.verdict}" count="{count}" mode="{mode}"/>
 </context_primer>
 
-WIKI LOG INSTRUMENTATION (FEAT-0805 — tap point of the auto-learning loop):
-This tap is GATED. Only attempt it when `features.has_wiki_overlay: true` AND
-`paths.wiki_log` is set in `baldart.config.yml` (it points at the project's
-wiki-log tap MODULE FILE, e.g. `tools/doc-rag/wiki_log.py` — there is no
-hardcoded `tools/doc-rag` default; that path is one consumer's layout and does
-not resolve elsewhere). If either is absent, SKIP the tap entirely and emit a
-single stderr WARNING
-"wiki_log skipped: features.has_wiki_overlay/paths.wiki_log not configured" —
-never silently no-op, and never assume a default path.
-
-When enabled: after every search_docs call, inspect the returned
-rag_telemetry.verdict. If verdict ∈ {"weak", "empty", "fallback_degraded"},
-log one entry to the wiki log so the nightly wiki-review can detect coverage
-gaps. Resolve `<wiki_log_dir>` as the PARENT DIRECTORY of `paths.wiki_log`
-(i.e. `dirname` — the importable package dir; `paths.wiki_log` itself is the
-`wiki_log.py` file):
-
-  python3 -c "import sys; sys.path.insert(0, '<wiki_log_dir>'); \
-    from wiki_log import append_entry; \
-    append_entry(entry_type='query', title='<query_short>', \
-      agent='context-primer', \
-      context={'verdict': '<verdict>', 'top_score': <top_score>, \
-               'count': <count>}, \
-      refs=[], outcome='<verdict>')"
-
-GRACEFUL DEGRADE (MANDATORY): if the import fails, the file is missing, or
-append_entry raises for any reason, emit a SINGLE line to stderr of the form
-"wiki_log unavailable: <reason>" and CONTINUE the primary task. NEVER abort,
-retry, or let the exception bubble. The loop is observational; its failure
-must never block orientation.
-
 CRITICAL OUTPUT RULES:
 - Constraints section MUST come FIRST (research: primacy effect +30%)
 - Keep total output under 50 lines — dense beats verbose
-- Include <rag_quality> tag so the caller can track RAG usefulness
 - Every memory_notes entry MUST have an acquired date
 - If a memory item file was modified >7 days ago AND refers to current
   state (not permanent decisions), mark it stale="true"

package/framework/.claude/skills/graph-align/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: graph-align
+effort: medium
+description: >
+  On-demand documentation alignment via the Graphify code knowledge graph.
+  Rebuilds the graph offline (graphify update .), then cross-checks graph
+  structure against the docs + wiki overlay to surface (1) core code (god nodes /
+  communities) with no doc coverage, (2) docs referencing code no longer in the
+  graph (stale), (3) drift vs the SSOT registry — emitting a report + synthesis
+  candidates. The interactive twin of the nightly doc-graph-align routine. Use
+  when the user says /graph-align, "allinea la documentazione", "doc graph align",
+  "check doc coverage", or wants an on-demand graph/doc reconciliation. Gated on
+  features.has_code_graph.
+---
+
+# /graph-align — Doc ↔ Code-Graph Alignment
+
+Reconcile documentation with the **real** code structure on demand. This is the
+manually-invoked twin of the nightly `doc-graph-align` routine; both delegate to
+the `doc-graph-aligner` agent. It does NOT duplicate Graphify's native `/graphify`
+query skill — it orchestrates a doc-alignment pass on top of the graph.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `features.has_code_graph`, `graph.output_dir`, `paths.wiki_dir`, `paths.references_dir`, `paths.docs_dir`.
+**Gated by features:** `features.has_code_graph` — refuses to run when the flag is `false` (point the user to `/graphify-bootstrap`).
+**Overlay:** loads `.baldart/overlays/graph-align.md` if present.
+**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth — detect once at kickoff, strip the token before consuming input.
+See `framework/agents/effort-protocol.md`.
+
+## Workflow
+
+1. **Refusal check.** If `features.has_code_graph: false`/missing, or `graphify`
+   is not installed:
+   ```
+   The code graph layer isn't set up. Run /graphify-bootstrap first.
+   ```
+   Stop. (If the flag is true but the binary is missing, suggest `baldart doctor`.)
+
+2. **Delegate to the agent.** Invoke the `doc-graph-aligner` agent (via Task tool,
+   `mode: "bypassPermissions"`). It refreshes the graph (`graphify update .`),
+   reads `${graph.output_dir}/GRAPH_REPORT.md`, and cross-checks graph → docs.
+
+3. **Surface results.** Present the agent's report: uncovered core code (proposed
+   synthesis candidates), stale docs (for `doc-reviewer`), registry drift. Offer
+   to act on the top candidates via `/capture` (synthesis pages) — never auto-write
+   canonical docs.
+
+## Output Contract
+
+A compact summary (not a multi-page dump), in `identity.language` (English
+default):
+
+```
+Graph align (graphify-out, built @ <commit>):
+  Uncovered core code: 3 god nodes / 1 community without a page → synthesis candidates queued
+  Stale docs: 2 references to deleted symbols (docs/references/foo.md) → doc-reviewer
+  Registry drift: 1 community with no ssot-registry entry
+Next: run /capture to distil the queued candidates; hand stale-doc findings to doc-reviewer.
+```
+
+## Notes
+
+- Offline / 0 API cost for the structural pass (graph + GRAPH_REPORT.md).
+- Propose, don't author: the skill never rewrites canonical SSOT or wiki pages
+  directly — it queues candidates and hands drift to `doc-reviewer`.
+- The graph is never canonical; candidates cite repo SSOT (`canonicality: derived`).
+
+## See Also
+
+- `framework/.claude/agents/doc-graph-aligner.md` — the agent this skill drives
+- `framework/routines/doc-graph-align.routine.yml` — the scheduled twin
+- `framework/agents/code-graph-protocol.md` — graph retrieval contract
+- `framework/agents/llm-wiki-methodology.md` — how the graph feeds the wiki

package/framework/.claude/skills/graphify-bootstrap/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: graphify-bootstrap
+effort: medium
+description: >
+  Install, verify, and wire the Graphify code-knowledge-graph layer for this
+  project. Installs the Graphify CLI (pipx install graphifyy), builds the graph
+  offline (graphify update .), installs the native post-commit auto-rebuild git
+  hook, wires Graphify's always-on mode into the enabled AI tools, and optionally
+  registers the graphify-mcp MCP server. Use when the user says /graphify-bootstrap,
+  "install graphify", "set up the code graph", or after enabling
+  features.has_code_graph for the first time. Idempotent — re-running re-verifies
+  and rebuilds a stale graph.
+---
+
+# Graphify Bootstrap
+
+Set up the code knowledge graph that lets agents answer **structural / relational**
+questions (what connects X to Y, blast-radius, clusters) and feeds the LLM-wiki
+overlay (Karpathy loop) from Graphify's native `GRAPH_REPORT.md`. This is the
+explicit install path — `baldart configure` only installs Graphify in its
+interactive branch, so this skill (and `baldart doctor`) cover CI / first-run.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `features.has_code_graph`, `graph.output_dir`, `graph.auto_rebuild_hook`, `graph.register_mcp`, `tools.enabled`.
+**Gated by features:** `features.has_code_graph` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
+**Overlay:** loads `.baldart/overlays/graphify-bootstrap.md` if present — project-specific build flags (e.g. `--mode deep`, a non-default output dir, an LLM backend for `--wiki`/community naming).
+**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+## What This Skill Does
+
+Graphify is a SINGLE language-agnostic tool (tree-sitter, 28 languages,
+local/offline) — there is no per-language step. This skill composes Graphify's
+own native commands via `src/utils/graphify-installer.js`:
+
+1. Confirms `features.has_code_graph: true`.
+2. Installs the CLI: `pipx install graphifyy` (fallback `pip install --user graphifyy`).
+   Provides binaries `graphify` + `graphify-mcp`.
+3. Builds the graph **offline** (no API cost): `graphify update .` →
+   `${graph.output_dir}/{graph.json, GRAPH_REPORT.md, graph.html}`.
+4. Wires Graphify's **always-on mode** into each tool in `tools.enabled`
+   (`graphify claude install`, `graphify codex install`, …) — writes a graph-first
+   section to the tool's instruction file + a pre-tool hook.
+5. Installs the native **post-commit git hook** (`graphify hook install`) when
+   `graph.auto_rebuild_hook: true`, so the graph never goes stale.
+6. Optionally registers the MCP server (`graph.register_mcp: true`) via
+   best-effort `claude mcp add graphify -- graphify-mcp <graph.json>`.
+7. Confirms `graphify-out/` is in `.gitignore` (generated artifact, never versioned).
+
+## Workflow
+
+1. **Refusal check.** If `features.has_code_graph: false` (or missing):
+   ```
+   This project hasn't opted in to the code graph layer yet.
+   Run `npx baldart configure` and answer YES to "Enable Graphify code-knowledge-graph layer?"
+   then re-run /graphify-bootstrap.
+   ```
+   Stop here. Do not proceed.
+
+2. **Probe + install.** Use the BALDART installer (internally
+   `src/utils/graphify-installer.js`):
+   ```
+   node -e 'const G=require("./.framework/src/utils/graphify-installer"); const g=new G(); if(!g.detect()){console.log(JSON.stringify(g.install()))} else {console.log(JSON.stringify(g.verify()))}'
+   ```
+   If install fails, print `pipx install graphifyy` for the user and stop with a
+   clear message (do not proceed to build).
+
+3. **Build the graph.** `graphify update .` (offline). For LLM-named communities /
+   wiki pages, `graphify label .` or `graphify update . --wiki` (needs an LLM key;
+   optional — skip silently if no key).
+
+4. **Wire always-on + hook.** Run `graphify <tool> install` for each enabled tool
+   and `graphify hook install` (when `auto_rebuild_hook`). Capture failures into a
+   "Skipped" bucket — never abort the whole skill on one failure.
+
+5. **Optional MCP.** When `graph.register_mcp: true` and the `claude` CLI is
+   present, register `graphify-mcp`; otherwise note the CLI path works without it.
+
+6. **Confirm `.gitignore`.** Ensure `graphify-out/` is ignored; add it if missing.
+
+7. **Output.** A compact one-line status block, in the project's
+   `identity.language` from `baldart.config.yml` (English default).
+
+## Output Contract
+
+A single short status block — never a multi-page report. Format:
+
+```
+Graphify bootstrap:
+  ✓ graphify 0.8.x installed (pipx) — binaries graphify + graphify-mcp
+  ✓ graph built — 571 nodes · 873 edges · 24 communities (graphify-out/, offline)
+  ✓ always-on wired: claude, codex
+  ✓ git hook installed (auto-rebuild on commit)
+  · MCP: CLI path active (register_mcp: false)
+  ✓ .gitignore covers graphify-out/
+Next: codebase-architect prefers the graph for structural queries; wiki-curator
+feeds synthesis candidates from GRAPH_REPORT.md. See code-graph-protocol.md.
+```
+
+## Notes
+
+- The structural graph is **offline / 0 API cost**. Only `--wiki` /
+  community-naming (`label`) need an LLM API key — both optional.
+- This skill never edits source code. Side effects: a Python package install,
+  the `graphify-out/` artifact, Graphify's own instruction-file sections + hooks,
+  and a `.gitignore` line.
+- Re-run safely. `graphify update .` is incremental; always-on / hook installs are
+  idempotent.
+- If the graph goes stale later (built from an older commit), `baldart doctor`
+  flags it and offers `graph-rebuild` — or the post-commit hook handles it.
+
+## See Also
+
+- `framework/agents/code-graph-protocol.md` — runtime retrieval + fallback rules
+- `framework/docs/CODE-GRAPH-LAYER.md` — lifecycle, schema, invariants
+- `src/utils/graphify-installer.js` — the native-command wrapper this skill drives
+- `src/commands/configure.js` — same install flow when first enabling the flag

package/framework/.claude/skills/issue-review/SKILL.md

@@ -25,7 +25,7 @@ If the user mentions `/issue-review` without a number, ask for the GitHub issue
 
 ### Phase 0 — Documentation Context
 
-Before triaging, use `search_docs` MCP tool (if available) with `mode: "hybrid"` to find related PRDs, ADRs, and reference docs for the issue's domain. The active retrieval layer is Obsidian-first LightRAG: use Obsidian for concept context, then verify implementation/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/`. Check `${paths.references_dir}/traceability-matrix.md` for source-to-doc mappings.
+Before triaging, route through `${paths.references_dir}/ssot-registry.md` and `rg` over `${paths.references_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/` to find related PRDs, ADRs, and reference docs for the issue's domain. Verify implementation/stateful claims against repo docs/code. Check `${paths.references_dir}/traceability-matrix.md` for source-to-doc mappings.
 
 ### Phase 1 — Triage
 

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

@@ -19,7 +19,7 @@ description: >
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; autodetected from `origin/HEAD` when the key is absent — see Phase 0 step 0), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer`.
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; autodetected from `origin/HEAD` when the key is absent — see Phase 0 step 0), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer` / `features.has_code_graph`.
 **Gated by features:** `features.has_backlog` (skill REFUSES to run when `false` — this orchestrator operates on backlog cards by definition).
 **Overlay:** loads `.baldart/overlays/new.md` if present — project-specific canonical-docs registry (e.g. ssot-registry, linking-protocol guides), tooling paths (e.g. validation scripts).
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.