baldart 5.5.0 → 5.6.0

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

@@ -2,6 +2,42 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.6.0 — 2026-07-04 (FEAT-0068 post-mortem: il root cause era qui)
+
+- **ISA "UI ROLE FAMILY (registry-first)"** (`discovery-phase.md` Dimension 9, gated su
+  `features.has_design_system`): per feature chrome/primitive enumera i PROPRIETARI della
+  superficie del goal dal registry (role families / Selection Policy), non solo i consumer
+  esistenti del meccanismo; **flag BLOCK su `@deprecated`** nel fix-path (i successori
+  documentati diventano il target). Era: DrilldownHeader/SectionHeader (~90% degli screen)
+  in NESSUNA card, ricetta ancorata su un Header deprecato da 5 pagine.
+- **§0 LOAD CONTRACT** in testa a `discovery-phase.md`: il modulo supera il cap del Read —
+  vista PARTIAL ⇒ offset-Read obbligatori fino alla fine (la coda persa conteneva Exit
+  condition + Codex completeness cross-check + Research Trigger, mai eseguiti sul run reale).
+- **`module_read` stamps** (SKILL.md): la lettura dei moduli di fase è ESEGUITA non recitata
+  — stamp nello state file, verificato dal validator (3 moduli mai letti sul run reale).
+- **`step_3_mode` enum CHIUSO + contratto `skipped`** (`ui-design-phase.md`): `skipped` =
+  NESSUN artefatto di design, `links.design` vuoto, ogni explainer passa da `/ui-design`
+  (era: modalità fabbricata `design-spec` + design.html hand-authored su 5/6 card);
+  **Reconciliation-lite** (no mockup ≠ no reconciliation: role family dal registry ⇒
+  `component_bindings`); **trigger di ri-enumerazione ISA** quando la ricetta cambia target.
+- **Gate quantificatore-universale sugli AC epic** (`validation-phase.md` item e):
+  "ogni schermata" ⇒ owner della superficie (census fresco) ⊆ unione scope figli, else
+  BLOCKER; `invariant_owners:` persistiti nell'epic.
+- **Item 0-ii Phase-evidence audit** (`validation-phase.md`): stamp module_read + gate con
+  evidenza (API Perf Gate stampato `N/A` senza spawn sul run reale) + enum step_3_mode.
+- **Stamp holistic evidence-gated** (`stamp-holistic-audit.js --audit-report` →
+  `agents_run`/`findings_count`; senza artefatto → `status: skipped` che `/new` tratta come
+  ASSENTE). Era: stamp su 6/6 card con zero spawn di audit (phantom stamp).
+- **Card-writer self-validation** (`backlog-phase.md` + agente): il validator gira
+  nell'output del writer PRIMA del return (era: round-trip completo su EARS in italiano);
+  **Rule A ramo deterministico** (files docs/test-only ⇒ owner coder, mai `links.design`);
+  epic con `ac_verification` obbligatoria + mai count hardcodato; invariante lifecycle
+  baseline per suite snapshot.
+- **Step 7.9 HARD RULE mw-docs** (`validation-phase.md`): mai `/mw` generico su worktree
+  `kind: docs` (+ guardia lato worktree-manager); era ~4M di BUILD_FAIL falso + unblock umano.
+- **EDIT CONTRACT dello state file** (template + HARD RULE 2): anchor sul bare `key:` con
+  literal appena letto (5 retry ciechi da ~250k sul run reale).
+
 ## 1.5.0 — 2026-07-03 (framework v5.4.0)
 
 - **Step 2.1 Tier Gate (elastic pipeline).** At Discovery exit the feature is classified

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

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.5.0
+version: 1.6.0
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 
@@ -54,9 +54,17 @@ message. You ask questions, wait for answers, and iterate.
 | 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
 | 7.6 | Obsidian back-reference — FINAL (upgrades the 1.2 provisional block; only if a spec note was given) | [validation-phase.md](references/validation-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 
-**Before starting each phase, read the corresponding reference file** — with ONE
-exception class: **agent-facing specs are passed BY PATH to the agent that consumes
-them and MUST NOT be loaded into the orchestrator context.** Today these are
+**Before starting each phase, read the corresponding reference file — EXECUTED, not
+recited (v5.6.0).** After reading a phase module, record `module_read: <file> (full)` in the
+state file's section for that phase; if the Read reported a PARTIAL view (the module exceeds
+the token cap — `discovery-phase.md` does), issue offset Reads until the END of the file
+before proceeding and stamp `(full, N reads)`. The Step 6 validator (`validation-phase.md`
+item 0-ii) checks these stamps deterministically. This exists because a real session ran
+Steps 2.5/4/4.5/5 with `research-phase.md`, `prd-writing-phase.md` and `backlog-phase.md`
+NEVER read (6 Reads total in 73 turns): the improvised Step 5 contract produced a full
+validator-rework round, and the truncated discovery tail silently dropped the mandatory Codex
+completeness cross-check. ONE exception class: **agent-facing specs are passed BY PATH to the
+agent that consumes them and MUST NOT be loaded into the orchestrator context.** Today these are
 `references/api-perf-gate.md` (read by `api-perf-cost-auditor` at Step 4.5 and at the
 Step 6 audit) and `references/audit-teammate-prompt.md` (read by each Step 6.6 audit
 teammate). Rationale: a spec loaded by a subagent costs one cheap Read in a disposable
@@ -70,7 +78,11 @@ for the rest of the run.
 > **Runtime portability.** On **Codex**, bind this skill's mechanics per `framework/agents/runtime-portability-protocol.md` (named-agent spawn, decision gates, file-backed state; never probe `Workflow`/`AskUserQuestion`/the task spine). Rules below are Claude-first with explicit **Codex:** branches (RULES 4, 11) — additive, Claude imperatives unchanged.
 
 1. Follow steps in order. NEVER skip a step or jump ahead.
