baldart 3.40.0 → 4.0.0

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

@@ -91,8 +91,8 @@ dimension from the discovery checklist. Pick exactly one branch:
 | UI impact = N/A | **Skip totale** | Mark task 2 `completed` ("Skipped — no UI"). `step_3_mode: skipped`. Proceed to PRD Writing Phase. |
 | `mockups.status: none` AND UI impact ≠ N/A | **3.0 Decision** | Run Step 3.0 above first. Branch A ⇒ fall through to **Full**; Branch B ⇒ STOP, then re-enter. |
 | `mockups.status: pending_external` | **STOP** | User is in handoff with Claude Design. Do not advance until paths arrive (see § "Re-entry from handoff"). |
-| `mockups.status: none` AND user picked Branch A in Step 3.0 | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
-| `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `skipped` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations`). |
+| `mockups.status: none` AND `mockups.source: internal` | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d → 3e as below. `step_3_mode: full`. |
+| `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `mockup-only` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations` — distinct from `skipped`, which means no UI at all). |
 
 Mark task 2 as `in_progress` for the Full and Hybrid branches.
 
@@ -110,9 +110,10 @@ The skill handles the full pipeline:
 | PRD Step | ui-design Skill Step | What happens |
 |----------|---------------------|--------------|
 | 3a — UI Context Analysis | Steps A + B | Component discovery, context screenshots, codebase analysis |
-| 3b — 3 Design Options | Steps C + D + E | Generate 3 HTML mockups, evaluate with separate agent, open in Safari |
+| 3b — 3 Design Options | Steps C + D + E | Generate 3 HTML mockups, evaluate with separate `ui-expert` agent, open in Safari |
 | 3c — Design Iteration | Step F | User feedback loop with re-evaluation |
 | 3d — Save & Inventory | Step G | Save design.html, extract UI Element Inventory |
+| 3e — Registry Coherence | **Step H** | Post-Intervention Coherence Check — BLOCKING when `features.has_design_system: true`; surfaces `DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` findings; must pass before task 2 is marked `completed` |
 
 ### What to pass to the skill
 
@@ -135,8 +136,9 @@ When invoking `ui-design`, ensure it has access to:
 Before invoking `ui-design`:
 
 1. Read `${paths.references_dir}/component-registry.md`.
-2. From feature description, identify UI elements likely needed (tables, forms, modals, etc.).
-3. Match against registry. Pass results to `ui-design`:
+2. When `features.has_design_system: true`, ALSO read `${paths.design_system}/INDEX.md` (component index + authority matrix) — required by HARD RULE 14 in `prd/SKILL.md` and by the BLOCKING cascade in `ui-design/SKILL.md`. Skipping this read is a protocol violation.
+3. From feature description, identify UI elements likely needed (tables, forms, modals, etc.).
+4. Match against both registries. Pass results to `ui-design`:
 
 ```
 ### Existing Components (from component-registry.md)
@@ -154,8 +156,12 @@ This prevents designing new components when 450+ reusable ones already exist.
 - **After Step 3b:** all 3 polished options open in Safari AND screenshots shown inline.
   **STOP.** Wait for user to choose.
 - **After Step 3c:** explicit user approval ("confermo", "va bene", "ok").
-- **After Step 3d:** `docs/prd/<slug>/design.html` exists AND `## UI Element Inventory`
+- **After Step 3d:** `${paths.prd_dir}/<slug>/design.html` exists (inside `$WORKTREE_PATH`) AND `## UI Element Inventory`
   is populated in the state file with at least 3 elements.
+- **After Step 3e (BLOCKING when `features.has_design_system: true`):** ui-design Step H
+  (Post-Intervention Coherence Check) must complete with no unresolved `DS_INDEX_DRIFT` /
+  `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` findings (or every finding explicitly waived
+  by the user and logged as such). Do NOT mark task 2 `completed` until this gate clears.
 
 Mark task 2 as `completed`. Update state file status to `specs-confirmed`.
 
