baldart 4.0.4 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-06-02
+
+**Portability: framework-wide path-literal de-contamination (`docs/…`, `backlog/`, `src/components/…` → `${paths.*}`) + new `paths.docs_dir` config key.** Closes the open follow-up forward-referenced in v4.0.3: a dedicated, per-occurrence judgment pass over the path-literals `contamination.js` flags across `framework/`. The scanner's `autofixable` count drops **219 → 49**; the 49 survivors are legitimate and intentionally kept. The new `paths.docs_dir` config key makes this **MINOR**.
+
+> **Why.** A hardcoded path in a shipped agent/skill is a frozen spot — a consumer whose docs live at `documentation/` (not `docs/`) gets a wrong directive. But not every literal is contamination: `${paths.*}` is resolved *at runtime* by the skill/agent that reads it, so a token only belongs where the file is an operative instruction. A literal correctly stays literal when it is a `# e.g.` config-default comment (converting is circular), a clickable markdown link (a token breaks the link), a concrete dated worked-example (`ADR-20260115-…` — the literal *is* the teaching), a negative instruction (`do not assume src/components/shared/`), or an overlay example (overlays are verbatim, never runtime-resolved). The judgment was made per-occurrence by a workflow (one judge per file → an adversarial bidirectional verifier) and applied deterministically through the `contamination.js` rule SSOT scoped to approved lines. The adversarial verifier also surfaced contamination the per-file judges missed — including the identity leak below.
+
+### Added
+
+- **`paths.docs_dir`** — umbrella docs-search root, used by the `rg`-fallback in `code-reviewer`, `senior-researcher`, and `worktree-manager` (where bare `docs/` had no config key). Propagated end-to-end per the schema-change rule: `baldart.config.template.yml` + `configure.js` (autodetection + prompt) + `project-context.md` autodetection table + `PROJECT-CONFIGURATION.md` key table. `update.js` detects it automatically via the generic `missingPaths` diff, so existing consumers are offered `configure` on their next update.
+
+### Changed — path-literals → `${paths.*}` across the framework payload (38 files changed, +162/−151)
+
+- **Agents** — `REGISTRY.md`, `codebase-architect`, `coder`, `doc-reviewer`, `prd`, `prd-card-writer`, `api-perf-cost-auditor`, `code-reviewer`, `plan-auditor`, `qa-sentinel`, `security-reviewer`, `senior-researcher`, `skill-improver`, `visual-designer`, `motion-expert`, `wiki-curator`, `hybrid-ml-architect`, `legal-counsel-gdpr`: operative read/write/search paths now resolve `${paths.design_system | references_dir | prd_dir | adrs_dir | wiki_dir | backlog_dir | components_* | docs_dir}`.
+- **Skills / commands** — `new`, `prd`, `bug`, `simplify`, `worktree-manager`, `check`, `codexreview`, `qa`, prd reference phases, and the prd asset templates (`card-template.yml`, `epic-template.yml`, `prd-template.md` — resolved by `prd-card-writer` at fill time).
+- **Routines** — `ds-drift`, `wiki-review`.
+- **`bug/SKILL.md`** — Project Context header now declares `paths.wiki_dir` (companion to the converted Phase-0 doc-rag fallback, keeping declared config deps in sync with the body).
+
+### Fixed
+
+- **Identity leak** — `prd-template.md` hardcoded `**Owner**: Antonio Baldassarre`, shipped into every consumer's PRD document; now the `{{Owner}}` placeholder.
+
+### Kept literal (intentional)
+
+- **`breaking-change-checklist.md`** — a human-read user-edit template (not agent-resolved), where a `${paths.*}` token would be inert text; left literal by design.
+- **Opt-out marker** (`<!-- contamination-scan: skip -->`) added to 3 wall-to-wall pedagogical files so the scanner stops re-flagging intentional teaching literals: `doc-writing-for-rag/references/line-count-targets.md`, `schemas-and-errors.md`, `templates/overlays/commands/codexreview.example.md`.
+- Config-default `# e.g.` comments (`baldart.config.template.yml`), worked examples, clickable links, and documented defaults across `design-system-init`, `prd/SKILL`, `design-review`, and others.
+
 ## [4.0.4] - 2026-06-02
 
 **Portability fix (visual identity): genericize the last fidelity-app visual-identity flavor in doc-RAG worked examples.** Confirms the graphic dimension is clean: `Neo-Brutalism` (plus the `Press Start 2P` font and `amber accents`) appeared as bare styling labels in the `doc-writing-for-rag` before/after examples — now generalized to "the project's design system (per `identity.design_philosophy`)". No behaviour change → **PATCH**.

package/VERSION

@@ -1 +1 @@
-4.0.4
+4.1.0

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

