baldart 4.23.0 → 4.24.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.24.1] - 2026-06-10
+
+**`new2`: an owner-gated gate no longer destroys a completed card (silent work-loss → commit + defer).** A real `/new2` run on a schema-change card produced **zero output** despite 52 min of work: the card's only obstacle was an *owner-gated* step (`db:check-sync` needs an approved remote `db:push`). That step was correctly `policy-deferred` up front — but the **same** condition was *also* re-raised by a reviewer as a fresh `MIGRATION_NOT_DEPLOYED` blocker, which (via the review-block branch's `s !== 'resolved' → cardBlocked`) triggered `rollbackCard`'s `git clean -fd` and **erased the completed migration**. Compounding it: the `E4-file-diff` gate logged `AUTO-REVERTED` while reverting *nothing* (leaving the card's DoD-mandated ADR/ER-doc edits orphaned in the worktree — its MAY-EDIT map was narrower than the DoD), and the residual follow-up was written *inside the worktree* and marked `materialized:true` without disk proof, so it vanished when the batch didn't merge. Root cause confirmed via the gate ledger + on-disk state + two rounds of adversarial review (the obvious "E4 reverted it" diagnosis was **wrong** — E4 was a no-op; `rollbackCard` was the eraser). **PATCH** (bug-fix to the EXPERIMENTAL `new2` skill + its workflows; **no `baldart.config.yml` key** and **no change to shared `/new` prose** — the DONE-deferral is handled entirely inside `new2`'s own merge prompt + skill, so `/new` interactive is provably unaffected; the schema-change propagation rule does not apply).
+
+### Fixed
+
+- **`framework/.claude/workflows/new2.js` + `new2-resolve.js` — classification-based card-block (the primary fix, F-040).** `resolve()` now propagates a structured `deferralClass` from `new2-resolve`'s terminal-judge. A review-block that resolves to an **owner-gated / not-a-code-defect** deferral no longer sets `cardBlocked` → the card's *complete* code is committed (it is **not** rolled back); only a genuine unresolved **code** defect (or `out-of-ownership`/`baseline`/`outage`) still blocks + rolls back. A deliberately-broken migration (`db:reset` failing) is still classified code-defect → blocks, so this is not an over-match escape hatch.
+- **`new2.js` — `E4-file-diff` is honest.** The old `AUTO-REVERTED` log reverted nothing. The owner agent now reconciles out-of-ownership edits itself (per `implement.md §11b`) and reports `revertedOutOfOwnership`; the gate logs `REVERTED` / `FLAGGED` to match reality, and an unresolved violation becomes a tracked residual (never silent, never orphaned).
+- **`new2.js` pre-flight — ownership map ⊇ DoD (root cause of the E4 false positive).** A card's MAY-EDIT now = `files_likely_touched` ∪ paths **named explicitly** in its `acceptance_criteria`/`definition_of_done` (the ADR/data-model/ER doc a schema-change must touch), so editing a DoD-mandated doc is no longer a file-diff violation.
+- **`new2.js` + `new2/SKILL.md` — DONE deferred to the skill, gated on the follow-up existing on disk (closes the F-029 false-DONE the review surfaced).** A card carrying an open owner-gated/policy-deferred AC commits its code but stays **NON-DONE**; the merge agent is told to leave those cards non-DONE; the **skill** marks them DONE post-run **only after** verifying the deferral's follow-up exists on disk in the main repo (fail-loud otherwise — never DONE with a dropped requirement).
+- **`new2-resolve.js` + `new2/SKILL.md` — follow-ups are reliable.** Follow-up materialisation is best-effort inside the workflow (it rides the merge if the batch merges); the **skill is the SSOT**, verifying every residual against the **main-repo** disk and creating any missing follow-up there — so a non-merged batch never loses one. `materialized` is now advisory only.
+- **`new2.js` (Fix G) — AC-deferral dedup is text-drift-proof.** The policy-deferred-AC key is now scoped to the AC *number* (`acSig`), so a deferred AC is no longer re-routed to `resolve()` a second time when the pre-flight and implement agents word the AC text slightly differently.
+- **`new2/SKILL.md` — telemetry reconciled against disk.** Before recording, the skill verifies each `committed` card actually has a commit on trunk and never presents progress the disk does not show; adds `cards_deferred_done_pending` so the A/B record distinguishes "code landed" from "DONE".
+
+## [4.24.0] - 2026-06-10
+
+**Atomic backlog-ID allocator — no FEAT/BUG collisions across parallel worktrees.** When several `/prd` (or `/new`/`new2` follow-up) sessions run in parallel on sibling worktrees, each branched from the same trunk, the old `max(^id: FEAT-) + 1` scan made them all land on the **same next integer**: the other session's card was in flight on an unmerged sibling branch, invisible to both the local backlog and the trunk merge-base — so two epics both became `FEAT-0024` and conflicted at rebase/merge. The `git fetch` + merge-base scan only ever covered *already-merged* IDs, never in-flight ones. A new allocator anchors a lock + per-prefix high-water mark in `$MAIN/.worktrees/` (the shared coordination point every worktree already reaches via `git rev-parse --git-common-dir`, gitignored like `registry.json`), so a reservation is atomic across every worktree **on the same machine**. The high-water mark bumped under the lock is the correctness anchor; `max()` against the real backlog + sibling-worktree backlogs + reservations log + trunk merge-base makes it **self-healing**. **MINOR** (additive capability on the `worktree-manager` skill; opt-in — callers fall back to the inline merge-base scan + `[ID-RACE-RISK]` note when the script is absent, so older installs and cross-machine cloud agents are unaffected. **No `baldart.config.yml` key** — the allocator reuses `paths.backlog_dir` + the gitignored `.worktrees/` convention, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/worktree-manager/scripts/allocate-id.sh`** — prefix-parametric (`FEAT`/`BUG`/`UI`/`DOC`/`PERF`/…) atomic ID allocator. `reserve <PREFIX> <slug>` prints the next free integer zero-padded to 4 digits; `release <worktree-path>` prunes a finished worktree's reservations. Cross-process mutex via atomic `mkdir` (stale-stolen after 30s via the lock dir's own mtime — a directory, not a git ref, so it never touches the shared `refs/stash` that `git stash` in worktrees is forbidden over). The slow `git fetch` runs **before** the lock, keeping the critical section local-FS-only (sub-second). Reads `paths.backlog_dir` + `git.trunk_branch` from `baldart.config.yml` and resolves `$MAIN` at runtime — no hardcoded project facts (passes the framework-edit-gate). Same-machine scope; the trunk merge-base scan is the best-effort cross-machine guard.
+
+### Changed
+
+- **`framework/.claude/skills/worktree-manager/SKILL.md`** — new section **"ID Allocation"** documenting the allocator, the shared `.id-alloc.lock/` / `.id-hwm-<PREFIX>` / `id-reservations.jsonl` files, the same-machine scope + opt-in fallback contract, and the gap-tolerant monotonic-counter design. `release` is wired into the cleanup paths of `/mw` (step 7), `mw-docs` (step 6), and `/cw` (step 4).
+- **`framework/.claude/agents/prd-card-writer.md`** — § "FEAT-XXXX numbering" + Pre-Generation Checklist item 1 now reserve the integer via the allocator (primary path), with the trunk fetch + merge-base scan + `[ID-RACE-RISK]` note as the documented fallback when the script is absent. Applies to any prefix the writer mints.
+- **`framework/.claude/agents/prd.md`** — § 4.1 NAMING CONVENTIONS prefers the allocator (any prefix) over the plain backlog scan, with the same documented fallback.
+
 ## [4.23.0] - 2026-06-09
 
 **Functional Traceability Gate — no orphan UI affordances from mockups.** Handed-off mockups (Claude Design / Figma / the internal generators) routinely add interactive-looking chrome — buttons, icons, menu entries — that no requirement backed. Implementing a mockup **1:1 for fidelity** materialised that chrome into real markup + dead handlers + unused icon imports, and the cruft propagated forever. A new **unconditional** gate (independent of `features.has_design_system`) now requires every interactive or iconographic artifact to trace to a function before it becomes code: each artifact is classified **backed** (implement) / **decorative** (static-render, `aria-hidden`) / **orphan** (drop or escalate — never silent). The oracle is the PRD **UI Element Inventory `function_ref`** allowlist → card AC → orphan. Enforced at three boundaries: PRD mockup-intake (orphans become BLOCKING Discovery items), `ui-expert` implementation-time (BLOCKING pre-work), and `code-reviewer` / `/design-review` per-merge (`UI_ORPHAN_AFFORDANCE` HIGH finding). The `visual-fidelity-verifier` gains a `resolved_orphans` carve-out so a deliberately-dropped orphan is *expected-absent*, not a `component-missing` false positive. **MINOR** (additive discipline across existing UI surfaces; no new agent/skill/command and **no `baldart.config.yml` key** — the gate is registry-independent and reads its allowlist from the PRD inventory, so the schema-change propagation rule does not apply).

package/VERSION

@@ -1 +1 @@
-4.23.0
+4.24.1

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

@@ -300,18 +300,36 @@ applies even when N=1.
 
 ### FEAT-XXXX numbering
 
-- Pick the next free `FEAT-XXXX` integer (Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-  add 1). **Reserve the entire integer for this epic** — do NOT reuse the integer
-  for unrelated cards even if it has fewer than ~99 children.
-- **Scan the canonical backlog, not just the worktree branch.** The worktree
-  branched from the trunk may not contain IDs committed on sibling branches not
-  yet merged. Before computing max, run
-  `git fetch <git.trunk_branch>` and grep `${paths.backlog_dir}/` on the merge-base of the
-  trunk (`git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)` plus
-  the local worktree) so concurrent PRD sessions don't both land on the same
-  "next free" integer. If a `git fetch` is not possible (offline), state the
-  reservation is best-effort against the local view and surface a
-  `[ID-RACE-RISK]` note so the caller can re-verify before commit.
+- Pick the next free `FEAT-XXXX` integer. **Reserve the entire integer for this
+  epic** — do NOT reuse the integer for unrelated cards even if it has fewer than
+  ~99 children.
+- **Use the atomic allocator when present (primary path).** Plain `max + 1` is
+  unsafe under parallelism: concurrent PRD sessions on sibling worktrees, all
+  branched from the same trunk, see the same max (the other session's card is in
+  flight on an unmerged branch) and both pick the same integer → merge conflict.
+  The `worktree-manager` allocator reserves the integer atomically across every
+  worktree on this machine (lock + shared high-water mark under `.worktrees/`):
+
+  ```bash
+  # $MAIN is the main repo root: dirname of `git rev-parse --git-common-dir`.
+  ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+  if [ -x "$ALLOC" ]; then
+    N="$("$ALLOC" reserve FEAT "<slug>")"   # e.g. prints 0024
+    # → the reserved epic id is FEAT-$N. The integer is now claimed; a parallel
+    #   session calling reserve will get FEAT-$((N+1)).
+  fi
+  ```
+
+  State the reserved integer in your response.
+- **Fallback when the allocator is absent** (older install, no script): degrade to
+  the canonical-backlog scan — `git fetch <git.trunk_branch>`, then
+  `max` over `git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)`
+  plus the local worktree backlog. This still misses in-flight sibling-worktree
+  IDs, so surface a `[ID-RACE-RISK]` note so the caller can re-verify before
+  commit. If `git fetch` is impossible (offline), say the reservation is
+  best-effort against the local view.
+- The same procedure applies to any other prefix you mint (`BUG`, `UI`, `DOC`,
+  `PERF`): `reserve <PREFIX> <slug>` — the allocator is prefix-parametric.
 
 ### FORBIDDEN PATTERNS — agent MUST refuse to generate
 
@@ -350,10 +368,12 @@ Mirror their structure when generating new epic+child sets.
 
 Before writing the first YAML file, confirm and report to the caller:
 
-1. **Reserved FEAT-XXXX integer**: Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-   pick max+1, per the concurrency-safe procedure in § "FEAT-XXXX numbering"
-   (fetch trunk + merge-base scan to avoid duplicate IDs across parallel
-   sessions). State the chosen integer in your response.
+1. **Reserved FEAT-XXXX integer**: reserve it via the atomic allocator
+   (`allocate-id.sh reserve FEAT <slug>`), per § "FEAT-XXXX numbering" — this is
+   the concurrency-safe path that prevents duplicate IDs across parallel sessions
+   on sibling worktrees. If the allocator is absent, fall back to the trunk
+   fetch + merge-base scan with an `[ID-RACE-RISK]` note. State the chosen
+   integer in your response.
 2. **Drafted epic + N children list**: list the planned filenames
    (`FEAT-XXXX-00-<slug>-epic.yml`, `FEAT-XXXX-01-<sub-slug>.yml`, ...) BEFORE
    writing them. This is a contract — the actual files MUST match the list.

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

@@ -498,7 +498,20 @@ Create protocol-compliant backlog cards for every actionable step. Cards MUST fo
 
 #### 4.1 — NAMING CONVENTIONS
 
-Before creating cards, scan `${paths.backlog_dir}/*.yml` to determine the next available number. File naming rules:
+Before creating cards, reserve the next number for the chosen prefix. **Prefer the
+atomic allocator** — a plain `${paths.backlog_dir}/*.yml` scan collides under
+parallelism (concurrent sessions on sibling worktrees both pick the same "next"
+integer and conflict at merge):
+
+```bash
+# $MAIN = dirname of `git rev-parse --git-common-dir` (shared across worktrees).
+ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+[ -x "$ALLOC" ] && N="$("$ALLOC" reserve FEAT <slug>")   # also BUG | UI | DOC | PERF
+```
+
+If the allocator is absent (older install), fall back to scanning
+`${paths.backlog_dir}/*.yml` for the max and add 1, noting `[ID-RACE-RISK]`. See
+`worktree-manager` § "ID Allocation" for the mechanism. File naming rules:
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|

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

@@ -117,42 +117,56 @@ returns when the batch is done. It returns:
 
 - `report` — ready-to-show markdown batch summary.
 - `residuals` — the **OFFLINE-SAFE ledger of record**: every residual the workflow
-  could not finish, each `{ card, kind, evidence, materialized }`. A residual with
-  `materialized:false` has NO follow-up card on disk yet (e.g. the workflow hit an
-  outage where no agent could write the file). **You (the skill) must reconcile it.**
+  could not finish, each `{ card, kind, evidence, materialized }`. The `materialized`
+  flag is **advisory only** — `true` means the workflow *attempted* a write (possibly
+  into a worktree that never merged), not that a card exists on disk in the main repo.
+  **You (the skill) must reconcile EVERY residual against the main-repo disk** (Step 5.1).
 - `degraded` / `degradationReasons` — the batch stopped early under a sustained
   outage (or another degradation). The batch is NOT complete; it must be resumed.
 - `telemetry` — the Phase-8 record (`variant:"new2"`).
 
 ### Step 5 — Reconcile, resume, present, record
 
-1. **Materialise missing follow-ups (offline-safe — you have filesystem access, the
-   workflow does not).** For every `residuals[]` entry with `materialized:false`,
-   create a follow-up card `${paths.backlog_dir}/<card>-followup-<kind>.yml` (status:
-   TODO). **Delegate the write to the `prd-card-writer` agent** — the same owner the
-   workflow uses (card-template, Rule C `review_profile`, `owner_agent` routed to the
-   residual's domain, traceability) — derived from the residual (≥1 requirement;
-   `acceptance_criteria` = the verbatim residual; `files_likely_touched` from the card's
-   ownership). Do NOT hand-write a minimal stub — the offline path must match the
-   agent-path quality (F-039). It MUST pass the `/new` pre-flight field check. If
-   `prd-card-writer` itself is unavailable (total outage), fall back to a minimal valid
-   stub so the card still exists. This is the layer that guarantees **nothing is ever
-   dropped, even when every agent was dead** during the run.
-2. **Resume if degraded.** If `degraded` is true, re-invoke the workflow with
+1. **Materialise follow-ups in the MAIN repo — verify on disk, do NOT trust `materialized`
+   (F-040).** The workflow's agents run cd'd into the *worktree*, so any follow-up they wrote
+   may live in a worktree that was NOT merged (and is now gone) — `materialized:true` only means
+   "the workflow attempted a write", never proof on disk. So for **every** `residuals[]` entry
+   (regardless of the `materialized` flag), check whether a matching follow-up card actually exists
+   on disk under `${paths.backlog_dir}` in the **MAIN repo** (`<card>-followup-*.yml`). If it is
+   absent, create it by **delegating to the `prd-card-writer` agent** — the same owner the workflow
+   uses (card-template, Rule C `review_profile`, `owner_agent` routed to the residual's domain,
+   traceability) — derived from the residual (≥1 requirement; `acceptance_criteria` = the verbatim
+   residual; `files_likely_touched` from the card's ownership). Do NOT hand-write a minimal stub —
+   the offline path must match agent-path quality (F-039); it MUST pass the `/new` pre-flight field
+   check. If `prd-card-writer` is unavailable (total outage), fall back to a minimal valid stub. This
+   main-repo, **disk-verified** write is the SSOT — nothing is dropped even on a non-merged batch.
+2. **Mark deferred cards DONE — only after their follow-up exists (F-040/H).** Some committed cards
+   were intentionally left **NON-DONE** because they carry an open owner-gated/policy-deferred AC
+   (e.g. a pending remote `db:push`): they are `perCardResults[]` entries with `deferred:true` (also
+   `cards_deferred_done_pending` in telemetry + the `F040-deferred` ledger row). For each such card,
+   now that step 1 guaranteed its deferral's follow-up exists on disk in the main repo, set the card
+   `status: DONE` + `completed_date` + an implementation_note (`"DONE post-run (new2) — AC deferred to
+   follow-up <id>"`) in `${paths.backlog_dir}/<card>.yml`, and fold all of them into ONE reconciliation
+   commit in the MAIN repo. **If a card's follow-up could NOT be created in step 1, leave it NON-DONE
+   and surface it** — fail-loud; NEVER mark a card DONE with a silently-dropped requirement (F-029).
+3. **Resume if degraded.** 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 — already-committed
    cards are skipped, only the incomplete/blocked ones run. Repeat until `degraded`
    is false (or the same cards stall twice → surface to the user).
-3. **Present.** Print `report` verbatim. Surface `residuals` prominently
+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).
-4. **Record truthful telemetry.** Before appending `telemetry` to
-   `${metricsDir}/skill-runs.jsonl`, fill the fields the workflow could not compute:
-   `wall_clock_s` (now − kickoff `ts`) and `followups_on_disk` (count the actual
-   follow-up files on disk, NOT `residualFollowups.length` — which double-counts).
-   `total_tokens`/`agent_count` come from the workflow (`budget.spent()` delta +
-   spawn counter); if `total_tokens` is null, run the `/new` Phase-8 `-stats` script
-   to backfill real `usage`. Keep `degraded`/`degradation_reasons` in the record so
-   the A/B comparison can exclude or weight degraded runs. Do NOT re-summarise the
-   cards — the workflow already did.
+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
+   residual may say "AC PASS / migration created" about a change a rollback later erased). Verify:
+   every `perCardResults` entry marked `committed` actually has a commit in `${trunk}`
+   (`git -C $MAIN log --oneline ${trunk} | grep <card>`); annotate any divergence and never present
+   progress the disk does not show. Then fill `wall_clock_s` (now − kickoff `ts`) and
+   `followups_on_disk` (count the actual follow-up files on disk in the main repo, NOT
+   `residualFollowups.length` — which double-counts). `total_tokens`/`agent_count` come from the
+   workflow; if `total_tokens` is null, run the `/new` Phase-8 `-stats` script to backfill real
+   `usage`. Keep `degraded`/`degradation_reasons` + `cards_deferred_done_pending` in the record so
+   the A/B comparison stays honest. Do NOT re-summarise the cards — the workflow already did.

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

