baldart 4.26.0 → 4.27.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.27.0] - 2026-06-11
+
+**`/prd`: the Obsidian back-reference is now two-phase — the spec note is linked the moment the PRD starts, not only at merge.** The end-of-run snippet (v4.22.0) is gated on a successful merge, so a PRD that is paused or abandoned mid-flow (e.g. parked at the UI-design step, worktree never merged) left its origin note empty — even though detection already happened at Step 1. Observed in the wild: a `realtime-order-collaboration` PRD stuck at `ui-design` never wrote back, while a completed sibling PRD did. **MINOR** (additive capability on `/prd`; reuses the existing slug-keyed markers + the snippet `status:` lifecycle field; no `baldart.config.yml` key, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/prd/references/obsidian-backref.md`** — new shared SSOT for the back-reference: the marker contract (`<!-- BALDART:prd:<slug> START/END -->`), the idempotent read-replace-or-append write procedure, the skip conditions (no note / `path: none` / unwritable → log, never fatal), and the two write modes. Both call sites cite it, so the snippet shape can't drift between them.
+- **Provisional write at detection (discovery-phase Step 1 point 2).** Right after the Obsidian note is detected, `/prd` writes a lightweight `status: drafting` block (slug + deterministic branch `prd/<slug>` + planned PRD path + trunk) into the note and sets state `## Obsidian Spec Note / status: provisional-written`. The note reflects "a PRD was started here" immediately.
+
+### Changed
+
+- **Final write upgrades the provisional block in place (validation-phase Step 7.6).** Same slug-keyed markers, so the post-merge full payload (epic + card IDs, merge SHA/PR, `resources:`, `status: planned`) replaces the `drafting` block — no duplicates. Step 7.6 is now a lean delegation to `obsidian-backref.md § Mode: FINAL` instead of an inlined copy of the snippet.
+- **Snippet `status:` enum tightened to `drafting | planned | done`** (was `planned | in-progress | done`) — a clean ladder: PRD in stesura → mergiato/pianificato → in produzione.
+- **State `## Obsidian Spec Note / status` enum** gains `provisional-written`: `none → detected → provisional-written → back-reference-written`.
+- **Coupling fix:** `prd-writing-phase.md` Step 4 point 2 now adds the PRD Canonical Sources row when the note status is anything other than `none` (was hard-coded to `== detected`), so the provisional-write status change doesn't suppress the traceability row.
+- **`SKILL.md` HARD RULE 19** rewritten for the two-phase lifecycle; flow-table gains a `1.2` row and annotates `7.6` as the FINAL upgrade.
+
+## [4.26.1] - 2026-06-11
+
+**`new2`: specialization integrity — a full audit of every agent spawn; no role mixing anywhere.** User principle: code is written ONLY by `coder`, UI only by `ui-expert`, each agent does one thing. The audit of all 16 spawn sites found two genuine violations and three under-specified plumbing roles. **PATCH** (role-integrity fixes on the EXPERIMENTAL `new2` surface; no config key, no change to `/new`).
+
+### Fixed
+
+- **`new2.js` E2 — the ops pre-flight agent no longer repairs the baseline.** "baseline FAILS → fix once" had a general-purpose git agent editing source code. Now: the pre-flight returns `baseline:'fail'` + an actionable log (explicit role boundary: it never edits source/doc files), and the WORKFLOW spawns the **coder** specialist for one bounded repair attempt — verified by deterministically re-running the baseline gates (no claim to trust), `E2-baseline: FIXED-BY-CODER` ledger row; still failing → batch-fatal as before. Zero extra spawns in the happy path.
+- **`new2.js` — the Codex driver never reviews.** Its runtime fallback was "perform the review yourself with the code-reviewer lens" — a general-purpose agent doing code review. Now the driver returns `note:'codex-unavailable'` with empty findings, and the workflow spawns the REAL `code-reviewer` (same `stdReview` call as the matrix), ledgered as `review-codex: FALLBACK`.
+- **`new2-resolve.js` — judge map completed per domain.** `doc` fixes are now judged by **doc-reviewer** (code-reviewer judging prose was cross-domain) and `test` fixes by **qa-sentinel**; `security`/`migration` → security-reviewer and `perf` → api-perf-cost-auditor unchanged; `ui`/`code` stay with code-reviewer (the judge verifies a CODE change — its charter, incl. DS rule 8 for UI). Fixer and judge of the same type remain two independent adversarial instances.
+
+### Changed
+
+- **`new2.js` — explicit ROLE BOUNDARY lines on every plumbing agent** (pre-flight, commit, merge, production-readiness): they never edit source/doc files; commit/merge touch ONLY card YAML status fields + registry rows; a content-level merge conflict is leave+report, never hand-resolved; production-readiness executes stack-matched commands but reports (never edits) code/config changes. The full writer map is now: code/perf/migration/test fixes → `coder`; UI → `ui-expert`; security fixes → `security-reviewer`; docs → `doc-reviewer`; backlog YAML → `prd-card-writer`; bookkeeping (status/registry) → mechanical commit/merge agents.
+
 ## [4.26.0] - 2026-06-11
 
 **`new2`: Phase 1 decomposed into specialist agents — the owner implements, it no longer explores.** The old per-card pipeline gave the owner agent one mega-prompt ("you ARE claim + architect + plan-auditor + owner"), so the owner absorbed the whole codebase exploration into its own context and reached the actual coding with a degraded window. Phase 1 now runs as dedicated specialists with file handoff (`/tmp`), per the "ognuno fa una cosa" principle. Verified premise: nested subagent spawning does NOT exist in Claude Code (official docs: "Subagents cannot spawn other subagents" + 2 empirical probes), so the decomposition lives at the WORKFLOW level — the JS is the orchestrator, exactly what dynamic workflows are for. **MINOR** (pipeline capability on the EXPERIMENTAL `new2` surface only; no config key, no change to `/new`).

package/VERSION

@@ -1 +1 @@
-4.26.0
+4.27.0

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

@@ -38,6 +38,7 @@ message. You ask questions, wait for answers, and iterate.
 |------|-------|-----------|
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
+| 1.2 | Obsidian provisional back-reference (only if a spec note was given) | [discovery-phase.md](references/discovery-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 | 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
 | 2 | Discovery Question Loop (+ Codex completeness cross-check at exit, v4.19.0) | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | the canonical **`prd-add` skill** ([../prd-add/SKILL.md](../prd-add/SKILL.md)) — worktree-aware (`references/prd-add-phase.md` is a redirect stub, not the implementation) |
@@ -49,7 +50,7 @@ message. You ask questions, wait for answers, and iterate.
 | 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
 | 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
 | 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
-| 7.6 | Obsidian back-reference (only if a spec note was given) | [validation-phase.md](references/validation-phase.md) |
+| 7.6 | Obsidian back-reference — FINAL (upgrades the 1.2 provisional block; only if a spec note was given) | [validation-phase.md](references/validation-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 
 **Before starting each phase, read the corresponding reference file.**
 
@@ -234,21 +235,28 @@ message. You ask questions, wait for answers, and iterate.
     transcripts for REAL per-role token + wall-clock cost. The token itself is NOT part
     of the feature description — strip it before recording the user's verbatim feature
     text in `## Feature Description`.
-19. **Obsidian back-reference (MANDATORY when a spec note was given).** If the user
-    kicked off the PRD from an Obsidian note (any of: `[[Note]]` wikilink,
-    `obsidian://open?…` URI, or a pasted `.md` path), Step 1 detection persists it in
-    the state file `## Obsidian Spec Note` (`wikilink:` + absolute `path:` + `status:`).
-    At the END of the run — **after** the merge (validation-phase Step 7, item 9) so the
-    paths/IDs/SHA are final — Step 7.6 writes an **idempotent** snippet back into that
-    note: a marker-delimited section (`<!-- BALDART:prd:<slug> START/END -->`) holding a
-    fenced `yaml` block with the feature slug, PRD path, epic + card IDs, branch, merge
-    commit/PR, and the PRD's Canonical Sources as `resources:`. This makes the original
-    note the durable index the user can later query ("come è stata sviluppata la feature
-    X, dov'è finita"). The note lives in the user's **vault, outside the worktree and
-    outside git** — it is a plain filesystem write, never staged/committed. The step is
-    **NON-BLOCKING**: no spec note, unresolved vault path, or an unwritable note all skip
-    it with a log line, never aborting the PRD. See discovery-phase.md Step 1 point 2 and
-    validation-phase.md Step 7.6.
+19. **Obsidian back-reference (MANDATORY when a spec note was given — TWO-PHASE since
+    v4.27.0).** If the user kicked off the PRD from an Obsidian note (any of: `[[Note]]`
+    wikilink, `obsidian://open?…` URI, or a pasted `.md` path), the same note becomes the
+    durable index the user can later query ("come è stata sviluppata la feature X, dov'è
+    finita"). It is written in two phases against ONE slug-keyed marker block
+    (`<!-- BALDART:prd:<slug> START/END -->`), so the second write replaces the first in
+    place (idempotent, no duplicates):
+    - **Provisional** — at Step 1 detection (discovery-phase Step 1 point 2): a lightweight
+      `status: drafting` block with slug + branch `prd/<slug>` + planned PRD path. So the
+      note reflects "a PRD was started here" **immediately**, even if the run is later
+      paused or abandoned before merge.
+    - **Final** — at the END of the run, **after** the merge (validation-phase Step 7 item
+      9) so paths/IDs/SHA are final (Step 7.6): the full payload — feature slug, PRD path,
+      epic + card IDs, branch, merge commit/PR, Canonical Sources as `resources:`,
+      `status: planned`.
+
+    The note lives in the user's **vault, outside the worktree and outside git** — a plain
+    filesystem write, never staged/committed. Both writes are **NON-BLOCKING**: no spec
+    note, unresolved vault path, or an unwritable note all skip with a log line, never
+    aborting the PRD. SSOT for the marker contract + write procedure + both modes:
+    [obsidian-backref.md](references/obsidian-backref.md). See also discovery-phase.md Step
+    1 point 2 and validation-phase.md Step 7.6.
 
 ---
 

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

@@ -16,10 +16,12 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 
 <!-- Populated by discovery-phase.md Step 1 point 2 ONLY when the user passed an
      Obsidian note as the documental starting point. When no note was given, leave
-     status: none and the Step 7.6 back-reference is skipped. -->
+     status: none and both back-reference writes are skipped. -->
 wikilink: none        # [[Note Name]] form — feeds PRD Canonical Sources row
-path: none            # absolute fs path of the note — target of the Step 7.6 writeback
-status: none          # none | detected | back-reference-written
+path: none            # absolute fs path of the note — target of the back-reference writeback
+status: none          # none | detected | provisional-written | back-reference-written
+                      # detected → provisional snippet written at Step 1.2 (provisional-written)
+                      # → upgraded to the full payload at Step 7.6 (back-reference-written)
 
 ## Feature Description
 {{user's description verbatim}}

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

@@ -84,6 +84,17 @@ this is a fresh session (no existing state file).
    Then read the note content (from `path:`) to pre-populate discovery dimensions
    where possible — treat it as a user-provided spec. This same note becomes the
    target of the back-reference snippet at the end of the run (HARD RULE 19).
+
+   **Provisional back-reference (NON-BLOCKING — v4.27.0).** Immediately after detection,
+   write a *provisional* snippet into the note so it reflects "a PRD was started here" even
+   if this session is later paused or abandoned before merge (the FINAL snippet at
+   validation-phase Step 7.6 is gated on a successful merge and would otherwise never run
+   for an incomplete PRD). Follow [obsidian-backref.md](obsidian-backref.md) **§ Mode:
+   PROVISIONAL** — the marker block is keyed on `<slug>`, so the FINAL write later replaces
+   it in place (no duplicates). All skip conditions in that module apply (no note / `path:
+   none` / unwritable → log and continue, never fatal). On success the module sets
+   `## Obsidian Spec Note / status: provisional-written`. The branch is the deterministic
+   `prd/<slug>` that `nw-docs` creates in the next point.
 3. **Create the docs worktree (MANDATORY — HARD RULE 17)** — invoke the
    `worktree-manager` skill in programmatic docs mode BEFORE any file write:
 

package/framework/.claude/skills/prd/references/obsidian-backref.md

@@ -0,0 +1,120 @@
+# Obsidian Back-Reference (shared SSOT)
+
+Single source of truth for the **idempotent back-reference snippet** that `/prd` writes
+into the user's Obsidian spec note. Two phases call this module; both target the SAME
+marker block keyed on the slug, so the later write **replaces the earlier one in place** —
+the note never accumulates duplicates.
+
+| Phase | Caller | Mode | Trigger |
+|---|---|---|---|
+| Provisional | `discovery-phase.md` Step 1 point 2 | `PROVISIONAL` | right after the note is detected — the PRD has only just started |
+| Final | `validation-phase.md` Step 7.6 | `FINAL` | after the merge succeeds — paths, card IDs, branch, SHA are now final |
+
+**Why two phases (v4.27.0).** A PRD can be paused or abandoned mid-flow (e.g. parked at the
+UI-design step, worktree never merged). The FINAL write is gated on a successful merge, so
+without a provisional write the note would stay empty for every incomplete PRD — even
+though detection already happened at Step 1. The provisional write makes the note reflect
+"a PRD was started here" immediately; the FINAL write upgrades it to the full,
+queryable payload once the run completes.
+
+## Marker contract
+
+The block is delimited by HTML-comment markers keyed on `<slug>`:
+
+```
+<!-- BALDART:prd:<slug> START -->
+…block…
+<!-- BALDART:prd:<slug> END -->
+```
+
+**Write procedure (identical for both modes):**
+1. Read the current note content at the absolute `path:` from state `## Obsidian Spec Note`.
+2. If both markers are present → REPLACE everything between them (inclusive) with the new block.
+3. If markers are absent → APPEND the new block at the end of the note, preceded by one blank line.
+4. Write the note back to `path:`.
+
+The note lives in the user's **vault, outside the worktree and outside git** — it is a
+plain filesystem write to the absolute `path:`, NEVER staged or committed.
+
+## Skip conditions (each logged, NEVER fatal — both phases)
+
+- `## Obsidian Spec Note / status` is `none` (no note was given) → skip silently.
+- `path:` is `none`/empty (vault root never resolved at Step 1) → skip with a one-line note.
+- The file at `path:` does not exist or is not writable → skip with a one-line warning.
+
+The back-reference is a convenience index, never a gate. Any failure logs
+`"Obsidian back-reference: SKIPPED (<reason>)"` and the run continues.
+
+## Mode: PROVISIONAL — `discovery-phase.md` Step 1 point 2
+
+**Known here:** `<slug>`, the deterministic branch `prd/<slug>` (the name `worktree-manager
+nw-docs` always uses), the planned PRD path, `git.trunk_branch`, the detection timestamp.
+**Not yet known:** epic/card IDs (Step 5), the merge SHA/PR (Step 7), the full Canonical
+Sources list (Step 4). Write the lighter block:
+
+````markdown
+<!-- BALDART:prd:<slug> START -->
+## 🛠 Sviluppo BALDART — <slug>
+
+```yaml
+feature: <slug>
+prd: ${paths.prd_dir}/<slug>/PRD.md   # path pianificato — il file viene scritto a Step 4
+branch: prd/<slug>
+trunk_branch: <git.trunk_branch>
+started: <ISO-8601 UTC>
+status: drafting   # drafting | planned | done
+```
+
+- **Stato:** PRD in stesura sul branch `prd/<slug>`. Lo snippet verrà completato al merge.
+
+_Avviato da `/prd` il <date>. Questo blocco si aggiorna automaticamente con card, merge e sorgenti canoniche quando il PRD viene mergiato._
+<!-- BALDART:prd:<slug> END -->
+````
+
+After the write, set `## Obsidian Spec Note / status: provisional-written` in the state file.
+
+## Mode: FINAL — `validation-phase.md` Step 7.6
+
+Runs AFTER the merge (Step 7 item 9). All identifiers are final. Write the full block,
+REPLACING the provisional one in place:
+
+````markdown
+<!-- BALDART:prd:<slug> START -->
+## 🛠 Sviluppo BALDART — <slug>
+
+```yaml
+feature: <slug>
+prd: ${paths.prd_dir}/<slug>/PRD.md
+epic: FEAT-XXXX-00-<slug>-epic
+cards:
+  - FEAT-XXXX-01-<sub-slug>
+  - FEAT-XXXX-02-<sub-slug>
+resources:        # other Canonical Sources from the PRD (mockups, ADRs, ref docs, research)
+  - ${paths.prd_dir}/<slug>/design.html      # omit if no design
+  - <ssot-registry entry / ADR path / research link>
+branch: prd/<slug>
+merge_commit: <SHA from state ## Validation>
+pr: <PR number, or n/a for local-push>
+trunk_branch: <git.trunk_branch>
+date: <ISO-8601 UTC>
+status: planned   # drafting | planned | done
+```
+
+- **PRD:** `${paths.prd_dir}/<slug>/PRD.md`
+- **Cards:** FEAT-XXXX-00 (epic) · FEAT-XXXX-01 · FEAT-XXXX-02 …
+- **Merge:** `<SHA>` su `<git.trunk_branch>`<!-- · PR #N -->
+
+_Generato da `/prd` il <date>. Aggiorna `status:` a `done` quando la feature è in produzione._
+<!-- BALDART:prd:<slug> END -->
+````
+
+Fill the `yaml` from the final state: `<slug>`, the real epic + child card IDs created in
+Step 5, the merge SHA written under `## Validation` (Step 7 item 8), the PR number from the
+`mw-docs` return (or `n/a`), and the Canonical Sources the PRD already assembled
+(`prd-writing-phase.md` Step 4 point 3) for `resources:`. The inner ```yaml``` block is
+fenced, NOT real top-of-file frontmatter — it is the queryable payload Claude reads back
+when asked about the feature later.
+
+After the write, set `## Obsidian Spec Note / status: back-reference-written` in the state
+file. (The state file is already committed; this is a local marker for a possible resume —
+do NOT re-commit just for this field.)

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

@@ -8,8 +8,9 @@ Mark task 3 as `in_progress`.
 
 1. Create directory `${paths.prd_dir}/<slug>/` if it doesn't exist.
 2. **Obsidian spec note (if present):** if the state file `## Obsidian Spec Note`
-   section has `status: detected`, add a row to the Canonical Sources table in the PRD
-   using its `wikilink:` value:
+   section has `status` other than `none` (i.e. `detected`, `provisional-written`, or
+   `back-reference-written` — a note was given), add a row to the Canonical Sources table
+   in the PRD using its `wikilink:` value:
    `| Obsidian spec | [[Note Name]] |`
    This preserves traceability from the user's original spec note to the final PRD, and
    the same note receives the end-of-run back-reference snippet (validation-phase Step 7.6).

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

@@ -249,76 +249,32 @@ branch is gone (or its deletion is explicitly user-deferred).
 
 ### Step 7.6 — Obsidian back-reference (NON-BLOCKING — runs only when a spec note was given)
 
-**Why this exists.** When the user kicked off the PRD from an Obsidian note (state
-file `## Obsidian Spec Note / status: detected`, see HARD RULE 19), they want that
-same note to become the durable index of *how the feature was developed and where it
-landed* — so they can later ask "come è stata sviluppata la feature X?" and get the
-PRD, cards, and merge from the note itself. This step writes a single, idempotent,
-machine-and-human readable snippet back into the note.
+**Why this exists.** When the user kicked off the PRD from an Obsidian note (state file
+`## Obsidian Spec Note / status` is not `none`, see HARD RULE 19), they want that same note
+to become the durable index of *how the feature was developed and where it landed* — so
+they can later ask "come è stata sviluppata la feature X?" and get the PRD, cards, and
+merge from the note itself.
 
-**Runs AFTER the merge (Step 7 item 9) succeeds** — only then are the canonical paths,
-card IDs, branch, PR/SHA final. The note lives in the user's **vault, OUTSIDE the
-worktree and outside git** — so this is a plain filesystem write to the absolute
-`path:`, NOT a worktree-relative path and NOT a git-tracked artefact (do not stage it).
-
-**Skip conditions (each logged, never fatal):**
-- `## Obsidian Spec Note / status` is `none` (no note was given) → skip silently.
-- `path:` is `none` or empty (vault root never resolved at Step 1) → skip with a note.
-- The file at `path:` does not exist or is not writable → skip with a one-line warning.
-
-**Procedure:**
-
-1. Read the current content of the note at `path:`.
-2. Build the snippet, delimited by HTML-comment markers keyed on the slug so the step
-   is **idempotent** — a re-run (or a later `/prd-add`) REPLACES the block between the
-   markers in place instead of appending a duplicate. If the markers are absent, append
-   the block at the end of the note (preceded by one blank line).
-
-   ```markdown
-   <!-- BALDART:prd:<slug> START -->
-   ## 🛠 Sviluppo BALDART — <slug>
-
-   ```yaml
-   feature: <slug>
-   prd: ${paths.prd_dir}/<slug>/PRD.md
-   epic: FEAT-XXXX-00-<slug>-epic
-   cards:
-     - FEAT-XXXX-01-<sub-slug>
-     - FEAT-XXXX-02-<sub-slug>
-   resources:        # other Canonical Sources from the PRD (mockups, ADRs, ref docs, research)
-     - ${paths.prd_dir}/<slug>/design.html      # omit if no design
-     - <ssot-registry entry / ADR path / research link>
-   branch: prd/<slug>
-   merge_commit: <SHA from state ## Validation>
-   pr: <PR number, or n/a for local-push>
-   trunk_branch: <git.trunk_branch>
-   date: <ISO-8601 UTC>
-   status: planned   # planned | in-progress | done
-   ```
-
-   - **PRD:** [`${paths.prd_dir}/<slug>/PRD.md`](...) 
-   - **Cards:** FEAT-XXXX-00 (epic) · FEAT-XXXX-01 · FEAT-XXXX-02 …
-   - **Merge:** `<SHA>` su `<git.trunk_branch>`<!-- · PR #N -->
+This is the **FINAL** write of the two-phase back-reference (the provisional write already
+happened at discovery-phase Step 1 point 2, status `provisional-written`). It **upgrades
+the provisional block in place** — same slug-keyed markers — replacing the lightweight
+"PRD in stesura" block with the full, queryable payload.
 
-   _Generato da `/prd` il <date>. Aggiorna `status:` a `done` quando la feature è in produzione._
-   <!-- BALDART:prd:<slug> END -->
-   ```
-
-   Fill the `yaml` block from the final state: `<slug>`, the real epic + child card
-   IDs created in Step 5, the merge SHA written under `## Validation` (Step 7 item 8),
-   the PR number from the `mw-docs` return (or `n/a`), and the Canonical Sources list
-   the PRD already assembled (prd-writing-phase.md Step 4 point 3) for `resources:`.
-   The inner ```` ```yaml ```` block is fenced, NOT real top-of-file frontmatter — it
-   is the queryable payload Claude reads back when asked about the feature later.
+**Runs AFTER the merge (Step 7 item 9) succeeds** — only then are the canonical paths,
+card IDs, branch, PR/SHA final.
 
-3. Write the updated note back to `path:`.
-4. Set `## Obsidian Spec Note / status: back-reference-written` in the state file.
-   (The state file is already committed; this is a local marker for a possible resume —
-   do NOT re-commit just for this field.)
+**Procedure:** follow [obsidian-backref.md](obsidian-backref.md) **§ Mode: FINAL** — it is
+the SSOT for the marker contract, the idempotent read-replace-or-append write procedure,
+the full snippet template, the skip conditions (no note / `path: none` / unwritable → log
+and continue, never fatal), and the final state update to
+`## Obsidian Spec Note / status: back-reference-written`. Fill the `yaml` from the final
+state: the real epic + child card IDs (Step 5), the merge SHA under `## Validation` (Step 7
+item 8), the PR number from the `mw-docs` return (or `n/a`), and the Canonical Sources the
+PRD assembled (prd-writing-phase.md Step 4 point 3) for `resources:`.
 
 **This step is NON-BLOCKING** — any failure (note moved, vault unmounted, permission
-denied) logs "Obsidian back-reference: SKIPPED (<reason>)" and the run completes. The
-PRD merge has already happened; the back-reference is a convenience index, never a gate.
+denied) logs "Obsidian back-reference: SKIPPED (<reason>)" and the run completes. The PRD
+merge has already happened; the back-reference is a convenience index, never a gate.
 
 ### Final output
 

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

@@ -99,7 +99,17 @@ const FOLLOWUP_SCHEMA = {
 // F-024 — domain-specialized fixer + judge (full map; reviewer-owns-its-domain — a doc
 // finding is fixed by doc-reviewer, a security finding by security-reviewer, never coder).
 const fixerAgent = ({ doc: 'doc-reviewer', ui: 'ui-expert', security: 'security-reviewer' })[domain] || 'coder'
-const judgeAgent = (domain === 'security' || domain === 'migration') ? 'security-reviewer' : domain === 'perf' ? 'api-perf-cost-auditor' : 'code-reviewer'
+// Specialization integrity (v4.26.1) — the judge is the VERIFICATION specialist of the
+// finding's domain: doc fixes judged by doc-reviewer (code-reviewer judging prose was
+// cross-domain), test fixes by qa-sentinel (THE test specialist). `ui` and `code` stay with
+// code-reviewer: the judge verifies a CODE change, which is code-reviewer's charter
+// (including DS-coherence rule 8 for UI). Fixer and judge of the same type are still two
+// independent instances — the judge prompt is adversarial and greps the files itself.
+const judgeAgent = (domain === 'security' || domain === 'migration') ? 'security-reviewer'
+  : domain === 'perf' ? 'api-perf-cost-auditor'
+  : domain === 'doc' ? 'doc-reviewer'
+  : domain === 'test' ? 'qa-sentinel'
+  : 'code-reviewer'
 
 const findingsBlock = findings.map((f, i) => `  ${i + 1}. [${f.kind || kind}/${f.domain || domain}] ${f.evidence}`).join('\n')
 const brief = [

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

@@ -219,9 +219,10 @@ try {
     `You are the deterministic PRE-FLIGHT for an autonomous /new batch (variant new2). Follow ${REF}/setup.md (Phase 0 + Pre-flight) and ${REF}/implement.md (Phase 1 depends-on gate) for the SEMANTICS, but replace EVERY AskUserQuestion with the deterministic policy below. You run all git/bash yourself (the workflow cannot).\n\n` +
       `${projectBrief}\n\nCards in batch (Read each YAML):\n${cardPaths.join('\n')}\nCard IDs: ${cardIds.join(' ')}\n\n` +
       `Create/maintain the recovery tracker at /tmp/batch-tracker-${firstCard}.md (per setup.md § Context Tracking).\n\n` +
+      `ROLE BOUNDARY (specialization integrity): you are the OPS/GIT agent. You NEVER edit source or doc files — any needed content change belongs to the coder specialist; report it instead.\n\n` +
       `DETERMINISTIC GATE POLICIES (NO user prompts):\n` +
       `• G1 dirty-tree (main repo ${MAIN}): partition framework-managed noise exactly as setup.md step 3 ($METRICS=${METRICS}, .baldart/generated|state.json|skill-conflicts.json — NOT overlays/). Genuine user work → auto-stash 'baldart-new2-${firstCard}' (main checkout) and record the label. Never commit/abort/prompt.\n` +
-      `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK}; install deps; assign a port; run the baseline (tsc+lint+build). Copy ONLY the artifacts needed (env/.env.local/.env.example/supabase/.temp) — do NOT bulk-copy untracked files from the main repo (avoids stray backlog cards in the worktree). Use the git-authoritative idempotency pre-check. E2: baseline FAILS → fix once; still failing → baseline:'fail' + baselineLog (batch-fatal).\n` +
+      `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK}; install deps; assign a port; run the baseline (tsc+lint+build). Copy ONLY the artifacts needed (env/.env.local/.env.example/supabase/.temp) — do NOT bulk-copy untracked files from the main repo (avoids stray backlog cards in the worktree). Use the git-authoritative idempotency pre-check. E2: baseline FAILS → do NOT fix it yourself (role boundary — the coder specialist repairs it); return baseline:'fail' + a baselineLog precise enough for a coder to act (failing command, error excerpt, suspect files).\n` +
       codexResolveBullet +
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c): card missing requirements/acceptance_criteria/files_likely_touched → EXCLUDE (excluded[] + reason). Never HALT for one bad card.\n` +
@@ -239,9 +240,28 @@ try {
   return finalReturn({ fatal: true, reason: 'pre-flight failed: ' + String(e && e.message) })
 }
 
-if (!preflight || preflight.ok === false || preflight.baseline === 'fail') {
-  ledger(firstCard, 'E2-baseline', 'BATCH-FATAL', (preflight && preflight.baselineLog) || 'workspace unworkable')
-  return finalReturn({ fatal: true, reason: 'baseline build irrecoverable — see baselineLog' })
+if (!preflight || preflight.ok === false) {
+  ledger(firstCard, 'preflight', 'BATCH-FATAL', (preflight && preflight.workspaceNote) || 'workspace unworkable')
+  return finalReturn({ fatal: true, reason: 'workspace unworkable — see pre-flight' })
+}
+if (preflight.baseline === 'fail') {
+  // E2 (specialization integrity) — baseline repair is CODE work: it belongs to the coder
+  // specialist, not the ops pre-flight agent (which never edits source). ONE bounded attempt;
+  // the verification is the deterministic re-run of the baseline gates themselves (no claim
+  // to trust — and every card's G26 re-exercises them anyway). Still failing → batch-fatal.
+  let repair = null
+  try {
+    repair = await agentSafe(
+      `You are the coder. The batch worktree BASELINE is failing on trunk-derived code (this is NOT card work — no card has run yet). Worktree: ${preflight.worktreePath} (cd into it).\n\nFailure log:\n${preflight.baselineLog || '(missing — re-run tsc/lint/build to reproduce)'}\n\nApply the minimal correct fix so the baseline gates (tsc + lint + build) pass, RE-RUN them, and report honestly (fixed:true ONLY if they now pass). Return: { fixed, log }`,
+      { label: 'baseline-repair', phase: 'Pre-flight', agentType: 'coder',
+        schema: { type: 'object', required: ['fixed'], additionalProperties: true, properties: { fixed: { type: 'boolean' }, log: { type: 'string' } } } }
+    )
+  } catch (e) { if (e && e.transientExhausted) noteDegraded('outage'); repair = null }
+  if (repair && repair.fixed) ledger(firstCard, 'E2-baseline', 'FIXED-BY-CODER', String(repair.log || '').slice(0, 200))
+  else {
+    ledger(firstCard, 'E2-baseline', 'BATCH-FATAL', preflight.baselineLog || 'baseline irrecoverable')
+    return finalReturn({ fatal: true, reason: 'baseline build irrecoverable — see baselineLog' })
+  }
 }
 
 for (const ex of preflight.excluded || []) ledger(ex.card, 'preflight-exclude', 'EXCLUDED', ex.reason)
@@ -563,28 +583,41 @@ async function runCard(cardId, cardPath) {
   const reviewSchema = { type: 'object', required: ['blocks', 'scopeExpansion'], additionalProperties: true,
     properties: { blocks: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeExpansion: { type: 'array', items: { type: 'object', additionalProperties: true } }, note: { type: 'string' } } }
   let reviewResults = []
+  const onErr = (e) => { if (e && e.transientExhausted) noteDegraded('outage'); return null }
+  // The standard SPECIALIST reviewer spawn — also reused as the JS-level fallback when the
+  // Codex companion dies at runtime (specialization integrity: the driver never reviews).
+  const stdReview = (ra) => agentSafe(
+    `You are ${ra}. Review card ${cardId} per ${REF}/review-cycle.md + ${REF}/codex-gate.md (your domain only). Run your gates on the COMMITTED-or-working state.\n\n${cardBrief}\nDiff: /tmp/diff-${cardId}.txt\n\n` +
+      `Report ONLY blocking failures that survive your retry cap as blocks:[{gate,domain,evidence}] (each MUST have non-empty gate AND evidence — F-014). Report legitimate findings BEYOND this card's AC as scopeExpansion:[{evidence,domain,withinOwnership,newAC}].\n\n` +
+      `Return: { blocks:[...], scopeExpansion:[...], note }`,
+    { label: `review:${cardId}:${ra}`, phase: 'Implement', agentType: ra, schema: reviewSchema }
+  ).catch(onErr)
   try {
     reviewResults = (await parallel(reviewers.map((ra) => () => {
-      const onErr = (e) => { if (e && e.transientExhausted) noteDegraded('outage'); return null }
       if (ra === 'codex') {
-        // Codex-light finder: a general-purpose agent drives the resolved companion (Bash, --wait).
+        // Codex-light finder: a general-purpose agent DRIVES the resolved companion (Bash,
+        // --wait). Driver role only — it never reviews; runtime failure → note flag, and the
+        // workflow spawns the real code-reviewer below.
         return agentSafe(
-          `You are the Codex review driver for card ${cardId} (review_profile=light — Codex is the SOLE finder since v4.18.0; you are NOT code-reviewer). Run the OpenAI Codex companion as a REVIEW-ONLY adversarial pass over this card's diff, then return its material findings in the schema below.\n\n${cardBrief}\nDiff: /tmp/diff-${cardId}.txt\nMAY-EDIT: ${JSON.stringify(mayEdit)}\n\n` +
+          `You are the Codex review DRIVER for card ${cardId} (review_profile=light — Codex is the SOLE finder since v4.18.0; you are a driver, NOT a reviewer). Run the OpenAI Codex companion as a REVIEW-ONLY adversarial pass over this card's diff, then return its material findings in the schema below.\n\n${cardBrief}\nDiff: /tmp/diff-${cardId}.txt\nMAY-EDIT: ${JSON.stringify(mayEdit)}\n\n` +
             `Run it in the FOREGROUND (it blocks; do NOT pass run_in_background):\n  node "${sharedCtx.codexScriptPath}" task "Review-only — DO NOT make edits, no --write flag. Adversarial review of card ${cardId} using the diff at /tmp/diff-${cardId}.txt. Focus: auth/permission boundaries, data-loss paths, race conditions, rollback safety, schema drift, invariant violations. Report ONLY material findings with file+line evidence." --wait\n` +
-            `Read the Codex output ONLY through a [codex]-trace-stripping filter. **Fallback**: if it exits non-zero / prints CODEX_NOT_FOUND / stays empty, set note='codex-unavailable' and perform the review yourself with the code-reviewer lens (your domain).\n\n` +
+            `Read the Codex output ONLY through a [codex]-trace-stripping filter. **Fallback**: if it exits non-zero / prints CODEX_NOT_FOUND / stays empty, return note:'codex-unavailable' with EMPTY blocks/scopeExpansion — do NOT review yourself (role boundary); the workflow spawns the real code-reviewer.\n\n` +
             `Map Codex BLOCKER/HIGH findings to blocks:[{gate:'codex-light',domain,evidence}] (each non-empty gate AND evidence — F-014). Map legitimate findings BEYOND this card's AC to scopeExpansion:[{evidence,domain,withinOwnership,newAC}].\n\n` +
             `Return: { blocks:[...], scopeExpansion:[...], note }`,
           { label: `review:${cardId}:codex`, phase: 'Implement', agentType: 'general-purpose', schema: reviewSchema }
         ).catch(onErr)
       }
-      return agentSafe(
-        `You are ${ra}. Review card ${cardId} per ${REF}/review-cycle.md + ${REF}/codex-gate.md (your domain only). Run your gates on the COMMITTED-or-working state.\n\n${cardBrief}\nDiff: /tmp/diff-${cardId}.txt\n\n` +
-          `Report ONLY blocking failures that survive your retry cap as blocks:[{gate,domain,evidence}] (each MUST have non-empty gate AND evidence — F-014). Report legitimate findings BEYOND this card's AC as scopeExpansion:[{evidence,domain,withinOwnership,newAC}].\n\n` +
-          `Return: { blocks:[...], scopeExpansion:[...], note }`,
-        { label: `review:${cardId}:${ra}`, phase: 'Implement', agentType: ra, schema: reviewSchema }
-      ).catch(onErr)
+      return stdReview(ra)
     }))).filter(Boolean)
   } catch (_) { /* parallel never rejects; nulls filtered */ }
+  // Specialization integrity — companion died at runtime: replace the empty driver result
+  // with a REAL code-reviewer pass (the same fallback the JS-level codexAvail gate uses).
+  if (reviewResults.some((r) => r && r.note === 'codex-unavailable')) {
+    reviewResults = reviewResults.filter((r) => !(r && r.note === 'codex-unavailable'))
+    g('review-codex', 'FALLBACK', 'companion failed at runtime → code-reviewer spawned (driver never reviews)')
+    const fb = await stdReview('code-reviewer')
+    if (fb) reviewResults.push(fb)
+  }
 
   // F-014 — only route well-formed blocks (non-empty gate+evidence).
   const blocks = reviewResults.flatMap((r) => (r.blocks || [])).filter((b) => b && b.gate && b.evidence)
@@ -642,7 +675,7 @@ async function runCard(cardId, cardPath) {
   let commitRes
   try {
     commitRes = await agentSafe(
-      `Commit card ${cardId} in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT re-read reference modules.\n` +
+      `Commit card ${cardId} in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT re-read reference modules. ROLE BOUNDARY: you NEVER modify file contents except the card YAML status/note fields and the ssot-registry row — source/doc changes are not yours.\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 }`,
@@ -863,6 +896,7 @@ if (!committed.length) {
     mergeResult = await agentSafe(
       `Auto-merge the batch worktree to ${TRUNK} per ${REF}/merge-cleanup.md (Phase 6 via /mw programmatic checksAlreadyPassed:true, Phase 6b status reconciliation, Phase 6c hygiene). Run git yourself.\n\n${projectBrief}\nWorktree: ${sharedCtx.worktreePath}\nBranch: ${sharedCtx.branch}\nmerge_strategy: ${mergeStrategy}\nCommitted cards: ${committed.map((r) => r.card).join(' ')}\nPhase-0 stash to restore (if any): see /tmp/batch-tracker-${firstCard}.md.\n\n` +
         `DETERMINISTIC POLICIES (NO prompts):\n` +
+        `• ROLE BOUNDARY: you are the OPS/GIT agent — you NEVER edit source or doc files. Reconciliation touches ONLY card YAML status fields + registry rows. A merge conflict on content is leave+report, never hand-resolved here.\n` +
         `• 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` +
@@ -894,7 +928,7 @@ phase('Production')
 if (mergeResult && mergeResult.merged) {
   try {
     prodReadiness = await agentSafe(
-      `Run the post-merge Production Readiness checklist per ${REF}/production-readiness.md (Phase 7) over the batch's changed files. Auto-EXECUTE only stack-matched index/access-rule/cron deploys; REPORT (do not execute) env vars, feature flags, DB migrations, secrets, DNS. NON-BLOCKING.\n\n${projectBrief}\nChanged files: ${dedupe(committed.flatMap((r) => r.filesChanged || [])).join(', ') || '(derive from git)'}\n\nReturn: { autoExecuted:[...], manualItems:[...], note }`,
+      `Run the post-merge Production Readiness checklist per ${REF}/production-readiness.md (Phase 7) over the batch's changed files. Auto-EXECUTE only stack-matched index/access-rule/cron deploys; REPORT (do not execute) env vars, feature flags, DB migrations, secrets, DNS. NON-BLOCKING. ROLE BOUNDARY: you EXECUTE commands, you never edit repository files — a needed code/config change is reported as a manual item.\n\n${projectBrief}\nChanged files: ${dedupe(committed.flatMap((r) => r.filesChanged || [])).join(', ') || '(derive from git)'}\n\nReturn: { autoExecuted:[...], manualItems:[...], note }`,
       { label: 'production-readiness', phase: 'Production', agentType: 'general-purpose',
         schema: { type: 'object', required: ['manualItems'], additionalProperties: true, properties: { autoExecuted: { type: 'array', items: { type: 'string' } }, manualItems: { type: 'array', items: { type: 'string' } }, note: { type: 'string' } } } }
     )

package/package.json

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