@@ -224,8 +230,8 @@ to the design system, approve, and inventory. Generate ONLY the screens not cove
      also ran. If at least one new screen was generated, the merged `design.html`
      includes both the new mockups and embeds/links to the existing ones.
    - For all-covered runs (`generated_in_step_3b: false` everywhere): set
-     `design.html_path: n/a (mockup-only)` in the state file; the PRD will link
-     directly to `${paths.prd_dir}/<slug>/mockups/`.
+     `design.html_path: n/a (mockup-only)` and `step_3_mode: mockup-only` in the state file;
+     the PRD will link directly to `${paths.prd_dir}/<slug>/mockups/`.
    - Update `## UI Element Inventory` in the state file with at least one row per
      covered screen + per generated screen.
 
@@ -239,6 +245,12 @@ to the design system, approve, and inventory. Generate ONLY the screens not cove
   swapped in the inventory) or explicitly waived by the user (logged as such).
 - **After 3d:** UI Element Inventory populated with at least one row per screen in
   `screens_in_scope[]`. `design.html_path` set OR `mockup-only` flag recorded.
+- **After 3e — Registry Coherence (BLOCKING when `features.has_design_system: true`):**
+  ui-design Step H (Post-Intervention Coherence Check) must complete with no
+  unresolved `DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` findings
+  (or every finding explicitly waived by the user and logged as such). Applies to
+  all Hybrid sub-modes (`hybrid`, `mockup-only`). Do NOT mark task 2 `completed`
+  until this gate clears.
 
 Mark task 2 as `completed`. Update state file status to `specs-confirmed`.
 

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

@@ -2,11 +2,11 @@
 
 ## Step 6 — Quality Audit
 
-**Precondition:** Backlog cards approved.
+**Precondition:** Backlog cards have been generated by `backlog-phase.md` and the user has not explicitly asked to abort. (There is no separate approval gate in the `/prd` flow; execution proceeds automatically from Step 5.)
 
 Mark task 5 as `in_progress`.
 
-0. **Agent Specialization Audit (runs FIRST — blocks if any failure)** — for each generated child card (epics are skipped):
+0. **Agent Specialization Audit (runs FIRST, blocks if any failure)** — for each generated child card (epics are skipped):
 
    a. **`owner_agent` enum check (BLOCKING)** — read the `owner_agent` field. It MUST equal one of:
       ```
@@ -22,7 +22,7 @@ Mark task 5 as `in_progress`.
       - For each marker hit, log a WARN line in the audit output:
         `"[UI-SCOPE-WARN] Card <ID> (ui-expert) mentions '<marker>' — review whether logic belongs in a sibling coder card. See backlog-phase.md § Rule B."`
       - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
-      - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected.
+      - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected. **[SEMANTIC — not purely deterministic]** Determining whether a marker substring is (a) inside a YAML quoted string and (b) that string contains one of the escape phrases requires contextual interpretation across multiple YAML quoting styles (single-quote, double-quote, block scalar). FP posture: when in doubt, log the WARN and let the human decide — do not suppress a WARN based on uncertain quoting analysis.
 
    c. **`review_profile` enum check (BLOCKING)** — read the `review_profile` field on each child card. It MUST equal one of:
       ```
@@ -30,12 +30,12 @@ Mark task 5 as `in_progress`.
       ```
       - **Missing or empty** = **BLOCKER** — the card-writer must compute it via `prd-card-writer.md § Rule C` (the SSOT mapping table). Message: `"Card <ID> has no review_profile — compute it from Rule C (skip|light|balanced|deep) before commit."`
       - **Out-of-enum value** = **BLOCKER**. Message: `"Card <ID> has review_profile: '<value>' — must be one of {skip, light, balanced, deep}."`
-      - **Consistency WARN (soft)**: a `feature`/`enhancement` card with `review_profile: light` violates Rule C ("never light for feature/enhancement"). Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — Rule C floors these at balanced."` and bump to `balanced` unless the author left an explicit override note.
+      - **Consistency WARN (soft)**: a `feature`/`enhancement` card with `review_profile: light` may violate Rule C. Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — verify against Rule C in prd-card-writer.md."` **Do NOT auto-bump the field** — `review_profile` is computed by `prd-card-writer` (Rule C); see `prd-card-writer.md` for the criteria. This is a soft gate: log the warning and surface it for human review.
       - **Epics**: `review_profile` MUST be `skip` (trackers have no code work). Any other value = WARN, normalize to `skip`.
 
    **Gate**: every card has `owner_agent` AND `review_profile` in their enums. WARN entries from checks (b)/(c) are noted in the audit log; user may accept them after review.
 