@@ -292,7 +292,9 @@ git -C "$WORKTREE_PATH" rebase "origin/$TRUNK"
 # 5. Sync local trunk ref — reuse /mw "Common" block: ff-only pull when main
 #    repo HEAD is already $TRUNK; otherwise just fetch.
 
-# 6. Remove the registry entry for this worktree.
+# 6. Remove the registry entry for this worktree, then release its backlog-ID
+#    reservations (best-effort, high-water mark untouched):
+#    .claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
 ```
 
 **Forbidden in docs merge**: pre-merge `npm run build`, `npx eslint`, `npx tsc`, `npm run test`, post-merge `npm run build`. The whole point of docs mode is that these gates are inapplicable.
@@ -356,6 +358,57 @@ Create the file if it doesn't exist. Update it on every `/nw`, `/mw`, `/cw` oper
 
 ---
 
+## ID Allocation — atomic backlog-ID reservation across parallel worktrees
+
+When several PRD / card sessions run in parallel on sibling worktrees, each
+branched from the same trunk, a plain `max(^id: PREFIX-) + 1` scan makes them all
+land on the **same next integer**: the other session's card is in flight on an
+unmerged sibling branch, invisible to both the local backlog and the trunk
+merge-base. They collide at rebase/merge time.
+
+`scripts/allocate-id.sh` closes that race **on the same machine**. Every worktree
+shares one main repo root (resolved from `git rev-parse --git-common-dir`), and
+`.worktrees/` lives there and is gitignored — so it is the natural shared
+coordination point, exactly like `registry.json`. The allocator anchors a lock
+and a per-prefix high-water-mark there:
+
+```bash
+# Reserve the next free integer for a prefix (FEAT, BUG, UI, DOC, PERF, …).
+# Prints the integer zero-padded to 4 digits on stdout; diagnostics on stderr.
+.claude/skills/worktree-manager/scripts/allocate-id.sh reserve FEAT <slug>
+
+# Release a finished worktree's reservations (best-effort prune; never blocks).
+.claude/skills/worktree-manager/scripts/allocate-id.sh release <worktree-path>
+```
+
+Shared files, all under `$MAIN/.worktrees/` (already gitignored):
+- `.id-alloc.lock/` — cross-process mutex (atomic `mkdir`, stale-stolen after 30s
+  via the dir's own mtime; it is a directory, NOT a git ref, so it does not touch
+  the shared `refs/stash` that `git stash` in worktrees is forbidden over).
+- `.id-hwm-<PREFIX>` — monotonic high-water mark per prefix. **This is the
+  correctness anchor**: bumped under the lock, never decremented.
+- `id-reservations.jsonl` — append-only `{prefix,id,worktree,slug,ts}` log for
+  observability + `release` pruning. NOT load-bearing for correctness.
+
+Inside the lock, `reserve` takes `NEXT = max(high-water file, local backlog, every
+sibling worktree's backlog from registry.json, reservations log, trunk
+merge-base) + 1`. The `max()` against the real backlog makes it **self-healing**:
+if `.id-hwm-*` is ever lost or a card was created bypassing the allocator, the
+next reservation still skips occupied numbers. Abandoned reservations leave
+**gaps**, which is fine — backlog IDs need not be contiguous, and "reserve the
+whole integer, never reuse" is already the rule.
+
+**Scope: same machine only.** The shared file cannot reach separate cloud agents;
+the trunk merge-base scan inside `reserve` is the best-effort cross-machine guard.
+Callers (`prd-card-writer`, the `prd` agent) invoke `reserve` when the script is
+present and **fall back to their inline merge-base scan + `[ID-RACE-RISK]` note**
+when it is absent (older installs) — the allocator is additive, never required.
+
+`release` is wired into the cleanup path of `/mw`, `mw-docs`, and `/cw` (see those
+steps) so a merged/cleaned worktree's reservations are pruned.
+
+---
+
 ## /nw — New Worktree
 
 Supports three modes:
@@ -1077,6 +1130,13 @@ git worktree prune
 
 Remove the entry from `.worktrees/registry.json`.
 
+Also release this worktree's backlog-ID reservations (best-effort; the high-water
+mark stays untouched so numbering remains monotonic):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
+```
+
 ### 8. Report
 
 ```
@@ -1184,7 +1244,12 @@ git worktree prune
 
 ### 4. Update registry
 
-Remove cleaned entries from `.worktrees/registry.json`.
+Remove cleaned entries from `.worktrees/registry.json`. For each removed
+worktree, also release its backlog-ID reservations (best-effort):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "<removed-worktree-path>" 2>/dev/null || true
+```
 
 ### 5. Report
 