-2. Every step MUST update the state file before proceeding.
+2. Every step MUST update the state file before proceeding. **State-file Edit hygiene
+   (v5.6.0):** anchor every Edit on the bare `key:` prefix with a literal you just Read —
+   never a recalled literal with trailing comments/alignment/blank lines (the template's
+   EDIT CONTRACT header; 5 blind retries at ~250k each on a real session). A failed match →
+   Read the exact lines, retry ONCE with the fresh literal.
 3. Every gate MUST be satisfied before moving to the next step.
 4. **Progress tracking.** Claude Code: use TaskCreate/TaskUpdate for ALL progress tracking. **Codex** (no task spine): use a file-backed queue at `$WORKTREE_PATH/${paths.prd_dir}/sessions/<slug>-tasks.jsonl` — one record per task (`status` / `claimed_by` / `findings_path`) — and the session **state file** stays the recovery SSOT either way. (Binding: `framework/agents/runtime-portability-protocol.md` § state-spine.)
 5. When context is compressed or session resumes: run Step 0 first.

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

@@ -1,4 +1,11 @@
 # PRD Session: {{slug}}
+
+<!-- EDIT CONTRACT (v5.6.0 — N8, 5 failed Edits at ~250k context each on a real session):
+     when updating a `key: value` line in this file, ANCHOR ON THE BARE KEY PREFIX ONLY
+     (`old_string` = from start-of-line through the current value you just Read — never a
+     recalled-from-memory literal that includes trailing `# comments`, column alignment, or
+     surrounding blank lines; those drift). If an Edit fails to match, Read the exact lines
+     FIRST and retry once with the fresh literal — never loop blind retries. -->
 Created: {{YYYY-MM-DD HH:MM}}
 Status: discovery   # discovery | mockups-pending-input | research-in-progress | pending-external-handoff | ui-design | writing | specs-confirmed | backlog | audit | validation | committing | completed | done
 stats_enabled: {{true if invoked with -stats/--stats, else false}}
@@ -121,7 +128,7 @@ mockup_analysis.design_system_alignment:
   status: pending                 # aligned | violations | not-applicable
   violations: []
 
-step_3_mode: pending              # full | hybrid | skipped | mockup-only
+step_3_mode: pending              # CLOSED ENUM: full | hybrid | skipped | mockup-only | pending_external_handoff — any other value is a Step 6 BLOCKER (v5.6.0)
 design.html_path: pending         # path | n/a (mockup-only)
 
 screens_in_scope: []              # [{ name, slot_id, screen_id, canvas_ref, covered_by_mockups: bool, generated_in_step_3b: bool }]

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

@@ -398,8 +398,19 @@ metadata:
     audited_at: "<HOLISTIC_AUDITED_AT>"
     audited_commit: "<HOLISTIC_AUDITED_COMMIT>"   # "" if git unavailable → /new treats as drift (runs Step 3d)
     audited_set: ["FEAT-XXXX-01", "FEAT-XXXX-02", ...]   # sorted; the joint cross-card scope
+    agents_run: ["plan-auditor", "codebase-architect", ...]   # v5.6.0 EVIDENCE — written by the
+      # stamper from the audit report artifact (--audit-report). A stamp WITHOUT a non-empty
+      # agents_run is treated as ABSENT by /new P1 (the plan-auditor runs): on FEAT-0068 the
+      # stamp landed on all 6 cards while the audit team never spawned (phantom stamp).
+    findings_count: 3                              # optional, from the report
 ```
 
+**Write the audit report artifact FIRST (v5.6.0 — the stamp's evidence).** Before running the
+stamper, persist the Step 6.6 audit outcome to `/tmp/prd-audit-<slug>.md` with at minimum a
+literal `agents_run: <comma-separated agent types actually spawned>` line and a
+`findings_count: <N>` line. No spawns happened → do NOT fabricate the file: run the stamper
+without `--audit-report` and it stamps `status: "skipped"` honestly.
+
 > **Fail-safe contract**: the block is an OPTIMIZATION hint for `/new`, never a *correctness* gate — if `audited_commit` is empty or the block is absent, `/new` Step 3d **and** the `implement.md` Phase-1 plan-auditor grounding (step 4, P1) simply RUN as before (redundant, never wrong). **But writing the block is MANDATORY whenever the audit ran.** It is the single most-omitted step under context pressure, and its absence is exactly what makes `/new` / `new2` spawn the plan-auditor on **every** freshly-authored card even when the batch is implemented immediately after this audit (nothing changed since). Do NOT skip it "to save a write". If git is genuinely unavailable, write `audited_commit: ""` **explicitly** — never omit the block. `validation-phase.md` Step 7 item 5b is the **deterministic backstop** that guarantees this lands before the PRD commit even if this per-card write is missed — but write it here too; the backstop is a safety net, not a license to skip.
 
 **Deterministic writer — EXECUTE, don't hand-edit.** `framework/scripts/stamp-holistic-audit.js` mechanizes this write (idempotent, additive, epic-skipping, self-verifying). Run it ONCE for the whole card set after the per-card field edits:
@@ -407,7 +418,8 @@ metadata:
 ```bash
 node .framework/framework/scripts/stamp-holistic-audit.js \
   --at "$HOLISTIC_AUDITED_AT" --commit "$HOLISTIC_AUDITED_COMMIT" \