-1. **Field Name Audit (runs BEFORE audit agents)** — for each generated card:
+1. **Field Name Audit (runs after item 0 — only when item 0 passes for a given card; skipped for cards blocked in item 0)** — for each generated card:
 
    a. Verify every `data_fields` entry has `ts_verified: true` OR `status: new` with `schema_ref`.
    b. For cards with `estimated_complexity: HIGH` or `MEDIUM`:
@@ -54,19 +54,27 @@ Mark task 5 as `in_progress`.
    Then execute the audit protocol described within, using the card IDs from Step 5.
    The protocol auto-detects which agents to include (security and performance
    are signal-triggered, no manual profile selection needed).
+   **I/O contract:** `audit-phase.md` may edit card YAML files (e.g. its Step 6.9 normalisation pass). The list of all card paths modified by the audit (including those edited in Step 6.9) is the complete set that Step 7 item 6 must stage. The glob `FEAT-XXXX-*.yml (all cards from Step 5)` in item 6 covers this; note it explicitly so that context compaction does not cause a model to stage only the pre-audit originals.
 3. Wait for audit report and card edits.
 
-**Gate:** all HIGH/MEDIUM findings resolved, no open `[MANUAL]` items.
+**Gate:** all HIGH/MEDIUM findings resolved, no open `[MANUAL]` items that require external human input beyond this orchestrator. (Items that the orchestrator can resolve autonomously are resolved before this gate; items that need a human decision were already routed to `AskUserQuestion` inside `audit-phase.md`. Items that survive to Step 7 item 1 are those that received a human answer but required card re-edits — these are explicitly handled there.)
 
 ## Step 7 — Resolution, Commit & Merge
 
 **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.
 
+**Variable guard (R6).** Before executing any item in Step 7, resolve and verify:
+- `$WORKTREE_PATH` — read from the state file `## Worktree / path:`. HALT with `"ABORT: WORKTREE_PATH not set in state file — cannot commit or merge."` if absent or empty.
+- `$MAIN` — the absolute path of the main (non-worktree) git repository root. **READ the persisted value from the state file `## Worktree / main_path:`** (written at SKILL.md Step 1, the R6 persist-then-read pattern `/new` uses). HALT with `"ABORT: MAIN absent from state — re-run from a session whose Step 1 persisted main_path."` if the field is absent or empty. Only when the field is genuinely missing (legacy state file) FALL BACK to deriving it once via `git -C "$WORKTREE_PATH" rev-parse --git-common-dir` (strips `/.git`). Every subsequent `git` command that runs outside the worktree MUST use `git -C "$MAIN" …`; never use a bare `git` command whose cwd is undefined. (This is the same variable name and resolution contract `/new` uses — the two skills must agree.)
+
 ### Resolve remaining items
 
-1. If `[MANUAL]` items remain: resolve each one.
+1. If `[MANUAL]` items remain: resolve each one. (These are items that the orchestrator could not auto-resolve in Step 6 and whose human decision was provided via `AskUserQuestion` — they survived the Step 6 gate legally. See gate text above.)
 2. If resolution required card re-edits: re-run the audit protocol (audit-phase.md) on affected cards.
+   **Re-audit iteration cap:** maximum 2 re-audit iterations. If HIGH/MEDIUM findings or open `[MANUAL]` items persist after iteration 2, raise ONE `AskUserQuestion`:
+   - Question: `"After 2 re-audit rounds, <N> finding(s) remain unresolved. Options: [Accept remaining findings and proceed to commit] / [Abort this PRD session] / [Show me the findings and decide]"`
+   Act on the answer; do not continue looping silently.
 
 ### Update knowledge base (inside the worktree)
 
