baldart 3.21.2 → 3.22.1

package/CHANGELOG.md

@@ -5,6 +5,97 @@ 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).
 
+## [3.22.1] - 2026-05-27
+
+Rimosso il gate `AskUserQuestion` di conferma merge introdotto in v3.22.0 Step 7 — era friction inutile contro il "seamless" che è il punto della release. Quando l'utente lancia `/prd` ha già implicitamente accettato la pipeline completa (discovery → design → cards → commit → merge in develop). Chiedere "Procedo con merge?" a fine sessione equivale a chiedere "sei sicuro di voler completare quello che mi hai chiesto di fare?".
+
+### Changed — `/prd` Step 7 merge è ora full-seamless
+
+- **[framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md)**: Step 7 point 9 non è più un `AskUserQuestion` ma una nota che chiarisce il razionale del no-confirmation flow + escape hatch user-initiated ("non mergiare" / "lascia il worktree" honora l'override e ferma dopo il commit).
+- **[framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)** HARD RULE 17 lifecycle: la descrizione di Step 7 cita "Seamless by default, no confirmation gate" + l'escape hatch.
+- **[framework/.claude/skills/prd/references/discovery-phase.md](framework/.claude/skills/prd/references/discovery-phase.md)**: il messaggio di kickoff visibile all'utente promette esplicitamente "commit + merge automatico in develop + cleanup worktree, seamless" — niente più sorprese a fine sessione.
+
+### Why PATCH and not MINOR
+
+Rimozione di un comportamento (gate di conferma) introdotto solo 0 minuti fa nella stessa giornata. Nessuna nuova capability, nessun breaking change per consumer: il gate non era una feature documentata né attesa dagli utenti pre-v3.22.0, era una sovra-cautela introdotta da me contro la richiesta esplicita ("seamless"). La decision tree di MAINTAINING.md classifica "bugfix di behaviour non desiderato senza breaking change" come PATCH.
+
+### Why no schema-change propagation
+
+Modifica puramente comportamentale dentro un singolo step di una singola skill. Zero chiavi nuove, zero modifiche CLI, zero hook.
+
+## [3.22.0] - 2026-05-27
+
+Le sessioni `/prd` ora vivono in un **docs worktree** dedicato, esattamente come fa `/new` per le card di codice. Il problema risolto: con 5-10 sessioni Claude in parallelo, ogni PRD inquinava il main checkout con `docs/prd/<slug>/PRD.md`, lo state file, le card YAML, l'eventuale `design.html`, e gli update a `ssot-registry.md` / `project-status.md`. `git status` diventava un campo minato, le sessioni `/new` rischiavano di stashare/committare file PRD non loro, e la review manuale era pressoché impossibile. Soluzione: estendere `worktree-manager` con una **modalità docs lean** (no `npm install`, no porta, no `.env` copy, no build verify, no lint/tsc gates) e integrarla nel ciclo di vita del PRD — creazione automatica al kickoff, merge automatico (previa conferma utente) al termine, cleanup seamless.
+
+### Added — `worktree-manager` programmatic docs mode
+
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)**: nuova sezione "Programmatic API — docs mode" con due funzioni:
+  - **`nw-docs`** — input `{ slug, branchPrefix? }`, output `{ path, branch, kind: "docs" }`. Esegue solo `git fetch origin develop` + `git worktree add .worktrees/prd-<slug> -b prd/<slug> origin/develop` + entry nel registry con `kind: "docs"`, `port: null`, `buildVerified: null`. Target di costo: < 5 secondi (vs minuti per `/nw` standard a causa di `npm install`).
+  - **`mw-docs`** — input `{ worktreePath, commitMessage? }`, output `{ merged, mergeCommit, prNumber, strategy, worktreeRemoved }`. Esegue safety commit + rebase su `origin/develop` (con il protocollo conflict-resolution doc-friendly esistente in `/mw` step 4b) + merge via `git.merge_strategy` configurato (`pr` o `local-push`) + cleanup worktree/branch. **Salta** i gate inapplicabili a un worktree di docs: `npm run build`, `npx eslint`, `npx tsc`, `npm run test`, post-merge build verify.
+- Forme **FORBIDDEN** documentate esplicitamente: niente `npm install`/port scan/`.env*` copy/build in `nw-docs`; niente lint/tsc/build gates in `mw-docs`. Il senso della modalità lean è proprio non eseguirli.
+- Registry condiviso con i code worktrees (`.worktrees/registry.json`) — `/lw` e `/cw` mostrano docs worktrees accanto ai code worktrees, distinti dal campo `kind`.
+
+### Changed — `worktree-manager`: rebase conflict protocol hardened
+
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)** — la tabella di conflict-resolution dello step 4b di `/mw` (riusata verbatim da `mw-docs`) è stata estesa con due categorie nuove **prima** della catch-all "Docs/config":
+  - **Structured registries** (`project-status.md`, `ssot-registry.md`, `field-registry.*`, `traceability-matrix.md`, `REGISTRY.md`) → **STOP**: abort rebase, report all'utente. Senza questa riga, due PRD paralleli che toccano `project-status.md` farebbero auto-strip dei marker di conflitto producendo file con sezioni duplicate e tabelle malformate. Il fix vale anche per `/mw` su code worktrees — qualsiasi card che modifica una di queste registry ora chiede risoluzione manuale invece di corromperle silenziosamente.
+  - **Append-only logs** (`**/*.jsonl` sotto `docs/metrics/`) → auto-resolve "keep both sides", che per JSONL è semanticamente corretto (file line-oriented additivo). Questo permette al Metrics Log del PRD (vedi sotto) di sopravvivere a merge concorrenti senza intervento.
+
+### Changed — `/prd` skill: HARD RULE 17 (worktree isolation)
+
+- **[framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)**: nuova HARD RULE 17 obbligatoria — ogni sessione PRD apre un docs worktree allo Step 1 prima di scrivere qualunque file, e committa/mergia tutto allo Step 7 prima di terminare. La regola include:
+  - **Path resolution explicit rule**: tutti i `Write` / `Edit` / `Read` di Claude Code DEVONO prefissare i path con `$WORKTREE_PATH` (Claude Code richiede path assoluti — senza prefisso esplicito i file finirebbero nel main repo, vanificando l'isolamento). Esempio `right vs wrong` nel testo della regola.
+  - **Forbidden operations**: nessun `git checkout`/`switch`/`branch` sul main, nessun `git stash` (refs/stash è condiviso fra worktree), nessuna scrittura diretta sul main repo durante la sessione.
+  - **Failure handling**: se `nw-docs` fallisce (e.g. `.worktrees/` non in `.gitignore`), la skill DEVE fermarsi e segnalare — niente fallback silenzioso al main repo.
+- **HARD RULE 9 aggiornata**: il session-start update di `project-status.md` viene **skippato** quando la sessione gira in un docs worktree (sarebbe invisibile alle altre sessioni). L'update at-commit resta attivo, eseguito nel worktree come ultima scrittura prima del rebase + merge.
+- **Step 1 (Kickoff)** in [discovery-phase.md](framework/.claude/skills/prd/references/discovery-phase.md): aggiunto step 3 che chiama `worktree-manager nw-docs` subito dopo aver derivato lo `<slug>`, prima di creare lo state file. Output kickoff aggiornato per mostrare path/branch del worktree all'utente.
+- **Step 0 (Context Recovery)** in [discovery-phase.md](framework/.claude/skills/prd/references/discovery-phase.md): scan iniziale di `.worktrees/registry.json` per entries con `kind: "docs"` che matchano lo slug — se trovate, `cd` nel worktree e riprendi. Gestito anche il caso "state file legacy nel main da pre-v3.22.0" (chiede all'utente se migrare o continuare in legacy mode).
+- **Step 7 (Resolution, Commit & Merge)** in [validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md) — rinominato da "Resolution and Commit" e riscritto end-to-end:
+  - Update di `ssot-registry.md` / `project-status.md` avviene nel worktree (skip se file inesistente).
+  - Commit con `git -C "$WORKTREE_PATH" commit` (file espliciti, mai `git add .`).
+  - **Gate di conferma esplicito** (`AskUserQuestion`) prima del merge: "Procedo con merge automatico in `develop` e cleanup del worktree?". Opzione "lascia il worktree" per review manuale o test.
+  - Sulla conferma: invocazione `worktree-manager mw-docs` che rebase + merge + cleanup. Failure handling: il worktree resta su disco, niente retry automatico.
+- **[framework/.claude/skills/prd/assets/state-template.md](framework/.claude/skills/prd/assets/state-template.md)**: nuova sezione `## Worktree` (path, branch, kind, created_at, merge_commit).
+- **Metrics Log riposizionato dentro il worktree.** La sezione "Metrics Log" di SKILL.md scriveva precedentemente in `docs/metrics/skill-runs.jsonl` con risoluzione del path rispetto al main repo root — incompatibile con HARD RULE 17 e con isolamento parallelo. Ora scrive in `$WORKTREE_PATH/docs/metrics/skill-runs.jsonl` come ultimo append PRIMA del commit di Step 7; il file è incluso nella lista di stage esplicita e il conflict protocol di `mw-docs` lo riconosce come append-only (vedi categoria "Append-only logs" sopra). Risultato: due PRD paralleli che terminano insieme producono un append di entrambe le righe nel file su `develop`, senza intervento manuale.
+
+### Why MINOR and not PATCH
+
+Nuova capability portata da una skill esistente (`worktree-manager` guadagna l'API docs mode) + cambio di workflow per `/prd` (gira sempre in worktree). Nessun breaking change per i consumer: le sessioni PRD esistenti pre-3.22.0 sono detettate in Step 0 e gestite con prompt di migrazione (legacy mode resta supportato). La decision tree di `MAINTAINING.md` classifica "added capability" come MINOR.
+
+### Why no schema-change propagation
+
+Zero nuove chiavi in `baldart.config.yml`. La modalità docs riusa:
+- `git.merge_strategy` (già esistente da v3.9.0) per il merge — `pr` o `local-push`, rispetta la scelta del progetto.
+- `paths.prd_dir`, `paths.backlog_dir`, `paths.references_dir` (esistenti) — risolti relativamente al worktree (HARD RULE 17).
+- `features.has_prd_workflow` (esistente) — gating della skill.
+
+Nota CHANGELOG-only (non normativa): per i PRD molti consumer preferiscono `merge_strategy: local-push` (no PR per documentazione). Chi vuole differenziare la strategia per skill può farlo via overlay `.baldart/overlays/prd.md` — la skill non impone scelte.
+
+### Pre-release code review fixes (within v3.22.0)
+
+Un `/code-review` high-effort eseguito prima del tag ha individuato 10 bug — tutti corretti in questa stessa release prima del rilascio. I più gravi:
+
+- **`prd-card-writer` agent + `backlog-phase.md` invocation**: il subagent scriveva le card a `backlog/` consumer-root-relative senza alcuna `$WORKTREE_PATH` awareness — Step 5 del PRD spruzzava le card nel main repo, vanificando l'isolamento. Fix: nuova sezione "Working Directory (MANDATORY)" nel file dell'agent + il prompt da `backlog-phase.md` ora passa `WORKING_DIRECTORY` esplicito (regola di substitution documentata).
+- **`ui-design/SKILL.md` Step G**: copia `design.html` a `${paths.prd_dir}/<slug>/design.html` consumer-root-relative. Fix identico: sezione "Working Directory" + `ui-design-phase.md` ora passa `WORKING_DIRECTORY=$WORKTREE_PATH` come arg.
+- **`/prd-add` Step 0**: listava `${paths.prd_dir}/sessions/` sul main repo, zero scan del registry. Fix: Step 0 riscritto — scansiona `.worktrees/registry.json` per `kind: "docs"` prima di guardare il main; gestisce sia worktree-mode che legacy; documenta gli effetti collaterali downstream (delta commit nel worktree, sub-agents ri-invocati con `WORKING_DIRECTORY`, no auto-merge per CR).
+- **Regressione `/new` introdotta dal conflict protocol hardening**: la prima versione della tabella step 4b in `worktree-manager` abortiva blanket il rebase su `ssot-registry.md` / `project-status.md`, ma `/new` AGGIORNA `ssot-registry.md` per ogni card (line 1131 di `framework/.claude/skills/new/SKILL.md`, hook pre-commit che blocca commit a `backlog/` senza ssot). Risultato: ogni batch multi-card di `/new` sarebbe fallito al rebase. Fix: sostituito il blanket abort con **structural validation** (`validate_structured_md` helper) — strip markers + check struttura (no marker residui, no header table duplicati, no frontmatter doppio). Se valido → accept (caso routine: append additivo); se invalido → abort (caso raro: due card hanno modificato la stessa riga). Restituisce a `/new` il comportamento additivo originale, mantiene la protezione contro corruzione reale.
+- **`git stash` in `mw-docs`**: la prima versione riusava verbatim `/mw` step 4b che fa `git stash push --include-untracked` prima del rebase. Violazione diretta della Safety Rule "NEVER use git stash in worktrees" (refs/stash condiviso fra worktree — incidente FEAT-0522). Fix: la sezione `mw-docs` ora esplicita "NO stash" — il safety commit dello step 1 garantisce working tree clean, qualunque dirty post-safety è un errore che richiede STOP, mai uno stash di recovery.
+- **`nw-docs` mancante `.gitignore` check**: la Safety Rule generale dice "Always verify `.worktrees/` is in `.gitignore` before creating", ma `nw-docs` la omette. Fix: step 0 di `nw-docs` è ora un pre-flight `.gitignore` check che fallisce con errore esplicito se mancante.
+- **`nw-docs` pseudo-bash relativo invece che assoluto**: il path ritornato come `path` doveva essere assoluto (per HARD RULE 17), ma lo pseudo-code lo settava relativo. Fix: ancorato a `$MAIN_ROOT` esplicito via `git rev-parse --show-toplevel` + `WORKTREE_PATH="$MAIN_ROOT/$WORKTREE_REL"`.
+- **Esempio HARD RULE 17 fuorviante**: l'esempio "RIGHT" mostrava `Write file_path = "$WORKTREE_PATH/..."` come stringa literal. Claude Code NON espande shell variables → o errore "path must be absolute" o creazione di una dir letterale `$WORKTREE_PATH/`. Fix: esempio riscritto con 3 forme "wrong" (main repo, literal var, relative) + 1 "right" (substitution textuale dell'absolute path).
+- **Off-by-one cross-ref Metrics Log**: "Add the file to Step 7 point 5" ma il staging è point 6 (point 5 è il Metrics Log step stesso, self-referential). Fix: cross-ref corretto a point 6 con nota di disambiguazione.
+- **Case pattern `*.jsonl` non raggiungibile per il secondo arm + auto-strip non desiderato per fixture**: `*.jsonl|docs/metrics/*.jsonl` matchava ogni `.jsonl` ovunque (anche fixture/seed). Fix: tabella sostituita con pattern espliciti — `docs/metrics/*.jsonl` auto-resolve, altri `*.jsonl` abort + manuale.
+- **Numerazione stale "Step 1, point 7"** in `discovery-phase.md` § 1.6: dopo la renumerazione, point 7 è "Context Loading", non l'output kickoff. Fix: aggiornato a "point 9 (Business Rationale Extraction is the final point)".
+
+### Verification
+
+Modifiche applicate ma non testabili automaticamente (nessuna test suite in questo repo, come da `CLAUDE.md`). Validazione richiesta in un consumer reale:
+1. Lanciare `/prd` su una feature qualunque → verificare la creazione `.worktrees/prd-<slug>/` + entry `kind: "docs"` nel registry.
+2. Aprire una seconda sessione Claude in parallelo e fare `git status` sul main → deve essere pulito.
+3. Procedere fino allo Step 7 → verificare il prompt di conferma merge, completare → worktree rimosso, branch eliminato, PRD su `develop`.
+4. Resume test: chiudere/riaprire la sessione a metà PRD → Step 0 deve trovare il worktree dal registry e `cd` lì.
+5. `/prd-add` su PRD attivo → deve riusare il worktree esistente, non crearne uno nuovo.
+
 ## [3.21.2] - 2026-05-26
 
 Aggiunto un livello di automazione che intercetta il drift fra la skill `/baldart-update` (v3.21.0+) e le sorgenti CLI che essa replica in chat. La skill replica **5 decision point fissi** del comando `npx baldart update`; quando una release tocca `src/commands/update.js` (nuovi prompt), `src/utils/hooks.js` (nuove entry in `HOOK_REGISTRY`), o `framework/templates/baldart.config.template.yml` (nuove top-level key), la skill può silenziosamente disallinearsi. Il bug v3.21.0 → v3.21.1 (`git -C .framework fetch` errato) è già stato un esempio del problema: la skill prometteva un pattern che il test live ha smentito. Senza un meccanismo di alert, futuri drift sarebbero individuabili solo per accidente.

package/VERSION

@@ -1 +1 @@
-3.21.2
+3.22.1

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

@@ -8,6 +8,42 @@ color: amber
 
 You are **PRD Card Writer** — a specialist agent that converts an approved PRD into a set of atomic, well-structured backlog cards with full traceability.
 
+## Working Directory (MANDATORY — read FIRST, since v3.22.0)
+
+When invoked by `/prd` Step 5 the caller passes a **`WORKING_DIRECTORY`** field
+in the prompt — its value is the absolute path of the docs worktree where the
+PRD lives (e.g. `/Users/alice/proj/.worktrees/prd-menu-info`). All your file
+writes MUST land **inside** this directory, otherwise the cards spray into the
+consumer's main repo and HARD RULE 17 of `/prd` SKILL.md is broken (cards
+become invisible to the worktree's commit, isolation collapses, parallel
+sessions get polluted `git status`).
+
+**Rule of thumb:** every path in this document — `backlog/`,
+`${paths.backlog_dir}/`, `docs/references/ssot-registry.md`,
+`${paths.references_dir}/...`, the card template — is **relative to
+WORKING_DIRECTORY**. Before any `Write`, `Read`, `Glob`, or `Grep` call,
+construct the absolute path as `<WORKING_DIRECTORY>/<relative-path>`.
+
+**Examples:**
+- ❌ `Write(file_path="backlog/FEAT-0500-00-...yml")` — relative path: Claude
+  Code rejects, or resolves against the wrong cwd.
+- ❌ `Write(file_path="/Users/alice/proj/backlog/FEAT-0500-00-...yml")` —
+  absolute, but main-repo: defeats the worktree.
+- ✅ `Write(file_path="/Users/alice/proj/.worktrees/prd-menu-info/backlog/FEAT-0500-00-...yml")`
+  — absolute, inside `WORKING_DIRECTORY`.
+
+**Sanity check before writing.** Always begin your work by running
+`Bash("cd <WORKING_DIRECTORY> && pwd && ls -la backlog/ | head -5")` and
+confirming the output matches `WORKING_DIRECTORY`. If it doesn't, halt and
+report — do NOT proceed to write cards on whatever cwd you ended up in.
+
+**When the caller does NOT pass `WORKING_DIRECTORY`** (legacy call sites
+predating v3.22.0): fall back to the consumer root (whatever Bash `pwd`
+returns). Log a `[WORKING-DIR-FALLBACK]` warning in your response so the
+caller can detect it and migrate.
+
+---
+
 ## Field Grounding Rule (HARD RULE — zero tolerance)
 
 **BEFORE writing any field name in any card**, execute this protocol:

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

@@ -38,7 +38,7 @@ message. You ask questions, wait for answers, and iterate.
 | 4b | Confirm Specs | [prd-writing-phase.md](references/prd-writing-phase.md) |
 | 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
 | 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
-| 7 | Resolution & Commit | [validation-phase.md](references/validation-phase.md) |
+| 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
 
 **Before starting each phase, read the corresponding reference file.**
 
@@ -55,6 +55,7 @@ message. You ask questions, wait for answers, and iterate.
 7. No code generation. This skill produces planning artifacts only.
 8. Use exact terminology from `agents/coding-standards.md` and the project's terminology section in `.baldart/overlays/prd.md` (audience segments come from `identity.audience_segments`; domain entities are listed in the overlay).
 9. Update `${paths.references_dir}/project-status.md` Active Code Context at session start and at commit (AGENTS.md MUST). Skip when the file does not exist in the project.
+   **Worktree-mode exception (HARD RULE 17):** when the PRD runs inside a docs worktree (default since v3.22.0), the session-start update is **SKIPPED** — writing `project-status.md` in the worktree wouldn't be visible to other terminals working on the main repo, and writing it on the main repo would pollute `git status` for parallel sessions (exactly what worktree isolation is meant to prevent). The at-commit update still applies and runs inside the worktree as the last write before rebase + merge — see [validation-phase.md](references/validation-phase.md) § Step 7.
 10. **STOP means STOP.** When you see `STOP`, end your message. Do not make more tool
     calls. Do not continue to the next step. Wait for the user.
 11. **Every message MUST end with the Progress Bar.** No exceptions.
@@ -108,6 +109,88 @@ message. You ask questions, wait for answers, and iterate.
     riusa esattamente questa stessa procedura di Step 1.6 → Step 3 entra in Hybrid mode.
     Vedi [ui-design-phase.md](references/ui-design-phase.md) § "Step 3.0 — Mockup Source Decision".
 
+17. **Worktree isolation (MANDATORY since v3.22.0).** Every PRD session runs inside
+    a dedicated **docs worktree** created by the `worktree-manager` skill in
+    programmatic docs mode — never on the consumer's main checkout. The worktree
+    isolates PRD artefacts from other parallel Claude sessions: `git status` on
+    the main repo stays clean, accidental stashes / commits / push from sibling
+    `/new` runs cannot pick up PRD files, and the merge back into `develop`
+    becomes a single atomic operation.
+
+    **Why this exists.** Without the worktree, every PRD pollutes the main
+    checkout with `${paths.prd_dir}/<slug>/PRD.md`, `${paths.prd_dir}/sessions/...`,
+    `${paths.backlog_dir}/FEAT-XXXX-*.yml`, plus design assets and updated
+    SSOT/project-status files. With 5-10 parallel sessions, this is unworkable.
+
+    **Lifecycle (deterministic, no opt-in):**
+    - **Step 1 (Kickoff)** — after computing `<slug>`, before writing ANY file,
+      call `worktree-manager` programmatic `nw-docs` with `{ slug: <slug> }`.
+      Save the returned `path` as `$WORKTREE_PATH` in the state file under
+      `## Worktree` (path, branch, kind: "docs"). Then `cd "$WORKTREE_PATH"`
+      and run `pwd` to verify. From this moment, EVERY file write happens inside
+      the worktree. See [discovery-phase.md](references/discovery-phase.md) § Step 1.
+    - **Step 0 (Context Recovery)** — when resuming a `/prd` or running
+      `/prd-add`, scan `.worktrees/registry.json` for entries with
+      `kind: "docs"` matching the slug; if found, `cd` into that worktree
+      before scanning for state files. See [discovery-phase.md](references/discovery-phase.md) § Step 0.
+    - **Step 7 (Commit & Merge)** — commit happens inside the worktree, then
+      `worktree-manager` programmatic `mw-docs` is invoked immediately to
+      rebase onto `origin/develop` and land the PRD via the configured
+      `git.merge_strategy`. Seamless by default, no confirmation gate (the
+      user opted into the full pipeline when they ran `/prd`). If the user
+      explicitly says "non mergiare" / "lascia il worktree", honor the
+      override and stop after the commit. See [validation-phase.md](references/validation-phase.md) § Step 7.
+
+    **Path resolution rule (CRITICAL — read carefully).** Claude Code's
+    `Write` / `Edit` / `Read` tools require ABSOLUTE paths and **do NOT
+    expand shell variables**. All `${paths.X}` references in this skill and
+    its phase references are relative to the worktree for the entire
+    session — but you must construct the final absolute path **textually
+    by concatenation**, never by passing the literal string `$WORKTREE_PATH`
+    to a tool call.
+
+    The variable name `$WORKTREE_PATH` used throughout this document is a
+    **placeholder for the absolute path returned by `nw-docs` at Step 1**
+    (e.g. `/Users/alice/my-project/.worktrees/prd-menu-info`). Substitute
+    that absolute path before every Write/Edit. Worked example:
+
+    ```
+    # State: nw-docs returned path="/Users/alice/my-project/.worktrees/prd-menu-info"
+    # Goal: write PRD.md for slug=menu-info
+
+    # ❌ WRONG #1 — writes to main repo, defeats isolation:
+    Write(file_path="/Users/alice/my-project/docs/prd/menu-info/PRD.md")
+
+    # ❌ WRONG #2 — literal $WORKTREE_PATH string:
+    Write(file_path="$WORKTREE_PATH/docs/prd/menu-info/PRD.md")
+    # Claude Code rejects ("path must be absolute") or creates a literal
+    # directory named "$WORKTREE_PATH" in the current cwd.
+
+    # ❌ WRONG #3 — relative path (also rejected by Write/Edit):
+    Write(file_path="docs/prd/menu-info/PRD.md")
+
+    # ✅ RIGHT — substitute the absolute path you got from nw-docs:
+    Write(file_path="/Users/alice/my-project/.worktrees/prd-menu-info/docs/prd/menu-info/PRD.md")
+    ```
+
+    Before every Write/Edit, mentally check: "does this path string start
+    with the absolute `nw-docs` path I saved at Step 1?" If not, you've
+    broken isolation. The exception is `/tmp/...` paths used for transient
+    reports (e.g., audit phase Step 2 step f) — those are intentionally
+    outside any worktree.
+
+    **Forbidden operations during the session:**
+    - `git checkout` / `git switch` / `git branch` on the main repo (worktree-manager Safety Rules).
+    - `git stash` anywhere (shared `refs/stash` across worktrees — see Safety Rules in worktree-manager).
+    - Writing to the main repo's `${paths.prd_dir}`, `${paths.backlog_dir}`,
+      or `${paths.references_dir}` directly. Only the merge in Step 7 touches `develop`.
+
+    **Exception — when the worktree cannot be created.** If `git worktree add`
+    fails (e.g., `.worktrees/` not in `.gitignore`, disk full, repo not a git
+    repository, or the consumer has explicitly disabled docs worktrees via
+    overlay), STOP and report the error to the user. Do NOT silently fall back
+    to writing on the main repo — that defeats the entire purpose of this rule.
+
 ---
 
 ## TEMPLATES
@@ -121,12 +204,16 @@ Use these templates when creating artifacts:
 | Backlog epic (always 1) | [assets/epic-template.yml](assets/epic-template.yml) |
 | Backlog child card (N≥1) | [assets/card-template.yml](assets/card-template.yml) |
 
-**State file location:** `${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
-**PRD location:** `${paths.prd_dir}/<slug>/PRD.md`
-**Design location:** `${paths.prd_dir}/<slug>/design.html`
+**State file location:** `$WORKTREE_PATH/${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
+**PRD location:** `$WORKTREE_PATH/${paths.prd_dir}/<slug>/PRD.md`
+**Design location:** `$WORKTREE_PATH/${paths.prd_dir}/<slug>/design.html`
 **Cards location:**
-- Epic: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` (mandatory when `features.has_backlog: true`)
-- Children: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M (at least 1)
+- Epic: `$WORKTREE_PATH/${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` (mandatory when `features.has_backlog: true`)
+- Children: `$WORKTREE_PATH/${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M (at least 1)
+
+**`$WORKTREE_PATH`** is set in Step 1 (Kickoff) by `worktree-manager nw-docs` —
+see HARD RULE 17. Until Step 1 has run, no file writes are allowed; until then
+the value lives only in the state file `## Worktree` section.
 
 ---
 
@@ -146,7 +233,7 @@ At the END of every message (after all text, before stopping), display:
 | 2 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
 | 3 | Conferma specifiche | ⬜/🔄/✅ |
 | 4 | Creazione backlog cards | ⬜/🔄/✅ |
-| 5 | Validazione e commit | ⬜/🔄/✅ |
+| 5 | Validazione, commit & merge | ⬜/🔄/✅ |
 
 Comprensione: X% (N/M dimensioni coperte) — ISA: N punti identificati
 Mockup: ⬜ non chiesto / 🔄 in attesa / ✅ N mockup / ⏭️ nessuno
@@ -231,7 +318,7 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 | 2 | Design UI & approvazione | ✅/⏭️ |
 | 3 | Conferma specifiche | ✅ |
 | 4 | Creazione backlog cards | ✅ |
-| 5 | Validazione e commit | ✅ |
+| 5 | Validazione, commit & merge | ✅ |
 
 Comprensione: 100%
 Mockup: ✅ N mockup analizzati / ⏭️ nessuno fornito
@@ -242,9 +329,22 @@ Step 3 mode: full / hybrid / skipped
 
 ---
 
-## Metrics Log (MANDATORY — after Phase 5 Validazione)
+## Metrics Log (MANDATORY — runs inside Step 7, BEFORE the commit)
+
+After cards are created and audited (Steps 5-6) and BEFORE the explicit stage in
+validation-phase.md Step 7 point 5, log this PRD run to the skill-runs file.
 
-After cards are created and committed, log this PRD run to `docs/metrics/skill-runs.jsonl`.
+**Location (HARD RULE 17 applies):**
+`$WORKTREE_PATH/docs/metrics/skill-runs.jsonl`
+
+The file is committed together with the rest of the PRD artefacts in Step 7,
+so it flows into `develop` via `mw-docs` atomically with the PRD.
+
+**Conflict resilience.** JSONL is line-oriented and additive: when two parallel
+PRDs both append a line and one rebases onto the other, the doc-friendly conflict
+protocol in `worktree-manager` step 4b auto-resolves the `.jsonl` conflict by
+keeping both lines (this is the one canonical case where "keep both sides" is
+exactly the correct semantics). No special handling needed.
 
 **Steps:**
 
@@ -256,10 +356,13 @@ After cards are created and committed, log this PRD run to `docs/metrics/skill-r
    - `has_db_indexes_pct`: % of cards that have a `db_indexes` field (covers any persistence layer; legacy `firestore_indexes` cards count too)
    - `discovery_iterations`: approximate number of Q&A rounds with the user (count AskUserQuestion calls in this session, default 1 if unknown)
 
-2. Write ONE JSON line (append) to `docs/metrics/skill-runs.jsonl`:
+2. Append ONE JSON line to `$WORKTREE_PATH/docs/metrics/skill-runs.jsonl`
+   (create the file + parent directory if absent):
 
    ```json
    {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
-**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar.
+3. Add the file to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+
+**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless.

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

@@ -2,6 +2,13 @@
 Created: {{YYYY-MM-DD HH:MM}}
 Status: discovery
 
+## Worktree
+- path: {{absolute worktree path returned by worktree-manager nw-docs}}
+- branch: prd/{{slug}}
+- kind: docs
+- created_at: {{ISO-8601 UTC}}
+- merge_commit: (pending — populated by validation-phase Step 7 after mw-docs)
+
 ## Feature Description
 {{user's description verbatim}}
 

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

@@ -162,9 +162,16 @@ Agent(
   prompt: """
     Generate backlog cards from the approved PRD.
 
-    PRD path: <prd_path>
-    State file path: <state_file_path>
-    Card template: .claude/skills/prd/assets/card-template.yml
+    WORKING_DIRECTORY: <$WORKTREE_PATH absolute path>
+    (Per HARD RULE 17 of /prd SKILL.md — all file writes must go inside this
+    directory, NOT into the consumer's main repo. See your "Working Directory"
+    section for the rule and sanity check.)
+
+    PRD path: <$WORKTREE_PATH>/<prd_path>
+    State file path: <$WORKTREE_PATH>/<state_file_path>
+    Card template: <$WORKTREE_PATH>/.claude/skills/prd/assets/card-template.yml
+      (the template is symlinked from .framework/ into the worktree just like
+      in the main repo — the symlink works inside the worktree)
     Feature slug: <slug>
 
     The PRD has been approved by the user. Read it in full, read the state file
@@ -175,7 +182,7 @@ Agent(
     error_handling, reuse_analysis). Populate them per your field-mapping instructions.
     Use Grep/Glob to verify file paths and line numbers for existing_patterns and reuse_analysis.
 
-    Write all card YAML files to backlog/.
+    Write all card YAML files to <$WORKTREE_PATH>/backlog/ (absolute path).
     Update the state file ## Backlog Cards section with card list and traceability matrices.
     Return the Parallel Execution Map summary.
   """,
@@ -183,6 +190,12 @@ Agent(
 )
 ```
 
+**Substitution rule.** In the prompt above, `<$WORKTREE_PATH>` is a textual
+placeholder — the `/prd` skill MUST replace it with the absolute path stored
+in the state file's `## Worktree` section BEFORE invoking the agent. Do NOT
+pass the literal string `$WORKTREE_PATH` — the subagent has no shell context
+to expand it.
+
 ### What the agent handles
 
 The `prd-card-writer` agent owns the entire card writing pipeline:

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

@@ -4,15 +4,36 @@
 
 Run BEFORE any other step.
 
-1. Check if `${paths.prd_dir}/sessions/` contains a state file for the current feature.
-2. If found: read it, identify last completed step, resume from next pending step.
-3. If not found: fresh session, proceed to Step 1.
-
-Triggers: session start, context compression, re-invocation of `/prd`.
+1. **Worktree lookup (since v3.22.0)** — read `.worktrees/registry.json` from
+   the main repo and scan for an entry with `kind: "docs"` whose `slug` matches
+   the feature the user just mentioned (or that you can infer from their
+   message — e.g., `/prd-add` for an active PRD).
+   - **Found**: `cd` into the worktree's `path` (save as `$WORKTREE_PATH`),
+     log "Resuming PRD session in worktree `<path>`", then continue to step 2.
+     All subsequent file paths in this skill resolve under `$WORKTREE_PATH`
+     (HARD RULE 17).
+   - **Not found, but main repo has a stale state file** at
+     `${paths.prd_dir}/sessions/*-<slug>-state.md`: this is a pre-v3.22.0 PRD
+     session created before the worktree mandate. ASK the user: "Found a
+     legacy PRD state file outside any worktree. Migrate it to a fresh docs
+     worktree before resuming, or continue on the main repo (legacy mode)?"
+     If migrate: create the worktree via `nw-docs`, `git mv` the relevant
+     files into it. If legacy mode: STOP and warn that parallel sessions
+     will pollute `git status`.
+   - **Not found and no state file**: fresh session, proceed to Step 1.
+2. With `$WORKTREE_PATH` resolved (or null for fresh sessions), check if
+   `$WORKTREE_PATH/${paths.prd_dir}/sessions/` contains a state file for the
+   current feature.
+3. If found: read it, identify last completed step, resume from next pending step.
+4. If not found: proceed to Step 1.
+
+Triggers: session start, context compression, re-invocation of `/prd`, every
+`/prd-add` invocation.
 
 ## Step 1 — Kickoff
 
-**Precondition:** user has described the feature.
+**Precondition:** user has described the feature; Step 0 ran and confirmed
+this is a fresh session (no existing state file).
 
 1. Derive `<slug>`: kebab-case, lowercase, max 40 chars, no special chars.
    Example: "Nutritional info on menu" -> `menu-nutritional-info`
@@ -22,16 +43,44 @@ Triggers: session start, context compression, re-invocation of `/prd`.
      `## Obsidian Spec Note: [[Note Name]]`. This will be added to Canonical Sources in the PRD.
    - Read the note content from the vault path in memory (`reference_obsidian_vault.md`)
      to pre-populate discovery dimensions where possible — treat it as a user-provided spec.
-3. Create state file: `${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
-   using template from `assets/state-template.md`.
-3. Create 5 macro-tasks via TaskCreate:
+3. **Create the docs worktree (MANDATORY — HARD RULE 17)** — invoke the
+   `worktree-manager` skill in programmatic docs mode BEFORE any file write:
+
+   ```
+   Skill: worktree-manager
+   Mode:  programmatic, nw-docs
+   Input: { "slug": "<slug>" }
+   ```
+
+   On success the skill returns `{ path, branch, kind: "docs" }`. Save
+   `path` as `$WORKTREE_PATH` for the entire session.
+
+   Verify the working directory is the worktree:
+
+   ```bash
+   cd "$WORKTREE_PATH"
+   pwd
+   # MUST print the absolute worktree path. If pwd shows the main repo root,
+   # STOP — every Write/Edit you make next will pollute the main checkout.
+   ```
+
+   **Failure handling.** If `nw-docs` fails (e.g., `.worktrees/` not in
+   `.gitignore`, slug already in registry as a non-docs entry, repo not
+   initialized), STOP and surface the error verbatim. Do NOT fall back to
+   writing on the main repo — that breaks HARD RULE 17.
+
+4. **Create state file** inside the worktree:
+   `$WORKTREE_PATH/${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
+   using template from `assets/state-template.md`. Populate the `## Worktree`
+   section with `path`, `branch`, `kind: docs`, `created_at` (ISO-8601 UTC).
+5. Create 5 macro-tasks via TaskCreate:
    - `[PRD] Discovery & comprensione feature`
    - `[PRD] Design UI & approvazione`
    - `[PRD] Conferma specifiche complete`
    - `[PRD] Creazione backlog cards`
-   - `[PRD] Validazione e commit`
-4. Mark task 1 as `in_progress`.
-5. **Context Loading (MANDATORY):** invoke the context-primer skill (`/cont`) with
+   - `[PRD] Validazione, commit & merge`
+6. Mark task 1 as `in_progress`.
+7. **Context Loading (MANDATORY):** invoke the context-primer skill (`/cont`) with
    2-4 keywords extracted from the user's feature description. This launches
    `codebase-architect` which searches the Obsidian-first LightRAG MCP index,
    docs, backlog, source code, and git history. The returned context informs all
@@ -39,10 +88,10 @@ Triggers: session start, context compression, re-invocation of `/prd`.
    feature domain. Use Obsidian hits for concept context, then verify
    implementation and stateful claims against repo docs/code before carrying
    them into the PRD.
-6. Mark clearly irrelevant dimensions as "N/A" with reason
+8. Mark clearly irrelevant dimensions as "N/A" with reason
    (e.g., backend-only -> UI impact = N/A).
    If UI impact is N/A, immediately mark task 2 as `completed` ("Skipped — no UI").
-7. **Business Rationale Extraction (MANDATORY):** Before entering the discovery loop,
+9. **Business Rationale Extraction (MANDATORY):** Before entering the discovery loop,
    evaluate the user's initial feature description for business rationale signals:
    - WHY is this feature needed? (business motivation)
    - What customer/market signal triggered it?
@@ -59,10 +108,16 @@ Triggers: session start, context compression, re-invocation of `/prd`.
 **Output:**
 
 ```
-Ho creato la sessione PRD per **<slug>**.
+Ho creato la sessione PRD per **<slug>** in un worktree dedicato.
 
+Worktree:    <relative-worktree-path>
+Branch:      prd/<slug>
 Descrizione: <user's description>
-Contesto caricato: <one-line summary from context-primer>
+Contesto:    <one-line summary from context-primer>
+
+Tutti i file del PRD vivono nel worktree — il main repo resta pulito.
+Al termine commit + merge automatico in develop + cleanup worktree, seamless.
+(Se in qualunque momento mi dici "non mergiare", mi fermo dopo il commit.)
 
 Ora comincio la fase di **Discovery** — ti faro delle domande per capire bene
 la feature prima di scrivere qualsiasi documento.
@@ -70,7 +125,9 @@ la feature prima di scrivere qualsiasi documento.
 <Progress Bar>
 ```
 
-**Gate:** state file exists on disk AND all tasks created AND context loaded.
+**Gate:** 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.
 
 **Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
 and ask the mockup intake question in the same turn.
@@ -86,7 +143,7 @@ result.
 
 ### 1.6.1 — Ask
 
-After the kickoff output (Step 1, point 7), append this question to the SAME message:
+After the kickoff output (Step 1, point 9 — Business Rationale Extraction is the final point of the Kickoff step since the v3.22.0 renumbering), append this question to the SAME message:
 
 ```
 ### Domanda — Mockup

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -118,6 +118,13 @@ The skill handles the full pipeline:
 
 When invoking `ui-design`, ensure it has access to:
 
+- **`WORKING_DIRECTORY`** — the absolute path of the PRD's docs worktree,
+  read from the state file `## Worktree` section. Pass it explicitly in the
+  args (e.g. `WORKING_DIRECTORY=<absolute-path-of-$WORKTREE_PATH>`) so the
+  skill's Step G saves `design.html` inside the worktree, not into the
+  consumer's main repo. Without this, the design lands on main, the `/prd`
+  Step 7 stage list can't find it, and the merged PRD ships without its
+  design asset. See `ui-design/SKILL.md` § "Working Directory" (added v3.22.0).
 - Feature description (from state file `## Feature Description`)
 - All discovery answers relevant to UI (from state file `## Discovery Log`)
 - The `<slug>` for file naming

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

@@ -49,34 +49,115 @@ Mark task 5 as `in_progress`.
 
 **Gate:** all HIGH/MEDIUM findings resolved, no open `[MANUAL]` items.
 
-## Step 7 — Resolution and Commit
+## Step 7 — Resolution, Commit & Merge
 
-**Precondition:** Step 6 complete.
+**Precondition:** Step 6 complete; the session is running inside a docs worktree
+created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
 
 ### Resolve remaining items
 
 1. If `[MANUAL]` items remain: resolve each one.
 2. If resolution required card re-edits: re-run the audit protocol (audit-phase.md) on affected cards.
 
-### Update knowledge base
-
-3. Add/update entry in `${paths.references_dir}/ssot-registry.md` pointing to the new PRD
-   as canonical source for this macro feature.
-4. Update `${paths.references_dir}/project-status.md` Active Code Context with PRD completion.
-
-### Commit
-
-5. Stage ONLY PRD session artifacts (explicit file names, never `git add .`):
-   - `${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
-   - `docs/prd/<slug>/PRD.md`
-   - `docs/prd/<slug>/design.html` (if exists)
-   - `backlog/FEAT-XXXX-*.yml` (all cards created in Step 5)
-   - `${paths.references_dir}/ssot-registry.md` (if updated)
-   - `${paths.references_dir}/project-status.md` (if updated)
-6. Update state file: status -> `completed`, add commit hash to `## Validation`.
-7. Commit with format: `[PRD] <slug>: <brief description>`
-
-**Gate:** commit successful, state file shows `completed`.
+### Update knowledge base (inside the worktree)
+
+3. Add/update entry in `$WORKTREE_PATH/${paths.references_dir}/ssot-registry.md`
+   pointing to the new PRD as canonical source for this macro feature. **Skip
+   when the file does not exist in the project** (some consumers don't maintain
+   one — check the path before writing).
+4. Update `$WORKTREE_PATH/${paths.references_dir}/project-status.md` Active Code
+   Context with PRD completion. **Skip when the file does not exist.**
+
+   **Note on cross-PRD collisions.** Both files (`ssot-registry.md` and
+   `project-status.md`) live on `develop` and are touched by other PRD sessions
+   in parallel. The rebase in step 8 below brings the worktree up to the latest
+   `origin/develop` BEFORE the merge, so two parallel PRDs ending at the same
+   time produce a clean append-only diff in most cases. If the rebase reports
+   conflicts on these two files specifically, the `worktree-manager mw-docs`
+   protocol stops and asks for manual resolution — do NOT auto-strip merge
+   markers on structured files like these.
+
+### Commit (inside the worktree)
+
+5. **Run the Metrics Log step from SKILL.md** ("Metrics Log — MANDATORY") FIRST
+   — it appends the run summary to `$WORKTREE_PATH/docs/metrics/skill-runs.jsonl`,
+   which must be part of the same commit. Non-blocking: if it fails, log
+   "Metrics Log: SKIPPED" in the progress bar and continue.
+
+6. Stage ONLY PRD session artefacts by explicit file name (NEVER `git add .`
+   or `git add -A`):
+   - `$WORKTREE_PATH/${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
+   - `$WORKTREE_PATH/${paths.prd_dir}/<slug>/PRD.md`
+   - `$WORKTREE_PATH/${paths.prd_dir}/<slug>/design.html` (if exists)
+   - `$WORKTREE_PATH/${paths.prd_dir}/<slug>/mockups/**` (if any)
+   - `$WORKTREE_PATH/${paths.backlog_dir}/FEAT-XXXX-*.yml` (all cards from Step 5)
+   - `$WORKTREE_PATH/${paths.references_dir}/ssot-registry.md` (if updated)
+   - `$WORKTREE_PATH/${paths.references_dir}/project-status.md` (if updated)
+   - `$WORKTREE_PATH/docs/metrics/skill-runs.jsonl` (if the Metrics Log step in 5 wrote a line)
+
+   Verify staged set with `git -C "$WORKTREE_PATH" diff --staged --name-only`.
+
+7. Update state file: status -> `completed`, add `worktree.branch`, will fill
+   commit hash after the commit lands.
+
+8. Commit with format: `[PRD] <slug>: <brief description>`
+   ```bash
+   git -C "$WORKTREE_PATH" commit -m "[PRD] <slug>: <brief description>"
+   ```
+   Capture the SHA via `git -C "$WORKTREE_PATH" rev-parse HEAD` and write it
+   back into the state file under `## Validation`.
+
+### Merge into develop (worktree-manager mw-docs)
+
+9. **Invoke `worktree-manager` programmatic mw-docs immediately** — no
+   confirmation prompt. The user opted into the full PRD pipeline when they
+   ran `/prd`; chiedere conferma a fine sessione è friction inutile e rompe
+   il "seamless" che è il punto della v3.22.0.
+
+   The merge is recoverable: if something goes wrong post-merge the user can
+   `git revert` on develop just like any other commit. The hard-to-reverse
+   operations (`git push`, branch deletion) happen inside `mw-docs` which
+   has its own failure handling (rebase abort, push rejection, gh CLI error)
+   — none of which silently corrupts state.
+
+   **Escape hatch.** If the user explicitly says "non mergiare" or "lascia il
+   worktree" at any point during Step 7 (e.g. they want to review the PRD
+   manually before it lands on develop), respect that and STOP after the
+   commit — the worktree stays on disk, ready for a future manual `/mw` or
+   `worktree-manager mw-docs`. This is a user-initiated override, not a
+   default gate.
+
+10. **Invoke `worktree-manager` programmatic mw-docs**:
+
+   ```
+   Skill: worktree-manager
+   Mode:  programmatic, mw-docs
+   Input: { "worktreePath": "$WORKTREE_PATH" }
+   ```
+
+   The skill executes:
+   - Safety commit (idempotent — likely no-op after step 8).
+   - `git fetch origin develop` + `git rebase origin/develop` inside the worktree.
+   - Conflict auto-resolution table (see `/mw` step 4b): additive docs/yaml and
+     append-only `.jsonl` files auto-resolve; **structured registries**
+     (`project-status.md`, `ssot-registry.md`, `field-registry.*`,
+     `traceability-matrix.md`, `REGISTRY.md`) abort the rebase and report —
+     these must be resolved manually because blindly stripping markers would
+     corrupt their internal structure.
+   - Merge via the configured `git.merge_strategy` (`pr` or `local-push`).
+   - Cleanup: `git worktree remove` + `git branch -d` + registry entry removal.
+   - Local develop ref sync (only if main repo HEAD is already `develop`).
+
+   On success it returns `{ merged: true, mergeCommit, prNumber, strategy,
+   worktreeRemoved: true }`.
+
+   **Failure handling.** If `mw-docs` reports failure (rebase conflicts, push
+   rejected, gh CLI error, post-cleanup error): STOP and surface the error
+   verbatim. The worktree stays on disk so the user can investigate. Do NOT
+   retry automatically — the next attempt should be user-driven.
+
+**Gate:** `mw-docs` returned `merged: true` AND `worktreeRemoved: true` AND
+the state file (now on `develop` via the merge) shows `completed`.
 
 Mark task 5 as `completed`.
 
@@ -84,9 +165,11 @@ Mark task 5 as `completed`.
 
 Print final summary:
 
-- PRD path
+- PRD path (relative to repo root, e.g. `docs/prd/<slug>/PRD.md`)
 - Design path (if applicable)
 - Card IDs created
-- Commit hash
+- Branch & merge strategy used
+- PR number (if `strategy = pr`) or merge SHA (if `local-push`)
+- Confirmation that the worktree was cleaned up
 
 Display completed Progress Bar.

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

@@ -64,11 +64,54 @@ Sequential, single-turn analysis + selective multi-turn re-execution.
 
 ## Step 0 — Session Locate
 
-1. List `${paths.prd_dir}/sessions/` for state files.
-2. If exactly ONE active session (status != `completed`): use it.
-3. If multiple active sessions: ask user which one.
-4. If zero sessions: inform user, suggest `/prd` instead.
-5. Read the state file AND the PRD document (if exists).
+**Since v3.22.0, active PRD sessions live inside docs worktrees** created by
+`/prd` Step 1 (HARD RULE 17 of `/prd` SKILL.md). The main repo's
+`${paths.prd_dir}/sessions/` may be EMPTY even when there are active sessions
+— each one lives at `<docs-worktree>/${paths.prd_dir}/sessions/`. This step
+must scan the worktree registry FIRST, then fall back to the main repo for
+legacy sessions.
+
+1. **Read `.worktrees/registry.json` from the main repo root.** Filter entries
+   with `kind: "docs"`. For each, list state files at
+   `<entry.path>/${paths.prd_dir}/sessions/*.md` and read the first line of
+   each to extract `status:` (or scan for `Status:` line — depends on
+   state-template.md format). Collect every state with `status != "completed"`
+   together with its `WORKING_DIRECTORY` = `<entry.path>` and `branch` =
+   `<entry.branch>`.
+
+2. **Also list `${paths.prd_dir}/sessions/` on the main repo** (legacy
+   pre-v3.22.0 sessions). Collect any state files there as candidates with
+   `WORKING_DIRECTORY` = main repo root.
+
+3. Merge the two lists. Behavior:
+   - **Exactly ONE active session**: use it. Save its `WORKING_DIRECTORY` and
+     `branch` for every subsequent step.
+   - **Multiple active sessions**: ask the user which one, surfacing
+     `WORKING_DIRECTORY` (worktree path or "main repo") in the choice list so
+     they know where the CR will be written.
+   - **Zero sessions**: inform user, suggest `/prd` instead.
+
+4. **`cd "$WORKING_DIRECTORY"`** before any read or write — every subsequent
+   step in this skill (intake → impact analysis → selective execution → delta
+   commit) MUST happen inside the selected session's directory.
+
+5. Read the state file AND the PRD document (if exists), both resolved under
+   `$WORKING_DIRECTORY`.
+
+6. **Worktree-mode side effects for the rest of the skill:**
+   - Step 5 "Delta Commit" stages files inside the worktree and commits with
+     `git -C "$WORKING_DIRECTORY" commit`. NEVER `git add` on the main repo.
+   - If `prd-card-writer` is re-invoked in Step 4 (Backlog Cards REDO), pass
+     `WORKING_DIRECTORY: $WORKING_DIRECTORY` in the prompt — same convention
+     as backlog-phase.md (see `framework/.claude/agents/prd-card-writer.md` §
+     "Working Directory").
+   - If `ui-design` is re-invoked in Step 4 (UI Design REDO), pass
+     `WORKING_DIRECTORY=$WORKING_DIRECTORY` as args — same convention as
+     ui-design-phase.md.
+   - The delta commit is NOT auto-merged. Document the new branch tip in the
+     `## Change Requests` section. The user merges with the rest of the PRD
+     when they run validation-phase.md Step 7 (`mw-docs` is invoked once per
+     PRD, not per CR).
 
 ---
 

package/framework/.claude/skills/ui-design/SKILL.md

@@ -28,6 +28,26 @@ Evaluation is always performed by a separate agent with fresh context.
 
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Working Directory (MANDATORY when invoked from `/prd`, since v3.22.0)
+
+When `/prd` Step 3 invokes this skill, the caller passes (or sets as cwd) an
+absolute **`WORKING_DIRECTORY`** that points to the PRD's docs worktree
+(e.g. `/Users/alice/proj/.worktrees/prd-menu-info`). All persistent design
+artefacts produced by this skill — most notably the `design.html` saved in
+Step G — MUST be written inside that directory, NOT into the consumer's main
+checkout. Without this, the design lands on the main repo, the `/prd` Step 7
+stage list at `$WORKTREE_PATH/${paths.prd_dir}/<slug>/design.html` finds
+nothing, and the PRD merged into `develop` ships without its design asset.
+
+**Rule:** every `${paths.prd_dir}/...` reference in this document — including
+Step G's "Copy approved HTML to `${paths.prd_dir}/<slug>/design.html`" — is
+relative to `WORKING_DIRECTORY` when invoked from `/prd`. Construct the
+absolute target path as `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`
+before any `Write`.
+
+**Standalone invocations** (when the user runs `/ui-design` directly, no PRD
+worktree): fall back to the consumer root. No prefix needed.
+
 ---
 
 ## Prerequisites — BLOCKING reads before ANY design work
@@ -141,7 +161,7 @@ Invoke a **separate** `code-reviewer` agent (NOT the same agent that generated):
 
 Read [references/inventory.md](references/inventory.md).
 
-1. Copy approved HTML to `${paths.prd_dir}/<slug>/design.html` (if `features.has_prd_workflow: true`; otherwise ask the user where to persist the design).
+1. Copy approved HTML to `${paths.prd_dir}/<slug>/design.html` (if `features.has_prd_workflow: true`; otherwise ask the user where to persist the design). **When invoked from `/prd` (since v3.22.0), prefix this with `WORKING_DIRECTORY` — see the "Working Directory" section near the top of this file.** Concrete absolute target: `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`.
 2. Extract UI Element Inventory (sprint contract).
 3. Update state file with chosen option, design decisions, component lists.
 4. Clean up `/tmp/prd-design-<slug>/`.

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -45,6 +45,207 @@ Output: `{ path: string, branch: string, port: number }`
 Input: `{ worktreePath: string, checksAlreadyPassed?: boolean }`
 Output: `{ merged: boolean, developVerified: boolean, prNumber: number|null, mergeCommit: string, strategy: "pr"|"local-push" }`
 
+## Programmatic API — docs mode (for /prd orchestrator)
+
+The docs mode is the **lean** counterpart to `/nw` and `/mw`. It is intentionally
+stripped down for skills that produce **documentation artefacts only** — PRDs,
+backlog cards, design references — and never touch source code.
+
+What docs mode SKIPS vs the standard flow:
+- No `npm install` (no `node_modules/` inside the worktree)
+- No port allocation (no dev server)
+- No `.env`/`.env.local` copy
+- No `npm run build` baseline verification
+- No lint / tsc baseline checks
+- No `--dev` server bootstrap
+- No build / lint / tsc gates at merge time
+
+What docs mode KEEPS:
+- Pre-flight `git fetch origin develop` (read-only on the main repo).
+- `git worktree add` branched from `origin/develop`.
+- Registry entry with `kind: "docs"` so `/lw` and `/cw` can list and clean docs worktrees alongside code worktrees.
+- Safety commit at merge time (uncommitted files are never lost).
+- Rebase onto `origin/develop` before merging (prevents PR/FF conflicts).
+- The configured `git.merge_strategy` (`pr` or `local-push`).
+- Cleanup of worktree + local branch + remote branch after merge.
+
+Cost target: **< 5 seconds** to create a docs worktree on a typical machine (no
+network beyond the `fetch`, no install, no build). Compare to `/nw` which can
+run for minutes due to `npm install` + build.
+
+### nw-docs programmatic
+
+Input:
+```json
+{
+  "slug": "string",            // REQUIRED — kebab-case feature slug
+  "branchPrefix": "string"     // OPTIONAL — defaults to "prd/"
+}
+```
+
+Output:
+```json
+{
+  "path": "string",            // absolute worktree path
+  "branch": "string",          // e.g. "prd/menu-nutritional-info"
+  "kind": "docs"
+}
+```
+
+**Steps (run exactly these, nothing else):**
+
+```bash
+# 0. Pre-flight: .gitignore safety check (MANDATORY — Safety Rules
+#    "Always verify .worktrees/ is in .gitignore before creating").
+#    Without this, the worktree IS git-tracked: `git status` on the main
+#    repo explodes with every file inside the worktree, exactly defeating
+#    the parallel-isolation purpose of the docs-mode.
+MAIN_ROOT="$(git rev-parse --show-toplevel)"
+if [ ! -f "$MAIN_ROOT/.gitignore" ] || ! grep -qE '^\.worktrees/?$' "$MAIN_ROOT/.gitignore"; then
+  echo "ERROR: .worktrees/ is not in $MAIN_ROOT/.gitignore" >&2
+  echo "Add it before running nw-docs:  echo '.worktrees/' >> .gitignore" >&2
+  echo "(or invoke this skill with --auto-ignore to append it for you — not yet implemented)" >&2
+  exit 1
+fi
+
+# 1. Pre-flight — read-only fetch, NEVER touches main repo HEAD
+git fetch origin develop
+
+# 2. Duplicate check — read registry; if an entry with the same slug AND kind=docs
+#    exists, return the existing { path, branch, kind } instead of creating a new
+#    one (resume semantics — Step 0 of /prd needs this).
+#    If an entry with same slug AND kind != "docs" exists (code worktree
+#    collision), fail loudly — never silently coexist.
+
+# 3. Create the worktree. The path returned MUST be ABSOLUTE — Claude Code's
+#    Write/Edit require absolute paths, and downstream skills (/prd, ui-design,
+#    prd-card-writer) interpolate this path verbatim.
+SLUG="<slug>"
+BRANCH_PREFIX="${branchPrefix:-prd/}"
+BRANCH="${BRANCH_PREFIX}${SLUG}"
+WORKTREE_REL=".worktrees/prd-${SLUG}"
+WORKTREE_PATH="$MAIN_ROOT/$WORKTREE_REL"   # absolute, anchored to main repo root
+git -C "$MAIN_ROOT" worktree add "$WORKTREE_REL" -b "$BRANCH" origin/develop
+
+# 4. Registry entry — kind: "docs", port: null, buildVerified: null
+#    Same registry file (.worktrees/registry.json) as code worktrees.
+#    The `path` field MUST hold $WORKTREE_PATH (absolute), not $WORKTREE_REL.
+```
+
+**Registry entry shape for docs worktrees:**
+
+```json
+{
+  "card": null,
+  "cards": [],
+  "groupParent": null,
+  "slug": "menu-nutritional-info",
+  "branch": "prd/menu-nutritional-info",
+  "path": "/abs/.worktrees/prd-menu-nutritional-info",
+  "port": null,
+  "kind": "docs",
+  "createdAt": "2026-05-27T10:00:00Z",
+  "envSyncedAt": null,
+  "buildVerified": null
+}
+```
+
+**Forbidden in docs mode**: `npm install`, port scan, `.env*` copy, `npm run build`,
+`npx tsc`, `npx eslint`, dev server start, `git checkout`/`switch`/`branch` on main.
+
+### mw-docs programmatic
+
+Input:
+```json
+{
+  "worktreePath": "string",    // REQUIRED — absolute path of the docs worktree
+  "commitMessage": "string"    // OPTIONAL — defaults to "[PRD] <slug>: <generated summary>"
+}
+```
+
+Output:
+```json
+{
+  "merged": true,
+  "mergeCommit": "string",                 // SHA of the merge commit (or branch tip in local-push)
+  "prNumber": null,                         // populated only when strategy = "pr"
+  "strategy": "pr" | "local-push",
+  "worktreeRemoved": true
+}
+```
+
+**Steps (run exactly these, nothing else):**
+
+```bash
+cd "$WORKTREE_PATH"
+
+# 1. Safety commit (MANDATORY — same as /mw step 3, never skippable).
+#    Stage every changed and untracked file by explicit name, then commit.
+#    For docs worktrees the staged set is typically:
+#      - ${paths.prd_dir}/<slug>/PRD.md
+#      - ${paths.prd_dir}/<slug>/design.html (if exists)
+#      - ${paths.prd_dir}/<slug>/mockups/** (if any)
+#      - ${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md
+#      - ${paths.backlog_dir}/FEAT-XXXX-*.yml (all cards)
+#      - ${paths.references_dir}/ssot-registry.md  (if updated by Step 7)
+#      - ${paths.references_dir}/project-status.md (if updated by Step 7)
+#    NEVER `git add .` or `git add -A`. NEVER `git stash` (see Safety Rules).
+
+# 2. Rebase onto latest develop. Reuses the /mw step 4b conflict-resolution
+#    table (additive auto-strip for docs/yaml/jsonl-in-docs-metrics; abort on
+#    structured registries when validation fails; abort on code/tests/fixtures).
+#
+#    IMPORTANT — NO `git stash` in mw-docs. The safety commit in step 1
+#    above guarantees a clean working tree, so the stash logic at the top of
+#    /mw step 4b ("stash dirty files before rebase, pop after") is a no-op
+#    for mw-docs and must be SKIPPED. Running `git stash push` from a
+#    worktree violates the Safety Rule "NEVER use git stash in worktrees"
+#    (refs/stash is shared across all worktrees via git.commondir — see the
+#    FEAT-0522 incident note). Two parallel mw-docs runs that both stash
+#    would race on the shared stash list and could pop into the wrong tree.
+#
+#    Direct rebase, no stash. If the working tree is unexpectedly dirty here
+#    (someone wrote between step 1 and step 2), STOP and report — a second
+#    safety commit would be the right answer, never a stash.
+DIRTY=$(git -C "$WORKTREE_PATH" status --porcelain 2>/dev/null)
+if [ -n "$DIRTY" ]; then
+  echo "ERROR: working tree dirty in $WORKTREE_PATH after safety commit." >&2
+  echo "Files: $DIRTY" >&2
+  echo "Investigate — never stash to recover (refs/stash shared across worktrees)." >&2
+  exit 1
+fi
+git -C "$WORKTREE_PATH" fetch origin develop
+git -C "$WORKTREE_PATH" rebase origin/develop
+# (apply /mw 4b conflict-resolution table if rebase reports conflicts)
+
+# 3. Land on develop — reuse /mw step 4c verbatim. Read git.merge_strategy from
+#    baldart.config.yml. NEVER `git checkout develop` on the main repo.
+#    - pr        → gh pr create + gh pr merge --merge --delete-branch
+#    - local-push → git push origin <branch>:develop (fast-forward only)
+#
+#    Note: many consumers prefer `local-push` for docs worktrees specifically,
+#    because a PRD is rarely worth a GitHub PR roundtrip. The CLI does not
+#    differentiate — it respects the project's configured strategy. If the user
+#    wants per-skill strategy, they should override via overlay (.baldart/overlays/prd.md).
+
+# 4. Cleanup — reuse /mw step 6 verbatim (worktree remove + branch -d + prune).
+#    Skip /mw step 5 (post-merge `npm run build`) — docs worktrees have nothing
+#    to build.
+
+# 5. Sync local develop ref — reuse /mw "Common" block: ff-only pull when main
+#    repo HEAD is already develop; otherwise just fetch.
+
+# 6. Remove the registry entry for this worktree.
+```
+
+**Forbidden in docs merge**: pre-merge `npm run build`, `npx eslint`, `npx tsc`, `npm run test`, post-merge `npm run build`. The whole point of docs mode is that these gates are inapplicable.
+
+**Failure handling**: if the safety commit, rebase, or merge fails, STOP and
+report — do NOT proceed to cleanup. The worktree must stay on disk so the user
+can investigate. Cleanup runs only after a successful merge.
+
+---
+
 The merge path depends on `git.merge_strategy` in `baldart.config.yml`:
 - `pr` (default, since v3.4.0): merge via `gh pr create` + `gh pr merge`. `prNumber` is the PR number, `mergeCommit` is the SHA returned by the GitHub merge API.
 - `local-push` (since v3.9.0): direct fast-forward push of the rebased feature branch to `origin/develop` — no PR, no `gh`. `prNumber` is `null`, `mergeCommit` is the local SHA of the feature branch tip.
@@ -412,25 +613,97 @@ fi
 CONFLICTED=$(git diff --name-only --diff-filter=U)
 ```
 
-Categorize each conflicted file and resolve:
-
-| Category | Patterns | Action |
-|----------|----------|--------|
-| **Docs/config** | `docs/**/*.md`, `backlog/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` | Auto-resolve: strip markers, keep both sides |
-| **Code** | `src/**/*.ts`, `*.tsx`, `*.js`, `*.jsx` | STOP — abort rebase, report to user |
-| **Tests** | `*.test.*`, `*.spec.*` | Manual only — report to user |
+Categorize each conflicted file and resolve. **Per-file rule of thumb**:
+auto-resolve only when "keep both sides" is semantically additive (markdown
+bullet lists, YAML lists, JSONL append-only logs); abort on anything with
+internal structure (tables, key/value blocks, code).
+
+| Category | Patterns | Action | Note |
+|----------|----------|--------|------|
+| **Structured registries** | `project-status.md`, `ssot-registry.md`, `field-registry.*`, `traceability-matrix.md`, `REGISTRY.md` | Strip markers, then **structural validation** — if valid, accept; if invalid, abort | The auto-strip "keep both sides" usually produces an additive result (new bullet rows appended to a table or section). The validation step catches the rare case where the two sides modified the same row. See `validate_structured_md` below. |
+| **JSONL logs under `docs/metrics/`** | `docs/metrics/*.jsonl`, `docs/metrics/**/*.jsonl` | Auto-resolve: strip markers, keep both sides | JSONL is line-oriented and additive — duplicating both branches' lines yields a valid file. |
+| **Other `.jsonl`** | `*.jsonl` outside `docs/metrics/` | STOP — abort and report | Fixtures, seeds, training data: auto-strip can corrupt them. The user must inspect. |
+| **Docs/config** | `docs/**/*.md`, `backlog/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` (excluding rows above) | Auto-resolve: strip markers, keep both sides | The canonical additive case. |
+| **Code** | `src/**/*.ts`, `*.tsx`, `*.js`, `*.jsx` | STOP — abort rebase, report to user | |
+| **Tests** | `*.test.*`, `*.spec.*` | Manual only — report to user | |
+
+The "Structured registries" row replaces the v3.22.0-initial blanket-abort
+behaviour. The blanket abort regressed the `/new` flow (every multi-card batch
+that updates `ssot-registry.md` would fail rebase); the validation-based
+approach restores the additive merge for the routine case while still
+catching genuine corruption.
 
 ```bash
+# Helper: validate that a structured markdown file is still parseable after
+# auto-strip. Cheap heuristics; returns 0 if file looks structurally intact.
+validate_structured_md() {
+  local f="$1"
+  # Reject if any residual conflict markers (shouldn't happen after sed)
+  if grep -qE '^(<{7}|={7}|>{7})' "$f"; then return 1; fi
+  # Reject if a top-level markdown table got duplicated header rows back-to-back
+  # (two `|---|---|` separator lines in a row = malformed table).
+  if awk 'prev~/^\|[ -:|]+\|$/ && $0~/^\|[ -:|]+\|$/{found=1; exit} {prev=$0} END{exit !found}' "$f"; then
+    return 1
+  fi
+  # Reject if a YAML frontmatter block (--- ... ---) got duplicated.
+  if [ "$(grep -cE '^---[[:space:]]*$' "$f")" -gt 2 ]; then return 1; fi
+  return 0
+}
+
 for FILE in $CONFLICTED; do
+  BASENAME=$(basename "$FILE")
+
+  # 1. Code / tests — always abort
   case "$FILE" in
     src/*.ts|src/*.tsx|src/*.js|src/*.jsx|*.test.*|*.spec.*)
-      # Code or test conflict — abort and report
       git rebase --abort
+      # When invoked from /mw (code worktree) a stash may have been created
+      # at the start of step 4b. Pop it back. mw-docs never stashes
+      # (safety commit step 1 leaves the tree clean) so the pop is a no-op.
       git stash pop 2>/dev/null || true
       echo "CONFLICT in $FILE — cannot auto-resolve" >&2
       exit 1 ;;
+  esac
+
+  # 2. Structured registries — strip + structural validation
+  case "$BASENAME" in
+    project-status.md|ssot-registry.md|traceability-matrix.md|REGISTRY.md)
+      sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
+      if ! validate_structured_md "$FILE"; then
+        git checkout --conflict=merge "$FILE" 2>/dev/null || true
+        git rebase --abort
+        git stash pop 2>/dev/null || true
+        echo "CONFLICT in structured registry $FILE produced invalid structure after auto-strip — manual resolution required." >&2
+        exit 1
+      fi
+      git add "$FILE"
+      continue ;;
+  esac
+  case "$BASENAME" in
+    field-registry.*)
+      # field-registry.json typically — strict JSON, can't auto-strip safely
+      git rebase --abort
+      git stash pop 2>/dev/null || true
+      echo "CONFLICT in structured registry $FILE — JSON cannot be auto-stripped." >&2
+      exit 1 ;;
+  esac
+
+  # 3. JSONL — only auto-resolve under docs/metrics/
+  case "$FILE" in
+    docs/metrics/*.jsonl|docs/metrics/**/*.jsonl)
+      sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
+      git add "$FILE"
+      continue ;;
+    *.jsonl)
+      git rebase --abort
+      git stash pop 2>/dev/null || true
+      echo "CONFLICT in $FILE (.jsonl outside docs/metrics/ — may be fixture/seed) — manual resolution required." >&2
+      exit 1 ;;
+  esac
+
+  # 4. Generic docs/config — additive merge
+  case "$FILE" in
     docs/*|backlog/*|*.md|*.json|*.yml)
-      # Doc/config conflict — auto-resolve keeping both sides
       sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
       git add "$FILE" ;;
   esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.21.2",
+  "version": "3.22.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"