-  --set "<sorted child IDs, comma-separated>" ${CARD_PATHS}
+  --set "<sorted child IDs, comma-separated>" \
+  --audit-report "/tmp/prd-audit-<slug>.md" ${CARD_PATHS}
 ```
 
 Hand-edit the YAML only when the script is genuinely unreachable in this install — and say so in the audit log.

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

@@ -22,6 +22,19 @@ and BLOCK the commit. The `/new` orchestrator dispatches implementation
 agent by this field (see `framework/.claude/skills/new/SKILL.md` § Agent
 Routing), so a wrong value silently routes the card to the wrong specialist.
 
+**Rule A deterministic branch (v5.6.0 — FEAT-0068):** when a card's
+`files_likely_touched` are ALL docs/test/config/meta paths (zero `src/` UI or
+component/style files), `owner_agent` MUST be `coder` regardless of the
+feature's topic — a docs+ADR+test card for a UI epic is still a coder card
+(`owner_agent: ui-expert` with zero UI paths is a Step 6 BLOCKER). Also do NOT
+stamp `links.design` on such a card: `links.design` goes ONLY on cards whose
+scope implements mocked regions (`component_bindings` present or
+`files_likely_touched` intersecting the mocked components); on anything else it
+is a stray pointer that clamps the build to ui-expert downstream (`/new`
+mockup-first router) — the FEAT-0068 docs card cost 6.55M for exactly this.
+This separates HETEROGENEOUS domains; it does not contradict the v5.4.0
+proportionality floor (which discourages splitting a small HOMOGENEOUS change).
+
 ### Rule B — UI cards have UI-only scope (no mixed scope)
 
 A card with `owner_agent: ui-expert` MUST be scoped EXCLUSIVELY to graphical
@@ -263,6 +276,13 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - State file update with card list and matrices
 - `env_vars` field: for every card that introduces/modifies/removes env vars (detectable from PRD Section 6 or requirements that mention `process.env`, secrets, API keys, feature flags), populate the field with `action: new|modified|removed`, `scope`, `required`, `note`. If the card does not touch env vars, write `env_vars: []`.
 - `review_profile` field: deterministic per-card review depth (`skip|light|balanced|deep`). The decision criteria (how each profile is chosen) live ONLY in `prd-card-writer.md § Rule C` — see that file for the criteria. The `/new` orchestrator reads this value from the card and runs an escalation-only detector; it does NOT re-derive from a duplicate criteria table. Epics always get `review_profile: skip`. Honor any explicit author override already present in the YAML.
+- **Self-validation BEFORE returning (v5.6.0 — reviewer-owns-its-domain, FEAT-0068 N6):** the
+  card-writer brief MUST require the agent to RUN the deterministic validator on its own output
+  (`node .framework/framework/scripts/validate-card-baseline.js --prd <card files>`) and return
+  only on exit 0, fixing its own deterministic defects (enums, EARS token language, forbidden
+  patterns) in-context. Step 6 re-runs the same validator as the independent gate — but a
+  deterministic failure discovered only at Step 6 costs a full orchestrator→agent round-trip
+  (~1.5M + a resume on the real session, where all 6 children bounced on Italian EARS tokens).
 
 ### What stays in the main context
 

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

@@ -1,5 +1,21 @@
 # Discovery Phase (Steps 0-2)
 
+> **§0 — LOAD CONTRACT (v5.6.0 — read this first; it exists because of a real truncation).**
+> This module is LARGER than the Read tool's default token cap. A plain `Read` returns a
+> **PARTIAL view** (the banner says so) and silently drops the TAIL — which contains the
+> **Exit condition**, the **mandatory Codex Discovery Completeness Cross-Check**, the
+> **Research Trigger**, and the `mockup_analysis` schema. On the FEAT-0068 session exactly
+> that happened: lines 953+ were never loaded, the cross-check never ran, and the coverage
+> blind spot it exists to catch (integration owners no dimension modelled) shipped into the
+> cards. HARD RULE: **if your Read of this file reports a partial view, you MUST issue
+> follow-up Read calls with `offset` until you have seen the end of the file — BEFORE
+> closing any discovery dimension.** Record `module_read: discovery-phase.md (full, N reads)`
+> in the state file's phase section (the Step 6 validator checks the stamp). The
+> tail-critical gates, so you know what you are looking for: (1) Exit condition — all
+> dimensions covered + user validation; (2) Codex Discovery Completeness Cross-Check —
+> MANDATORY sweep for the questioner's own blind spots before closing; (3) Research
+> Trigger — background launch at 6+ dimensions; (4) `mockup_analysis` schema.
+
 ## Step 0 — Context Recovery
 
 Run BEFORE any other step.
@@ -815,6 +831,25 @@ Instead, run the ISA scan and present findings for validation.
      the picker-mode call, while the live catalog-mode consumer page was never
      enumerated → it surfaced as a HIGH only at the final review.) Grep the function
      name across the codebase and list each distinct caller file:line.
+   - UI ROLE FAMILY — registry-first surface OWNERSHIP (v5.6.0; only when
+     features.has_design_system is true AND the feature's recipe targets a chrome/
+     primitive ROLE: "the header/top edge of every screen", bottom bars, anchored
+     overlays/toasts, page shells). Every other category above enumerates EXISTING
+     code that references the feature's mechanism — but a component that LACKS the
+     mechanism is structurally invisible to that grep. This category enumerates the
+     OWNERS of the goal surface instead: read the design-system registry
+     (${paths.design_system}/INDEX.md role families / Selection Policy +
+     components/<Name>.md) for the family that renders that role, list EVERY member
+     as its OWN touchpoint (with its consumer count: `grep -rl <Component> | wc -l`),
+     and mark each HIGH (the goal is invisible wherever an unlisted member renders).
+     **@deprecated flag (BLOCKING):** if a family member the recipe anchors on carries
+     a `@deprecated` docblock, the touchpoint MUST name the documented successors and
+     the recipe MUST target them — anchoring a surface-wide goal on a deprecated
+     member is a scope error, not a style choice. (FEAT-0068: the ISA enumerated the
+     44 existing consumers of env(safe-area-*) and anchored "the header" on a
+     @deprecated Header.tsx serving 5 pages, while the successors DrilldownHeader/
+     SectionHeader — 63 files, ~90% of screens — appeared in NO card; the coverage
+     gate then passed 44/44 vacuously against the wrong inventory.)
 
    For each touchpoint found, report:
    - Category (from above)

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

@@ -114,6 +114,34 @@ dimension from the discovery checklist. Pick exactly one branch:
 | `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). |
 