@@ -78,12 +86,12 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    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, `worktree-manager mw-docs` does **not** ask
-   immediately: it strips the markers ("keep both sides", which on append-only
+   `project-status.md`) live on `git.trunk_branch` and are touched by other PRD
+   sessions in parallel. The rebase in step 8 below brings the worktree up to the
+   latest `origin/git.trunk_branch` 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, `worktree-manager mw-docs` does **not**
+   ask immediately: it strips the markers ("keep both sides", which on append-only
    registries is the correct additive result) and then runs a structural
    validation. The merge proceeds automatically when the validation passes. It
    escalates to the user **only** in the rare case where both PRDs modified the
@@ -92,10 +100,10 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
 
 ### 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.
+5. **Run the Metrics Log step from SKILL.md** ("Metrics Log — MONITORING SIGNAL, non-blocking") FIRST
+   — it appends the run summary to `$WORKTREE_PATH/${paths.metrics}/skill-runs.jsonl`
+   (`paths.metrics` default: `docs/metrics`), 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`):
@@ -104,53 +112,55 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    - `$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)
+   - `$WORKTREE_PATH/${paths.references_dir}/ssot-registry.md` (only if item 3 wrote the file)
+   - `$WORKTREE_PATH/${paths.references_dir}/project-status.md` (only if item 4 wrote the file)
+   - `$WORKTREE_PATH/${paths.metrics}/skill-runs.jsonl` (only if the Metrics Log step in 5 wrote a line)
+   - `$WORKTREE_PATH/${paths.metrics}/sessions/prd-<slug>.md` (only if `-stats` was active and the sessions file was written)
 
    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.
+7. Update state file: status -> `committing`, add `worktree.branch`.
+   (Status is set to `committing` — not `completed` — so that if the commit in
+   item 8 fails, any subsequent `/prd` recovery session sees an incomplete run
+   rather than a false `completed` with no SHA.)
 
 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, no "vuoi che mergi e pulisca il worktree?" question.
-   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. Merge **and** worktree cleanup run automatically.
-
-   **The ONLY thing that stops the automatic merge is a conflict `mw-docs`
-   genuinely cannot auto-resolve** (a code/test conflict, or a structured
-   registry whose strip+validate failed — see step 10). Everything `mw-docs`
-   can auto-resolve (additive docs/YAML/JSONL, append-only registries that pass
+   After the commit succeeds: capture the SHA via `git -C "$WORKTREE_PATH" rev-parse HEAD`,
+   then update the state file atomically: status -> `completed`, write the SHA
+   under `## Validation`. If the commit fails, leave status as `committing` and
+   HALT with the git error verbatim.
+
+### Merge into `git.trunk_branch` (worktree-manager mw-docs)
+
+9. **Invoke `worktree-manager` programmatic mw-docs** — no confirmation prompt.
+   The user opted into the full PRD pipeline when they ran `/prd`; asking for
+   confirmation at the end is unnecessary friction and breaks the seamless
+   flow (v3.22.0 design intent). Merge and worktree cleanup run automatically.
+
+   **Why:** the ONLY thing that stops the automatic merge is a conflict
+   `mw-docs` genuinely cannot auto-resolve (a code/test conflict, or a
+   structured registry whose strip+validate failed). Everything `mw-docs` can
+   auto-resolve (additive docs/YAML/JSONL, append-only registries that pass
    validation) merges with zero questions. Do NOT pre-empt the merge with a
    confirmation gate "just in case there might be conflicts" — let `mw-docs`
    run and only surface what it actually reports as unresolvable.
 
    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
+   `git revert` on `git.trunk_branch` 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
+   **Escape hatch.** If the user explicitly says "do not merge" or "leave the
+   worktree" at any point during Step 7, 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**:
-
+   **Invocation (one call only):**
    ```
    Skill: worktree-manager
    Mode:  programmatic, mw-docs
@@ -158,8 +168,11 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    ```
 
    The skill executes:
-   - Safety commit (idempotent — likely no-op after step 8).
-   - `git fetch origin develop` + `git rebase origin/develop` inside the worktree.
+   - Safety commit (idempotent — likely no-op after step 8; if any file was
+     missed by item 6's explicit list, the safety commit picks it up, but the
+     tip commit message will be the safety message rather than `[PRD] …`. To
+     avoid this, ensure item 6 stages every file written in Steps 5-7).
+   - `git fetch origin git.trunk_branch` + `git rebase origin/git.trunk_branch` 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.*`,
@@ -169,7 +182,7 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
      conflicts always abort and escalate.
    - 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`).
