baldart 5.4.1 → 5.6.0

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.6.0
+version: 1.8.0
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background
@@ -85,8 +85,9 @@ everywhere this skill branches on it — Step 3.5 resolves deterministically (it
 AUTONOMOUS branch) and **Step 3b's escape hatch is SKIPPED** (the user asked for
 `-auto`; a post-batch question — and a possible `/new` re-invocation at full
 inline cost — would break that promise even with a TTY present). `/new` only
-delegates **migration-free** batches (it probes `migration_plan.required`
-itself), so Step 3.5's one interactive question cannot fire on a delegated run —
+delegates **migration-free** batches (it probes ALL migration vocabularies
+itself — `migration_plan.required`, epic `db_migrations_summary`, per-card
+`db_migration.required`), so Step 3.5's one interactive question cannot fire on a delegated run —
 if you nonetheless find a declared, unapplied migration in a delegated batch,
 HALT and hand back to `/new` classic (`"batch con migrazione dichiarata — riesegui
 /new <cards> -auto -inline"`) instead of asking. Everything else is identical to a
@@ -129,8 +130,16 @@ untouched), so the schema is live **before** the workflow starts. It mirrors `/n
 1. **Find the batch's epic card(s)** — distinct `group.parent` of the resolved cards (or the `-full`
    parent). Read each epic YAML in `${paths.backlog_dir}` (`<PARENT>-*-epic.yml`, or the card whose
    `id == <PARENT>` / `group.is_epic: true`).
-2. **Look for `migration_plan` with `required: true`.** None → set `migration = { status: 'none' }`
-   and go to Step 4 (identical to today — zero extra prompts; do not surface anything).
+2. **Look for a declared migration — under ANY recognized vocabulary.** Primary: epic
+   `migration_plan` with `required: true`. **Compat aliases (consumer-overlay conventions —
+   FEAT-0067 root cause: probing only `migration_plan` made this gate structurally blind to
+   `db_migration`-declaring cards)**: epic `db_migrations_summary` (non-empty), or any batch card
+   with `db_migration.required: true` (map: `artifacts` ← `db_migration.expected_file`; `summary`
+   ← the slug; modalities ← `db_migration.remote_push` + overlay). Nothing declared → set
+   `migration = { status: 'none' }` and go to Step 4 (identical to today — zero extra prompts; do
+   not surface anything). Declared via ANY vocabulary → record `migrationDeclared: true` +
+   `declaredVia` in your own working state (Step 5.1b keys off it — it must NOT depend on the
+   workflow's residual ledger surviving) and continue below.
 3. **(declared) Verify `migration_plan.artifacts` exist on disk under `$MAIN`.** Any missing → do NOT
    apply or prompt; set `migration = { status: 'degraded', reason: 'artifact missing', artifacts }`
    and go to Step 4 (the migration falls back to the current end-of-batch owner-gated deferral — no
@@ -193,7 +202,9 @@ Workflow({ name: 'new2', args: {
 ```
 
 Record the kickoff time (`ts`) before the call — Step 5 uses it to stamp the
-real wall-clock duration (the workflow cannot read a clock).
+real wall-clock duration (the workflow cannot read a clock). Also record the
+pre-batch trunk sha (`git -C $MAIN rev-parse ${trunk}`) — Step 5.4b audits every
+non-card commit the batch introduced against it (v5.6.0).
 
 Capture `sessionId` the same way, in THIS skill's own context (not a subagent):
 `Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")`. The workflow stamps it as
@@ -245,6 +256,44 @@ returns when the batch is done. It returns:
    step-1b HALT fields — the `/new` pre-flight back-fill (step 1b-ii) then normalizes its
    `review_profile`/`owner_agent` on first ingestion, so even the crisis stub self-heals. This
    main-repo, **disk-verified** write is the SSOT — nothing is dropped even on a non-merged batch.