+**`step_3_mode` is a CLOSED ENUM (v5.6.0): `full | hybrid | mockup-only | skipped |
+pending_external_handoff`.** Writing any other value is a protocol violation the Step 6
+validator now rejects deterministically. The FEAT-0068 session invented `design-spec` when the
+user declined mockups on a UI feature — an unscoped gap the model filled by fabrication — and
+the hand-authored inline "visual explainer" it produced became `links.design` on 5/6 cards,
+routing a docs card to ui-expert downstream. The rules that close that gap:
+- **`skipped` means NO design artifact.** No inline design.html, no "visual spec" Write, and
+  `links.design` stays EMPTY on every card. Any visual explainer the user asks for goes through
+  `Skill(ui-design)` (which runs its craft gates) — the orchestrator NEVER hand-authors design
+  HTML.
+- **UI feature + user declines mockups is still `skipped`** (or Full if the user accepts
+  internal generation) — there is no third "spec-only" lane. What the cards need instead is
+  § Reconciliation-lite below.
+- **Reconciliation-lite (v5.6.0 — "no mockup" must NOT mean "no reconciliation").** When
+  `step_3_mode: skipped` (or `mockup-only`) AND the feature touches design-system primitives
+  (`features.has_design_system: true`), STILL run the registry half of Component
+  Reconciliation: resolve the affected ROLE FAMILIES from `${paths.design_system}/INDEX.md`
+  (Selection Policy + role families — same lens as the ISA "UI ROLE FAMILY" category, which by
+  now has enumerated the owners), and emit `component_bindings` for the cards from the registry
+  alone. The FEAT-0068 chain — mockups skipped → reconciliation never ran → the registry that
+  named DrilldownHeader/SectionHeader as the canonical headers was never consulted → the recipe
+  anchored on a @deprecated component — is exactly what this closes.
+- **Re-enumeration trigger (v5.6.0).** If a design/recipe decision taken IN THIS PHASE changes
+  WHAT the feature applies to (a different component family, a broader/narrower surface than
+  discovery assumed), the ISA surface inventory is STALE: re-run the affected ISA category
+  (Dimension 9 — at minimum UI ROLE FAMILY) before PRD writing. Locking a recipe after the scan
+  without re-enumerating is how a correct inventory goes wrong silently.
+
 Mark task 2 as `in_progress` for the Full and Hybrid branches.
 
 ## Delegation to `ui-design` Skill

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