+   - Local `git.trunk_branch` ref sync (only if main repo HEAD is already on `git.trunk_branch`).
 
    On success it returns `{ merged: true, mergeCommit, prNumber, strategy,
    worktreeRemoved: true }`.
@@ -180,48 +193,59 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    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`.
+`strategy` is one of `pr` or `local-push` (well-formedness check — ensures
+the return object is complete before the final summary reads it) AND the
+state file (now on `git.trunk_branch` via the merge) shows `completed`.
 
 Mark task 5 as `completed`.
 
 ### Step 7.5 — Workspace hygiene & finalization (BLOCKING — the run MUST conclude clean)
 
 **Why this exists (v3.39.0).** A PRD run used to end by handing the user a list of
-"azioni tue, non bloccanti" — an uncommitted file blocking the local `develop`
+"non-blocking manual actions" — an uncommitted file blocking the local `git.trunk_branch`
 fast-forward, a remote branch left undeleted. That is a half-finished process.
 `/prd` now closes the loop exactly like `/new` Phase 6c: **no residue is ever
 surfaced as a passive manual TODO.** Every leftover is either auto-resolved or put
 behind ONE explicit `AskUserQuestion` gate.
 
+**Requires `$MAIN`** (resolved in the Step 7 variable guard above).
+
 Scan the captured `mw-docs` stdout (the merge step above) for the structured
 markers it can emit, then act:
 
-1. **`[SYNC-NEEDS-DECISION] …`** — the local `develop` could not fast-forward and
-   the blocker is a **foreign** uncommitted file (one this run does not own), or a
-   genuine divergence/rebase conflict. Do NOT auto-commit foreign work. Raise ONE
-   `AskUserQuestion`:
-   - Question: `"Il develop locale non si è sincronizzato: <dettaglio dal marker>. Come chiudo?"`
-   - Options: `[Committa tu adesso (descrivi cosa)]` / `[Lo gestisco io — chiudi senza sync locale]` / `[Mostrami il diff e decidiamo]`.
+1. **`[SYNC-NEEDS-DECISION] …`** — the local `git.trunk_branch` could not
+   fast-forward and the blocker is a **foreign** uncommitted file (one this run
+   does not own), or a genuine divergence/rebase conflict. Do NOT auto-commit
+   foreign work. Raise ONE `AskUserQuestion`:
+   - Question: `"Local <git.trunk_branch> did not sync: <detail from marker>. How should we close?"`
+   - Options: `[Commit the pending file now (describe it)]` / `[I will handle it — close without local sync]` / `[Show me the diff and we decide]`.
    Act on the answer in this turn. Never leave it as a printed note.
 
-2. **`[SYNC-DEFERRED] …`** (main repo HEAD ≠ `develop`) — fetch already updated
-   `refs/remotes/origin/develop`. If the user's HEAD is now `develop`, run
-   `git -C "$MAIN" pull --ff-only origin develop`. Otherwise raise ONE
-   `AskUserQuestion` (`[ff-pull adesso]` / `[Lascio deferred, riconcilio io]`).
+2. **`[SYNC-DEFERRED] …`** (main repo HEAD ≠ `git.trunk_branch`) — fetch already
+   updated `refs/remotes/origin/git.trunk_branch`. If the user's HEAD is now
+   `git.trunk_branch`, run `git -C "$MAIN" pull --ff-only origin git.trunk_branch`.
+   Otherwise raise ONE `AskUserQuestion`:
+   `[Pull now (fast-forward only)]` / `[Leave deferred, I will reconcile]`.
 
 3. **No marker** — `mw-docs` already fast-forwarded (or auto-reconciled the
-   framework telemetry log). Nothing to do; the tree is clean.
+   framework telemetry log). If `mw-docs` stdout contains the auto-reconcile
+   message (`✅ Reconciled stale metrics log…`), check whether local
+   `git.trunk_branch` is 1 commit ahead of `origin/git.trunk_branch`
+   (`git -C "$MAIN" status --porcelain -b`). If it is, run
+   `git -C "$MAIN" push origin git.trunk_branch`. On push failure, treat
+   as a `[SYNC-NEEDS-DECISION]` case.
+   If neither condition applies: nothing to do; the tree is clean.
 
 4. **Remote feature branch** — `mw-docs` deletes the merged remote branch as
    routine cleanup (see AGENTS.md § branch deletion: deleting an **already-merged**
    feature branch is NOT the gated "branch deletion" that needs owner approval).
-   If for any reason the deletion was blocked, do NOT print "puoi cancellarlo a
-   mano": run `git push origin --delete <branch>` now, and only if THAT is denied
-   raise ONE `AskUserQuestion`.
+   If for any reason the deletion was blocked, do NOT print "you can delete it
+   manually": run `git -C "$MAIN" push origin --delete <branch>` now,
+   and only if THAT is denied raise ONE `AskUserQuestion`.
 
-**Gate:** `git -C "$MAIN" status --porcelain` for framework-owned paths is empty,
-no `[SYNC-NEEDS-DECISION]` marker is left unhandled, and the merged remote branch
-is gone (or its deletion is explicitly user-deferred).
+**Gate:** `git -C "$MAIN" status --porcelain` for framework-owned paths is
+empty, no `[SYNC-NEEDS-DECISION]` marker is left unhandled, and the merged remote
+branch is gone (or its deletion is explicitly user-deferred).
 
 ### Final output
 
@@ -234,11 +258,12 @@ Print final summary:
 - PR number (if `strategy = pr`) or merge SHA (if `local-push`)
 - Confirmation that the worktree was cleaned up AND the remote branch was deleted
 
-**HARD RULE — no passive deferral.** The final summary MUST NOT contain a "azioni
-tue / note non bloccanti / puoi farlo a mano" section. If something genuinely needs
-the user, it was already raised as an `AskUserQuestion` in Step 7.5 and acted on —
-it does not reappear here as a TODO. A run that prints "il develop locale non si è
-fast-forwardato, gestisci tu il file e poi pulla" has FAILED Step 7.5 — go back and
-resolve it before printing the summary.
+**HARD RULE — no passive deferral.** The final summary MUST NOT contain a
+"your manual actions / non-blocking notes / you can do it yourself" section.
+If something genuinely needed the user, it was already raised as an
+`AskUserQuestion` in Step 7.5 and acted on — it does not reappear here as a TODO.
+A run that prints "local `git.trunk_branch` did not fast-forward, handle the file
+yourself and then pull" has FAILED Step 7.5 — go back and resolve it before
+printing the summary.
 
 Display completed Progress Bar.

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

@@ -3,7 +3,7 @@ name: prd-add
 description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
 ---
 
-# /prd-add — Change Request per PRD attivi
+# /prd-add — Change Request for Active PRD Sessions
 
 Add a new requirement to an existing PRD session. Uses the ICIAS protocol
 (Impact-Confidence-Artifact Stakes) to determine which phases and artifacts
@@ -31,6 +31,13 @@ description, the `/prd` skill invokes `/prd-add` automatically.
 Detection signal: the user's answer introduces NEW entities (endpoints, collections,
 pages, roles, flows) that were not part of the original feature scope.
 
+**IMPORTANT — auto-trigger target:** `/prd`'s dispatch table row `2→CR` points to
+`references/prd-add-phase.md` (a legacy stub). When executing a Change Request,
+**this SKILL.md is the canonical spec** — use it, not the stub. The stub lacks the
+worktree registry scan (Step 0), the `WORKING_DIRECTORY` discipline, and the
+side-effect rules; executing via the stub will operate on the main repo and break
+session isolation. Always load and follow this file (`framework/.claude/skills/prd-add/SKILL.md`).
+
 ---
 
 ## EXECUTION MODEL
@@ -52,7 +59,7 @@ Sequential, single-turn analysis + selective multi-turn re-execution.
 
 1. NEVER start from scratch. Always build on the existing PRD session.
 2. Read the state file and PRD before any analysis.
-3. Follow ICIAS protocol exactly — read [impact-analysis.md](references/impact-analysis.md).
+3. Follow ICIAS protocol exactly — read [impact-analysis.md](../prd/references/impact-analysis.md) (canonical SSOT; see B4).
 4. Present verdict BEFORE executing changes. Wait for user confirmation.
 5. When re-running phases, follow the SAME reference files as `/prd` (discovery-phase.md, etc.).
 6. Update the state file with a `## Change Requests` section tracking all CR history.