@@ -13,7 +13,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
-| **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `docs/wiki/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `docs/wiki/`, wiki lint, reindex follow-up |
+| **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `${paths.wiki_dir}/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `${paths.wiki_dir}/`, wiki lint, reindex follow-up |
 | **coder** | Code | Write, modify, or refactor production code | Features, bugs, optimizations | Yes | Build tools, testing, Playwright |
 | **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md`. NOT a visual-design evaluator (that is `ui-expert` / `visual-fidelity-verifier`). | No (review-only role — emits findings; fixes are applied by `coder`. The `bypassPermissions` tool-mode all agents run under is execution access, not an implementer role) | Static analysis, security audit |
 | **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |
@@ -226,7 +226,7 @@ Maps domains to their canonical SSOT docs and the agents that own maintenance, u
 
 | Domain         | Canonical SSOT Docs                                | Owner Agents                                              |
 | -------------- | -------------------------------------------------- | --------------------------------------------------------- |
-| design-system  | `docs/design-system/INDEX.md` (entry point)        | `ui-expert`, `visual-designer`, `motion-expert`, `doc-reviewer` |
-|                | `docs/design-system/tokens/semantic.tokens.json`   |                                                           |
-|                | `docs/design-system/components/*.md`               |                                                           |
-|                | `docs/references/ui-guidelines.md` (brand)         |                                                           |
+| design-system  | `${paths.design_system}/INDEX.md` (entry point)        | `ui-expert`, `visual-designer`, `motion-expert`, `doc-reviewer` |
+|                | `${paths.design_system}/tokens/semantic.tokens.json`   |                                                           |
+|                | `${paths.design_system}/components/*.md`               |                                                           |
+|                | `${paths.references_dir}/ui-guidelines.md` (brand)         |                                                           |

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

@@ -98,13 +98,13 @@ Your audit scope is STRICTLY limited to **changed files only** unless the orches
 
 ## First Read
 
-Use `search_docs` MCP with `mode: "hybrid"` to locate API and data-model references before reading files directly. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/references/`, `docs/decisions/`, and `backlog/`.
+Use `search_docs` MCP with `mode: "hybrid"` to locate API and data-model references before reading files directly. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.references_dir}/`, `${paths.adrs_dir}/`, and `${paths.backlog_dir}/`.
 
 Read when relevant:
 - `AGENTS.md` (NFR Performance section)
 - `agents/index.md`
-- `docs/references/api/index.md`
-- `docs/references/data-model.md`
+- `${paths.references_dir}/api/index.md`
+- `${paths.references_dir}/data-model.md`
 - `agents/architecture.md`
 - `agents/performance.md`
 - The project's index manifest for any new composite/multi-attribute query —
@@ -124,7 +124,7 @@ Every finding MUST include a confidence level:
 
 Before reporting any HIGH finding:
 1. Grep for the same pattern in the codebase — if used elsewhere consistently, may be a convention.
-2. Check ADRs in `docs/decisions/` that justify the pattern.
+2. Check ADRs in `${paths.adrs_dir}/` that justify the pattern.
 3. If <80% certain, classify as MEDIUM.
 
 **Never demote** (override conventions): unbounded/unindexed reads, offset pagination, N+1 read loops (e.g. `getDoc()` in a loop), missing required indexes, transaction hotspots on shared records, route handlers >50 reads. These remain HIGH regardless.

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

@@ -114,7 +114,7 @@ Every finding MUST include a confidence level:
 
 Before reporting any HIGH finding:
 1. **Grep the codebase** for the same pattern — if used elsewhere, it's likely intentional.
-2. **Check ADRs** in `docs/decisions/` that justify the pattern.
+2. **Check ADRs** in `${paths.adrs_dir}/` that justify the pattern.
 3. If <80% certain, classify as MEDIUM, not HIGH.
 
 **Never demote** (typical project-level invariants — adapt the list to your project's MEMORY.md / conventions): deprecated permission patterns, hardcoded design tokens, missing themed text/background pairing, unbounded database reads, missing auth guard on non-public routes, hardcoded status colors that should come from a registry, `getDoc()`-equivalent calls in loops, missing composite indexes for new queries, PII / stack traces leaked in error responses. These remain HIGH regardless.
@@ -213,7 +213,7 @@ If you spot a missing doc invariant, emit it as a `category: docs` finding for t
 
 When documentation is part of your evidence set, review with the retrieval layer:
 
-1. Run `search_docs` via MCP with `mode: "hybrid"` for doc-heavy questions. Active contract: Obsidian-first LightRAG with repo-first verification. If MCP unavailable, fall back to `rg` over `docs/`, `backlog/`, `.claude/`.
+1. Run `search_docs` via MCP with `mode: "hybrid"` for doc-heavy questions. Active contract: Obsidian-first LightRAG with repo-first verification. If MCP unavailable, fall back to `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, `.claude/`.
 2. Start from domain routers / canonical reference docs before large PRDs/specs.
 3. If a root canonical declares `max_safe_read_scope: root-summary-only`, treat it as router-first and descend into the linked child doc.
 4. Prefer canonical references over product-intent docs unless the question is about requirements.

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

@@ -27,14 +27,14 @@ Per the project's AGENTS.md MUST rules, all agents must invoke you (codebase-arc
 **Project-Specific Context:**
 
 This codebase follows strict protocols defined in AGENTS.md. Key architectural references you should consult:
-- `/docs/references/data-model.md` - Database schema and entity relationships
-- `/docs/references/ssot-registry.md` - Macro feature to canonical-doc routing
-- `/docs/wiki/` - Derived wiki overlay for synthesized navigation and summaries
-- `/docs/references/product-scope.md` - Product intent and scope boundaries
-- `/docs/references/api/` - API contracts and endpoints
-- `/docs/references/ui/index.md` - Frontend routing and page structure
-- `/docs/decisions/ADR-*.md` - Architectural Decision Records explaining why choices were made
-- `/docs/references/project-status.md` - Current system state and active work
+- `/${paths.references_dir}/data-model.md` - Database schema and entity relationships
+- `/${paths.references_dir}/ssot-registry.md` - Macro feature to canonical-doc routing
+- `/${paths.wiki_dir}/` - Derived wiki overlay for synthesized navigation and summaries
+- `/${paths.references_dir}/product-scope.md` - Product intent and scope boundaries
+- `/${paths.references_dir}/api/` - API contracts and endpoints
+- `/${paths.references_dir}/ui/index.md` - Frontend routing and page structure
+- `/${paths.adrs_dir}/ADR-*.md` - Architectural Decision Records explaining why choices were made
+- `/${paths.references_dir}/project-status.md` - Current system state and active work
 - `agents/coding-standards.md` - Terminology and coding conventions
 
 ## MCP dependencies
@@ -42,7 +42,7 @@ This codebase follows strict protocols defined in AGENTS.md. Key architectural r
 See [framework/docs/MCP-INTEGRATION.md](../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
 
 **Required** (this agent's primary investigation protocol assumes them; degraded operation only):
-- `mcp__doc-rag__search_docs` — semantic + knowledge-graph search across project docs. This is the **first** call in the Investigation Protocol; without it the agent falls back to broad `rg` sweeps that blow the token budget and miss canonical sources. If the MCP is unavailable the agent must announce the degrade explicitly and switch to targeted `rg` over `docs/`, `backlog/`, and `.claude/agents/` (see § Investigation Protocol step 1).
+- `mcp__doc-rag__search_docs` — semantic + knowledge-graph search across project docs. This is the **first** call in the Investigation Protocol; without it the agent falls back to broad `rg` sweeps that blow the token budget and miss canonical sources. If the MCP is unavailable the agent must announce the degrade explicitly and switch to targeted `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/agents/` (see § Investigation Protocol step 1).
 
 **Optional** (the agent benefits if present, has a documented fallback):
 - LSP find-references / go-to-definition (whichever LSP MCP / plugin is wired by [features.has_lsp_layer](../../templates/baldart.config.template.yml)) — preferred over `rg` for symbol queries (cap: 3 LSP calls per task, then escalate to direct file reads). Fallback: silent degrade to Grep, per [code-search-protocol.md](../../agents/code-search-protocol.md).
@@ -59,22 +59,22 @@ perform documentation maintenance; that belongs to `doc-reviewer`.
 When analyzing a feature, resolve documentation authority in this order:
 
 1. Backlog card `links.ssot`, `links.prd`, `links.spec` if present
-2. `docs/references/ssot-registry.md`
-3. `docs/references/product-scope.md`
+2. `${paths.references_dir}/ssot-registry.md`
+3. `${paths.references_dir}/product-scope.md`
 4. Relevant ADRs and domain reference docs in `docs/references/*`
 5. Parent/epic backlog cards if the canonical source is still ambiguous
-6. `docs/wiki/` derived pages when the question is about synthesis, recurring
+6. `${paths.wiki_dir}/` derived pages when the question is about synthesis, recurring
    documentation questions, or dashboard-style summaries
 
 **UI / design-system questions** follow a parallel resolution path (paths are
 project-specific; the convention below is recommended):
 
-1. `docs/design-system/INDEX.md` — agentic-first component index + authority matrix
-2. `docs/design-system/components/<Name>.md` — per-component spec (variants, props)
-3. `docs/design-system/tokens-reference.md` — token contract
-4. `docs/design-system/patterns/*` — theming, overlays, animations, platform quirks
-5. `docs/references/ui-guidelines.md` — brand philosophy and aesthetic rules
-6. `docs/references/component-registry.md` — inventory of shared components
+1. `${paths.design_system}/INDEX.md` — agentic-first component index + authority matrix
+2. `${paths.design_system}/components/<Name>.md` — per-component spec (variants, props)
+3. `${paths.design_system}/tokens-reference.md` — token contract
+4. `${paths.design_system}/patterns/*` — theming, overlays, animations, platform quirks
+5. `${paths.references_dir}/ui-guidelines.md` — brand philosophy and aesthetic rules
+6. `${paths.references_dir}/component-registry.md` — inventory of shared components
 
 When a query concerns UI, styling, tokens, or shared components, resolve through the
 design-system path in addition to the main path. Adapt the paths to your project's
@@ -106,7 +106,7 @@ When documentation is part of your evidence set, run a fast reliability scan bef
 trusting it as authoritative:
 
 1. **Registry coverage** — confirm the feature exists in
-   `docs/references/ssot-registry.md`; if the feature only exists in backlog/PRD, report
+   `${paths.references_dir}/ssot-registry.md`; if the feature only exists in backlog/PRD, report
    `REGISTRY_GAP`
 2. **Freshness markers** — compare `Last updated`, `Last reviewed`, or explicit change-log
    markers against `git log -1` on the shared hub or canonical doc you rely on
@@ -147,7 +147,7 @@ Before providing any architectural guidance or implementation advice, follow thi
    - `weak` or `fallback_degraded` → supplement with steps 2-3.
    - `empty` → fall back to full manual search (steps 2-3-4).
    If MCP is unavailable, fall back to targeted canonical docs plus `rg` over
-   `docs/`, `backlog/`, and `.claude/agents/`.
+   `docs/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
 
    **Wiki log instrumentation (auto-learning loop tap point — MONITORING
    SIGNAL, non-blocking):** After every `search_docs` call, if
@@ -204,8 +204,8 @@ As part of step 4, summarize:
 - any ambiguity, drift, or missing owner you found
 
 Derived wiki overlay routing:
-- Use `docs/wiki/` as a compression layer for recurrent knowledge questions.
-- Never treat `docs/wiki/` as canonical when a repo doc or ADR exists.
+- Use `${paths.wiki_dir}/` as a compression layer for recurrent knowledge questions.
+- Never treat `${paths.wiki_dir}/` as canonical when a repo doc or ADR exists.
 - If the wiki and canonical docs disagree, report the drift explicitly.
 
 ## Reuse Analysis Protocol (CONDITIONAL)
@@ -219,7 +219,7 @@ component discovery.
 1. **Identify what the feature needs**: List the UI components, hooks, utilities, API patterns, and data flows the feature will require.
 2. **Search for existing matches** — use RAG results first before grepping:
    - If RAG already returned component/hook matches, use those directly.
-   - Only if RAG missed: check `docs/references/component-registry.md` (read the
+   - Only if RAG missed: check `${paths.references_dir}/component-registry.md` (read the
      relevant table section only, not the full file).
    - Grep only for 2-3 specific component names, not broad semantic sweeps.
 3. **Classify each candidate**:
@@ -295,7 +295,7 @@ broad file reads — don't re-read what RAG already told you.
 - Permission system: use the project's canonical permission helper; flag deprecated fallbacks
 - API versioning: breaking changes require new version paths (e.g. `/api/v2/`)
 - Documentation sync: code and docs must stay aligned
-- Backlog-driven work: features are tracked in `/backlog/*.yml` files
+- Backlog-driven work: features are tracked in `${paths.backlog_dir}/*.yml` files
 
 **Communication Style:**
 

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

@@ -28,7 +28,7 @@ Violating this rule has caused repeated user frustration. Treat it as a blocking
 2. Verify a backlog card exists for this work.
 3. Update the card to `IN_PROGRESS`.
 4. Read the `git_strategy` recorded in the card for context only — it describes the eventual branch/PR plan but does NOT authorize branch operations. See the Hard Rule above.
-5. Treat `docs/references/project-status.md` as coordination context only.
+5. Treat `${paths.references_dir}/project-status.md` as coordination context only.
 
 ## Context Loading Protocol (MANDATORY — before writing any code)
 
@@ -48,15 +48,15 @@ Load context in this exact order before touching any file:
    - **`input_output_examples`**: Use as test fixtures and implementation guides for API handlers and data transformations.
    - **`error_handling`**: Implement each error handler exactly as specified. Do not invent alternative error handling.
    - **`reuse_analysis`**: If structured (has `reuse`/`create` keys), follow it. If free-form text (legacy `|` format), read and follow its guidance.
-8. **STEP 8 — MANDATORY Design System SSOT read (BLOCKING for any visual-output task)**: if your project has a documented design system, read its index (typically `docs/design-system/INDEX.md`) BEFORE ANY coding decisions. Skipping this step is a protocol violation when the design system exists.
+8. **STEP 8 — MANDATORY Design System SSOT read (BLOCKING for any visual-output task)**: if your project has a documented design system, read its index (typically `${paths.design_system}/INDEX.md`) BEFORE ANY coding decisions. Skipping this step is a protocol violation when the design system exists.
     1. Read the design-system index (component table + canonical authority matrix). BLOCKING prerequisite.
-    2. For each UI component being modified, read its per-component spec (typically `docs/design-system/components/<Name>.md`).
+    2. For each UI component being modified, read its per-component spec (typically `${paths.design_system}/components/<Name>.md`).
     3. Read relevant pattern docs for the pattern the change touches (overlays, theming, animations, platform-specific quirks).
     4. Check the tokens-reference doc for canonical token names before adding colors/shadows.
     5. If the change introduces a NEW reusable component: add a stub row to the design-system component index (coder invariant). The full doc body is doc-reviewer's responsibility.
     6. NEVER hardcode hex colors or shadow values — use the project's CSS custom properties / design tokens.
-    7. For themed backgrounds, follow the project's text-on-background pairing rules (typically documented in `docs/design-system/patterns/<theme>.md`).
-    8. For ANY chart / data-viz: follow the project's charting standard (typically `docs/design-system/patterns/charting.md`) and the approved chart library list. Exceptions require an ADR.
+    7. For themed backgrounds, follow the project's text-on-background pairing rules (typically documented in `${paths.design_system}/patterns/<theme>.md`).
+    8. For ANY chart / data-viz: follow the project's charting standard (typically `${paths.design_system}/patterns/charting.md`) and the approved chart library list. Exceptions require an ADR.
 
 ## Conditional Requirements — Binary-Outcome Items (MUST)
 
@@ -81,7 +81,7 @@ Never skip a conditional requirement or mark it `done` without evidence of one o
 When implementation depends on documentation, consume the retrieval layer before broad scans:
 
 1. Run `search_docs` via MCP with `mode: "hybrid"` when the task is doc-heavy. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable,
-   fall back to targeted canonical docs plus `rg` over `docs/`, `backlog/`, and `.claude/`.
+   fall back to targeted canonical docs plus `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`.
 2. Start from the highest-ranked domain router or canonical result.
 3. If a doc advertises `max_safe_read_scope: root-summary-only`, treat it as a router-first
    canonical: read the root summary, then jump to the linked child doc.

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

@@ -8,7 +8,7 @@ color: green
 
 **Reference material (OPTIONAL — graceful degradation).** Extended reference material *may* live in a `doc-reviewer-support` skill (`.claude/skills/doc-reviewer-support/references/…`). That skill is NOT shipped with the framework — it is an optional, project-installed extension. Throughout this prompt, every "for details, read `doc-reviewer-support/…`" pointer means: **if the file exists, read it for the fuller protocol; if it is absent, proceed with the minimal inline rules given here and do NOT halt.** Never block a review on a missing `doc-reviewer-support` file.
 
-**Writing Protocol (NEW docs or major rewrites)**: When creating/rewriting files under `docs/references/`, `docs/prd/`, or `docs/specs/`, **load the `doc-writing-for-rag` skill** for the validated compact protocol: endpoint template, schemas.md/errors.md cross-references, minimal 4-field frontmatter, line-count targets (API ref <1500, PRD <1500, ADR <200). This protocol was validated on 45 files with -48% line reduction while preserving all semantic content.
+**Writing Protocol (NEW docs or major rewrites)**: When creating/rewriting files under `docs/references/`, `${paths.prd_dir}/`, or `docs/specs/`, **load the `doc-writing-for-rag` skill** for the validated compact protocol: endpoint template, schemas.md/errors.md cross-references, minimal 4-field frontmatter, line-count targets (API ref <1500, PRD <1500, ADR <200). This protocol was validated on 45 files with -48% line reduction while preserving all semantic content.
 
 You are Documentation Reviewer. You own documentation completeness and drift control. Every reader is an AI agent, so optimize for scan-ability, precise links, and low-token retrieval.
 
@@ -39,15 +39,15 @@ For cards exceeding 3 files or triggering invariants, use the full Required Deli
 ## Parallel Safety (MUST)
 
 When running in parallel with other agents (code-reviewer, security-reviewer):
-- NEVER edit backlog YAML files (`.yml` in `/backlog/`). Report needed changes and let the orchestrator apply them.
+- NEVER edit backlog YAML files (`.yml` in `${paths.backlog_dir}/`). Report needed changes and let the orchestrator apply them.
 - You MAY edit files under `docs/` directly -- that is your domain.
-- You MAY edit `docs/references/ssot-registry.md` -- that is your responsibility.
-- You MAY edit `docs/design-system/**` -- this is part of your documentation domain.
-- **ssot-registry/backlog co-staging:** a pre-commit doc-freshness hook may require that any commit touching `backlog/*.yml` ALSO stages `ssot-registry.md`. You write the `ssot-registry.md` update in your own pass, but you do NOT control when the backlog card is flipped to DONE (that is a later orchestrator phase). If your `ssot-registry.md` edit and the card's DONE flip could land in separate commits, explicitly note in your report: "ssot-registry updated for `<CARD-ID>`; orchestrator must stage it together with the backlog DONE flip." Do not stage or commit anything yourself.
+- You MAY edit `${paths.references_dir}/ssot-registry.md` -- that is your responsibility.
+- You MAY edit `${paths.design_system}/**` -- this is part of your documentation domain.
+- **ssot-registry/backlog co-staging:** a pre-commit doc-freshness hook may require that any commit touching `${paths.backlog_dir}/*.yml` ALSO stages `ssot-registry.md`. You write the `ssot-registry.md` update in your own pass, but you do NOT control when the backlog card is flipped to DONE (that is a later orchestrator phase). If your `ssot-registry.md` edit and the card's DONE flip could land in separate commits, explicitly note in your report: "ssot-registry updated for `<CARD-ID>`; orchestrator must stage it together with the backlog DONE flip." Do not stage or commit anything yourself.
 
 ## Design System Scope (MUST — when the project has a design system)
 
-If your project ships a design-system SSOT (typically under `docs/design-system/**`
+If your project ships a design-system SSOT (typically under `${paths.design_system}/**`
 with INDEX, per-component docs, tokens reference, pattern docs), include it in your
 documentation scope. Standard drift checks against this corpus:
 
@@ -142,7 +142,7 @@ the flags above.
 
 ## Linking Protocol (quick reference)
 - Resolution order: SSOT registry -> backlog links -> parent/epic -> file paths -> standalone PRD/spec.
-- Authority within feature: SSOT -> ADR -> reference docs -> backlog/status.
+- Authority within feature: SSOT -> ADR -> reference docs -> ${paths.backlog_dir}/status.
 - Non-duplication: one owner per fact, pointers elsewhere.
 - For full protocol (normalization, drift handling, link compatibility), read `.claude/skills/doc-reviewer-support/references/linking-protocol.md` **if it exists**; otherwise apply the resolution order, authority order, and non-duplication rules above.
 
@@ -157,18 +157,18 @@ the flags above.
 Every invocation MUST begin here.
 
 1. Extract card ID, feature name, and changed paths from prompt/context.
-2. Read `docs/references/ssot-registry.md` and match in this order:
+2. Read `${paths.references_dir}/ssot-registry.md` and match in this order:
    - card ID prefix
    - valid `links.masterplan|ssot|prd|spec`
    - parent/epic linkage
    - changed file paths
    - keyword match
 3. If no macro-feature match exists:
-   - look for a standalone PRD in `docs/prd/FEAT-XXXX-*.md`
+   - look for a standalone PRD in `${paths.prd_dir}/FEAT-XXXX-*.md`
    - else look in `docs/specs/`
    - else mark `MACRO_FEATURE: standalone / no SSOT`
 4. Log: Feature, Card, SSOT path(s), Reference docs to check.
-5. If a new macro feature is discovered, add it to `docs/references/ssot-registry.md` before proceeding.
+5. If a new macro feature is discovered, add it to `${paths.references_dir}/ssot-registry.md` before proceeding.
 6. If a feature has real PRD/spec/backlog artifacts but no registry entry, mark `REGISTRY_GAP` and either add the missing entry or record explicit `standalone / no SSOT` status.
 
 ---
@@ -190,7 +190,7 @@ When a SSOT exists, update it before any derived doc.
 When invoked after development or bug-fix work:
 
 1. Scan: `qa/<CARD-ID>*.md`, backlog notes, prompt context, recent git history for `fix|bug|hotfix`.
-2. For each issue, map doc impact: API -> `docs/references/api/`, data model -> `data-model.md` or `collections/`, UI -> `docs/references/ui/`, defaults/config -> SSOT, invalid ADR assumption -> ADR addendum.
+2. For each issue, map doc impact: API -> `${paths.references_dir}/api/`, data model -> `data-model.md` or `collections/`, UI -> `${paths.references_dir}/ui/`, defaults/config -> SSOT, invalid ADR assumption -> ADR addendum.
 3. If a future doc update is blocked on a code fix, create a `[DOC-DEBT]` task.
 4. Report doc debt explicitly. If none exists, say so.
 5. When invoked after the fix lands, apply the update, close the doc-debt task, refresh the SSOT.
@@ -259,7 +259,7 @@ Key points:
 
 When reviewing a diff, check for environment variable changes:
 
-- **New `process.env.VAR` added** (not in `docs/references/env-vars.md`): add a row to the appropriate domain section. Required fields: Name, Scope, Required, Deployment envs, Default, Feature/Card, Status=active, Note.
+- **New `process.env.VAR` added** (not in `${paths.references_dir}/env-vars.md`): add a row to the appropriate domain section. Required fields: Name, Scope, Required, Deployment envs, Default, Feature/Card, Status=active, Note.
 - **Last usage of `process.env.VAR` removed**: move row to `## Deprecated / Legacy` section with date in Note column.
 - **Default value changed** in `src/lib/env.ts`: update Default column in env-vars.md.
 - **Card has `env_vars` field**: verify every entry is tracked in env-vars.md.
@@ -284,12 +284,12 @@ When invoked for **nightly audit**, **weekly full-sweep**, or **before declaring
 
 | Script | Detects | Exit on drift |
 |---|---|---|
-| `npm run validate:errors` | API error codes used in code but missing in `docs/references/errors.md` | 1 if ≥1% missing |
+| `npm run validate:errors` | API error codes used in code but missing in `${paths.references_dir}/errors.md` | 1 if ≥1% missing |
 | `npm run validate:perms` | Permission strings used in code but not defined in the project's permissions constants (e.g. `src/lib/permissions/constants.ts`) | 1 if any (security gap) |
-| `npm run validate:env` | `process.env.*` references not in `docs/references/env-vars.md` | 0 (advisory) |
+| `npm run validate:env` | `process.env.*` references not in `${paths.references_dir}/env-vars.md` | 0 (advisory) |
 | `npm run validate:frontmatter` | Missing required frontmatter fields (esp. ADR `status:`) | 1 if ADR missing status |
 | `npm run validate:imports` | Banned chart libs imported outside allowlist | 1 if any |
-| `npm run doctest` | Runnable `js` examples in `docs/references/api/**`, `permissions.md`, `frontmatter-standard.md` that throw at execution (added W1.1 / 2026-05-17) | 1 if any block fails. 0 if zero `js` blocks (placeholder state). |
+| `npm run doctest` | Runnable `js` examples in `${paths.references_dir}/api/**`, `permissions.md`, `frontmatter-standard.md` that throw at execution (added W1.1 / 2026-05-17) | 1 if any block fails. 0 if zero `js` blocks (placeholder state). |
 | `npm run regenerate:field-registry` | Field-registry drift vs current TS types | 0 (rewrites in place) |
 | `npm run audit:full-sweep` | Weekly: aggregates all above + history delta | 0 always |
 
@@ -441,7 +441,7 @@ symbols, well under the per-validator 5-minute timeout).
 ## Schema Field-Level Drift Detection (added 2026-05-17)
 
 Beyond route existence, also check schema diffs:
-- When a route's request/response schema (zod or TS types) changes, compare to `docs/references/api/<domain>.md` and `api/schemas.md`. Flag `SCHEMA_DRIFT` if diverged.
+- When a route's request/response schema (zod or TS types) changes, compare to `${paths.references_dir}/api/<domain>.md` and `api/schemas.md`. Flag `SCHEMA_DRIFT` if diverged.
 - For new fields in a documented payload: NEEDS_UPDATE.
 - For removed fields still in doc: ORPHAN_FIELD.
 

package/framework/.claude/agents/hybrid-ml-architect.md

@@ -267,7 +267,7 @@ Deliverable Format:
 ## AGENTS.md COMPLIANCE
 
 - You MUST invoke `codebase-architect` agent (via Task tool) before planning or implementing changes to understand existing system structure.
-- You MUST update `docs/references/project-status.md` Active Code Context before work.
+- You MUST update `${paths.references_dir}/project-status.md` Active Code Context before work.
 - You MUST pick a backlog card (TODO/READY), set IN_PROGRESS, and assign yourself before work.
 - You MUST keep docs and code in sync — code change without doc update is invalid.
 - You MUST use commit format `[FEAT-XXX] Brief description`.

package/framework/.claude/agents/legal-counsel-gdpr.md

@@ -172,7 +172,7 @@ When first invoked on a project, before doing anything else:
 
 You MUST follow all rules in AGENTS.md, including:
 - Invoke `codebase-architect` agent (via Task tool) before planning or implementing changes to understand existing patterns
-- Update `docs/references/project-status.md` Active Code Context before work
+- Update `${paths.references_dir}/project-status.md` Active Code Context before work
 - Pick a backlog card, set IN_PROGRESS, and assign yourself before work
 - Keep docs and code in sync
 - Use commit format `[FEAT-XXX] Brief description`

package/framework/.claude/agents/motion-expert.md

@@ -9,7 +9,7 @@ You are an elite Motion & Interaction Designer. You possess deep expertise in pu
 
 ## Authoritative Style Reference
 
-**MUST read `docs/references/ui-guidelines.md` before any motion design work.** This is the single source of truth for ALL visual and interaction standards: interaction states, animation guidelines, reduced motion rules, component patterns with their hover/active/focus states, and the overall design aesthetic.
+**MUST read `${paths.references_dir}/ui-guidelines.md` before any motion design work.** This is the single source of truth for ALL visual and interaction standards: interaction states, animation guidelines, reduced motion rules, component patterns with their hover/active/focus states, and the overall design aesthetic.
 
 **Never hard-code style rules in your reasoning.** Always derive motion decisions (easing, duration, shadow shifts, transform values) from the guidelines document. If the guidelines don't cover a motion case, flag it and propose an addition.
 
@@ -19,7 +19,7 @@ You design motion that is bold, intentional, and direct. Every animation you spe
 
 ## Motion Design Principles
 
-Your motion specifications must align with the interaction states and animation rules defined in `docs/references/ui-guidelines.md`. Key principles:
+Your motion specifications must align with the interaction states and animation rules defined in `${paths.references_dir}/ui-guidelines.md`. Key principles:
 
 - **Sharp, snappy transitions** — no lazy drifting
 - **Bold, decisive movement** with clear start/end states
@@ -85,7 +85,7 @@ Structure your responses as:
 2. **No copywriting**: You do not write UI text or labels
 3. **No code unless explicitly requested**: Provide specs, not implementation (unless asked)
 4. **Motion must have UX purpose**: Every animation must answer "Why does this move?"
-5. **Guidelines compliance**: All specs must be verifiable against `docs/references/ui-guidelines.md`
+5. **Guidelines compliance**: All specs must be verifiable against `${paths.references_dir}/ui-guidelines.md`
 
 ## Quality Checks
 

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

@@ -122,7 +122,7 @@ This converts memory from "loaded but unused" to "actively retrieved per audit".
 
 When the plan depends on repository documentation, consume the retrieval layer before auditing:
 
-1. Run `search_docs` via MCP with `mode: "hybrid"` for documentation-heavy plan sections. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/`, `backlog/`, and `.claude/`.
+1. Run `search_docs` via MCP with `mode: "hybrid"` for documentation-heavy plan sections. The active retrieval contract is Obsidian-first LightRAG with repo-first verification for implementation and stateful claims. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/`, `${paths.backlog_dir}/`, and `.claude/`.
 2. Start from the highest-ranked domain router or canonical result.
 3. Treat hubs/index docs as navigation, not final truth owners, unless the metadata says they are the canonical target.
 4. If a root canonical advertises `max_safe_read_scope: root-summary-only`, read the summary and then descend into the linked child doc instead of full-reading the root.
@@ -192,7 +192,7 @@ If ranking is weak but metadata clearly points to the right canonical, flag retr
 - Versioning strategy (APIs/events) — breaking changes require `/api/v2/` with RFC 8594 deprecation headers
 
 ### G) Traceability & Documentation Coverage
-- Verify `files_likely_touched` against `docs/references/traceability-matrix.md` — flag gaps where code changes don't list corresponding doc updates.
+- Verify `files_likely_touched` against `${paths.references_dir}/traceability-matrix.md` — flag gaps where code changes don't list corresponding doc updates.
 
 ### H) Verification Quality (Card-Level)
 - **Verification evidence**: Do card requirements cite specific line numbers, field names, or type signatures from a Verification Report? If requirements contain no code-level references → BLOCK — Phase 3.5 was not executed or was ignored.
@@ -216,7 +216,7 @@ AGENTS.md mandates ADRs for these triggers. The plan-auditor MUST scan the plan
 | Multi-feature data model change | Same field touched by 2+ cards in this batch |
 
 For each detected trigger:
-- If plan references existing ADR → verify the ADR exists in `docs/decisions/` and is not superseded.
+- If plan references existing ADR → verify the ADR exists in `${paths.adrs_dir}/` and is not superseded.
 - If plan proposes new ADR → verify ADR file is created or scheduled in plan steps.
 - If neither → emit `[Target: notes]` HIGH finding `adr_required_missing`.
 
@@ -224,7 +224,7 @@ For each detected trigger:
 
 Per AGENTS.md: "MUST NOT work on files/components already claimed by another in-progress agent."
 
-1. Read `docs/references/project-status.md` § Active Code Context.
+1. Read `${paths.references_dir}/project-status.md` § Active Code Context.
 2. Extract `claimed_paths` from any IN_PROGRESS card listed.
 3. Intersect with the plan's `files_likely_touched`.
 4. If overlap exists → emit BLOCK finding `claimed_path_collision` with the conflicting card ID.

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

@@ -79,7 +79,7 @@ You receive:
 3. The **card template** at `.claude/skills/prd/assets/card-template.yml`
 
 You produce:
-- N atomic YAML card files in `backlog/`
+- N atomic YAML card files in `${paths.backlog_dir}/`
 - Traceability matrices (FR/NFR, ISA, UI) appended to the state file
 - Parallel execution metadata on the epic parent card
 - A Parallel Execution Map summary returned to the caller
@@ -89,8 +89,8 @@ You produce:
 1. **Read the PRD** in full — all 15 sections. Extract: FR/NFR list, user stories, data model, API contracts, UI specs, acceptance criteria, edge cases, test plan, ISA map, UI Element Inventory.
 2. **Read the state file** — comprehension checklist, research findings, confirmed specs, UI design notes.
 3. **Read the card template** — `.claude/skills/prd/assets/card-template.yml`.
-4. **Scan existing backlog** — `backlog/*.yml` to find the highest `FEAT-XXXX` number. Use Glob to list files, then Grep for `^id:` lines to extract IDs.
-5. **Read existing card conventions** — sample 2-3 recent cards from `backlog/` to match style.
+4. **Scan existing backlog** — `${paths.backlog_dir}/*.yml` to find the highest `FEAT-XXXX` number. Use Glob to list files, then Grep for `^id:` lines to extract IDs.
+5. **Read existing card conventions** — sample 2-3 recent cards from `${paths.backlog_dir}/` to match style.
 6. **Reuse the `/prd` session's codebase-architect findings (MANDATORY when forwarded).** Per AGENTS.md, codebase understanding flows through `codebase-architect`. The `/prd` skill invokes it during discovery; when the caller forwards those findings (architecture summary, reuse analysis, `existing_patterns` file:line anchors) in your prompt, treat them as the PRIMARY source for `existing_patterns` / `reuse_analysis` and only run your own targeted Grep to VERIFY a specific anchor — do not re-explore from scratch and diverge from what the session already discovered. If no findings are forwarded, perform the targeted Grep/Glob yourself (as the field instructions below describe) and note in your output that no codebase-architect handoff was available.
 
 ## Agent Specialization Rules (HARD RULE — zero tolerance)
@@ -227,7 +227,7 @@ applies even when N=1.
 
 ### Epic card (always exactly 1)
 
-- **Filename**: `backlog/FEAT-XXXX-00-<slug>-epic.yml` (suffix `-epic` mandatory).
+- **Filename**: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` (suffix `-epic` mandatory).
 - **Role**: tracker only — NO implementation work, NO acceptance criteria for code,
   NO `files_likely_touched` for code modifications.
 - **Required fields**:
@@ -251,7 +251,7 @@ applies even when N=1.
 
 ### Child cards (always N >= 1)
 
-- **Filename**: `backlog/FEAT-XXXX-NN-<sub-slug>.yml` where `NN` is zero-padded
+- **Filename**: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` where `NN` is zero-padded
   (`01`, `02`, ..., `11`, ...) and `<sub-slug>` describes the sub-feature
   (e.g. `data-model`, `category-api`, `customer-ui`).
 - **Required fields** (in addition to the standard template fields):
@@ -263,13 +263,13 @@ applies even when N=1.
 
 ### FEAT-XXXX numbering
 
-- Pick the next free `FEAT-XXXX` integer (Grep `^id: FEAT-` in `backlog/`, find max,
+- Pick the next free `FEAT-XXXX` integer (Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
   add 1). **Reserve the entire integer for this epic** — do NOT reuse the integer
   for unrelated cards even if it has fewer than ~99 children.
 - **Scan the canonical backlog, not just the worktree branch.** The worktree
   branched from the trunk may not contain IDs committed on sibling branches not
   yet merged. Before computing max, run
-  `git fetch <git.trunk_branch>` and grep `backlog/` on the merge-base of the
+  `git fetch <git.trunk_branch>` and grep `${paths.backlog_dir}/` on the merge-base of the
   trunk (`git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)` plus
   the local worktree) so concurrent PRD sessions don't both land on the same
   "next free" integer. If a `git fetch` is not possible (offline), state the
@@ -313,7 +313,7 @@ Mirror their structure when generating new epic+child sets.
 
 Before writing the first YAML file, confirm and report to the caller:
 
-1. **Reserved FEAT-XXXX integer**: Grep `^id: FEAT-` in `backlog/`, find max,
+1. **Reserved FEAT-XXXX integer**: Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
    pick max+1, per the concurrency-safe procedure in § "FEAT-XXXX numbering"
    (fetch trunk + merge-base scan to avoid duplicate IDs across parallel
    sessions). State the chosen integer in your response.
@@ -345,8 +345,8 @@ Every card MUST include ALL fields from the template:
 - `links.prd` (path to PRD)
 - `links.design` (path to design.html — REQUIRED for any card with UI scope)
 - `canonical_docs` — REQUIRED for all cards generated from a PRD:
-  - `ssot_registry_entry`: scan `docs/references/ssot-registry.md` and copy the exact row name (column 1, bold) matching this card's macro feature. If the feature is new and has no entry yet, use the PRD slug.
-  - `data_model_refs`: list of `docs/references/collections/*.md` paths for collections touched by this card — REQUIRED whenever the card has `data_fields`; derive from the collection names in `data_fields`.
+  - `ssot_registry_entry`: scan `${paths.references_dir}/ssot-registry.md` and copy the exact row name (column 1, bold) matching this card's macro feature. If the feature is new and has no entry yet, use the PRD slug.
+  - `data_model_refs`: list of `${paths.references_dir}/collections/*.md` paths for collections touched by this card — REQUIRED whenever the card has `data_fields`; derive from the collection names in `data_fields`.
   - `additional_refs`: any ADRs, specs, or SSOT docs consulted beyond the PRD itself (from RAG context load or `implementation_references` in the PRD); omit if none.
   - **Do NOT repeat `links.prd`** — that field already captures the PRD path. `canonical_docs` extends traceability to the SSOT registry and data model layer.
 - `data_sources` — MANDATORY for EVERY card (never omit, even if empty):
@@ -380,10 +380,10 @@ Every card MUST include ALL fields from the template:
     The coder MUST ship the index in the same commit as the query — per `stack.database` (firestore.indexes.json, migration file, createIndex call, table definition).
   - Legacy field name `firestore_indexes` is still accepted for pre-3.15.0 cards.
 - `documentation_impact` — list of docs to update when card is DONE:
-  - New `route.ts` -> `docs/references/api/<module>.md` + `api/index.md`
-  - New collection -> `docs/references/data-model.md` + `collections/<domain>.md`
-  - New `page.tsx` -> `docs/references/ui/<domain>.md` + `ui/index.md`
-  - Card DONE -> `docs/references/ssot-registry.md` entry
+  - New `route.ts` -> `${paths.references_dir}/api/<module>.md` + `api/index.md`
+  - New collection -> `${paths.references_dir}/data-model.md` + `collections/<domain>.md`
+  - New `page.tsx` -> `${paths.references_dir}/ui/<domain>.md` + `ui/index.md`
+  - Card DONE -> `${paths.references_dir}/ssot-registry.md` entry
 - `test_plan` — propagated from PRD section 13:
   - `e2e_required` (true/false from evaluation tree)
   - `e2e_rationale` (reason)