package/framework/.claude/skills/worktree-manager/scripts/allocate-id.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+#
+# allocate-id.sh — atomic, cross-worktree backlog-ID allocator (same machine).
+#
+# Problem it solves: several PRD/card sessions running in parallel on sibling
+# worktrees all branch from the same trunk, so each computes the same
+# "max(^id: PREFIX-) + 1" and they collide at rebase/merge time. A plain
+# backlog scan cannot see IDs that are still in flight on an unmerged sibling
+# worktree branch.
+#
+# Mechanism: every worktree shares the same main repo root (resolved from
+# `git rev-parse --git-common-dir`), and `.worktrees/` lives there and is
+# gitignored. We anchor a lock + a per-prefix high-water-mark file there, so a
+# reservation is atomic across every worktree on this machine. The high-water
+# bumped under the lock is the correctness mechanism; the max() against the real
+# backlog makes it self-healing if the counter file is ever lost or bypassed.
+#
+# Scope: SAME MACHINE only (a shared local file). Cross-machine (separate cloud
+# agents) is not covered here — the caller keeps the merge-base scan as a
+# best-effort cross-machine guard and surfaces an [ID-RACE-RISK] note.
+#
+# Usage:
+#   allocate-id.sh reserve <PREFIX> <slug>     # prints the reserved integer, zero-padded to 4
+#   allocate-id.sh release <worktree-path>     # prunes that worktree's reservations (best-effort)
+#
+# Exit non-zero on hard failure (not a git repo, lock unobtainable) so the
+# caller can fall back to its inline scan. All diagnostics go to stderr; stdout
+# carries ONLY the allocated number on success.
+
+set -u
+
+LOCK_STALE_SECONDS=30
+LOCK_MAX_TRIES=150   # ~30s at 0.2s/try
+
+err() { printf '%s\n' "$*" >&2; }
+
+# --- Resolve the shared main repo root from any worktree -------------------
+resolve_main() {
+  local common
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$common" in
+    /*) ;;                          # already absolute
+    *)  common="$(pwd)/$common" ;;  # relative (we're in the main repo) → absolutise
+  esac
+  (cd "$common/.." 2>/dev/null && pwd) || return 1
+}
+
+# --- Read a paths.* / git.* scalar from baldart.config.yml -----------------
+config_scalar() {
+  # $1 = top-level block (paths|git), $2 = key
+  local block="$1" key="$2" cfg="$MAIN/baldart.config.yml"
+  [ -f "$cfg" ] || return 0
+  grep -A60 "^${block}:" "$cfg" 2>/dev/null \
+    | grep -m1 "[[:space:]]*${key}:" \
+    | sed -E "s/.*${key}:[[:space:]]*\"?([^\"#]*)\"?.*/\1/" \
+    | sed -E 's/[[:space:]]+$//'
+}
+
+# --- Highest integer for PREFIX across one or more directories -------------
+scan_dirs_max() {
+  local prefix="$1"; shift
+  local max="$1"; shift     # starting floor
+  local d line n
+  for d in "$@"; do
+    [ -d "$d" ] || continue
+    while IFS= read -r line; do
+      [ -n "$line" ] || continue
+      n="$(printf '%s' "$line" | sed -E "s/^id:[[:space:]]*${prefix}-0*([0-9]+).*/\1/")"
+      case "$n" in ''|*[!0-9]*) continue ;; esac
+      [ "$n" -gt "$max" ] && max="$n"
+    done <<EOF
+$(grep -rhoE "^id:[[:space:]]*${prefix}-[0-9]+" "$d"/*.yml 2>/dev/null)
+EOF
+  done
+  printf '%s' "$max"
+}
+
+# --- Lock helpers (mkdir is atomic on POSIX; portable, no flock) -----------
+# Staleness uses the lock directory's own mtime (set atomically by mkdir, and
+# refreshed when the holder writes pid) — NOT a ts file that may not be written
+# yet, which would race a just-created lock into an instant false steal. The
+# critical section is local-FS only (the slow `git fetch` runs before the lock),
+# so the stale threshold is never tripped by a legitimate holder.
+file_mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0; }
+acquire_lock() {
+  local tries=0 now m age
+  mkdir -p "$WT_DIR" 2>/dev/null || true
+  while ! mkdir "$LOCKDIR" 2>/dev/null; do
+    if [ -d "$LOCKDIR" ]; then
+      now="$(date +%s)"; m="$(file_mtime "$LOCKDIR")"
+      case "$m" in ''|*[!0-9]*) m=0 ;; esac
+      age=$(( now - m ))
+      if [ "$m" -gt 0 ] && [ "$age" -gt "$LOCK_STALE_SECONDS" ]; then
+        err "WARN: stealing stale id-alloc lock (age ${age}s)"; rm -rf "$LOCKDIR" 2>/dev/null; continue
+      fi
+    fi
+    tries=$(( tries + 1 ))
+    [ "$tries" -gt "$LOCK_MAX_TRIES" ] && { err "ERROR: could not acquire id-alloc lock"; return 1; }
+    sleep 0.2
+  done
+  printf '%s\n' "$$" > "$LOCKDIR/pid" 2>/dev/null || true
+}
+release_lock() { rm -rf "$LOCKDIR" 2>/dev/null || true; }
+
+# ===========================================================================
+CMD="${1:-}"
+MAIN="$(resolve_main)" || { err "ERROR: not inside a git repository"; exit 1; }
+WT_DIR="$MAIN/.worktrees"
+LOCKDIR="$WT_DIR/.id-alloc.lock"
+RESV="$WT_DIR/id-reservations.jsonl"
+REG="$WT_DIR/registry.json"
+
+case "$CMD" in
+  reserve)
+    PREFIX="${2:-}"; SLUG="${3:-}"
+    [ -n "$PREFIX" ] || { err "usage: allocate-id.sh reserve <PREFIX> <slug>"; exit 2; }
+    case "$PREFIX" in *[!A-Z]*|'') err "ERROR: PREFIX must be uppercase letters (e.g. FEAT, BUG)"; exit 2 ;; esac
+
+    BACKLOG_DIR="$(config_scalar paths backlog_dir)"; [ -n "$BACKLOG_DIR" ] || BACKLOG_DIR="backlog"
+    TRUNK="$(config_scalar git trunk_branch)"
+    WT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$MAIN")"
+    HWM="$WT_DIR/.id-hwm-$PREFIX"
+
+    # Refresh the remote trunk ref BEFORE taking the lock — it's the only slow
+    # (network) step; keeping it out of the critical section means a holder can
+    # never be stale-stolen mid-allocation.
+    [ -n "$TRUNK" ] && git fetch origin "$TRUNK" --quiet 2>/dev/null || true
+
+    acquire_lock || exit 1
+    trap release_lock EXIT
+
+    # 1) Floor = stored high-water mark (correctness anchor).
+    max=0
+    if [ -f "$HWM" ]; then
+      max="$(tr -cd '0-9' < "$HWM" 2>/dev/null)"; case "$max" in ''|*[!0-9]*) max=0 ;; esac
+    fi
+
+    # 2) Local worktree backlog + every sibling worktree's backlog (in flight).
+    dirs="$MAIN/$BACKLOG_DIR"
+    [ "$WT" != "$MAIN" ] && dirs="$dirs $WT/$BACKLOG_DIR"
+    if [ -f "$REG" ]; then
+      while IFS= read -r p; do
+        [ -n "$p" ] && dirs="$dirs $p/$BACKLOG_DIR"
+      done <<EOF
+$(grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' "$REG" 2>/dev/null | sed -E 's/.*"([^"]*)"$/\1/')
+EOF
+    fi
+    # shellcheck disable=SC2086
+    max="$(scan_dirs_max "$PREFIX" "$max" $dirs)"
+
+    # 3) Reservations log (covers a wiped HWM with reservations still in flight).
+    if [ -f "$RESV" ]; then
+      while IFS= read -r n; do
+        n="$(printf '%s' "$n" | sed -E "s/.*\"${PREFIX}-0*([0-9]+).*/\1/")"
+        case "$n" in ''|*[!0-9]*) continue ;; esac
+        [ "$n" -gt "$max" ] && max="$n"
+      done <<EOF
+$(grep -oE "\"id\":\"${PREFIX}-[0-9]+" "$RESV" 2>/dev/null)
+EOF
+    fi
+
+    # 4) Best-effort cross-machine guard: merge-base of trunk (already-merged IDs).
+    #    The fetch already ran before the lock; this is a local object-store read.
+    if [ -n "$TRUNK" ]; then
+      MB="$(git merge-base HEAD "origin/$TRUNK" 2>/dev/null || git merge-base HEAD "$TRUNK" 2>/dev/null || true)"
+      if [ -n "$MB" ]; then
+        while IFS= read -r n; do
+          n="$(printf '%s' "$n" | sed -E "s/^id:[[:space:]]*${PREFIX}-0*([0-9]+).*/\1/")"
+          case "$n" in ''|*[!0-9]*) continue ;; esac
+          [ "$n" -gt "$max" ] && max="$n"
+        done <<EOF
+$(git grep -hoE "^id:[[:space:]]*${PREFIX}-[0-9]+" "$MB" -- "$BACKLOG_DIR/*.yml" 2>/dev/null)
+EOF
+      fi
+    fi
+
+    NEXT=$(( max + 1 ))
+    printf '%s\n' "$NEXT" > "$HWM" 2>/dev/null || true
+    printf '{"prefix":"%s","id":"%s-%04d","worktree":"%s","slug":"%s","ts":"%s"}\n' \
+      "$PREFIX" "$PREFIX" "$NEXT" "$WT" "$SLUG" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$RESV" 2>/dev/null || true
+
+    release_lock; trap - EXIT
+    printf '%04d\n' "$NEXT"
+    ;;
+
+  release)
+    WT="${2:-}"
+    [ -n "$WT" ] || { err "usage: allocate-id.sh release <worktree-path>"; exit 2; }
+    [ -f "$RESV" ] || exit 0
+    acquire_lock || exit 0   # best-effort prune; never block cleanup
+    trap release_lock EXIT
+    # grep -v exit code: 0 = some lines kept, 1 = none kept (all pruned → empty
+    # file is the correct result), >=2 = real error (keep the original).
+    grep -vF "\"worktree\":\"$WT\"" "$RESV" > "$RESV.tmp" 2>/dev/null
+    if [ "$?" -le 1 ]; then
+      mv "$RESV.tmp" "$RESV" 2>/dev/null || rm -f "$RESV.tmp" 2>/dev/null
+    else
+      rm -f "$RESV.tmp" 2>/dev/null
+    fi
+    release_lock; trap - EXIT
+    ;;
+
+  *)
+    err "usage: allocate-id.sh {reserve <PREFIX> <slug> | release <worktree-path>}"
+    exit 2
+    ;;
+esac

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