@@ -52,6 +52,19 @@ Mark task 5 as `in_progress`.
         surface / ISA file owned by NO card is a BLOCKER (this is the gap that otherwise surfaces only
         at `/new`'s expensive final review). Message: `"ISA touchpoint <path> (<category>) is owned by
         no card — assign it to a card's files_likely_touched."`
+      - **Universal-quantifier epic AC gate (v5.6.0 — FEAT-0068):** for every EPIC acceptance
+        criterion carrying a universal quantifier over a UI/route surface ("ogni schermata",
+        "tutte le route", "every screen", "all pages", "nessun <difetto> su <superficie>"),
+        derive the surface's OWNER components from the **fresh registry/ISA census** (the
+        UI ROLE FAMILY touchpoints of discovery Dimension 9 — NOT the raw mechanism-consumer
+        touchpoints, or you inherit an incomplete inventory) and verify each owner appears in
+        the union of the child cards' `files_likely_touched`/scope. An owner covered by NO
+        child is a BLOCKER: `"Epic AC-<n> quantifies over <surface> but owner <component>
+        (<N> files) belongs to no card."` Persist the resolved owner list as
+        `invariant_owners:` in the epic YAML so the `/new` epic-closure gate can re-verify
+        it. (FEAT-0068: the epic promised "no seam on every screen" while DrilldownHeader/
+        SectionHeader — ~90% of screens — belonged to no card; the ISA→card gate passed
+        44/44 vacuously because the inventory itself was wrong.)
       Both are SEMANTIC (path extraction from prose / ISA needs interpretation) — bias toward flagging.
 
    **Gate**: the 0-i validator exits 0 on every card (enums, conditional `requirements`, zero
@@ -59,6 +72,22 @@ Mark task 5 as `in_progress`.
    checks (b)/(c) are noted in the audit log; user may accept them after review. The 0-i and (e)
    BLOCKERs must be fixed before commit.
 
+0-ii. **Phase-evidence audit (v5.6.0 — executed, not recited; FEAT-0068 shipped TWO phantom
+   gates).** Deterministic checks on the STATE FILE before the audit protocol runs:
+   - **`module_read` stamps**: each executed phase section must carry its `module_read:
+     <reference file> (full)` stamp (SKILL.md § phase-module loading). A phase that ran with
+     its module unread is a protocol violation to surface — on FEAT-0068, `research-phase.md`,
+     `prd-writing-phase.md` and `backlog-phase.md` were never read and the improvised Step 5
+     contract produced the EARS rework round.
+   - **Gate stamps carry evidence**: any gate recorded as run/passed/`N/A` (API Performance
+     Gate, holistic audit, Codex Discovery Cross-Check) must name its evidence — an agent
+     spawn/report path for agent gates, the concrete reason for an `N/A`. A gate stamp with no
+     evidence is treated as NOT RUN (the FEAT-0068 session stamped `pass # N/A` on the API
+     gate without ever spawning the auditor, and the holistic stamp landed with zero audit
+     spawns).
+   - **`step_3_mode` ∈ {full, hybrid, mockup-only, skipped, pending_external_handoff}**: any
+     other value (the session fabricated `design-spec`) is a BLOCKER — fix the state file and
+     re-run the branch it should have taken.
 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`.
@@ -142,9 +171,15 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
    HOLISTIC_AUDITED_COMMIT="$(git -C "$WORKTREE_PATH" merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git -C "$WORKTREE_PATH" rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
    # --set = the sorted Step-5 child card IDs (the joint cross-card scope), comma-separated.
+   # --audit-report (v5.6.0, REQUIRED for a full stamp) = the audit-phase report artifact
+   #   (e.g. /tmp/prd-audit-<slug>.md, written by audit-phase Step 6.9 with its `agents_run:`
+   #   line). NO artifact on disk = the audit team never ran (the FEAT-0068 phantom stamp) →
+   #   run WITHOUT the flag and the script writes `status: skipped` + NO agents_run, which
+   #   /new's P1 treats as ABSENT (plan-auditor runs — fail-safe, exactly right).
    node .framework/framework/scripts/stamp-holistic-audit.js \
      --at "$HOLISTIC_AUDITED_AT" --commit "$HOLISTIC_AUDITED_COMMIT" \
-     --set "<ID1,ID2,...>" "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
+     --set "<ID1,ID2,...>" --audit-report "/tmp/prd-audit-<slug>.md" \
+     "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
    ```
    The script is **idempotent** (a card already stamped by Step 6.9.4 is untouched),
    **additive** (never overwrites other `metadata` keys), skips EPIC cards (they carry
@@ -223,6 +258,15 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    Input: { "worktreePath": "$WORKTREE_PATH" }
    ```
 
+   **HARD RULE (v5.6.0 — FEAT-0068 N1): `mw-docs`, NEVER generic `/mw`, for a docs worktree.**
+   The registry entry for this worktree says `kind: "docs"` — a generic `/mw` on it runs the
+   forbidden unbounded `npm run build` (a docs worktree has no node_modules → guaranteed false
+   BUILD_FAIL, manual recovery, classifier-blocked push; ~4M wasted on the real session). If
+   you find yourself about to call `/mw`, or to invent invocation args (`checksAlreadyPassed`
+   is NOT an input of this contract), STOP — the invocation above is the whole contract.
+   `/mw` itself refuses a `kind: "docs"` worktree since v5.6.0 (worktree-manager pre-flight),
+   but do not rely on the belt: use the right mode.
+
    The skill executes:
    - 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

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

@@ -2,6 +2,19 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.2.0 — 2026-07-04 (FEAT-0068 post-mortem)
+
+- **`merge-worktree.sh --safety-sweep <all|allowlist:globs>`**: in modalità allowlist il
+  safety commit pre-rebase stagia SOLO i file che matchano (bookkeeping del batch), con
+  messaggio onesto che li enumera; le modifiche TRACKED fuori allowlist vengono messe in
+  quarantena byte-per-byte (`quarantined:` nel manifest) e ripristinate a HEAD, gli
+  untracked restano su disco (`uncommitted_left:`). Default `all` invariato per `/mw`
+  interattivo. Chiude lo split-brain col F-030 del chiamante ("[safety] Auto-commit" da
+  751 righe opaco su develop, ricorrente FEAT-0067/FEAT-0068).
+- **Guardia docs-worktree in `/mw`** (BLOCKING, step 1): registry `kind: "docs"` ⇒ rifiuto
+  con puntatore a `mw-docs` (un `/mw` generico su un docs worktree = build unbounded senza
+  node_modules ⇒ BUILD_FAIL falso garantito, ~4M su un run `/prd` reale).
+
 ## 1.1.0 — 2026-07-03
 
 ### Fixed — local-trunk sync robustness (step 4c "Common", both strategies)

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

@@ -1,7 +1,7 @@
 ---
 name: worktree-manager
 effort: medium
-version: 1.1.0
+version: 1.2.0
 description: >
   Manage fully independent git worktrees for parallel coding agents.
   Commands: /nw (new worktree) creates an isolated workspace with its own
@@ -685,6 +685,16 @@ Supports two modes:
 
 Read `.worktrees/registry.json`. If multiple entries exist or user didn't specify, list them and ask which to merge.
 
+**Docs-worktree guard (v5.6.0 — BLOCKING, before anything else).** If the resolved registry
+entry carries `kind: "docs"`, this is the WRONG mode: REFUSE and route to `mw-docs`
+(programmatic: `Mode: programmatic, mw-docs`). A generic `/mw` on a docs worktree runs the
+build/check pipeline against a tree with no node_modules → a guaranteed false BUILD_FAIL,
+manual recovery, and a blocked push (observed on a real `/prd` session: ~4M tokens + a human
+unblock). Message: `"WRONG MODE: worktree '<slug>' is kind:docs — use mw-docs (docs merge:
+no build, additive-registry resolution). Refusing generic /mw."` Also ignore any invented
+invocation args (`checksAlreadyPassed` is a `/new`-orchestrator flag, not a user contract) —
+the registry entry is the SSOT for what kind of merge this is.
+
 Fallback: `git worktree list` if registry is missing.
 
 Determine, reading them from the worktree's registry entry (R6):

package/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh

@@ -48,6 +48,21 @@
 #   --tc-build <cmd>       toolchain build cmd     (default: config / npm run build)
 #   --log <path>           build/merge log sink    (default: /tmp/wt-merge-<slug>.log)
 #   --build-timeout <s>    hard build timeout sec  (default: 600)
+#   --safety-sweep <mode>  what the pre-rebase safety commit may stage (v5.6.0):
+#                            all               — every changed+untracked file (default;
+#                                                the historical /mw interactive behavior)
+#                            allowlist:<globs> — comma-separated shell globs (e.g.
+#                                                "backlog/*.yml,docs/metrics/*,.baldart/*").
+#                              Matching files → committed with an honest message that
+#                              ENUMERATES them. Non-matching TRACKED changes → preserved
+#                              byte-for-byte into a labeled quarantine dir, then restored
+#                              to HEAD (so the rebase can start). Non-matching UNTRACKED
+#                              files → left in place. Both reported in the manifest.
+#                              Rationale (FEAT-0068 5f618347d / FEAT-0067 5a5f1c135): an
+#                              unconditional sweep contradicts the caller's F-030 "never
+#                              commit ungated code" by construction — dirty code at merge
+#                              time did NOT pass the per-card gates and must never ride an
+#                              opaque "[safety]" commit onto the trunk.
 #
 # Status file written (parsed by callers — STABLE contract):
 #   status: success | code_conflict | build_fail | sync_needs_decision | error
@@ -63,6 +78,8 @@
 #   sync_marker: <none | SYNC-DEFERRED | SYNC-NEEDS-DECISION>
 #   sync_detail: <message | ->
 #   build_log: <path | ->
+#   uncommitted_left: <csv | ->        (allowlist mode — untracked files left in place, NOT committed)
+#   quarantined: <dir | ->             (allowlist mode — tracked changes preserved here, then reset to HEAD)
 #
 # Exit: 0 ONLY on status:success. Non-zero otherwise (the exit code mirrors the
 # status: 10=code_conflict, 11=build_fail, 12=sync_needs_decision, 1/2=error). The
@@ -75,7 +92,7 @@ err() { printf '%s\n' "$*" >&2; }
 
 # --- args ------------------------------------------------------------------
 WORKTREE= MANIFEST= CONTINUE=0 BRANCH= TRUNK= MAIN= STRATEGY= SKIP_CHECKS=0
-METRICS_DIR= TC_TC= TC_LINT= TC_BUILD= LOG= BUILD_TIMEOUT=600
+METRICS_DIR= TC_TC= TC_LINT= TC_BUILD= LOG= BUILD_TIMEOUT=600 SAFETY_SWEEP=all
 while [ $# -gt 0 ]; do
   case "$1" in
     --worktree) WORKTREE="${2:-}"; shift 2 ;;
@@ -92,6 +109,7 @@ while [ $# -gt 0 ]; do
     --tc-build) TC_BUILD="${2:-}"; shift 2 ;;
     --log) LOG="${2:-}"; shift 2 ;;
     --build-timeout) BUILD_TIMEOUT="${2:-}"; shift 2 ;;