@@ -79,21 +86,40 @@ legacy sessions.
    together with its `WORKING_DIRECTORY` = `<entry.path>` and `branch` =
    `<entry.branch>`.
 
+   **Registry absent or entry missing with worktree dir present:** If
+   `.worktrees/registry.json` does not exist, OR it is parseable but contains
+   zero `kind: "docs"` entries, AND a directory matching
+   `.worktrees/docs-*` exists on disk: surface a diagnostic —
+   `REGISTRY_MISMATCH: .worktrees/registry.json is absent or has no docs entries
+   but a docs worktree directory exists on disk. Running a CR from the main repo
+   would break session isolation.` — then HALT and ask the user to manually
+   provide the docs worktree path before continuing. Do NOT silently fall through
+   to the legacy scan in this case.
+
 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.
+   This fallback only applies when Step 1 produced zero registry entries AND no
+   on-disk docs-worktree directory was detected.
 
 3. Merge the two lists. Behavior:
-   - **Exactly ONE active session**: use it. Save its `WORKING_DIRECTORY` and
-     `branch` for every subsequent step.
+   - **Exactly ONE active session**: use it. **Write `WORKING_DIRECTORY` and
+     `BRANCH` to the state file tracker under `## CR Session`** before proceeding
+     — every later consumer reads them from there. These variables must survive
+     context compaction; every step that uses them MUST begin with a
+     presence-and-non-empty guard: if either is absent or empty in the tracker,
+     HALT with `MISSING_VAR: WORKING_DIRECTORY / BRANCH not found in state file`.
    - **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.