@@ -153,12 +153,12 @@ if (kind === 'scope-expansion') {
         `If INTEGRATE: apply (you are ${fixerAgent}), re-run lint+tsc, return applied:true verified:true. If FOLLOW-UP: applied:false verified:false note:'needs-followup: <why>'.`,
       { label: `resolve:scope:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
     )
-  } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during scope-expansion', outOfScopeFindings: [] }; throw e }
+  } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during scope-expansion', deferralClass: 'outage', outOfScopeFindings: [] }; throw e }
   if (decide && decide.verified) {
     const ok = await judgeVerify([{ i: 1, r: decide }])
     if (ok.ok) { log('scope-expansion integrated within ownership.'); return { status: 'resolved', outOfScopeFindings: collectOOS(decide) } }
   }
-  return await materialiseFollowup('scope-expansion', (decide && decide.note) || 'outside ownership / new AC / protected', collectOOS(decide))
+  return await materialiseFollowup('scope-expansion', (decide && decide.note) || 'outside ownership / new AC / protected', collectOOS(decide), 'scope-expansion')
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -179,7 +179,7 @@ try {
     `Tier-1 targeted repair for card ${card} (${kind}).\n\n${brief}\n\n${gateHint}\n\nApply the minimal correct fix within MAY-EDIT only. Re-run the originating gate and report verified honestly (never claim verified without re-running it).`,
     { label: `resolve:${kind}:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
   )
-} catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during tier-1', outOfScopeFindings: [] }; throw e }
+} catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during tier-1', deferralClass: 'outage', outOfScopeFindings: [] }; throw e }
 
 // F-008 — terminal short-circuit, verified not trusted.
 if (attempt && attempt.terminal) {
@@ -197,7 +197,7 @@ if (attempt && attempt.terminal) {
       confirmed = !!(tj && tj.confirmed)
     } catch (_) { confirmed = false }
   }