+    --safety-sweep) SAFETY_SWEEP="${2:-all}"; shift 2 ;;
     *) err "ERROR: unknown arg: $1"; exit 2 ;;
   esac
 done
@@ -99,6 +117,7 @@ done
 # --- status writer (called on EVERY exit path) -----------------------------
 M_STATUS="error" M_PHASE="identify" M_ERROR="-" M_MERGE="-" M_MERGETS="-"
 M_CONFLICTS="-" M_SYNCMARK="none" M_SYNCDETAIL="-" M_BLOG="-"
+M_UNCOMMITTED="-" M_QUARANTINE="-"
 write_status() {
   [ -n "$MANIFEST" ] || return 0
   {
@@ -115,6 +134,8 @@ write_status() {
     printf 'sync_marker: %s\n' "$M_SYNCMARK"
     printf 'sync_detail: %s\n' "$M_SYNCDETAIL"
     printf 'build_log: %s\n' "$M_BLOG"
+    printf 'uncommitted_left: %s\n' "$M_UNCOMMITTED"
+    printf 'quarantined: %s\n' "$M_QUARANTINE"
   } > "$MANIFEST" 2>/dev/null || true
 }
 fail()          { M_STATUS="error";         M_ERROR="$1"; write_status; err "ERROR: $1"; exit "${2:-1}"; }
@@ -362,19 +383,74 @@ else
   # -------------------------------------------------------------------------
   # FRESH path: safety commit → (checks) → rebase
   # -------------------------------------------------------------------------
-  # 1. Safety commit (ALWAYS — never skippable; files lost after rebase are unrecoverable)
+  # 1. Safety commit. Mode `all` (default, /mw interactive): every changed+untracked file —
+  #    files lost after rebase are unrecoverable. Mode `allowlist:<globs>` (v5.6.0, passed by
+  #    orchestrated callers like new2): only batch bookkeeping is committed (with an honest,
+  #    enumerating message); non-matching TRACKED changes are quarantined byte-for-byte then
+  #    reset to HEAD (a dirty tracked file would block the rebase), non-matching UNTRACKED
+  #    files stay in place. Nothing is silently lost, nothing ungated rides to the trunk.
   M_PHASE="safety"
   CHANGED="$(git -C "$WORKTREE" diff --name-only HEAD 2>/dev/null)"
   UNTRACKED="$(git -C "$WORKTREE" ls-files --others --exclude-standard 2>/dev/null)"
   if [ -n "$CHANGED" ] || [ -n "$UNTRACKED" ]; then
-    for f in $CHANGED $UNTRACKED; do git -C "$WORKTREE" add "$f" 2>>"$LOG"; done
-    git -C "$WORKTREE" commit -m "[safety] Auto-commit uncommitted files before merge
+    case "$SAFETY_SWEEP" in
+      allowlist:*)
+        SWEEP_GLOBS="${SAFETY_SWEEP#allowlist:}"
+        sweep_match() { # POSIX case-glob match of $1 against any comma-separated pattern
+          _f="$1"; _rest="$SWEEP_GLOBS"
+          while [ -n "$_rest" ]; do
+            _pat="${_rest%%,*}"
+            [ "$_pat" = "$_rest" ] && _rest= || _rest="${_rest#*,}"
+            # shellcheck disable=SC2254 — unquoted on purpose: $_pat is a glob
+            case "$_f" in $_pat) return 0 ;; esac
+          done
+          return 1
+        }
+        SWEPT= LEFT_UNTRACKED= QUAR_TRACKED=
+        for f in $CHANGED; do
+          if sweep_match "$f"; then git -C "$WORKTREE" add "$f" 2>>"$LOG"; SWEPT="$SWEPT $f"
+          else QUAR_TRACKED="$QUAR_TRACKED $f"; fi
+        done
+        for f in $UNTRACKED; do
+          if sweep_match "$f"; then git -C "$WORKTREE" add "$f" 2>>"$LOG"; SWEPT="$SWEPT $f"
+          else LEFT_UNTRACKED="${LEFT_UNTRACKED:+$LEFT_UNTRACKED,}$f"; fi
+        done
+        if [ -n "$QUAR_TRACKED" ]; then
+          QDIR="/tmp/wt-merge-quarantine-$(basename "$WORKTREE")-$(date +%s)"
+          for f in $QUAR_TRACKED; do
+            mkdir -p "$QDIR/$(dirname "$f")" 2>>"$LOG"
+            cp -p "$WORKTREE/$f" "$QDIR/$f" 2>>"$LOG" || err "WARN: quarantine copy failed for $f"
+          done
+          # restore ONLY after the byte-for-byte copy — the rebase needs a clean tracked tree
+          for f in $QUAR_TRACKED; do git -C "$WORKTREE" checkout -- "$f" 2>>"$LOG"; done
+          M_QUARANTINE="$QDIR"
+          err "WARN: $(echo "$QUAR_TRACKED" | wc -w | tr -d ' ') tracked change(s) OUTSIDE the sweep allowlist quarantined to $QDIR + reset to HEAD (ungated code never rides a safety commit — F-030)"
+        fi
+        [ -z "$LEFT_UNTRACKED" ] || M_UNCOMMITTED="$LEFT_UNTRACKED"
+        write_status
+        if [ -n "$SWEPT" ]; then
+          git -C "$WORKTREE" commit -m "[safety] Materialize batch bookkeeping before merge (sweep allowlist)
+
+Allowlist-matched files that were uncommitted when merge-worktree.sh started:
+$(for f in $SWEPT; do printf '  - %s\n' "$f"; done)
+
+Non-matching files were NOT committed (quarantined/left + reported in the manifest).
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
+            || err "WARN: allowlist safety commit produced no commit (nothing staged?)"
+        fi
+        ;;
+      *)
+        for f in $CHANGED $UNTRACKED; do git -C "$WORKTREE" add "$f" 2>>"$LOG"; done
+        git -C "$WORKTREE" commit -m "[safety] Auto-commit uncommitted files before merge
 
 Files were uncommitted when merge-worktree.sh started. This safety commit
 prevents file loss during rebase.
 
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
-      || err "WARN: safety commit produced no commit (nothing staged?)"
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
+          || err "WARN: safety commit produced no commit (nothing staged?)"
+        ;;
+    esac
   fi
 
   # 2. Pre-merge checks (skipped when --skip-checks / checksAlreadyPassed)