+   **Exception (v5.6.0):** residuals of kind `false-epic-closure` and `main-repo-contamination` are
+   **reconciliation ACTIONS, not backlog work** — do NOT mint follow-up cards for them. The former
+   is handled by step 2's REOPEN branch; the latter by step 4b's hygiene audit (inspect + restore
+   the named main-repo paths).
+1b. **Migration Sync Tail (post-merge "branch B" — the interactive owner-gated deploy the
+   autonomous batch could not run).** The workflow has returned and merged; you are the skill
+   main loop, in `$MAIN`, typically on `$TRUNK` — exactly the precondition of the project's
+   post-merge sync gate (e.g. the overlay's "on trunk, post-merge" branch). **Trigger — EITHER
+   condition, independently** (belt-and-braces: the FEAT-0067 failure dropped the residual
+   mid-run, so this tail keys on the Step-3.5 DECLARATION, never only on the ledger):
+   (a) `migrationDeclared` from Step 3.5 (any vocabulary) with `migration.status ≠ 'applied'`;
+   (b) any `residuals[]` entry whose kind/owner-gated action maps to `db-migration-deploy`.
+   Neither → skip silently. Steps:
+   - **Resolve the project's post-merge sync contract**, in source order: (i) the batch cards'
+     `db_migration.remote_push` / `migration_plan` (check command + push command); (ii) the
+     post-merge / trunk branch of the Migration Sync Gate section in `.baldart/overlays/new.md`;
+     (iii) `migration_plan.verify` alone (check-only). Nothing resolvable → skip the tail (the
+     step-1 follow-up card remains the ledger) and say so in the presentation.
+   - **Run the read-only sync CHECK first** (e.g. the overlay's check-sync command), from `$MAIN`
+     on `$TRUNK` (if `$MAIN` is not on `$TRUNK`, do not switch branches yourself — report and
+     leave the follow-up as ledger). **Green** → the migration is live: the `db-migration-deploy`
+     residual is SATISFIED (no follow-up needed — if step 1 already created one, delete it in the
+     same reconciliation commit and note why); record it and let step 2 DONE-flip the migration
+     card with its schema AC satisfied.
+   - **Red + INTERACTIVE** → ONE `AskUserQuestion` (post-batch skill-layer interaction, same
+     class as Step 3b — the zero-ask-during-batch invariant is untouched): *"La migration del
+     batch non risulta applicata al DB remoto (check-sync rosso). Come procedo?"* Options:
+     **[Push now]** (run the declared owner-gated push command from `$TRUNK` — honour
+     `stack.schema_deploy_from_trunk_only`; output to `/tmp/migration-push-<firstCard>.log`,
+     surface the exit code, then RE-RUN the check and require green) / **[Defer]** (keep the
+     step-1 follow-up card as the ledger; the card stays DONE-with-follow-up per its
+     `owner-gated` class) / **[Override]** (record the user's verbatim reason). Never push
+     without the user picking it.
+   - **Red + AUTONOMOUS** (env / delegated `/new -auto` origin — Step 1.5) → NEVER push
+     (outward, owner-gated). Ensure the step-1 follow-up exists, and surface the pending deploy
+     PROMINENTLY in the presentation (step 4) — a truthful "schema NOT live" line, not a footnote.
+   - Record `migration_sync_tail: { ran, trigger: 'declared'|'residual'|'both', check:
+     'green'|'red'|'unavailable', pushed: <bool>, outcome }` for telemetry (step 5).
 2. **Mark deferred cards DONE — only after their follow-up exists AND every deferral class allows
    it (F-040/H + A3).** Some committed cards were intentionally left **NON-DONE** because they carry
    an open deferred AC: they are `perCardResults[]` entries with `deferred:true` plus a
@@ -267,11 +316,25 @@ returns when the batch is done. It returns:
    **Then re-run the epic-closure check for the cards just marked DONE.** The merge agent's
    epic-closure (Phase 6b step 5e) ran BEFORE this step, when the deferred cards were still
    NON-DONE — so an epic whose last open child was a deferred card is still TODO and nothing
-   else will ever close it. For each distinct `group.parent` of the cards marked DONE here: if
-   `grep -l "parent: <EPIC-ID>" ${paths.backlog_dir}/*.yml | xargs grep -L "status: DONE"`
-   prints nothing, set the epic card `status: DONE` + `completed_date` + note
-   `"epic-closure gate — all children DONE (post-run, new2 skill)"`, folded into the SAME
-   reconciliation commit. If any child is still open, leave the epic untouched.
+   else will ever close it. For each distinct `group.parent` of the cards marked DONE here,
+   close ONLY when the FULL v5.6.0 predicate holds (the same one the merge agent runs —
+   `merge-cleanup.md` § epic closure): (a) `grep -l "parent: <EPIC-ID>" ${paths.backlog_dir}/*.yml
+   | xargs grep -L "status: DONE"` prints nothing — **follow-up cards count as children** (step 1
+   just materialised them here in the main repo, so this grep now sees them); (b) no `residuals[]`
+   entry of a blocking class (`scope-expansion`/`unresolved`/`ac-unmet`/`out-of-ownership`) maps to
+   a child of this epic; (c) the epic YAML's own `acceptance_criteria` are all `[x]` — verify any
+   still-`[ ]` item with its `ac_verification` oracle (or a targeted check) and flip it ONLY with
+   evidence; an unverifiable AC leaves the epic OPEN. When all three hold, set the epic
+   `status: DONE` + `completed_date` + note `"epic-closure gate — children DONE + epic ACs
+   verified (post-run, new2 skill)"`, folded into the SAME reconciliation commit. Otherwise leave
+   the epic untouched and say why in the presentation.
+   **REOPEN branch (v5.6.0 — the ratchet is two-way now).** For every `false-epic-closure`
+   residual, AND for any epic found `status: DONE` on disk while the grep above still prints an
+   open child (follow-ups included) or a closure-invalidating finding stands: flip the epic back
+   to `status: IN_PROGRESS`, remove/annotate its `completed_date`, add note `"REOPENED — closed
+   against open scope (false DONE, v5.6.0 guard)"`, and fold into the same reconciliation commit.
+   An epic whose registry/ADR text says "goal not achieved" while its YAML says DONE is exactly
+   the FEAT-0068 contradiction this branch exists to prevent — the STATE wins, not the prose.
 3. **Resume if degraded — HARD-BOUNDED (v4.92.0).** If `degraded` is true, re-invoke
    the workflow with `Workflow({ scriptPath, resumeFromRunId })` (same `args` + the
    new `ts`). The per-card **skip-completed** guard makes the resume idempotent —
@@ -334,11 +397,31 @@ returns when the batch is done. It returns:
      (out of scope by design — the workflow is autonomous).
    - Record `escape_hatch: { eligible: N, offered: <bool>, ran_new: <bool>, followups: [...] }`
      in telemetry (step 5 below) so the A/B stays honest about when the hatch was used.
-4. **Present.** Print `report` verbatim. Surface `residuals` prominently
-   ("questi residui sono tracciati come follow-up: …") — the post-run review that
-   replaced the ~25 mid-run questions. If `degraded`, say so plainly (the run was
-   incomplete and resumed). If the escape hatch ran `/new` (step 3b), fold its outcome
-   into the presentation (which follow-ups were closed by `/new`).
+4. **Present.** Print `report` verbatim — **including its verdict headline** (`⚠️ PARTIAL` /
+   `✅ COMPLETO`, v5.6.0): NEVER re-headline a PARTIAL run as a success in your own framing, and
+   never bury an epic-goal gap under a completion table (the FEAT-0068 report said "✅ 6/6 DONE"
+   over a disclosed-but-buried HIGH gap — the user discovered it only by asking). Surface
+   `residuals` prominently ("questi residui sono tracciati come follow-up: …") — the post-run
+   review that replaced the ~25 mid-run questions; a HIGH residual is REMAINING WORK, present it
+   as such. If `degraded`, say so plainly (the run was incomplete and resumed). If the escape
+   hatch ran `/new` (step 3b), fold its outcome into the presentation (which follow-ups were
+   closed by `/new`).
+4b. **Batch git hygiene audit (v5.6.0 — never assert provenance without checking).** From the
+   kickoff you know the trunk's pre-batch sha (record `git -C $MAIN rev-parse ${trunk}` at Step 4
+   BEFORE launching the workflow). Now:
+   - `git -C $MAIN log --oneline <pre-sha>..HEAD` — for every commit whose subject does NOT
+     reference a batch card id (e.g. `[safety]`, unexpected chores), run `git show --stat <sha>`
+     and LIST it in the presentation with its files. Never attribute a commit to "a previous run"
+     without this check (the FEAT-0068 orchestrator asserted exactly that, and it was false).
+     A safety/sweep commit whose files are outside the batch's bookkeeping is a finding to
+     surface, not to normalize.
+   - `git -C $MAIN stash list` — any stash created during this batch (grep the batch/card ids and
+     the `baldart-new2-` label) MUST be reconciled NOW: inspect (`git stash show -p`), then apply
+     or drop with the user's standing policy — in AUTONOMOUS mode leave it but list it as a
+     PROMINENT pending item, never as a footnote and never "not mine to drop" (if this batch's
+     machinery created it, it IS yours to reconcile).
+   - Every `main-repo-contamination` residual: inspect the named paths in `$MAIN` and restore
+     them (they are the commit-agent detour's droppings), reporting what was restored.
 5. **Record truthful telemetry — reconciled against disk (F-040).** Before appending `telemetry`
    to `${metricsDir}/skill-runs.jsonl`, fill the fields the workflow could not compute and
    **reconcile the report against the real disk state** (agent `reason` strings can over-claim — a
@@ -358,7 +441,8 @@ returns when the batch is done. It returns:
    (partial, output-only, excludes nested workflows). Keep `degraded`/`degradation_reasons` +
    `cards_deferred_done_pending` in the record so
    the A/B comparison stays honest. Also record `migration_gate: <migration.status>`
-   (`none`|`applied`|`skipped`|`degraded`) — the Step-3.5 gate is a pre-launch interaction, NOT a
+   (`none`|`applied`|`skipped`|`degraded`) and `migration_sync_tail` (Step 5.1b — whether the
+   post-merge check ran, its outcome, and whether an owner-gated push was user-approved) — the Step-3.5 gate is a pre-launch interaction, NOT a
    mid-batch question, so it does not break the zero-ask-during-batch invariant; logging it keeps the
    A/B honest about when a migration was front-loaded. Keep `deferral_breakdown` (per-class counts
    of WHY residuals became follow-ups instead of in-batch fixes) in the record — a class dominating

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):