baldart 4.12.0 → 4.13.0

package/framework/.claude/skills/new/references/team-mode.md

@@ -0,0 +1,253 @@
+<!-- Modulo on-demand di /new — NON un file installato a sé. Caricato via Read dalla § "Routing" del SKILL.md core. -->
+
+> **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
+
+## Team Mode (parallel coder agents with isolated contexts)
+
+When the complexity assessment (step 3c) selects team mode, the orchestrator changes role: instead of executing each card's pipeline sequentially, it coordinates parallel coder agents — each with its OWN isolated context window.
+
+**Key principle**: the orchestrator stays LEAN. It holds only:
+- The tracker file path
+- Parallel group status (pending/active/done)
+- Completion verdicts per card (pass/fail + files changed)
+
+It does NOT accumulate implementation details, codebase-architect findings, or review outputs — those live and die in each agent's isolated context.
+
+### Team Mode Pre-flight
+
+After the standard pre-flight (steps 1-7), add:
+
+1. Read the `execution_strategy.groups` (each with `level` + `cards`) and sort into execution layers by `level`. For legacy cards lacking the block, fall back to the on-the-fly topological-layer computation from step 3c.
+2. Update tracker with team mode section:
+   ```
+   ## Team Mode
+   Status: active
+
+   ## Parallel Groups
+   | Group | Cards | Status |
+   |-------|-------|--------|
+   | 0 | FEAT-01 | pending |
+   | 1 | FEAT-02, FEAT-03 | pending |
+   | 2 | FEAT-04, FEAT-05 | pending |
+   ```
+
+### Per-Group Execution
+
+Process groups in order (0, 1, 2, ...). Within each group, spawn coder agents IN PARALLEL — one per card.
+
+#### Step A: Pre-compute shared context (ONCE per group)
+
+Before spawning coders, the orchestrator runs **codebase-architect** ONCE for the entire group (not per card). This single call covers all cards in the group.
+
+Prompt:
+```
+Explore the codebase for context relevant to these cards:
+[list card IDs + their scope.summary, one line each]
+
+Focus on: [combined files_likely_touched from all cards in group]
+Return: file paths, type signatures, existing patterns. Max 30 lines.
+```
+
+This is the ONLY context the orchestrator accumulates per group. After passing it to the coders, it can be purged.
+
+**Persist for review reuse (since v3.35.0)** — also write these findings to
+`/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`. D.4b's per-card `/codexreview` lean contract points
+its `arch_baseline_path` at this file, so the review reuses the group baseline instead of re-spawning
+`codebase-architect`.
+
+#### Step B: Spawn parallel coder agents
+
+**→ Visibility (wave change)**: this is a new wave starting. TaskUpdate ALL of this group's card spine tasks → `in_progress`, and emit a Progress Bar with the new `Wave <X>/<Y>` header per § "Progress Visibility".
+
+For each card in the current group, spawn a coder agent using the Agent tool. ALL agents for the group MUST be spawned in a **SINGLE message** (multiple Agent tool calls) to run truly in parallel.
+
+Each coder agent receives a **SELF-CONTAINED** mission briefing that includes EVERYTHING it needs — it will NOT call codebase-architect or plan-auditor itself:
+
+```
+Agent tool call:
+  subagent_type: "coder"
+  mode: "bypassPermissions"
+  run_in_background: true
+  name: "coder-<CARD-ID>"
+  prompt: |
+    ## AUTONOMOUS CARD IMPLEMENTATION — <CARD-ID>
+
+    You are implementing this card AUTONOMOUSLY. Complete ALL phases below
+    without external coordination. You have your own isolated context.
+
+    ### 1. Card Specification (verbatim)
+    Requirements:
+    [copy from card YAML]
+
+    Acceptance Criteria:
+    [copy from card YAML]
+
+    ### 2. Codebase Context (pre-computed)
+    [paste codebase-architect findings from Step A]
+
+    ### 3. Working Directory
+    All work MUST happen in the worktree: <worktree-path>
+    cd to this directory before any file operations.
+
+    ### 4. File Permissions (ENFORCED)
+    MAY EDIT:
+    [files from ownership map for THIS card only]
+
+    FORBIDDEN:
+    - ALL files not in the MAY EDIT list
+    - Do NOT create files outside the designated paths
+
+    ### 5. Design Reference (if UI card)
+    [path to design.html if exists]
+
+    ### 6. Your Pipeline
+    Execute these steps in order:
+    a) Print the numbered requirements checklist (anti-skip measure)
+    b) Implement ALL requirements
+    c) Run: npx tsc --noEmit && npx eslint --max-warnings=0 <your-files>
+    d) Self-heal up to 3 times if checks fail
+    e) Verify completeness: for each requirement, confirm code exists (read it)
+    f) If any requirement is missing after implementation, implement it now
+    g) Output the completion report (MANDATORY format below)
+
+    ### 7. Completion Report (MANDATORY)
+    ```completion-report
+    card: <CARD-ID>
+    status: done | partial | blocked   # card-level — matches coder.md four-state (coder never self-emits deferred-approved; the orchestrator sets that after the AC-Closure Gate)
+    requirements:
+      - id: 1
+        text: "[text]"
+        status: done | not_implemented   # per-requirement is BINARY (legacy row-level partial/blocked were silent-deferral channels — removed)
+        evidence: "file:line"
+    files_changed:
+      - path/to/file.ts
+    build_status: pass | fail
+    lint_status: pass | fail
+    tsc_status: pass | fail | n/a        # n/a when stack.language excludes typescript
+    retry_count: N
+    ```
+```
+
+#### Step C: Wait for group completion
+
+The orchestrator waits for ALL background agents in the group to complete. It will be notified automatically as each finishes (`run_in_background`).
+
+> **Do NOT poll with `sleep N; echo "waiting..."` loops.** Background agents (and background `Bash` commands) re-invoke the orchestrator automatically when they finish — issuing `sleep`/`echo` "waiting" turns burns orchestrator turns and tokens for zero progress. Simply end your turn after spawning the background work; you will be woken on completion. This applies to EVERY barrier in Step D (D.1 build, D.2 reviewers, D.3/D.3b agents, D.4 qa-sentinel, D.4a doc-reviewer, D.4b `/codexreview`), not just Step C.
+
+For each completed agent:
+1. Read the completion report from the agent's output.
+2. Log to tracker: card ID, status, files changed, build/lint status.
+3. Do NOT read or store implementation details — only the verdict.
+
+**If an agent fails** (status: failed after 3 retries — the central repair cap):
+- Log failure in tracker `## Issues & Flags`.
+- Other agents in the group continue unaffected.
+- After group completes, ask user: retry failed card or skip?
+- **Retry re-entry (defined path):** on "retry", re-run the failed card from **Step B** (re-spawn the autonomous coder with a fresh briefing) — NOT from Step A, because the Step A arch context for the group is already in hand and is reused. The retried card then rejoins the group's Step D pipeline and MUST pass the SAME mandatory per-card sub-steps as its peers (D.3a AC-Closure → D.3b Simplify → D.3c E2E → D.4 QA → D.4a doc → D.4b codex → D.5 commit → D.6 backlog); there is no shortcut. The Step D coverage assertion will block Step E until the retried card has all mandatory tracker entries — so a retried card cannot silently skip a gate. **Cap: one Step-B re-entry per card** (consistent with the central cap discipline); on a second failure, re-ask with only skip/abandon so the loop cannot recur unbounded.
+
+#### Step D: Post-group review + QA (ALL sub-steps MANDATORY)
+
+> **The sub-steps below are ALL MANDATORY.** The previous lean Step D (build → combined review → qa → codex → commit) was an incident-causing shortcut (FEAT-0006: 10 sub-cards committed with 0 invocations of Phase 2.5b / 2.55 / 2.6 / 3 / 3.5 / 3.7) and is now FORBIDDEN. Every card in the group MUST complete every per-card sub-step (D.3a, D.3b, D.3c, D.4a) before the group reaches D.5 commit. Skipping any sub-step "to save time", "to save tokens", "because the diff is small", or for any model-invented reason is a protocol violation. Auto Mode does NOT override this.
+
+After ALL agents in the group complete successfully:
+
+1. **D.1 — Build verification (group)** — Run `npm run build` in the worktree to verify combined changes compile (redirect to `/tmp/build-group.txt` per § "Context economy"; surface only exit code + bounded extract on failure). If build fails, identify which card's changes broke it (from `git diff --name-only` per card), spawn a targeted fix-coder for those files only.
+
+1.5. **D.1.5 — Effective per-card review profile (compute ONCE; drives D.2 + D.4b)** — For EACH card in the group, compute its **effective codex profile** with the SAME deterministic rule the sequential Phase 3.7 Step C uses, so the two paths never disagree:
+   - **Floor**: read the card's `review_profile` field (`skip`/`light`/`balanced`/`deep`) per the QA Profile Selector (fallback-computed only for legacy cards lacking the field).
+   - **Escalation-only (Step A detector)**: run the Phase 3.7 **Step A** high-risk detector (bash + grep) on THIS card's committed diff (`git diff "$TRUNK...HEAD" -- <card files from ownership map>`). A matched trigger promotes `light`→`full`; it can NEVER downgrade `full`→`light`. The card's `review_profile` is the floor; the detector is the safety net on top.
+   - **Partition** the group into two lists and log them in the tracker under `## Team Mode`:
+     - `LIGHT_CARDS` = cards whose effective profile is `light` or `skip` **AND** zero Step-A triggers.
+     - `FULL_CARDS` = all others (effective profile `balanced`/`deep`, OR any Step-A trigger).
+   - **Sub-classify `TRIVIAL_CARDS` ⊆ `LIGHT_CARDS`** = cards that are `IS_TRIVIAL` on the committed diff (§ "Trivial-card fast-lane": `review_profile == skip` AND 0 Step-A triggers AND **non-source diff**). These are the LIGHT cards that have nothing for `code-reviewer` to review. (A `skip` card whose diff DID touch a source file is in `LIGHT_CARDS` but NOT `TRIVIAL_CARDS` — the guard keeps it on the code-review path.)
+   - **Sub-classify `DOC_DEFER_CARDS`** (since v4.7.0, for #2 doc deferral) = cards with `review_profile == light` whose committed diff touches **NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). Their per-card doc-review is deferred to the Final F.3 doc-reviewer. (Trivial cards, and any card whose diff touches a doc file, are NOT in this set — doc-review stays relevant for them.)
+   - Log: `## D.1.5 Effective Profiles\n<CARD-ID>: profile=<floor> triggers=<n> diff=<source|non-source> → effective=<light|full> (<LIGHT_CARDS|FULL_CARDS>)<, TRIVIAL / DOC_DEFER if applicable>` per card. This single computation is the SSOT for D.2 (code-reviewer + doc-reviewer scoping), D.3b/D.3c (already skipped for trivial), and D.4b (inclusion) — do NOT recompute it downstream.
+
+2. **D.2 — Combined static review (group)** — Two reviewers, **scoped by the D.1.5 partition** so each card gets exactly ONE per-card/group code review proportional to its risk (the other is the Final FULL gate):
+   - **doc-reviewer — over the group MINUS `DOC_DEFER_CARDS`** (since v4.7.0). It runs **read-only here** (it cannot write while code-reviewer reads in parallel — parallel-safety), MUST **attribute every doc finding to a specific card** (by file → ownership map), and applies the full Phase 3 mandate INCLUDING the spec/docs-drift→bug lens (since v3.35.0). The `DOC_DEFER_CARDS` (light, no-doc diff per D.1.5) are excluded — their doc-review is deferred to the Final F.3 doc-reviewer (batch-wide). **If the group is entirely `DOC_DEFER_CARDS` → skip the D.2 doc-reviewer** and log `D.2 doc-reviewer: DEFERRED to Final FULL gate (all cards light + no-doc diff)`. D.4a consumes the per-card findings (for the non-deferred cards) and dispatches the doc-reviewer (now alone, in write mode) to apply them — no second AUDIT spawn, but the FIXES are still owned by doc-reviewer.
+   - **code-reviewer — scoped to the diff-union of `LIGHT_CARDS` MINUS `TRIVIAL_CARDS`** (run it in parallel with the doc-reviewer over those files). These light non-trivial cards skip D.4b, so D.2 is their single per-card code review (the cross-batch Codex pass at Final covers them adversarially). **`TRIVIAL_CARDS` are excluded from the code-reviewer scope** — their diff is non-source, so there is nothing to code-review (doc-reviewer still covers them via the whole-group pass above; the Final FULL gate covers them adversarially). **If `LIGHT_CARDS \ TRIVIAL_CARDS` is empty → do NOT spawn code-reviewer at D.2** (every remaining card is either `FULL_CARDS` — deeper review at D.4b — or `TRIVIAL_CARDS` — nothing to review). Log the deterministic gate reason: `D.2 code-reviewer: scope=[<ids>] | excluded-trivial=[<ids>] | SKIPPED (no code-bearing light cards)`.
+   - **Tradeoff (documented, accepted — see top-of-file `REVIEW DEPTH SCALES` clause)**: for `FULL_CARDS`, cross-card detection moves from the per-group D.2 pass to the per-batch **Final-review FULL gate** (Codex over the entire batch diff, plus code-reviewer fallback) — same merge-gate safety, feedback arrives at batch-end rather than per-group. This is the intended de-duplication: `FULL_CARDS` are NOT re-reviewed by a group-level code-reviewer on top of their D.4b `/codexreview`.
+
+3. **D.3 — Apply fixes (group)** — If D.2 findings exist, spawn ONE fix-coder to apply all fixes in a single pass. Run build + lint after.
+
+3a. **D.3a — Phase 2.5b AC-Closure Gate (per-card, BLOCKING — non-skippable)** — For EACH card in the group, **sequentially**, invoke the full Phase 2.5b gate as documented in `### Phase 2.5b — AC-Closure Gate (BLOCKING — Scope Closure Discipline)`. This includes: build the AC Closure Ledger from the card YAML, run the rationalization scan, invoke `AskUserQuestion` one-per-deferred-AC, run the `implementation_notes` deferral audit, and persist the ledger in the tracker. Until EVERY card in the group exits PASS, do NOT proceed to D.3b. Cards exiting with `not_implemented` ACs that the user routes to "Implementa adesso" must finish their fix-coder loop and re-pass the gate before D.3b starts for the next card. Log under `## AC Closure Ledger — <CARD-ID>` per card.
+
+3b. **D.3b — Phase 2.55 Simplify (per-card, FANNED OUT across the group)** — The Simplify agents are **read-only analysis on file-disjoint per-card diffs** (the orchestrator applies the fixes afterward), so there is NO reason to run them one card at a time. **Spawn the per-card Simplify analysis for ALL eligible cards in PARALLEL** — in a SINGLE message, fire each card's Phase 2.55 trio (Reuse / Quality / Efficiency) against that card's diff captured to `/tmp/diff-<CARD-ID>.txt` (per Phase 2.55 step 2 — pass each trio the **path**, scoped to the card's File Ownership Map; never inline the diff). Per-card (not group-aggregate) so findings stay attributable. When all analyses return, **apply fixes per card** (file-disjoint → no write conflict), then re-run `npm run lint` and `npx tsc --noEmit` on the worktree ONCE for the whole group (redirect to disk per § "Context economy"). (Concurrency is capped by the platform; passing N cards is safe — excess agents queue.)
+   - **Gate (enumerated, `review_profile`-driven)**: SKIP D.3b for a card whose `review_profile == skip` (trivial / non-implementable card — Simplify is quality-only, so there is no merge-gate coverage to lose, and there is no substantive diff to simplify). Log `simplify: SKIPPED (review_profile=skip)`. For `light`/`balanced`/`deep` cards D.3b runs unchanged. This is the ONLY enumerated skip — never skip D.3b "for time" on a `light`+ card. (Skipped cards are simply omitted from the parallel fan-out.)
+
+3c. **D.3c — Phase 2.6 E2E-Review (per-card)** — First, evaluate the existing Gate table for EVERY card at once (skip when `features.has_e2e_review: false`, backend-only diff per the diff predicate documented in Phase 2.6, or card type in the Phase 2.6 skip set — `backend`/`api`/`db`/`infra`/`docs`/`chore`/`config`). In practice most cards in a group skip this gate (backend/db/api), so the eligible set is usually 0–1. For the cards that PASS the gate, invoke `/e2e-review` in programmatic mode with that card's payload. Each `/e2e-review` keeps its own isolated state dir (`.baldart/e2e-review/<CARD-ID>/`), so multiple runs do not clobber each other's artifacts.
+   - **Parallel-when-safe**: if **two or more** cards pass the gate, you MAY fan them out in parallel ONLY when they hit **disjoint routes/pages** — the genuinely shared resource is the worktree's single dev-server port, and concurrent Playwright sessions against one server are fine for disjoint routes. If the eligible cards touch overlapping routes (or `/e2e-review` spins its own server and a port clash is possible), run those **sequentially** to avoid a flaky cross-test. Default to parallel for the common disjoint case; fall back to sequential on any contention.
+   - BLOCKING per-card: if `/e2e-review` returns `"blocked"` or `"error"`, surface to the user via the same `AskUserQuestion` documented in Phase 2.6 — do NOT proceed to D.4 with an unresolved card. Skips are logged with the documented gate reason, never with `"time budget"` or similar.
+
+4. **D.4 — QA gate (group; since v4.7.0 — runs only for `deep` / risk-escalation, else deferred to Final)** — Read each card's `review_profile` field and the D.1.5 Step-A trigger result. **Run the group qa-sentinel (once, at FULL) iff** the group's MAX profile is `deep` **OR** any card in the group had a Step-A risk escalation. **Otherwise (max profile ≤ `balanced`, no escalation) → DEFER the group QA to the Final Review F.3 qa-sentinel** (FULL suite + build + audit over the entire batch — the unconditional merge gate); log `D.4 QA: DEFERRED to Final FULL gate (group max=balanced, no risk escalation)`. This mirrors sequential step 21b. When it DOES run, invoke qa-sentinel at FULL (the combined group diff must be validated together) using the same prompt contract as Phase 3.5 step 22. ⚠️ A balanced-only group runs its first suite at the Final gate; merge safety is preserved because Final is FULL over the whole batch.
+
+4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0; doc-reviewer-applied since v3.40.0)** — Do NOT re-run the doc AUDIT (D.2 already produced per-card-attributed findings). If any card in the group has doc findings, invoke the **doc-reviewer once in write mode** over the group, passing the per-card-attributed findings from D.2, to APPLY all doc fixes in a single pass (it is now alone — code-reviewer is done — so the D.2 parallel-safety constraint no longer applies). Do **NOT** spawn a fix-coder for doc findings: `doc` is owned by `doc-reviewer` (see "Domain-Override Domains"); a code-oriented coder lacks the doc-invariant contract. The only exception is a doc-drift→bug finding rooted in CODE — that follows the D.4b code fix path. (Previously D.4a spawned a fix-coder per card; the audit was already collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so the doc AUDIT runs once per group while the doc FIXES run once per group via doc-reviewer.) **Telemetry** — append one row per applied doc finding to `## Fix Application Log`: `D.4a | doc | est_lines=<n> | decision=doc-reviewer | applied_by=doc-reviewer | card=<ID> | finding=<1-line>`. **Phase-8 producer (named counter)** — ALSO record per card the `doc_gaps: found=<N> fixed=<M>` line in that card's `## Completed Cards` entry (same named counter as sequential Phase 3 step 15), so Phase 8 reads `doc_gaps_found`/`doc_gaps_fixed` from a structured field, not a free-form row.
+
+4b. **D.4b — Pre-Merge Codex Review Gate (per-card, profile-gated via D.1.5)** — Invoke `/codexreview` for **EACH card in `FULL_CARDS`** (the partition computed at D.1.5), one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path.
+   - **`LIGHT_CARDS` → SKIP D.4b** (enumerated `review_profile`-driven gate reason, NOT a time skip). A `light`/`skip` 0-trigger card already received its single per-card code review at the **D.2 group pass**, and its Codex-adversarial review is **guaranteed by the unconditional Final-review FULL gate** (Codex over the entire batch diff, post-batch). Running `/codexreview` here at `light` would only re-run `code-reviewer` + FP-gate (Codex is dropped at `light` since v3.38.0) — a pure duplicate of D.2. Log per card: `codex-review: SKIPPED (light, 0 triggers — D.2 group code-review covered + Codex adversarial guaranteed by Final FULL gate)`.
+   - **`FULL_CARDS` → run `/codexreview` as today** (the per-card Codex adversarial + CoVe + FP-gate pass is exactly where the per-card code review for these cards lives — D.2 deliberately did NOT re-review them). The profile passed is always `full` (D.1.5 already resolved it; do NOT recompute). Keep the sequential one-at-a-time loop (avoid N concurrent `/codexreview`, each of which fans out multiple sub-agents → rate-limit risk).
+   Apply the same fix sub-loop as sequential Phase 3.7 Step C.4: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and — **re-writing the consumed-once lean contract first** — re-invoke `/codexreview` via the Skill tool with `args: <CARD-ID>` (max 2 retries per card; a bare prose mention or a missing card-ID would let the retry review the wrong card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, `skip_api_perf_auditor: true` (since v4.7.0 — api-perf deferred to the Final F.3 batch-wide auditor), and `profile: full` (every card that reaches D.4b is in `FULL_CARDS` per D.1.5 — `light`/`skip` 0-trigger cards were already partitioned out and skip D.4b entirely; do NOT recompute the profile here). `full` runs the standard pipeline (Codex adversarial + CoVe + FP-gate, minus the duplicate doc-reviewer). The merge-gate safety for the skipped `LIGHT_CARDS` is the post-batch **Final-review FULL gate** (a single FULL `/codexreview` over the entire batch diff, which team mode reaches via "Post-batch — same as sequential mode"). To make D.4b run for every card again (pre-v4.5.0 behavior), drop the D.1.5 partition and iterate over all group cards here at their per-card profile; the final full gate stays regardless.
+
+5. **D.5 — Commit** — One commit per card using explicit staging from the ownership map. **NO stash in worktrees** (stashes are globally shared via `refs/stash` — see Phase 4 WORKTREE COMMIT RULE):
+   ```bash
+   cd <worktree-path>
+   # For each card in the group:
+   git add <card's-files-only>
+   # Disambiguate "nothing to commit" from a hook rejection BEFORE committing:
+   if [ -z "$(git status --porcelain)" ]; then
+     echo "D.5 <CARD-ID>: nothing staged — already committed upstream; record HEAD and skip"
+   else
+     git commit -m "[CARD-ID] Brief description"
+   fi
+   ```
+   If `git commit` itself fails with a non-empty staging area (a pre-commit / lint-staged hook rejected it), apply the SAME bounded handler as sequential Phase 4 step 27: clear a stale `COMMIT_LOCK`, re-stage explicitly, retry at most **2 times**, then log `[COMMIT-BLOCKED]` and escalate via `AskUserQuestion` — never loop unbounded and never silently leave a card uncommitted.
+
+6. **D.6 — Update backlog (MANDATORY — do NOT skip)** — For EACH card in the group:
+   a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`, add implementation notes (NEVER include `[USER-APPROVED DEFERRAL]` lines that didn't actually pass through D.3a's gate).
+   b. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry.
+   c. Stage the updated YAML and include it in the card's commit (or as an immediate follow-up commit).
+   d. Log in tracker: `card_status: DONE (verified)` for each card.
+   e. **→ Visibility**: TaskUpdate each card's spine task → `completed` (strip any live phase suffix) as it reaches DONE here.
+   Note: Phase 6b (Status Reconciliation) will catch any card missed here, but aim for zero misses.
+
+#### Step D coverage assertion (MANDATORY end-of-group check)
+
+Before moving to Step E, the orchestrator MUST verify the tracker contains, for EACH card in the group, ALL of the following entries (or an explicit gate-skip log with the documented reason):
+
+- `## AC Closure Ledger — <CARD-ID>` with `ac-closure: implemented=N | user-approved deferrals=M | follow-up cards created=K` (NEVER skipped — applies to trivial cards too)
+- `simplify: <N fixes | clean — 0 fixes | SKIPPED (review_profile=skip)>` (per-card from D.3b)
+- `e2e-review: <status>` (with documented gate-skip reason if SKIP)
+- `doc-review: <status | DEFERRED to Final FULL gate (DOC_DEFER_CARDS: light + no-doc diff)>` (from D.4a — runs for trivial cards too; the DEFERRED form is valid ONLY for `DOC_DEFER_CARDS` per D.1.5)
+- `qa: <profile=... | verdict=... | mechanical-only (trivial) | DEFERRED to Final FULL gate (group max=balanced, no risk escalation)>` (group-level from D.4; the DEFERRED form is valid when the group max profile ≤ balanced with no Step-A escalation)
+- `api-perf: <covered at D.4b | DEFERRED to Final FULL gate (skip_api_perf_auditor)>` (per-card — `skip_api_perf_auditor` defers it to F.3 batch-wide; DEFERRED is the normal v4.7.0 value)
+- `code-review: <covered at D.2 | covered at D.4b | SKIPPED (trivial — non-source diff)>` (per-card — the trivial SKIP is valid ONLY for `TRIVIAL_CARDS` per the D.1.5 partition)
+- `codex-review: <verdict | SKIPPED (light, 0 triggers — D.2 group code-review covered + Final FULL gate) | SKIPPED (trivial — non-source diff; covered by Final FULL gate)>` (per-card from D.4b — the SKIPPED forms are valid ONLY for `LIGHT_CARDS` / `TRIVIAL_CARDS` respectively)
+
+A missing entry means a sub-step was skipped. An entry whose value is a **`review_profile`-driven SKIP/DEFER**, an **`IS_TRIVIAL` SKIP**, or a **`/prd`-provenance SKIP** with a documented enumerated reason above (D.3b `skip` profile; D.4b `LIGHT_CARDS`; code/codex `TRIVIAL_CARDS`; doc-review `DOC_DEFER_CARDS`; QA `group max=balanced, no escalation`; api-perf `skip_api_perf_auditor`; plan-auditor `holistic_audit provenance`) is a VALID, present entry — not a violation; all defer to the unconditional Final FULL gate. What remains forbidden: a missing entry, or a skip whose reason is `time budget` / `to save tokens` / any model-invented constraint. If any entry is genuinely missing, do NOT proceed to Step E — return to the missing sub-step and execute it. Documenting "skipped per time budget" or similar is a protocol violation per the top-of-file rigidity clause.
+
+#### Step E: Context purge + next group
+
+After committing all cards in the group:
+1. Update tracker: move group to done, log all results per card.
+2. **PURGE**: forget all implementation details, review findings, architect context.
+3. **→ Visibility**: emit a Progress Bar reflecting the wave boundary (this wave done; next `Wave <X+1>/<Y>` pending) per § "Progress Visibility".
+4. Move to the next pending group (Step A again).
+
+### Sequential fallback within team mode
+
+If two cards in the same parallel group are discovered at runtime to have a file conflict (e.g., one coder created an unexpected file that overlaps):
+1. Detect via file-diff gate after Step C.
+2. Revert the later card's conflicting files.
+3. Re-run that card as a standalone sequential step after the group.
+
+### Dependency gates between groups
+
+Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If any card in a previous group failed and was skipped:
+- If cards in group N `depends_on` it: skip those dependent cards too, log in `## Issues & Flags`.
+- If no dependency: proceed normally.
+
+### Post-batch (same as sequential mode)
+
+After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Since v3.37.0 the Final Review runs a **single FULL `/codexreview` over the entire batch diff** (per the Final-review FULL gate) — no scope reduction — so every team-mode card, including any reviewed at `light` in D.4b, receives a guaranteed full review before merge.
+
+---

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

@@ -977,8 +977,14 @@ if [ "$CURRENT_BRANCH" = "$TRUNK" ]; then
     # (v3.39.0 — the finalizer MUST conclude). The cause is almost always an
     # uncommitted append to the framework-owned telemetry log left by a prior run.
     # Partition the dirty tree:
-    #   - framework-owned artifact (${paths.metrics}/skill-runs.jsonl) → auto-reconcile
-    #     (commit + rebase) so the ff completes with zero data loss;
+    #   - framework-owned artifacts → auto-reconcile (commit + rebase) so the ff
+    #     completes with zero data loss. Two sub-classes:
+    #       (a) telemetry: ${paths.metrics}/skill-runs.jsonl
+    #       (b) BALDART-managed install output left by `baldart update`/`add`/`push`:
+    #           .baldart/generated/ (overlay-merged agents/commands), .baldart/state.json
+    #           (version ledger), .baldart/skill-conflicts.json — these ARE meant to be
+    #           committed; a reinstall just leaves them uncommitted until the next sync.
+    #           .baldart/overlays/ is NOT owned here — an overlay edit is genuine work.
     #   - ANY foreign file → emit a decision marker the orchestrator MUST convert
     #     into ONE explicit user gate. Never auto-commit work this run did not own.
     METRICS_LOG="${paths.metrics}/skill-runs.jsonl"   # paths.metrics default: docs/metrics
@@ -988,22 +994,24 @@ if [ "$CURRENT_BRANCH" = "$TRUNK" ]; then
     for f in $DIRTY; do
       case "$f" in
         "$METRICS_LOG") OWNED="$OWNED $f" ;;
+        .baldart/generated/*|.baldart/state.json|.baldart/skill-conflicts.json) OWNED="$OWNED $f" ;;
         *) FOREIGN="$FOREIGN $f" ;;
       esac
     done
     if [ -n "$FOREIGN" ]; then
       echo "[SYNC-NEEDS-DECISION] main repo $TRUNK cannot fast-forward; foreign uncommitted files:${FOREIGN} — orchestrator MUST raise ONE explicit user gate (commit / user-handles), never a passive note."
     elif [ -n "$OWNED" ]; then
-      # Only framework-owned telemetry is dirty → reconcile autonomously, lossless.
-      git -C "$MAIN" add "$METRICS_LOG"
-      git -C "$MAIN" commit -m "chore(metrics): reconcile skill-runs telemetry before $TRUNK sync" --quiet
+      # Only framework-owned artifacts (telemetry + BALDART-managed install output) are
+      # dirty → reconcile autonomously, lossless.
+      git -C "$MAIN" add $OWNED
+      git -C "$MAIN" commit -m "chore(baldart): reconcile framework-managed artifacts before $TRUNK sync" --quiet
       if git -C "$MAIN" pull --rebase origin "$TRUNK" 2>/dev/null; then
         git -C "$MAIN" push origin "$TRUNK" 2>/dev/null \
-          && echo "✅ Reconciled stale metrics log + synced $TRUNK to origin." \
-          || echo "✅ Reconciled stale metrics log (local $TRUNK 1 commit ahead; syncs on next push). Tree clean."
+          && echo "✅ Reconciled framework-managed artifacts + synced $TRUNK to origin." \
+          || echo "✅ Reconciled framework-managed artifacts (local $TRUNK 1 commit ahead; syncs on next push). Tree clean."
       else
         git -C "$MAIN" rebase --abort 2>/dev/null || true
-        echo "[SYNC-NEEDS-DECISION] metrics rebase conflict on $TRUNK — orchestrator MUST raise ONE explicit user gate."
+        echo "[SYNC-NEEDS-DECISION] framework-managed reconcile rebase conflict on $TRUNK — orchestrator MUST raise ONE explicit user gate."
       fi
     else
       echo "[SYNC-NEEDS-DECISION] main repo $TRUNK cannot fast-forward and the working tree is clean (diverged?) — orchestrator MUST raise ONE explicit user gate."

package/framework/agents/coding-standards.md

@@ -91,8 +91,8 @@ if (error) {
 > **SSOT.** This section is the canonical policy for reference-aliasing mutation
 > hazards. It is cited as the source of truth by `coder.md`
 > (§ Reference-Aliasing Mutation Hazards), `code-reviewer.md` (review checklist),
-> and `.claude/skills/new/SKILL.md` (Phase 2.5 step 5c deterministic detector +
-> Phase 3.7 trigger #6). When those files cite "§ Reference-Aliasing Mutation
+> and `.claude/skills/new/references/{completeness,codex-gate}.md` (Phase 2.5 step 5c
+> deterministic detector + Phase 3.7 gate). When those files cite "§ Reference-Aliasing Mutation
 > Patterns", they mean this section.
 
 ### The hazard
@@ -165,10 +165,10 @@ the helper's JSDoc so future editors find the contract.
 - **This section** — full policy + JSDoc contract + remediation menu.
 - `coder.md § Reference-Aliasing Mutation Hazards` — pre-implementation check.
 - `code-reviewer.md` review checklist — flags un-guarded patterns at review time.
-- `.claude/skills/new/SKILL.md § Phase 2.5 step 5c` — deterministic detector
-  that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in
+- `.claude/skills/new/references/completeness.md § Phase 2.5 step 5c` — deterministic
+  detector that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in
   `## Issues & Flags`.
-- `.claude/skills/new/SKILL.md § Phase 3.7 trigger #6` — a mutation-after-helper
+- `.claude/skills/new/references/codex-gate.md § Phase 3.7` — a mutation-after-helper
   call invokes a per-card adversarial cross-model review before commit.
 
 ## Commit Message Format

package/package.json

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