+     they know where the CR will be written. Write chosen values to tracker.
    - **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.
+   commit) MUST use absolute paths rooted at `$WORKING_DIRECTORY`. Note: Claude
+   Code's Read/Write/Edit tools require absolute paths and do not honor a working
+   directory state set by a prior shell `cd`; always concatenate
+   `$WORKING_DIRECTORY/<relative-path>` explicitly for every tool call.
 
 5. Read the state file AND the PRD document (if exists), both resolved under
    `$WORKING_DIRECTORY`.
@@ -141,7 +167,7 @@ Record in state file under `## Change Requests`:
 
 ## Step 2 — Impact Analysis (ICIAS Protocol)
 
-**Read [references/impact-analysis.md](references/impact-analysis.md) for the full protocol.**
+**Read [../prd/references/impact-analysis.md](../prd/references/impact-analysis.md) for the full protocol.**
 
 Quick summary — 3 phases executed in sequence:
 
@@ -177,18 +203,24 @@ Present the impact matrix to the user:
 | D3 | Data model | - | D4->D3 | 1 | 2 | 3 | 6 | PATCH |
 | ... | ... | ... | ... | ... | ... | ... | ... | ... |
 
-**Fasi da rieseguire:**
-- Discovery: PATCH (D2, D4 da aggiornare)
-- UI Design: REDO (nuovo flow)
-- PRD: PATCH (sezioni 4, 6, 9)
-- Backlog Cards: PATCH (nuove cards + update esistenti)
+**Phases to re-execute:**
+- Discovery: PATCH (D2, D4 to update)
+- UI Design: REDO (new flow)
+- PRD: PATCH (sections 4, 6, 9)
+- Backlog Cards: PATCH (new cards + update existing)
 