-  if (confirmed) { log(`${kind} terminal (${tr}) — short-circuit to follow-up.`); return await materialiseFollowup(kind, `terminal: ${tr} — ${attempt.note || ''}`, collectOOS(attempt)) }
+  if (confirmed) { log(`${kind} terminal (${tr}) — short-circuit to follow-up.`); return await materialiseFollowup(kind, `terminal: ${tr} — ${attempt.note || ''}`, collectOOS(attempt), tr || 'unresolved') }
   log(`terminal verdict (${tr}) rejected — proceeding to multi-attempt.`)
 }
 
@@ -242,7 +242,7 @@ if (canFanOut && !protectedDomain) {
   log('budget near target — skipping tier-2 fan-out.')
 }
 
-return await materialiseFollowup(kind, (attempt && attempt.note) || 'unresolved after repair tiers', collectOOS(attempt).concat(tier2OOS))
+return await materialiseFollowup(kind, (attempt && attempt.note) || 'unresolved after repair tiers', collectOOS(attempt).concat(tier2OOS), 'unresolved')
 
 // ───────────────────────────────────────────────────────────────────────────
 // F-015/F-033 — mandatory adversarial judge + deterministic JS cross-check.
@@ -266,11 +266,20 @@ async function judgeVerify(verifiedAttempts) {
   return { ok: true, best: judge.best }
 }
 