package/framework/.claude/workflows/new-final-review.js

@@ -340,13 +340,15 @@ const codexPrompt =
   `The companion script is ALREADY CONFIRMED PRESENT at:\n  ${codexScriptPath}\n\n` +
   `Run EXACTLY these steps and nothing else:\n` +
   `  1. Write the task text (everything after "TASK PROMPT:" at the end of this message) to ${codexTaskFile} using the Write tool — do NOT inline it into the shell command (avoids quote breakage).\n` +
-  `  2. Launch Codex in the BACKGROUND (run_in_background:true — a sync run hits the Bash timeout):\n` +
-  `       node "${codexScriptPath}" task "$(cat ${codexTaskFile})" --cwd "${a.worktreePath || '.'}" > ${codexReviewFile} 2>&1\n` +
-  `  3. POLL ${codexReviewFile} (BashOutput / repeated reads) until ONE of these appears — whichever is FIRST ends the poll (do NOT keep waiting once one is present). Set \`marker\` accordingly:\n` +
-  `       • "<<<END_FINDINGS_JSON>>>"  → marker = "END_JSON"\n` +
-  `       • "Turn completed."          → marker = "TURN_COMPLETED" (Codex finished; it may have written prose instead of the JSON block)\n` +
-  `       • "CODEX_NOT_FOUND"          → marker = "CODEX_NOT_FOUND" (companion missing)\n` +
-  `       • the full 10-minute window elapses with none of the above → marker = "TIMEOUT" (NEVER pick this just because a single poll returned slowly)\n` +
+  `  2. Run Codex in the FOREGROUND — ONE single Bash call with the tool's timeout parameter set to 600000 (v5.6.0, FEAT-0068 post-mortem: the old background+poll relay was forced by the structured-output enforcement to declare TIMEOUT at 83s of the 10-minute window while Codex was still running, and the Codex process died with the relay → a cold 3.68M fallback review with no cross-model diversity. A blocking call has no idle turn to misjudge — same pattern as the per-card Codex-light driver):\n` +
+  `       node "${codexScriptPath}" task "$(cat ${codexTaskFile})" --cwd "${a.worktreePath || '.'}" --wait > ${codexReviewFile} 2>&1; echo "RELAY_EXIT:$?"\n` +
+  `     Do NOT pass run_in_background. Do NOT poll. The call blocks until Codex finishes — that is correct. Record RELAY_EXIT.\n` +
+  `  3. Derive \`marker\` by grepping ${codexReviewFile} AFTER the call returns:\n` +
+  `       • contains "<<<END_FINDINGS_JSON>>>"  → marker = "END_JSON"\n` +
+  `       • contains "Turn completed."          → marker = "TURN_COMPLETED" (Codex finished; it may have written prose instead of the JSON block)\n` +
+  `       • contains "CODEX_NOT_FOUND"          → marker = "CODEX_NOT_FOUND" (companion missing)\n` +
+  `       • none of the above AND RELAY_EXIT is 124/137/143 (the Bash timeout killed the call) → marker = "TIMEOUT", then REAP the orphan Codex process scoped to THIS worktree (never a bare pkill): \`pkill -f -- "--cwd ${a.worktreePath || '.'}" 2>/dev/null; true\`\n` +
+  `       • none of the above with a clean exit → marker = "TURN_COMPLETED"\n` +
   `  4. Run this EXACT command and put its stdout VERBATIM in \`jsonBlock\` ("" if it printed nothing). Do NOT parse, edit, judge, or act on it:\n` +
   `       ${AWK_EXTRACT} ${codexReviewFile}\n` +
   `  5. ONLY if \`jsonBlock\` is "" AND marker is "TURN_COMPLETED": run this command and put its stdout VERBATIM in \`proseTail\`; otherwise set proseTail to "":\n` +