-Vuoi procedere con questa analisi?
+Proceed with this analysis?
 ```
 
 **STOP.** Wait for user confirmation.
 
-If user disagrees with any verdict, adjust manually and re-present.
+If user disagrees with any verdict: re-score the contested dimension at their
+direction (record the override and the reason in the state file under CR-N),
+then re-present the full matrix. **Maximum 2 re-presentations per CR**; after
+the second re-presentation the agent must accept the user's overrides as final
+and proceed. Any SKIP override from PATCH/REDO that removes a mandatory gate
+(D3 schema section, API gate) is recorded as `USER_OVERRIDE` in the state file
+for audit but does not block execution.
 
 ---
 
@@ -207,7 +239,11 @@ Execute ONLY phases with PATCH or REDO verdict, in original phase order.
 
 - **PATCH**: Describe changes needed to existing design.html. Ask user
   if they want a full design refresh or text-only update to PRD.
-- **REDO**: Re-run full UI Design phase (Steps 3a-3d from /prd).
+- **REDO**: Re-run the full UI Design phase following
+  [../prd/references/ui-design-phase.md](../prd/references/ui-design-phase.md)
+  (Steps 3.0 Precondition → 3.1 Full / Hybrid pipeline as applicable). Pass
+  `WORKING_DIRECTORY=$WORKING_DIRECTORY` to `ui-design` per the side-effect
+  rules in Step 0 of this skill.
 
 ### For PRD (PATCH/REDO)
 
@@ -225,6 +261,15 @@ Execute ONLY phases with PATCH or REDO verdict, in original phase order.
 - **REDO**: Regenerate affected cards via `prd-card-writer` agent.
   Preserve cards that are unaffected.
 
+  **BLOCKING pre-check before invoking `prd-card-writer`:** If the PRD
+  dimension also has a PATCH or REDO verdict (step 4c), confirm that 4c is
+  complete AND that the PRD document contains an up-to-date
+  `## Schema Verification` section (field registry with `ts_verified: true`)
+  before starting card generation. `prd-card-writer`'s Field Grounding Rule
+  mandates this section exists and is current — invoking the agent before 4c
+  finishes will cause it to halt after writing partial cards. Do not proceed
+  if the section is absent or stale.
+
 ### For ISA (always re-scan if any PATCH/REDO exists)
 
 Run a delta ISA scan focused on the new requirement. Merge new
@@ -238,7 +283,12 @@ touchpoints into existing ISA table. Assign new ISA-N IDs.
    - CR status: `applied`
    - Update comprehension checklist with changes
    - Update `## Change Requests` with summary of what was done
-2. Re-run API Performance Gate (Step 4.5) if API/data model changed.
+2. **Re-run API Performance Gate** if the CR produces a PATCH or REDO verdict on
+   D3 (Data model) or D4 (API contracts). Read
+   [../prd/references/api-perf-gate.md](../prd/references/api-perf-gate.md) for
+   the full gate protocol. Invoke `api-perf-cost-auditor` following the same
+   pattern as `/prd` Step 4.5. Record the gate result in the state file
+   `## Change Requests › CR-N` section before the delta commit.
 3. Stage ONLY modified files (explicit names).
 4. Commit: `[PRD-ADD] <slug>: <CR description>`
 
@@ -250,16 +300,16 @@ touchpoints into existing ISA table. Assign new ISA-N IDs.
 ---
 🔄 **Change Request: <slug> — CR-N**
 
-| # | Fase | Verdict | Stato |
-|---|------|---------|-------|
+| # | Phase | Verdict | Status |
+|---|-------|---------|--------|
 | 1 | Intake | - | ⬜/✅ |
 | 2 | Impact Analysis | - | ⬜/🔄/✅ |
-| 3 | Verdict & conferma | - | ⬜/🔄/✅ |
+| 3 | Verdict & confirm | - | ⬜/🔄/✅ |
 | 4a | Discovery (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
 | 4b | UI Design (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
 | 4c | PRD (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
 | 4d | Backlog Cards (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
 | 5 | Delta Commit | - | ⬜/✅ |
 
-Prossimo passo: <what happens next>
+Next: <what happens next>
 ```