-async function materialiseFollowup(k, reason, oos) {
+// F-040 — `deferralClass` (4th arg) classifies WHY this became a follow-up so new2.js can
+// decide whether the CARD should still commit. owner-gated / not-a-code-defect → the card's
+// own code is complete; the residual is an external step (do NOT roll the card back). Anything
+// else (unresolved code defect, out-of-ownership, baseline) → genuine block → rollback as before.
+// The classifier flows back through resolve() in new2.js; never write it into the worktree.
+async function materialiseFollowup(k, reason, oos, deferralClass) {
+  const cls = deferralClass || 'unresolved'
   let r = null
   try {
     // F-039 — backlog cards are owned by prd-card-writer (card-template + Rule C
     // review_profile + owner_agent + traceability), NOT a hand-written Haiku stub.
+    // F-040 — the workflow agent runs cd'd into the worktree, so this write is BEST-EFFORT
+    // (it rides the merge if the batch merges). The SKILL is the SSOT: it verifies/creates the
+    // card in the MAIN repo post-run, so a non-merged batch never loses the follow-up.
     r = await agentSafe(
       `Create ONE follow-up backlog card so this residual is TRACKED, not dropped (per ${REF}/completeness.md Phase 2.5b option 3). You are prd-card-writer: apply your card-template, Rule C (review_profile), owner_agent routing, and traceability rules — do NOT emit a minimal stub.\n\n${brief}\nKind: ${k}\nResidual domain: ${domain}\nReason unresolved: ${reason}\n\n` +
         `Write ${backlogDir}/${card}-followup-<gate>.yml with status: TODO, derived from the residual: requirements + acceptance_criteria (the verbatim residual as ≥1 AC), owner_agent routed to the residual domain (${domain}), review_profile per Rule C, files_likely_touched ≥1 from the card ownership / remedy files. It MUST pass the /new pre-flight field check. Return the created card id.`,
@@ -280,9 +289,9 @@ async function materialiseFollowup(k, reason, oos) {
     // F-020 — could not materialise (e.g. outage): return WITHOUT a followupCard so the
     // SKILL writes it from the offline-safe residual ledger. Never claim it was created.
     log(`follow-up materialisation failed (${String(e && e.message)}) — skill will reconcile.`)
-    return { status: 'followup', followupCard: null, reason, outOfScopeFindings: oos || [] }
+    return { status: 'followup', followupCard: null, reason, deferralClass: cls, outOfScopeFindings: oos || [] }
   }
   const followupCard = (r && r.created && r.followupCard) ? r.followupCard : null
   log(`${k} → follow-up ${followupCard || '(deferred to skill)'} (nothing dropped).`)
-  return { status: 'followup', followupCard, reason, outOfScopeFindings: oos || [] }
+  return { status: 'followup', followupCard, reason, deferralClass: cls, outOfScopeFindings: oos || [] }
 }

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

@@ -70,6 +70,11 @@ function sig(card, gate, evidence) {
   const e = String(evidence || '').toLowerCase().replace(/\s+/g, ' ').replace(/[0-9a-f]{7,40}/g, '#').trim().slice(0, 160)
   return `${card}::${String(gate || '').toLowerCase()}::${e}`
 }
+// F-040 (Fix G) — AC-deferral key on AC NUMBER ONLY. The full-text sig() drifted between the
+// pre-flight policyDeferredACs[].text and the implement agent's unmetACs[].text, so a policy-
+// deferred AC got re-routed to resolve() a second time (the migration-card double-routing). This
+// coarse key is scoped to ac-defer so it never collides with a freeform 'blocker' finding.
+function acSig(card, n) { return `${card}::ac-defer::ac-${String(n)}` }
 
 function ledger(card, gate, decision, detail) {
   gateLedger.push({ card, gate, decision, detail: detail || '' })
@@ -163,6 +168,7 @@ const MERGE_SCHEMA = {
     mergeTs: { type: 'string' },
     reconciliation: { type: 'string' },
     forcedDone: { type: 'array', items: { type: 'string' }, description: 'MUST be empty — false-DONE is forbidden (F-029)' },
+    deferredLeftOpen: { type: 'array', items: { type: 'string' }, description: 'F-040 — committed cards left NON-DONE (open owner-gated AC); the skill marks them DONE post-run' },
     epicsClosed: { type: 'array', items: { type: 'string' }, description: 'Epic/parent cards marked DONE by Phase 6b step 5e (all children DONE) — NOT a forcedDone violation' },
     uncommittedLeft: { type: 'boolean', description: 'true if dirty code was left (NOT committed) + reported (F-030)' },
     note: { type: 'string' },
@@ -208,7 +214,7 @@ try {
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
       `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs }.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
-      `• Complexity (setup.md 3c): decide executionMode sequential|team (+ groups for team). Build the file-ownership map → /tmp; return ownershipMapPath.\n` +
+      `• Complexity (setup.md 3c): decide executionMode sequential|team (+ groups for team). Build the file-ownership map → /tmp; return ownershipMapPath. F-040: each card's MAY-EDIT = files_likely_touched ∪ every path NAMED EXPLICITLY in that card's acceptance_criteria/definition_of_done (an ADR the DoD says to update, the data-model / ER doc for a schema-change, etc.) — so editing a DoD-mandated doc is NOT a file-diff violation. Do NOT add another card's files this way.\n` +
       `• Persist per-card architecture baselines to /tmp/arch-baseline-<CARD>.md; return archBaselinePaths.\n\n` +
       `Return the structured PREFLIGHT object. ok:false ONLY if the workspace is unworkable.`,
     { label: 'preflight', phase: 'Pre-flight', agentType: 'general-purpose', schema: PREFLIGHT_SCHEMA }
@@ -249,6 +255,8 @@ for (const n of cardGraph) {
   for (const ac of (n.policyDeferredACs || [])) {
     residuals.push({ card: n.id, kind: 'policy-deferred-ac', evidence: `AC-${ac.n}: ${ac.text} (${ac.reason || 'out-of-ownership / owner-gated'})`, materialized: false })
     acceptedDeferrals.add(sig(n.id, 'ac-unmet', `AC-${ac.n}: ${ac.text}`))
+    acceptedDeferrals.add(acSig(n.id, ac.n)) // F-040 (Fix G) — text-drift-proof AC key
+
     ledger(n.id, 'F016-policy-defer', 'DEFERRED-BY-POLICY', `AC-${ac.n} → follow-up (owner: ${ac.owningCard || ac.owningFile || '?'})`)
   }
 }
@@ -274,11 +282,15 @@ function domainMayEdit(dom, codeScope) {
   return docPaths.length ? docPaths : codeScope // doc-only ownership; fall back to code scope if no doc paths configured
 }
 
+// F-040 — returns { status:'resolved'|'followup'|'fatal', deferralClass }. deferralClass tells
+// the caller WHY a followup happened: 'owner-gated'/'not-a-code-defect' → the card's own code is
+// complete (external/infra step remains) → caller must NOT roll the card back; anything else
+// ('unresolved'/'out-of-ownership'/'baseline-not-reached'/'outage') → genuine block → rollback.
 async function resolve(kind, card, evidence, extra) {
   const s = sig(card, kind, evidence)
   if (resolvedSignatures.has(s) || acceptedDeferrals.has(s)) {
     ledger(card, 'resolve:' + kind, 'DEDUP-SKIP', 'already resolved/deferred this run')
-    return 'resolved'
+    return { status: 'resolved', deferralClass: null }
   }
   resolvedSignatures.add(s)
   const dom = (extra && extra.domain) || 'code'
@@ -295,10 +307,11 @@ async function resolve(kind, card, evidence, extra) {
     })
   } catch (e) {
     if (e && (e.transientExhausted || isTransient(e))) noteDegraded('outage')
-    res = { status: 'followup', reason: 'resolve workflow error: ' + String(e && e.message) }
+    res = { status: 'followup', reason: 'resolve workflow error: ' + String(e && e.message), deferralClass: 'outage' }
   }
   const status = (res && res.status) || 'followup'
-  if (status === 'fatal') { batchFatal = true; ledger(card, 'resolve:' + kind, 'FATAL', (res && res.reason) || ''); return status }
+  const deferralClass = (res && res.deferralClass) || null
+  if (status === 'fatal') { batchFatal = true; ledger(card, 'resolve:' + kind, 'FATAL', (res && res.reason) || ''); return { status, deferralClass } }
   if (status === 'followup') {
     acceptedDeferrals.add(s) // F-028 — a deferred residual must not be re-routed by a later gate.
     const fc = (res && res.followupCard) || null
@@ -310,7 +323,7 @@ async function resolve(kind, card, evidence, extra) {
     residuals.push({ card, kind: 'out-of-scope', evidence: `${osf.file || ''}:${osf.line || ''} ${osf.evidence || ''}`, materialized: false })
   }
   ledger(card, 'resolve:' + kind, status, (res && (res.followupCard || res.reason)) || '')
-  return status
+  return { status, deferralClass }
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -337,6 +350,11 @@ async function runCard(cardId, cardPath, lessons) {
   const node = graphById[cardId] || {}
   const ownerAgent = node.ownerAgent || 'coder'
   const reviewProfile = node.reviewProfile || 'balanced'
+  // F-040/H — a card carrying an open owner-gated/policy-deferred AC commits its code but stays
+  // NON-DONE; the SKILL marks it DONE post-run only after the deferral's follow-up exists on disk
+  // in the main repo. Seeded from the pre-flight policy-deferred ACs; set by any owner-gated review
+  // deferral or unmet-AC follow-up below.
+  let deferredOpen = ((node.policyDeferredACs) || []).length > 0
   function g(name, decision, detail) { gates.push({ gate: name, decision, detail: detail || '' }); ledger(cardId, name, decision, detail) }
 
   // F-026 — skip-completed: only if committed AND gates green for that sha AND no open follow-up.
@@ -361,10 +379,11 @@ async function runCard(cardId, cardPath, lessons) {
     impl = await agentSafe(
       `Implement card ${cardId} per ${REF}/implement.md (Phase 1 claim+architect+plan-auditor, Phase 2 you ARE the owner_agent '${ownerAgent}') and ${REF}/completeness.md (Phase 2.5 + 2.5b AC-closure ledger). Run all gates/bash yourself.\n\n${cardBrief}\n\n` +
         `POLICIES: G26 Phase-2 lint/tsc/test/build failing after the module's retry cap → buildBlocked:true + blockedGate. Build the AC Closure Ledger (one row per AC: implemented|unmet|policy-deferred). DO NOT silently defer; report unmet rows (excluding policy-deferred). Persist arch baseline to /tmp/arch-baseline-${cardId}.md and the diff to /tmp/diff-${cardId}.txt.\n\n` +
-        `Return: { epic, buildBlocked, blockedGate, unmetACs:[{n,text}], scopeFiles, mayEditPaths, fileDiffViolation, note }`,
+        `E4 OWNERSHIP RECONCILE (implement.md §11b — do this BEFORE returning): the card's MAY-EDIT includes files_likely_touched ∪ paths NAMED EXPLICITLY in this card's acceptance_criteria/definition_of_done (e.g. an ADR the DoD says to update, the data-model / ER doc for a schema change). Editing THOSE is in-scope. For any OTHER dirty file outside MAY-EDIT (another card's file, or unrelated): \`git checkout -- <file>\` to revert it (NEVER leave it orphaned), list it in revertedOutOfOwnership. Set fileDiffViolation:true ONLY if such an edit genuinely could not be reverted (then say why in note) — it is no longer a silent label.\n\n` +
+        `Return: { epic, buildBlocked, blockedGate, unmetACs:[{n,text}], scopeFiles, mayEditPaths, revertedOutOfOwnership:[paths], fileDiffViolation, note }`,
       { label: `implement:${cardId}`, phase: 'Implement', agentType: ownerAgent,
         schema: { type: 'object', required: ['epic', 'buildBlocked', 'unmetACs', 'scopeFiles'], additionalProperties: true,
-          properties: { epic: { type: 'boolean' }, buildBlocked: { type: 'boolean' }, blockedGate: { type: 'string' }, unmetACs: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeFiles: { type: 'array', items: { type: 'string' } }, mayEditPaths: { type: 'array', items: { type: 'string' } }, fileDiffViolation: { type: 'boolean' }, note: { type: 'string' } } } }
+          properties: { epic: { type: 'boolean' }, buildBlocked: { type: 'boolean' }, blockedGate: { type: 'string' }, unmetACs: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeFiles: { type: 'array', items: { type: 'string' } }, mayEditPaths: { type: 'array', items: { type: 'string' } }, revertedOutOfOwnership: { type: 'array', items: { type: 'string' } }, fileDiffViolation: { type: 'boolean' }, note: { type: 'string' } } } }
     )
   } catch (e) {
     if (e && e.transientExhausted) { noteDegraded('outage'); return { card: cardId, status: 'pending', gates, telemetry: tele } }
@@ -375,19 +394,28 @@ async function runCard(cardId, cardPath, lessons) {
 
   const mayEdit = (impl && impl.mayEditPaths) || []
   const scopeFiles = (impl && impl.scopeFiles) || []
-  if (impl && impl.fileDiffViolation) g('E4-file-diff', 'AUTO-REVERTED', 'coder touched files outside ownership')
+  // F-040 — E4 honest label: 'AUTO-REVERTED' used to be a no-op log (files were left orphaned).
+  // Now the owner agent reconciles out-of-ownership edits itself (implement.md §11b); we report
+  // what it actually did. A genuine unresolved violation becomes a tracked residual, never silent.
+  const reverted = (impl && impl.revertedOutOfOwnership) || []
+  if (reverted.length) g('E4-file-diff', 'REVERTED', `out-of-ownership reverted: ${reverted.join(', ')}`)
+  if (impl && impl.fileDiffViolation) {
+    g('E4-file-diff', 'FLAGGED', 'unresolved out-of-ownership edit — tracked as residual')
+    residuals.push({ card: cardId, kind: 'file-diff-violation', evidence: `unresolved out-of-ownership edit: ${(impl && impl.note) || ''}`, materialized: false })
+  }
 
   if (impl && impl.buildBlocked) {
-    const s = await resolve('blocker', cardId, `Phase-2 gate failing: ${impl.blockedGate}`, { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })
+    const s = (await resolve('blocker', cardId, `Phase-2 gate failing: ${impl.blockedGate}`, { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })).status
     g('G26-build', s === 'resolved' ? 'RESOLVED' : 'FOLLOWUP', impl.blockedGate)
     if (s !== 'resolved') { await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'followup', gates, commit: '-', scopeFiles, telemetry: tele } }
   }
 
   // F-010/F-016 — unmet ACs that are policy-deferred are skipped (already tracked).
   for (const ac of (impl && impl.unmetACs) || []) {
-    if (acceptedDeferrals.has(sig(cardId, 'ac-unmet', `AC-${ac.n}: ${ac.text}`))) { g('G7-ac-closure', 'DEFERRED-BY-POLICY', `AC-${ac.n}`); continue }
-    const s = await resolve('ac-unmet', cardId, `AC-${ac.n}: ${ac.text}`, { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })
+    if (acceptedDeferrals.has(acSig(cardId, ac.n)) || acceptedDeferrals.has(sig(cardId, 'ac-unmet', `AC-${ac.n}: ${ac.text}`))) { g('G7-ac-closure', 'DEFERRED-BY-POLICY', `AC-${ac.n}`); deferredOpen = true; continue }
+    const s = (await resolve('ac-unmet', cardId, `AC-${ac.n}: ${ac.text}`, { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })).status
     g('G7-ac-closure', s === 'resolved' ? 'RESOLVED' : 'FOLLOWUP', `AC-${ac.n}`)
+    if (s !== 'resolved') deferredOpen = true // F-040/H — unmet AC tracked as follow-up → card stays NON-DONE
   }
 
   // --- Review fan-out (F-024/F-025): specialized agents, trimmed by review_profile. ---
@@ -437,23 +465,38 @@ async function runCard(cardId, cardPath, lessons) {
   let cardBlocked = false
   for (const b of blocks) {
     const kind = /e2e/i.test(b.gate) ? 'e2e-blocked' : /qa/i.test(b.gate) ? 'qa-fail' : 'blocker'
-    const s = await resolve(kind, cardId, `${b.gate}: ${b.evidence}`, { mayEditPaths: mayEdit, scopeFiles, domain: b.domain || 'code' })
-    g(b.gate, s === 'resolved' ? 'RESOLVED' : 'FOLLOWUP', b.evidence)
-    if (s !== 'resolved') cardBlocked = true
+    const r = await resolve(kind, cardId, `${b.gate}: ${b.evidence}`, { mayEditPaths: mayEdit, scopeFiles, domain: b.domain || 'code' })
+    // F-040 — THE primary fix. An owner-gated / not-a-code-defect deferral means the card's OWN
+    // code is complete and correct; the residual is an external/infra step (e.g. a remote db push)
+    // already tracked as a follow-up. Do NOT roll the card back — it proceeds to commit, NON-DONE
+    // (the skill marks it DONE post-run once the follow-up exists on disk). This replaces the old
+    // `s !== 'resolved' → cardBlocked` which destroyed a completed migration card's work over a db:push gate.
+    // A genuine unresolved CODE defect (or out-of-ownership/baseline/outage) still blocks + rolls back.
+    const ownerGated = r.status === 'followup' && (r.deferralClass === 'owner-gated' || r.deferralClass === 'not-a-code-defect')
+    g(b.gate, r.status === 'resolved' ? 'RESOLVED' : ownerGated ? 'DEFERRED-OWNER-GATED' : 'FOLLOWUP', b.evidence)
+    if (ownerGated) deferredOpen = true
+    else if (r.status !== 'resolved') cardBlocked = true
   }
   for (const sx of scopeExp) {
-    const s = await resolve('scope-expansion', cardId, sx.evidence || '', { mayEditPaths: mayEdit, scopeFiles, domain: sx.domain || 'code' })
+    const s = (await resolve('scope-expansion', cardId, sx.evidence || '', { mayEditPaths: mayEdit, scopeFiles, domain: sx.domain || 'code' })).status
     g('scope-expansion', s === 'resolved' ? 'INTEGRATED' : 'FOLLOWUP', sx.evidence || '')
   }
 
   if (cardBlocked) { await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'followup', gates, commit: '-', scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, telemetry: tele } }
 
   // --- Phase 4 — commit (F-023: Haiku + git-status reconcile, never git add -A). ---
+  // F-040/H — DONE policy. A card with an OPEN owner-gated/policy-deferred AC commits its code but
+  // must NOT be marked DONE here (its own DoD isn't met yet — e.g. the remote db:push is pending).
+  // The new2 SKILL marks it DONE post-run, ONLY after the deferral's follow-up exists on disk in the
+  // main repo (so a card is never DONE with a silently-dropped requirement — F-029).
+  const doneStep = deferredOpen
+    ? `(4) DO NOT mark the card DONE: it has an OPEN owner-gated/policy-deferred AC. Keep status IN_PROGRESS and add an implementation_note "deferred — DONE pending follow-up (new2 skill reconciles post-run)". STILL add the ssot-registry row for the committed code.`
+    : `(4) mark the card DONE in its YAML + add the ssot-registry row.`
   let commitRes
   try {
     commitRes = await agentSafe(
       `Commit card ${cardId} in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT re-read reference modules.\n` +
-        `Steps: (1) \`git status --porcelain\`; (2) stage = MAY-EDIT (${JSON.stringify(mayEdit)}) ∩ dirty — NEVER \`git add -A\`, NEVER \`git stash\`; if dirty has files OUTSIDE MAY-EDIT, do NOT stage them and set reconcileNote; (3) commit message \`[${cardId}] <concise>\`; (4) mark the card DONE in its YAML + add the ssot-registry row; (5) 'nothing to commit' = already committed (record HEAD).\n` +
+        `Steps: (1) \`git status --porcelain\`; (2) stage = MAY-EDIT (${JSON.stringify(mayEdit)}) ∩ dirty — NEVER \`git add -A\`, NEVER \`git stash\`; if dirty has files OUTSIDE MAY-EDIT, do NOT stage them and set reconcileNote; (3) commit message \`[${cardId}] <concise>\`; ${doneStep} (5) 'nothing to commit' = already committed (record HEAD).\n` +
         `On COMMIT_LOCK: clear stale lock + retry once. Still locked → committed:false.\n\n` +
         `Return: { committed, commit, filesChanged, reconcileNote }`,
       { label: `commit:${cardId}`, phase: 'Implement', agentType: 'general-purpose', model: 'haiku',
@@ -465,17 +508,20 @@ async function runCard(cardId, cardPath, lessons) {
   }
 
   if (!commitRes || !commitRes.committed) {
-    const s = await resolve('blocker', cardId, 'commit blocked after retries', { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })
+    const s = (await resolve('blocker', cardId, 'commit blocked after retries', { mayEditPaths: mayEdit, scopeFiles, domain: 'code' })).status
     g('G16-commit', s === 'resolved' ? 'RESOLVED' : 'FOLLOWUP')
     if (s !== 'resolved') { await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'followup', gates, commit: '-', scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, telemetry: tele } }
   }
   if (commitRes && commitRes.reconcileNote) g('commit-reconcile', 'NOTE', commitRes.reconcileNote)
 
-  g('commit', 'COMMITTED', (commitRes && commitRes.commit) || '')
+  g('commit', 'COMMITTED', `${(commitRes && commitRes.commit) || ''}${deferredOpen ? ' (NON-DONE — deferred, skill reconciles)' : ''}`)
   return {
     card: cardId, status: 'committed',
     commit: (commitRes && commitRes.commit) || '-',
     filesChanged: (commitRes && commitRes.filesChanged) || [],
+    // F-040/H — true when this committed card is intentionally left NON-DONE (open deferral). The
+    // merge agent leaves it non-DONE and the SKILL marks it DONE after its follow-up materialises.
+    deferred: deferredOpen,
     scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates, telemetry: tele,
   }
 }
@@ -594,14 +640,14 @@ if (committed.length && !batchFatal && !degraded) {
     }
     for (const area of Object.keys(byArea)) {
       const group = byArea[area]
-      const s = await resolve('merge-blocker', group[0].finding_id || firstCard,
+      const s = (await resolve('merge-blocker', group[0].finding_id || firstCard,
         group.map((f) => `${f.severity} ${f.title}: ${f.evidence}`).join(' || '),
         { mayEditPaths: reviewScopeFiles, scopeFiles: reviewScopeFiles, domain: group[0].domain || 'code',
-          findings: group.map((f) => ({ kind: 'merge-blocker', evidence: `${f.title}: ${f.evidence}`, domain: f.domain || 'code' })) })
+          findings: group.map((f) => ({ kind: 'merge-blocker', evidence: `${f.title}: ${f.evidence}`, domain: f.domain || 'code' })) })).status
       if (s !== 'resolved') mergeBlocked = true
     }
     if (finalSummary && finalSummary.failingGates && finalSummary.failingGates.length) {
-      const s = await resolve('qa-fail', firstCard, `final gates failing: ${finalSummary.failingGates.join(', ')}`, { mayEditPaths: reviewScopeFiles, scopeFiles: reviewScopeFiles, domain: 'code' })
+      const s = (await resolve('qa-fail', firstCard, `final gates failing: ${finalSummary.failingGates.join(', ')}`, { mayEditPaths: reviewScopeFiles, scopeFiles: reviewScopeFiles, domain: 'code' })).status
       if (s !== 'resolved') mergeBlocked = true
     }
   } else {
@@ -621,6 +667,10 @@ if (committed.length && !batchFatal && !degraded) {
 phase('Merge')
 let mergeResult = null
 const incomplete = runnableCards.filter((id) => state[id] !== 'committed' && state[id] !== 'epic-skipped')
+// F-040/H — committed cards intentionally left NON-DONE (open owner-gated/policy-deferred AC). They
+// ARE merged (their code is complete), but Phase 6b must NOT force them to DONE; the SKILL does that
+// post-run once the deferral's follow-up exists on disk. They count as complete for the merge gate.
+const deferredCards = committed.filter((r) => r.deferred).map((r) => r.card)
 const integrityOK = committed.length > 0 && !mergeBlocked && !batchFatal && !degraded && incomplete.length === 0
 if (!committed.length) {
   ledger(firstCard, 'merge', 'SKIPPED', 'no committed cards')
@@ -635,15 +685,23 @@ if (!committed.length) {
         `• G24 → auto-merge via merge_strategy.\n` +
         `• F-030 HARD RULE: NEVER \`git add\`/commit code that did not pass the per-card gates. If the worktree is dirty with uncommitted code → DO NOT commit it; leave it, set uncommittedLeft:true, and report. NO "safety commit". Security/migration code is NEVER swept in.\n` +
         `• F-029 HARD RULE: Phase 6b reconciliation marks a card DONE ONLY if it has a real commit in ${TRUNK}..HEAD AND its gates are green. NEVER force a non-implemented card to DONE. Return forcedDone:[] (must be empty).\n` +
+        `• F-040 DEFERRED CARDS — leave NON-DONE (do NOT force to DONE in Phase 6b): ${deferredCards.length ? deferredCards.join(' ') : '(none)'}. These committed their code but carry an OPEN owner-gated/policy-deferred AC (e.g. a pending remote db:push). Their YAML is INTENTIONALLY IN_PROGRESS; the new2 skill marks them DONE post-run after materialising the deferral's follow-up. They ARE part of the merge — just skip them in the DONE-reconciliation. Return deferredLeftOpen:[the ones you left non-DONE].\n` +
         `• EPIC CLOSURE (Phase 6b step 5e): the epic/parent card (group.is_epic:true) is NOT in the batch and stays TODO unless closed here. For each distinct group.parent of the batch cards (and any epic card in the batch itself): if EVERY child of that epic — \`grep -l "parent: <EPIC-ID>" backlog/*.yml | xargs grep -L "status: DONE"\` prints nothing — set the epic card status:DONE + completed_date + note "epic-closure gate — all children DONE" and fold into the reconciliation commit. If any child is still open → leave the epic untouched. This is NOT a forcedDone violation (the epic is a tracker, gated on all-children-DONE, not on its own commit). Return epicsClosed:[<EPIC-IDs marked DONE>].\n` +
         `• G19 sync-deferred → HEAD==${TRUNK} ff-pull, else leave+report. G20 → leave+report. G21 post-batch dirty → partition-ignore framework artifacts; leave the rest + report (do NOT commit). G22 divergence → behind: ff-pull; ahead/both: leave+report; NEVER reset --hard/force-push. G23 stash restore conflict → leave intact + report.\n\n` +
-        `Return: { merged, mergeCommit, mergeTs, reconciliation, forcedDone:[], uncommittedLeft, note }`,
+        `Return: { merged, mergeCommit, mergeTs, reconciliation, forcedDone:[], deferredLeftOpen:[], uncommittedLeft, note }`,
       { label: 'merge', phase: 'Merge', agentType: 'general-purpose', schema: MERGE_SCHEMA }
     )
   } catch (e) { if (e && e.transientExhausted) noteDegraded('outage'); mergeResult = null }
   if (mergeResult && (mergeResult.forcedDone || []).length) { noteDegraded('false_done'); ledger(firstCard, 'F029-guard', 'VIOLATION', `forcedDone: ${mergeResult.forcedDone.join(' ')}`) }
   if (mergeResult && mergeResult.uncommittedLeft) ledger(firstCard, 'F030-guard', 'LEFT-UNCOMMITTED', 'dirty code left (not swept) + reported')
   if (mergeResult && (mergeResult.epicsClosed || []).length) ledger(firstCard, 'epic-closure', 'CLOSED', `epics marked DONE (all children DONE): ${mergeResult.epicsClosed.join(' ')}`)
+  if (deferredCards.length) {
+    ledger(firstCard, 'F040-deferred', 'LEFT-NON-DONE', `${deferredCards.join(' ')} — skill marks DONE post-run after follow-up materialises`)
+    // F-040 guard — catch a merge agent that ignored the instruction and force-DONE'd a deferred card.
+    const leftOpen = (mergeResult && mergeResult.deferredLeftOpen) || []
+    const wronglyDone = deferredCards.filter((c) => !leftOpen.includes(c))
+    if (mergeResult && wronglyDone.length) { noteDegraded('false_done'); ledger(firstCard, 'F040-guard', 'VIOLATION', `deferred cards force-DONE by merge: ${wronglyDone.join(' ')}`) }
+  }
   ledger(firstCard, 'G24-merge', (mergeResult && mergeResult.merged) ? 'MERGED' : 'INCOMPLETE', (mergeResult && (mergeResult.mergeCommit || mergeResult.note)) || '')
   if (mergeResult && mergeResult.reconciliation) ledger(firstCard, 'G19-23-reconcile', 'AUTO', mergeResult.reconciliation)
 }
@@ -686,6 +744,9 @@ function buildTelemetry() {
     ts: TS || null,
     cards_total: cardIds.length,
     cards_real_done: perCardResults.filter((r) => r.status === 'committed').length,
+    // F-040/H — committed cards left NON-DONE pending their owner-gated follow-up (the skill marks
+    // them DONE post-run). Surfaced so the A/B telemetry distinguishes "code landed" from "DONE".
+    cards_deferred_done_pending: perCardResults.filter((r) => r.deferred).length,
     cards_force_done: 0, // F-029 — force-DONE forbidden; always 0.
     cards_followup: perCardResults.filter((r) => r.status === 'followup').length,
     cards_blocked: runnableCards.filter((id) => state[id] === 'blocked').length,
@@ -716,7 +777,7 @@ function buildReport(o) {
   L.push(``, `## Esito card`)
   L.push(`| Card | Status | Commit | File |`)
   L.push(`|------|--------|--------|------|`)
-  for (const r of perCardResults) L.push(`| ${r.card} | ${r.status} | ${r.commit || '-'} | ${(r.filesChanged || []).length} |`)
+  for (const r of perCardResults) L.push(`| ${r.card} | ${r.status}${r.deferred ? ' (NON-DONE: deferred)' : ''} | ${r.commit || '-'} | ${(r.filesChanged || []).length} |`)
   const blockedIds = runnableCards.filter((id) => state[id] === 'blocked' || state[id] === 'pending')
   for (const id of blockedIds) L.push(`| ${id} | ${state[id]} | - | 0 |`)
   if (finalSummary) {

package/package.json

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