package/framework/.claude/workflows/new2-resolve.js

@@ -76,7 +76,11 @@ const FIX_SCHEMA = {
     verified: { type: 'boolean', description: 'true only if you re-ran the originating gate and it passed' },
     // F-008 — terminal short-circuit (impossible-by-definition). Not trusted blindly.
     terminal: { type: 'boolean', description: 'true if no in-MAY-EDIT fix can ever satisfy the gate' },
-    terminalReason: { enum: ['out-of-ownership', 'baseline-not-reached', 'owner-gated', 'not-a-code-defect', ''] },
+    terminalReason: { enum: ['out-of-ownership', 'baseline-not-reached', 'owner-gated', 'not-a-code-defect', 'verification-posture-change', ''] },
+    // v5.6.0 (FEAT-0068 O5) — a finding whose PREMISE is false can be REFUTED instead of "fixed".
+    // Adversarially ratified below — never an easy escape hatch.
+    refuted: { type: 'boolean', description: "true if the finding's premise is FALSE (no defect exists) — change NOTHING, cite proof" },
+    refutedEvidence: { type: 'string', description: 'file:line proof the finding is wrong' },
     remedyFiles: { type: 'array', items: { type: 'string' }, description: 'files the real fix would require editing (for out-of-ownership JS verification)' },
     crashed: { type: 'boolean' },
     // F-022 — incidental findings outside this card's MAY-EDIT (so they are not dropped).
@@ -145,6 +149,8 @@ const brief = [
   `Reference modules (Read for exact semantics): ${REF}/`,
   `UI re-verify obligation: if your fix touches a UI file, re-run the Phase 2.6 E2E review (per ${REF}/review-cycle.md) before declaring verified.`,
   `If the fix requires editing files OUTSIDE MAY-EDIT, return terminal:true terminalReason:'out-of-ownership' remedyFiles:[...] (do NOT edit them). If the remedy is an owner-gated infra action, terminal:true terminalReason:'owner-gated'. Report any incidental defect outside MAY-EDIT in outOfScopeFindings.`,
+  `VALIDATE THE PREMISE FIRST (v5.6.0): before touching any file, check the finding against the actual code. If its premise is FALSE (misread code, condition already satisfied, documented-by-design), return refuted:true + refutedEvidence:'<file:line proof>' and change NOTHING — NEVER edit code to appease a wrong finding.`,
+  `VERIFICATION-POSTURE RULE (v5.6.0): a "fix" that disables, skips, or opt-in-gates a test/check/suite that an acceptance criterion of this batch mandates is FORBIDDEN — it erodes the DoD (FEAT-0068: a repair flag-gated the epic's visual-regression suite to silence a blocker). If that looks like the only available fix, return terminal:true terminalReason:'verification-posture-change' instead.`,
 ].filter(Boolean).join('\n')
 
 // JS-deterministic ownership check (F-008 anti-escape-hatch): are remedy files ⊆ MAY-EDIT?
@@ -213,6 +219,28 @@ try {
   )
 } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during tier-1', deferralClass: 'outage', outOfScopeFindings: [] }; throw e }
 
+// v5.6.0 (FEAT-0068 O5 — false-positive BLOCKER): refuted short-circuit, adversarially ratified.
+// The FEAT-0068 CR-001 blocker had a false premise ("baselines missing" = the documented bootstrap
+// state) and was "resolved" by flag-gating the epic's mandated visual-regression suite — 4.73M
+// spent eroding the DoD to appease a wrong finding. A ratified refutation resolves with ZERO edits.
+if (attempt && attempt.refuted && !attempt.terminal) {
+  let refConfirmed = selfJudges // reviewer-writer specialists self-verify (same trust model as terminal)
+  if (!selfJudges) {
+    try {
+      const rj = await agentSafe(
+        `A repair agent claims this finding's PREMISE IS FALSE (refuted) — no defect exists, nothing was changed. Claimed proof: ${attempt.refutedEvidence || attempt.note || '(none)'}\n\n${brief}\n\nIndependently verify the refutation against the actual files (grep/read them yourself; do NOT trust the claim). Return confirmed:true ONLY if the finding is genuinely wrong.`,
+        { label: `resolve:refute-judge:${card}`, phase: 'Verify', agentType: judgeAgent, schema: TERMINAL_JUDGE_SCHEMA }
+      )
+      refConfirmed = !!(rj && rj.confirmed)
+    } catch (_) { refConfirmed = false }
+  }
+  if (refConfirmed) {
+    log(`${kind} REFUTED (false premise${selfJudges ? '' : ', judge-ratified'}) — resolved with zero edits.`)
+    return { status: 'resolved', reason: `refuted: ${attempt.refutedEvidence || attempt.note || 'false premise'}`, outOfScopeFindings: collectOOS(attempt) }
+  }
+  log('refutation NOT ratified — treating as a real finding.')
+}
+
 // F-008 — terminal short-circuit, verified not trusted.
 if (attempt && attempt.terminal) {
   const tr = attempt.terminalReason || ''