baldart 4.0.4 → 4.1.1

package/framework/.claude/agents/prd.md

@@ -49,12 +49,12 @@ When the feature being planned is for **Customers** (B2C users), you MUST invoke
 - The Implementation Plan - add gamification-specific validation steps
 
 **Repository Scan** (always perform):
-- Read AGENTS.md, agents/index.md, and docs/references/project-status.md
-- Examine docs/references/data-model.md for schema understanding
-- Review docs/references/api/index.md for API surface
-- Check docs/references/ui/index.md for UI structure
-- Scan backlog/*.yml for existing cards and naming conventions
-- Review docs/decisions/*.md for architectural decisions
+- Read AGENTS.md, agents/index.md, and ${paths.references_dir}/project-status.md
+- Examine ${paths.references_dir}/data-model.md for schema understanding
+- Review ${paths.references_dir}/api/index.md for API surface
+- Check ${paths.references_dir}/ui/index.md for UI structure
+- Scan ${paths.backlog_dir}/*.yml for existing cards and naming conventions
+- Review ${paths.adrs_dir}/*.md for architectural decisions
 - Check src/ structure for code organization
 - Look at package.json for dependencies and scripts
 
@@ -473,7 +473,7 @@ This means cards 04 and 05 run in parallel, card 06 depends on both.
 
 Every implementation plan MUST include these cards (as the last steps):
 
-1. **Documentation card** (owner: `doc-reviewer`) — update `docs/references/*` to reflect the new feature
+1. **Documentation card** (owner: `doc-reviewer`) — update `${paths.references_dir}/*` to reflect the new feature
 2. **Code review card** (owner: `code-reviewer`) — review all implementation cards before marking DONE
 
 These can be a single combined card for small features.
@@ -498,7 +498,7 @@ Create protocol-compliant backlog cards for every actionable step. Cards MUST fo
 
 #### 4.1 — NAMING CONVENTIONS
 
-Before creating cards, scan `backlog/*.yml` to determine the next available number. File naming rules:
+Before creating cards, scan `${paths.backlog_dir}/*.yml` to determine the next available number. File naming rules:
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|
@@ -516,7 +516,7 @@ When a feature requires multiple cards, create a **parent card** (epic) and **ch
 
 **Parent card** (epic): Contains the full feature overview, PRD link, and lists all child cards.
 ```yaml
-# File: backlog/FEAT-NNNN-feature-name.yml  (parent/epic)
+# File: ${paths.backlog_dir}/FEAT-NNNN-feature-name.yml  (parent/epic)
 id: FEAT-NNNN
 title: "[Feature Name] — Epic"
 status: TODO
@@ -535,7 +535,7 @@ child_cards:
   - FEAT-NNNN-03  # [Brief description]
 
 links:
-  prd: docs/prd/FEAT-NNNN-feature-name.md
+  prd: ${paths.prd_dir}/FEAT-NNNN-feature-name.md
 
 notes: |
   Parent epic. See child cards for implementation.
@@ -543,7 +543,7 @@ notes: |
 
 **Child card**: References parent, declares dependencies on sibling cards.
 ```yaml
-# File: backlog/FEAT-NNNN-NN-child-slug.yml
+# File: ${paths.backlog_dir}/FEAT-NNNN-NN-child-slug.yml
 id: FEAT-NNNN-NN
 title: "[Imperative title for this piece]"
 status: TODO  # TODO | READY | IN_PROGRESS | BLOCKED | DONE
@@ -563,7 +563,7 @@ git_strategy:                        # OBJECT (per card-template.yml SSOT), neve
 #### 4.3 — CARD TEMPLATE (FEATURE CARDS)
 
 ```yaml
-# File: backlog/FEAT-NNNN-NN-slug.yml
+# File: ${paths.backlog_dir}/FEAT-NNNN-NN-slug.yml
 id: FEAT-NNNN-NN
 title: "[Imperative title]"
 status: TODO  # TODO | READY | IN_PROGRESS | BLOCKED | DONE
@@ -582,7 +582,7 @@ git_strategy:                        # OBJECT (per card-template.yml SSOT), neve
 context: |
   [Background, motivation, and links to PRD requirement IDs: FR-001, NFR-002]
   PRD Reference: [FR-XXX to FR-YYY]
-  Epic: backlog/FEAT-NNNN-feature-name.yml
+  Epic: ${paths.backlog_dir}/FEAT-NNNN-feature-name.yml
 
 scope:
   summary: "[1-2 sentence description]"
@@ -607,7 +607,7 @@ files_likely_touched:
 definition_of_done:
   - "[ ] Code implemented and reviewed"
   - "[ ] CI checks pass on PR"
-  - "[ ] docs/references/* updated (api-surface, data-model, ui-pages, project-status)"
+  - "[ ] ${paths.references_dir}/* updated (api-surface, data-model, ui-pages, project-status)"
   - "[ ] No build errors"
 
 test_plan: |
@@ -624,7 +624,7 @@ assumptions:
   - "[A-1] Assumption made — mark ASSUMED with rationale per AGENTS.md"
 
 links:
-  prd: docs/prd/FEAT-NNNN-feature-name.md
+  prd: ${paths.prd_dir}/FEAT-NNNN-feature-name.md
   related_features: []
 
 notes: ""
@@ -639,7 +639,7 @@ metadata:
 Bug cards have additional mandatory fields per AGENTS.md (mandatory clarity analysis):
 
 ```yaml
-# File: backlog/BUG-NNNN-issue-NNN-slug.yml
+# File: ${paths.backlog_dir}/BUG-NNNN-issue-NNN-slug.yml
 id: BUG-NNNN
 title: "[Fix: imperative description]"
 status: TODO
@@ -694,7 +694,7 @@ Record `git_strategy` as an OBJECT in every card — `{ branch: "feat/FEAT-NNNN-
 
 - One card per atomic deliverable (no mega-cards)
 - **Break large cards into smaller scoped tasks** — each card should be completable in a single agent session with a clean build/test/lint cycle. If a card touches more than 5-7 files or spans multiple concerns (e.g., API + UI + docs), split it.
-- Scan `backlog/*.yml` to determine the next available number in the sequence
+- Scan `${paths.backlog_dir}/*.yml` to determine the next available number in the sequence
 - Each card must be independently testable
 - Each card's acceptance criteria MUST include build/lint/test passing
 - Link to PRD requirement IDs (FR-###, NFR-###) in the `context` field

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

@@ -269,7 +269,7 @@ When you need to examine code, use Glob/Grep to find actual file paths before re
 
 - Respect `AGENTS.md` as authoritative.
 - Use `codebase-architect` for architecture discovery before broad security recommendations that depend on current structure.
-- Treat `docs/references/project-status.md` as transient coordination context, not canonical feature truth.
+- Treat `${paths.references_dir}/project-status.md` as transient coordination context, not canonical feature truth.
 - When you find a security issue that implies doc or ADR drift, flag the required follow-up explicitly.
 
 **Update your agent memory** as you discover security patterns, recurring vulnerabilities, authorization model details, trust boundaries, secrets handling patterns, and attack surface characteristics in this codebase. This builds institutional security knowledge across reviews.

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

@@ -18,7 +18,7 @@ You are **Senior Researcher**, a web-native research specialist with 20+ years o
 Before external web searches, check if the answer exists in the project's documentation:
 
 1. Use `search_docs` MCP tool (if available) with `mode: "hybrid"` to query the project's Obsidian-first LightRAG index semantically. Treat Obsidian hits as primary knowledge and verify implementation/stateful claims against repo docs/code before relying on them.
-2. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/`, `backlog/`, and `.claude/agents/`.
+2. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
 3. Internal findings should be cited alongside external research.
 
 ## MISSION

package/framework/.claude/agents/skill-improver.md

@@ -19,7 +19,7 @@ findings and automatically improve the skill/agent instructions to prevent recur
 
 **MUST NOT MODIFY:**
 - Any file under `src/` — no application code
-- `backlog/`, `docs/prd/`, `docs/decisions/` — no product docs
+- `${paths.backlog_dir}/`, `${paths.prd_dir}/`, `${paths.adrs_dir}/` — no product docs
 - `.claude/settings.json` — no infra config changes
 
 ## Weekly Analysis Process

package/framework/.claude/agents/visual-designer.md

@@ -15,16 +15,16 @@ You are the Visual Designer, an expert in visual design and API-driven image gen
 
 ## Authoritative Style Reference
 
-**MUST read `docs/references/ui-guidelines.md` before any design work.** This is the single source of truth for ALL visual style decisions: brand identity, color palette, design system rules, component patterns, SVG illustration standards, image format requirements, and text embedding policy.
+**MUST read `${paths.references_dir}/ui-guidelines.md` before any design work.** This is the single source of truth for ALL visual style decisions: brand identity, color palette, design system rules, component patterns, SVG illustration standards, image format requirements, and text embedding policy.
 
 **Never hard-code style rules in your reasoning.** Always derive visual decisions (colors, strokes, shadows, shapes, DO/DON'T rules) from the guidelines document. If the guidelines don't cover a case, flag it and propose an addition.
 
 ## YOUR ROLE & BOUNDARIES
 
-You design and generate visual assets according to the style defined in `docs/references/ui-guidelines.md`. You directly call the configured image generation API to generate images, poll for completion, download results, and prepare both original and WebP-optimized versions.
+You design and generate visual assets according to the style defined in `${paths.references_dir}/ui-guidelines.md`. You directly call the configured image generation API to generate images, poll for completion, download results, and prepare both original and WebP-optimized versions.
 
 **You DO:**
-- Create visual style guides derived from `docs/references/ui-guidelines.md`
+- Create visual style guides derived from `${paths.references_dir}/ui-guidelines.md`
 - Design asset inventories for pages and sections
 - Write and execute image generation API requests
 - Poll for task completion and download results
@@ -41,7 +41,7 @@ You design and generate visual assets according to the style defined in `docs/re
 Before generating assets, you need:
 1. Messaging framework (ICP, value prop, proof, tone)
 2. UI page structure + section list (from ui-expert agent)
-3. Brand constraints (read from `docs/references/ui-guidelines.md`, plus any brand-specific overrides)
+3. Brand constraints (read from `${paths.references_dir}/ui-guidelines.md`, plus any brand-specific overrides)
 
 If any of these are missing, ask at most 5 targeted questions, then proceed with clearly labeled [ASSUMPTION] tags.
 
@@ -50,7 +50,7 @@ If any of these are missing, ask at most 5 targeted questions, then proceed with
 You MUST produce these deliverables in this exact order:
 
 ### 1) VISUAL_STYLE_GUIDE
-- Style interpretation for the specific brand/context, derived from `docs/references/ui-guidelines.md`
+- Style interpretation for the specific brand/context, derived from `${paths.references_dir}/ui-guidelines.md`
 - Primary and accent color definitions with hex codes (from guidelines palette)
 - Composition rules (grid, alignment, spacing)
 - Illustration rules (stroke weight, fill style, shadow treatment)
@@ -164,7 +164,7 @@ When generation produces weak results:
 ## QUALITY CONTROL
 
 Before finalizing any asset:
-1. Verify style compliance against `docs/references/ui-guidelines.md`
+1. Verify style compliance against `${paths.references_dir}/ui-guidelines.md`
 2. **Verify transparent background** — all illustrations MUST have no background. If the generated image has a solid/colored background, regenerate with stronger transparency instructions
 3. Check contrast ratios for accessibility
 4. Confirm no text is embedded in image

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

@@ -1,6 +1,6 @@
 ---
 name: wiki-curator
-description: "Maintain the derived LLM wiki surface under docs/wiki/. 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 + RAG layer) without becoming canonical themselves."
 model: sonnet
 color: blue
 ---
@@ -14,7 +14,7 @@ Maintain the derived wiki overlay without weakening SSOT discipline.
 ## Responsibilities
 
 - Read canonical repo docs and approved Obsidian notes.
-- Create or update derived wiki pages under `docs/wiki/`.
+- Create or update derived wiki pages under `${paths.wiki_dir}/`.
 - Prefer compact synthesis over duplication.
 - Preserve explicit provenance and canonical references on every page.
 - Keep pages small enough to recompile quickly.
@@ -35,7 +35,7 @@ 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
-`docs/wiki/log.md`) via the project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
+`${paths.wiki_dir}/log.md`) via the project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
 
 Example call shape:
 
@@ -71,8 +71,8 @@ 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 `docs/wiki/log.md` → the topic is a documentation gap, propose synthesis.
-- Output candidates by appending to `docs/wiki/log.md` with `entry_type: synthesis_candidate` and including: title, source refs, expected scope, agent who triggered.
+- 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.
 
 ## Frontmatter Discipline
 
@@ -128,7 +128,7 @@ 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 `docs/wiki/log.md` for newly-detected clusters (≥10 entities) that
+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.
 

package/framework/.claude/commands/check.md

@@ -15,7 +15,7 @@ Look for backlog cards with status `TODO` or `READY` that need pre-development v
 - If cards are identifiable from the conversation context → use those.
 - If not → ask the user which card IDs to check (accept same formats as `/new`: space-separated, comma-separated, or hyphen-range).
 
-Read each card from `/backlog/*.yml` to understand scope, requirements, acceptance criteria, and planned changes.
+Read each card from `${paths.backlog_dir}/*.yml` to understand scope, requirements, acceptance criteria, and planned changes.
 
 ## Step 2 — Choose Audit Profile
 

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

@@ -18,7 +18,7 @@ If card IDs are provided as arguments, use them directly and skip this step.
 If `/codexreview` is invoked **without card IDs**, infer them from context in this order:
 
 1. **Recent git commits on current branch**: run `git log --oneline -10` and extract card IDs from commit messages matching patterns `[FEAT-\d+]`, `[BUG-\d+]`, `[TECH-\d+]`, `[UI-\d+]` (and any other project-specific prefixes — adapt to your taxonomy).
-2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" /backlog/*.yml` and read their `id` fields.
+2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" ${paths.backlog_dir}/*.yml` and read their `id` fields.
 3. **Current branch name**: parse the branch name (e.g. `feat/FEAT-0123-slug` → `FEAT-0123`).
 
 The patterns above (`FEAT-`, `BUG-`, `TECH-`, `UI-`) are BALDART's default taxonomy; consumer
@@ -81,7 +81,7 @@ inherits a stale lean contract from a prior `/new` run. Record the resolved mode
 
 For each provided card ID:
 
-1. Resolve the card file with Glob in `/backlog/*.yml`.
+1. Resolve the card file with Glob in `${paths.backlog_dir}/*.yml`.
 2. Read the card YAML and extract at minimum:
    - `id`, `title`, `status`
    - `acceptance_criteria`

package/framework/.claude/commands/qa.md

@@ -20,7 +20,7 @@ You are the **QA Orchestrator**. When the user invokes `/qa [profile] [--card FE
 **Auto-detect card** (in order, stop at first match):
 1. Extract from current branch: `git rev-parse --abbrev-ref HEAD` → pattern `feat/FEAT-XXXX-*` or `codex/FEAT-XXXX-*` or `claude/FEAT-XXXX-*` → capture ID.
 2. Extract from latest commit: `git log -1 --pretty=%s` → pattern `[FEAT-XXXX]` or `[DIO-XXXX]` → capture ID.
-3. Scan `/backlog/*.yml` for a card with `status: IN_PROGRESS` assigned to current work context.
+3. Scan `${paths.backlog_dir}/*.yml` for a card with `status: IN_PROGRESS` assigned to current work context.
 4. Fallback: use timestamp session ID `session-YYYYMMDD-HHMM` (compute from current date/time).
 
 ---

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

@@ -16,7 +16,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`.
+**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.references_dir`, `paths.wiki_dir` (Phase 0 doc-rag `rg` fallback 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.
@@ -29,7 +29,7 @@ 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 `docs/wiki/`.
+- `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.
 

package/framework/.claude/skills/doc-writing-for-rag/references/line-count-targets.md

@@ -1,5 +1,7 @@
 # Line Count Targets — Dense Documentation Sizing
 
+<!-- contamination-scan: skip — file is 100% illustrative sample-domain examples (fenced split-strategy snippets, bash commands); the docs/references/api/ literals are intentional teaching, not portable contamination. See the disclaimer blockquote below. -->
+
 Soglie validate su 45 file riscritti. Obiettivo: mantenere chunks LightRAG gestibili e signal/noise alto.
 
 > File path examples below (`docs/references/api/booking.md`, ecc.) are taken

package/framework/.claude/skills/doc-writing-for-rag/references/schemas-and-errors.md

@@ -1,5 +1,7 @@
 # Schemas & Errors — Central Reference Files
 
+<!-- contamination-scan: skip — illustrative SAMPLE-domain reference (see disclaimer below); every docs/references/ literal is a worked example or a documented default of the already-tokenized ${paths.api_schemas}/${paths.api_errors}, not portable contamination. -->
+
 > **Illustrative sample domain.** Error codes, routes, and entity names in the
 > examples below are a SAMPLE domain — substitute your own. Only the protocol
 > (central schema/error files, anchor cross-referencing) is normative.

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

@@ -16,7 +16,7 @@ description: >
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; default `develop`), `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`.
 **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.
@@ -130,7 +130,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
 0. **Feature gate + config resolution (BLOCKING)** — before anything else:
    - Read `features.has_backlog` from `baldart.config.yml`. If it is `false` (or the key is absent and the user confirms there is no backlog), this skill REFUSES to run: print "`/new` operates on backlog cards and requires `features.has_backlog: true` — run `npx baldart configure` to enable." and HALT. Do NOT proceed to step 1.
-   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml` (default `develop` only when the key is absent). Persist it as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from config".
+   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml`. **When the key is absent** (consumer updated to ≥4.0.0 without re-running `configure`), do NOT hard-assume `develop` — autodetect the repo's real default branch exactly as worktree-manager does, so `/new` and `nw` agree on the base: `git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD` (strip `refs/remotes/origin/`), else the first existing local branch among `develop` / `main` / `master`. A `main`-trunk repo defaulted to `develop` here would diverge from the worktree base `nw` picks and break every `git diff "$TRUNK...HEAD"` gate. Only HALT ("Trunk branch unresolved — run `npx baldart configure`") if nothing resolves. Persist the resolved value as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from the tracker".
 
 1. **Resolve `$MAIN`** — the absolute path of the main repo (not a worktree). If `/new` was invoked from inside a worktree, walk up to the parent repo via `git rev-parse --show-superproject-working-tree` or `git worktree list` until you find the non-worktree root. Persist as `Main repo:` in the tracker `## Worktree` section. **Write `$MAIN` to the tracker the moment it is computed** — every later consumer (Phase 6c, Phase 6b) MUST re-read it from the tracker and HALT with "`$MAIN` absent from tracker" if the field is missing or empty, never silently use an undefined `$MAIN` (it does not survive context compaction).
 
@@ -279,7 +279,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
    ```
 
    **Variable interpolation**:
-   - `${CARD_PATHS}`: newline-separated list of all `- backlog/FEAT-XXXX-*.yml` paths in the batch
+   - `${CARD_PATHS}`: newline-separated list of all `- ${paths.backlog_dir}/FEAT-XXXX-*.yml` paths in the batch
    - `${FILE_OWNERSHIP_MAP}`: the file-ownership map built in step 3b
 
    > `<SESSION-ID>` is the current session id (e.g. `$CLAUDE_CODE_SESSION_ID`, or a run UUID if unset). The task-scoped unique name prevents two concurrent `/new` sessions on the same day from clobbering each other's findings (a date-only name silently collides). Record the exact `$AUDIT_FILE` path in the tracker under `## Cross-Card Conflicts (Codex)` so the result-handling step reads the SAME path — never re-derive it by wildcard/timestamp.
@@ -1280,7 +1280,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
 
-`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, default `develop`). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
+`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
 
 ```bash
 cd <worktree-path>
@@ -1460,7 +1460,7 @@ The detector (Step A) is bash + grep — guaranteed to run, no LLM skip. The dow
 28. **Mark card DONE (MANDATORY — do NOT skip)**:
     a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`.
     b. Add implementation notes summarizing what was built.
-    c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `backlog/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
+    c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
 29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**.
@@ -1800,9 +1800,9 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    b. **Stage backlog YAMLs AND related docs** (pre-commit hook requires doc updates):
       ```bash
       # Stage only the force-updated backlog YAMLs
-      git add backlog/CARD-001.yml backlog/CARD-002.yml
+      git add ${paths.backlog_dir}/CARD-001.yml ${paths.backlog_dir}/CARD-002.yml
       # If ssot-registry.md was modified during the batch, stage it too
-      # (doc-freshness hook blocks commits that touch backlog/ without ssot-registry.md)
+      # (doc-freshness hook blocks commits that touch ${paths.backlog_dir}/ without ssot-registry.md)
       git diff --name-only ${paths.references_dir}/ssot-registry.md && git add ${paths.references_dir}/ssot-registry.md || true
       ```
    c. **Commit with explicit file list**:

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -27,7 +27,7 @@ git_strategy:
 context: |
   {{Background and motivation. Reference PRD sections.}}
 
-  PRD: docs/prd/{{slug}}/PRD.md ({{FR/NFR refs}})
+  PRD: ${paths.prd_dir}/{{slug}}/PRD.md ({{FR/NFR refs}})
 
 business_rationale: |
   {{2-3 righe che spiegano PERCHÉ questa feature esiste: motivazione di business +
@@ -124,8 +124,8 @@ files_likely_touched:
   - {{path}} ({{NEW|MODIFY}})
 
 links:
-  prd: "docs/prd/{{slug}}/PRD.md"
-  design: "docs/prd/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
+  prd: "${paths.prd_dir}/{{slug}}/PRD.md"
+  design: "${paths.prd_dir}/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
 
 # --- Canonical Docs (REQUIRED for cards generated from a PRD) ---
 # Traces which SSOT documents informed this card's requirements.

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -56,8 +56,8 @@ context: |
    - come è strutturato lo storage / data model ad alto livello (1 paragrafo)
   }}
 
-  PRD: docs/prd/{{slug}}/PRD.md
-  Design: docs/prd/{{slug}}/design.html
+  PRD: ${paths.prd_dir}/{{slug}}/PRD.md
+  Design: ${paths.prd_dir}/{{slug}}/design.html
   Cards: {{FEAT-XXXX-01}} .. {{FEAT-XXXX-NN}} ({{N}} sub-card, {{K}} livelli di esecuzione)
 
 business_rationale: |
@@ -148,9 +148,9 @@ execution_strategy:
 # =============================================================================
 
 canonical_docs:
-  prd_ref: docs/prd/{{slug}}/PRD.md
-  design_ref: docs/prd/{{slug}}/design.html
-  traceability_ref: docs/prd/{{slug}}/traceability.md
+  prd_ref: ${paths.prd_dir}/{{slug}}/PRD.md
+  design_ref: ${paths.prd_dir}/{{slug}}/design.html
+  traceability_ref: ${paths.prd_dir}/{{slug}}/traceability.md
   ssot_registry_entry: "{{Feature Name as registered/to-register in ssot-registry.md}}"
   data_model_refs:
     - ${paths.references_dir}/collections/{{collection}}.md
@@ -181,7 +181,7 @@ documentation_impact:
     action: "{{component registration}}"
     owner_card: {{FEAT-XXXX-NN}}
   - file: ${paths.references_dir}/ssot-registry.md
-    action: "Aggiungi riga '{{Feature Name}}' → docs/prd/{{slug}}/PRD.md"
+    action: "Aggiungi riga '{{Feature Name}}' → ${paths.prd_dir}/{{slug}}/PRD.md"
     owner_card: {{FEAT-XXXX-NN-last}}  # tipicamente l'ultima card (E2E o docs-sync)
 
 # =============================================================================

package/framework/.claude/skills/prd/assets/prd-template.md

@@ -10,7 +10,7 @@ freshness_status: fresh
 # {{Feature Name}} PRD
 
 **Version**: 1.0
-**Owner**: Antonio Baldassarre
+**Owner**: {{Owner}}
 **Date**: {{YYYY-MM-DD}}
 **Status**: Draft
 **Feature ID**: {{FEAT-ID}}
@@ -51,7 +51,7 @@ Backlog cards to be created after PRD approval.
 
 **Mockup status:** {{provided | partial | none | n/a}}
 **Step 3 mode:** {{full | hybrid | skipped}}
-**Design entry point:** {{`docs/prd/<slug>/design.html` | `docs/prd/<slug>/mockups/` | both}}
+**Design entry point:** {{`${paths.prd_dir}/<slug>/design.html` | `${paths.prd_dir}/<slug>/mockups/` | both}}
 
 ### Screen inventory
 

package/framework/.claude/skills/prd/assets/state-template.md

@@ -6,7 +6,7 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}
 - main_path: {{absolute path of the MAIN repo checkout ($MAIN) — persisted at Step 1 so finalization (validation-phase Step 7.5) never references an undefined var}}
-- trunk_branch: {{resolved git.trunk_branch (default develop)}}
+- trunk_branch: {{resolved git.trunk_branch (autodetected from origin/HEAD when the config key is absent)}}
 - branch: prd/{{slug}}
 - kind: docs
 - created_at: {{ISO-8601 UTC}}

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

@@ -226,7 +226,7 @@ Suppress findings where the strongest false-positive argument is convincing.
 ```
 
 **Variable interpolation** (build the command string before execution; read all values from the session tracker written at Phase 0 — never guess):
-- `${CARD_PATHS}`: newline-separated list of `- backlog/FEAT-XXXX-*.yml` paths from Step 5
+- `${CARD_PATHS}`: newline-separated list of `- ${paths.backlog_dir}/FEAT-XXXX-*.yml` paths from Step 5
 - `${PRD_PATH}`: the PRD file path from the session state
 - `${ADJACENT_CARD_PATHS}`: newline-separated list from Step 6.4
 - `${CARD_ID_SLUG}`: hyphen-separated list of card IDs being audited (e.g. `FEAT-0042-FEAT-0043`) — written to session tracker at Phase 0

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

@@ -89,13 +89,13 @@ Every PRD generates **1 epic card + N children**, regardless of N. The
 `prd-card-writer` agent enforces this; the skill MUST verify it post-generation
 and HALT if violated.
 
-- **Epic**: `backlog/FEAT-XXXX-00-<slug>-epic.yml` — tracker only (no code work);
+- **Epic**: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` — tracker only (no code work);
   contains AC-EPIC, execution_strategy with parallel groups, documentation_impact
   map.
-- **Children**: `backlog/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M — atomic
+- **Children**: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M — atomic
   implementation cards. `group.parent: FEAT-XXXX-00`, `group.sequence: N`.
 
-**Forbidden** (post-write verification: skill MUST `ls backlog/FEAT-XXXX-*.yml`
+**Forbidden** (post-write verification: skill MUST `ls ${paths.backlog_dir}/FEAT-XXXX-*.yml`
 and confirm a `-00-...-epic.yml` exists, plus at least one `-NN-` child):
 
 - Flat cards `FEAT-XXXX-<slug>.yml` (no `-NN-` segment).

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

@@ -149,12 +149,17 @@ la feature prima di scrivere qualsiasi documento.
 <Progress Bar>
 ```
 
-**MONITORING SIGNAL (non-blocking):** docs worktree created (registry entry with
-`kind: "docs"` present) AND state file exists on disk inside the worktree AND
-all tasks created AND context loaded. These are logged for observability; they
-do not halt execution. Precondition failures that would surface as a STOP are
-already handled by the BLOCKING gates in points 3 and 4 above — this note is
-a post-completion consistency reminder only, not an additional gate.
+**Gate (BLOCKING).** Before leaving Step 1 you MUST verify, on disk, that the
+docs worktree actually exists: `pwd` prints the absolute worktree path AND its
+registry entry (`kind: "docs"`) is present AND the state file exists inside the
+worktree AND all tasks were created AND context loaded. If the worktree was NOT
+created — e.g. `nw-docs` aborted because no trunk branch could be resolved, or
+`.worktrees/` is not in `.gitignore` — **HALT and surface the `nw-docs` error
+verbatim**. Do NOT show the "Ho creato la sessione PRD … in un worktree
+dedicato" message and do NOT proceed to Discovery: writing PRD artefacts on the
+main checkout breaks HARD RULE 17 and pollutes every parallel session. This is a
+hard gate, not an observability note — the kickoff output above is emitted only
+after this gate passes.
 
 **Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
 and ask the mockup intake question in the same turn.

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

@@ -6,7 +6,7 @@ Mark task 3 as `in_progress`.
 
 ## Write PRD
 
-1. Create directory `docs/prd/<slug>/` if it doesn't exist.
+1. Create directory `${paths.prd_dir}/<slug>/` if it doesn't exist.
 2. **Obsidian spec note (if present):** if the state file contains `## Obsidian Spec Note`,
    add a row to the Canonical Sources table in the PRD:
    `| Obsidian spec | [[Note Name]] |`
@@ -93,7 +93,7 @@ Mark task 3 as `in_progress`.
    - If regulatory findings exist: add a dedicated "Compliance Requirements" section.
    - Include a "Research-Informed Decisions" subsection listing decisions influenced
      by research, with brief rationale and source reference.
-5. Write `docs/prd/<slug>/PRD.md` using the template from `assets/prd-template.md`.
+5. Write `${paths.prd_dir}/<slug>/PRD.md` using the template from `assets/prd-template.md`.
 
 ### PRD sections checklist