baldart 4.62.0 → 4.63.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.63.0] - 2026-06-23
+
+**Fixes from the FEAT-0042 post-mortem — the first real `/new` run on v4.62.0.** v4.62.0 worked (that run billed −29% vs the FEAT-0041 baseline, 1 unplanned fix-coder vs 4, `/mw` and the durable tracker held), but the deep post-mortem surfaced a new class of bug and two real leaks — including one *introduced by* v4.62.0 itself.
+
+**MINOR** — adds a `doctor` diagnostic + guidance/agent edits; no layout/install change, **no new `baldart.config.yml` key**.
+
+### Fixed
+
+- **CLI ↔ framework version-skew silently disabled the Codex broker teardown (the v4.62.0 leak)** — `merge-cleanup.md` / `new/SKILL.md` / `new2/SKILL.md` + `src/commands/doctor.js`. The framework prose ships via the git subtree (current), but `npx baldart` resolves the SEPARATELY-installed CLI; on a consumer whose global CLI predated v4.62.0, `npx baldart teardown-codex-broker` returned `unknown command`, which `2>/dev/null || true` masked as a no-op → the Codex broker + its Playwright/… MCP children survived every run (FEAT-0042: 5 brokers leaked). The teardown snippets now **capture stderr (no masking), detect `unknown command`, warn to `npm i -g baldart@latest`, fall back to a direct `pkill` of the broker by cwd, and assert the broker is actually gone**. `baldart doctor` gains a **CLI↔framework version-skew check** (warns when the installed CLI is older than the framework, so new `npx baldart` subcommands can't silently fail). The earlier `$MAIN`-non-persistence hypothesis was **refuted** by the post-mortem's adversarial verification — the run passed the correct absolute `--cwd`.
+- **Fix-pass coder could edit the live MAIN repo (worktree-isolation gap)** — `coder.md` + `completeness.md`. The reactive AC-fix-pass spawn had no canonical worktree-isolation clause (it lived only in `implement.md`'s per-card brief), so an improvised thinner brief dropped it and a fix-coder Edited `<main>/src/lib/i18n/*.ts` on the MAIN repo, then reverted + re-applied (~3M wasted; the `tsc 2353` it triggered was a stale artifact, not a real defect). Now: `coder.md` STEP 0 carries an **intrinsic per-Edit path guard** (every Edit path must be worktree-rooted; `cd` is not enough; assert `.worktrees/` before editing shared/locale files) — applies to every spawn even when the brief omits it — and the fix-pass spawn brief must carry the verbatim isolation clause.
+- **i18n locale-parity gate ↔ coder "do-not-translate" contradiction** — `implement.md` / `coder.md` / `i18n-protocol.md` / `prd-card-writer.md`. The `coder` writes the source locale only (by design), but a project's own locale-parity test (a `test`/`build` gate) fails on a source-only commit → `/new` spawned `i18n-translator` reactively (~2M round-trip). Resolved: a **planned per-card `i18n-translator` fill pass** runs after the coder and before the parity gate (when `has_i18n` + new source keys), a parity failure is explicitly an `i18n-translator` task (never a coder retry), and the ownership docs (coder STEP 9.6, the i18n cascade, the P3 DoD line) are reconciled so the coder stays source-only with no contradiction.
+
+### Changed
+
+- **`new-session-audit.mjs` detector false-positives fixed (audit tooling).** `B1_mw_delegation` now inspects the actual `Skill` tool-call inputs (not the raw transcript, which quotes `new:new`/`__phase6_merge__` as the merge-cleanup.md "don't do this" text → a false FAIL even when the `/mw` call was correct); `B3_nul_grep` matches only genuine output phrases (`Binary file … matches`, `graphify-out`), not the v4.62.0 guidance text; in-context-merge detection is scoped to Bash commands; and command/mode detection now selects the actual `/new` line (not a later `/model`).
+- **Tracker-write cadence coarsened (O2/M3).** The v4.62.0 "lone tracker-Edit = violation" prose did not change behavior (a measured run still paid 38 standalone tracker-Edit turns ≈13.6M / 9%), so `SKILL.md` § Update rules now mandates tracker writes only at **card-state-changing boundaries**, always co-emitted with that action — recovery reconstructs the phase from commits + `phase_module_loaded` + backlog statuses, so per-phase writes are not needed.
+- **markdownlint debt prevented at `/prd` authoring (L1/L2)** — `prd-writing-phase.md` gains a markdown-hygiene rule: escape a literal `|` in a prose/table cell (`\|` or a code span — the `isManagerOf||isOwner` incident), honor MD058, and run `markdownlint` on generated docs when configured, rather than shipping debt for `/new`'s doc-review to catch.
+
+### Deferred (documented)
+
+- **Codex sentinel-JSON prompt tax (~270k/batch)** — `new-card-review.js` already tolerates Codex's prose output (it fetches both the sentinel JSON and the prose tail), the gain is ~0.1%, and the Codex relay is a delicate, much-iterated subsystem; not worth a regression risk in this sweep.
+
 ## [4.62.0] - 2026-06-22
 
 **Token-economy + reliability hardening for `/new` and `/prd`, distilled from a real `/new FEAT-0041 -full -auto` run that billed ~364M tokens (~95% cache_read).** A deep multi-agent post-mortem (with adversarial verification that refuted several plausible-but-wrong hypotheses — e.g. the workflow-`<result>`-payload-bloat theory was false by ~430×) traced the cost to a small set of root causes: in-context work that should have been off-context (a hallucinated `/mw` delegation and a killed-final-review recovery, ~36M combined), friction multipliers (a NUL-byte/GNU-grep trap ~8–12M, ~28 lone tracker-Edit turns ~11M), and `/prd` design gaps that pushed work downstream into `/new`'s expensive orchestrator context. Plus a proactive Codex-broker teardown so terminated reviews stop leaking MCP processes.

package/VERSION

@@ -1 +1 @@
-4.62.0
+4.63.0

package/framework/.claude/agents/coder.md

@@ -24,6 +24,7 @@ Violating this rule has caused repeated user frustration. Treat it as a blocking
 
 ## Before Starting
 0. You were spawned by the orchestrator **already on the correct branch / worktree**. The heavy/light decision (worktree or not) was taken before your spawn — see `AGENTS.md § Post-Approval Complexity Gate`. Do not create or switch branches/worktrees. Safety check: at startup run `git rev-parse --show-toplevel` and `git branch --show-current`. If you are inside the main repo but on a branch different from the project's trunk branch (`git.trunk_branch` in `baldart.config.yml`, autodetected default), or the orchestrator asks you to work on a new branch, STOP and report the error: work that requires a new branch must happen inside a worktree (typically `.worktrees/*`), not on the main repo. Do not proceed until you are given a correct worktree path.
+   - **WORKTREE ISOLATION — per-Edit path guard (HARD, intrinsic — applies to EVERY spawn, even when the task brief omits it).** Capture your worktree root at startup: `WT="$(git rev-parse --show-toplevel)"`. **Every** path you `Edit`/`Write`/`create` MUST be UNDER `$WT`. `cd`-ing into the worktree is NOT enough — an **absolute** path (or a `../`) that lands in the main repo (`<main>/…`, no `.worktrees/` segment) is checked out live by other sessions and silently pollutes it. Before editing a path, assert it is worktree-rooted; this is non-negotiable for **shared / generated / locale files** (`i18n`/locale `*.ts`, `data.ts`, design-system files) where a main-repo write is most damaging and hardest to spot. If a brief gives you a bare relative path, resolve it against `$WT`, never the process cwd. (FEAT-0042 incident: a fix-pass coder Edited `<main>/src/lib/i18n/{en,fr,es,de}.ts` on the MAIN repo, then had to `git checkout --` + re-apply in the worktree — wasted ~3M tokens and risked main-repo corruption.)
 1. Read `AGENTS.md`, `agents/index.md`, and `.claude/agents/REGISTRY.md`.
 2. Verify a backlog card exists for this work.
 3. Update the card to `IN_PROGRESS`.
@@ -62,7 +63,7 @@ Load context in this exact order before touching any file:
     2. Add the new key to the source-language native locale file (the `source` value).
     3. Add a **stub entry** to the registry (`${paths.i18n_registry}`): `source`, a **hyper-brief `context`** (what the label is for / where it appears — one line), and `domain` (the feature area). Set `char_limit`/`icu` when relevant. The QUALITY of `context` is curated by `doc-reviewer` — your job is to never leave the entry missing.
     4. Follow the naming convention (`namespace.domain.key`, semantic not literal, `global.*` for genuinely reused strings) unless an overlay overrides it.
-    5. Do NOT translate into other languages (that is `i18n-translator` / the `/i18n` skill) and do NOT curate other keys (that is `doc-reviewer`). Skipping this step when the feature is on is a protocol violation: a hardcoded user-facing string, or a key referenced in `t()` with no registry entry (`I18N_REGISTRY_DRIFT`), fails review.
+    5. Do NOT translate into other languages (that is `i18n-translator` / the `/i18n` skill) and do NOT curate other keys (that is `doc-reviewer`). Skipping this step when the feature is on is a protocol violation: a hardcoded user-facing string, or a key referenced in `t()` with no registry entry (`I18N_REGISTRY_DRIFT`), fails review. **You source-only by design — even if the project has a locale-PARITY test that fails on your source-only commit, do NOT add the other locales yourself: the `/new` pipeline runs a planned `i18n-translator` fill pass after you (and before the parity gate) to satisfy it (`implement.md` Phase 2 step 9; `i18n-protocol.md` cascade). Adding translations yourself is the violation, not the missing locales.**
 
 ## Conditional Requirements — Binary-Outcome Items (MUST)
 

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

@@ -435,10 +435,12 @@ Every card MUST include ALL fields from the template:
 - `acceptance_criteria` (testable `[ ] [AC-N]` items)
 - `definition_of_done` (checklist including doc invariants). **When `features.has_i18n: true`** AND the
   card introduces user-facing strings, the DoD MUST carry an i18n-completeness line — NOT merely "strings
-  via `t()` + registered", but: *"new keys authored in the source locale + the i18n context registry, AND
-  translated to ALL maintained target languages (via `i18n-translator`); the i18n parity / no-placeholder
-  gate passes."* Otherwise the coder ships only the source locale and `/new`'s per-card review reactively
-  spawns `i18n-translator` — a ~2M-token round-trip the DoD should have made author-time-left. Cross-ref
+  via `t()` + registered", but: *"new keys authored in the source locale + the i18n context registry (by
+  the `coder`), then filled to ALL maintained target languages by the `/new` pipeline's planned
+  `i18n-translator` pass; the i18n parity / no-placeholder gate passes."* This is an OUTCOME the card
+  commits to, owned by the pipeline (`implement.md` Phase 2 step 9), **not** a coder-translates instruction
+  — the coder stays source-only (`coder.md` STEP 9.6). Stating it makes the translation pass a planned
+  step instead of a reactive ~2M-token round-trip after a parity-gate failure. Cross-ref
   `framework/agents/i18n-protocol.md`.
 - `depends_on` / `blocks` (card IDs)
 - `estimated_complexity`

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

@@ -167,7 +167,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 ### Update rules
 
 - **Before starting a card**: move it to `## Current Card` with phase info, and record `phase_module_loaded: <modulo>` as you Read each phase module (per § "Routing" HARD RULE) so context recovery can re-load it.
-- **After each phase**: update the current card's phase status in the tracker.
+- **At card-state-changing boundaries only** (NOT after every sub-step): update the tracker's phase status when something recovery-relevant changes — a commit, a gate verdict, a blocker, a phase-module load. **Always co-emit the `Edit` with that action's tool call** (never a standalone status-only turn — § "Context economy" makes a lone tracker-`Edit` turn a violation). A measured run still paid 38 standalone tracker-Edit turns (~13.6M / ~9%) because "after each phase" was read as "emit a status turn per phase" — so the cadence is deliberately coarsened here: between two real actions there is nothing to write. Fine-grained phase recovery does not depend on per-phase writes — § "Context recovery protocol" reconstructs the current phase from the last commit + `phase_module_loaded` + backlog statuses.
 - **After completing a card**: move it from `Current Card` to `## Completed Cards` with:
   - Commit hash
   - One-line summary of what was implemented
@@ -410,7 +410,11 @@ an unrecoverable HALT, or resuming a run whose final-review workflow was KILLED
 § "workflow-killed recovery") and then deciding to stop — the batch's `codex app-server` broker (and its
 Playwright/… MCP children) is still alive. Before exiting, run it once (idempotent, cwd-scoped, NON-blocking):
 ```bash
-npx baldart teardown-codex-broker --cwd "$MAIN/<relative worktree Path from tracker ## Worktree>" 2>/dev/null || true
+WT="$MAIN/<relative worktree Path from tracker ## Worktree>"
+TD="$(npx baldart teardown-codex-broker --cwd "$WT" 2>&1)"
+printf '%s' "$TD" | grep -qi "unknown command" \
+  && { echo "AUTO: codex-teardown CLI unavailable — run npm i -g baldart@latest; killing broker by cwd"; pkill -f "app-server-broker\.mjs.*--cwd $WT" 2>/dev/null || true; } \
+  || printf '%s\n' "$TD"
 ```
 This NEVER touches a broker for another worktree or the user's interactive session (different cwd). If the
 orchestrator is hard-killed and never resumed, the `baldart doctor` reaper is the final safety net.

package/framework/.claude/skills/new/references/completeness.md

@@ -256,7 +256,7 @@ This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` a
    For each `deferred` row whose `User-approved?` is `pending`, invoke `AskUserQuestion` with:
    - Question: `"AC-<N> of <CARD-ID> non implementata. Testo verbatim: '<AC text>'. Motivazione dell'implementer: '<reason or 'nessuna — silent skip'>'. Come procedo?"`
    - Options (max 4):
-     1. **"Implementa adesso"** — spawn a targeted fix `coder` agent scoped to this card's MAY EDIT files (from `## File Ownership Map`) with the instruction "Implement ONLY AC-<N>: '<AC text>'. Do not refactor or expand scope." Re-run Phase 2.5 verification on the resulting diff — **including the mandatory sub-steps 5b (API contract), 5c (alias-mutation), 5d (caller-pattern test)** if the fix touched a route, an exported helper, or a call site (a single-AC fix can still introduce these). **Hard cap: 2 attempts on the same AC.** On the 2nd failure, do NOT re-offer "Implementa adesso" — re-invoke `AskUserQuestion` with only options 2/3/4 (approve deferral / follow-up card / stop), so the loop cannot recur unbounded.
+     1. **"Implementa adesso"** — spawn a targeted fix `coder` agent scoped to this card's MAY EDIT files (from `## File Ownership Map`) with the instruction "Implement ONLY AC-<N>: '<AC text>'. Do not refactor or expand scope." **The brief MUST carry the verbatim WORKTREE ISOLATION clause** (the same one the per-card brief uses — `implement.md` § FORBIDDEN: "every path you Edit/Write/create MUST be UNDER the worktree root `<ABSOLUTE_WORKTREE_PATH>`; `cd` is not enough; an absolute main-repo path bypasses it"). Do NOT improvise a thinner fix-pass brief that drops it — a reactive fix-coder with a weak brief is exactly where the FEAT-0042 main-repo i18n write happened (`coder.md` STEP 0's per-Edit path guard is the intrinsic backstop, but the brief must still carry it). Re-run Phase 2.5 verification on the resulting diff — **including the mandatory sub-steps 5b (API contract), 5c (alias-mutation), 5d (caller-pattern test)** if the fix touched a route, an exported helper, or a call site (a single-AC fix can still introduce these). **Hard cap: 2 attempts on the same AC.** On the 2nd failure, do NOT re-offer "Implementa adesso" — re-invoke `AskUserQuestion` with only options 2/3/4 (approve deferral / follow-up card / stop), so the loop cannot recur unbounded.
      2. **"Approva il deferral"** — record `[USER-APPROVED DEFERRAL] <today>: <user-supplied reason>` on its own line in the card's `implementation_notes`. Mark the row `User-approved? yes`.
      3. **"Sposta su follow-up card"** — create the follow-up card by **delegating to the `prd-card-writer` agent in Standalone Single-Card Mode** (NOT a hand-written stub — backlog cards are owned by `prd-card-writer`, same discipline as `new2`/`new2-resolve`). Brief it: `MODE: standalone`, write `${paths.backlog_dir}/<CARD-ID>-followup-AC<N>.yml` with `status: TODO`, derived from the deferred AC — a non-empty `requirements` (≥1, derived from the AC), `acceptance_criteria` = the verbatim AC text (≥1), `files_likely_touched` (≥1, carried from the parent card's ownership map for this AC), `owner_agent` routed to the AC's domain, and `review_profile` per Rule C — i.e. the full STANDALONE baseline of `framework/agents/card-schema.md`. If `prd-card-writer` is unavailable (total outage), fall back to a minimal valid stub carrying at least the step-1b HALT fields (`requirements`/`acceptance_criteria`/`files_likely_touched`/`scope`); the consumer back-fill (step 1b-ii) then fills `review_profile`/`owner_agent` on first ingestion. Mark the row `User-approved? yes (follow-up: <new-card-id>)`. Do NOT proceed to Phase 2.55 until the follow-up file exists on disk and passes the step-1b field check.
      4. **"Ferma il batch"** — halt the orchestrator, leave the worktree intact, log the reason in `## Issues & Flags`. Do NOT commit.

package/framework/.claude/skills/new/references/implement.md

@@ -373,6 +373,7 @@
    ```
    The `echo "<gate>:$?"` lines surface only the **exit code** inline — the full log stays on disk. When `stack.language` does NOT include `typescript`, skip the `tsc` line (no equivalent gate). Capturing to `/tmp/*-<CARD-ID>.txt` guarantees the failing output is available for step 9. On a non-zero exit, read a **bounded** extract only (`tail -n 30 /tmp/<gate>-<CARD-ID>.txt`), never the whole log — do NOT run the gates without redirect-to-file capture.
 9. **If any check fails**: categorize the error (`lint | TypeScript | test | build | i18n`), log it in the tracker as `retry-cause: <category>`. An `i18n` failure means a hardcoded user-facing string — the fix is to externalize it via `t()` + register the key (coder STEP 9), never to weaken the gate. Because the gate is **diff-scoped to this card's changed files**, an `i18n` failure is unambiguously a string **this card** introduced — it is never pre-existing baseline debt in an untouched file (so do NOT spend a retry triaging "is this mine?"; it is). The Final review re-runs the gate over the whole batch diff as the merge backstop.
+   - **i18n locale-PARITY ≠ anti-hardcoded (do NOT retry the coder on it).** The `i18n` category above is the *anti-hardcoded* gate. A separate **locale-parity** failure — the project's OWN parity test/build complaining that a new key exists in the source locale but not in the others — surfaces under `test`/`build`, and is **NOT a `coder` retry**: the `coder` writes the source locale only **by design** (`coder.md` STEP 9.6), so retrying it just loops. Route it to **`i18n-translator`** (fills the missing target locales context-aware from the registry), then re-run the gate. **Proactively — to avoid the fail-then-fix round-trip (a measured ~2M tokens, FEAT-0042): when `features.has_i18n` AND this card's diff added new source-locale keys, spawn the `i18n-translator` fill pass right after the coder commits and BEFORE these gates**, so parity holds first-try. This is the planned per-card i18n cascade step (`agents/i18n-protocol.md`); the coder still never translates.
    **Code-recovery check (MUST do before rewriting)**: before spawning a fix agent or rewriting code, check whether lint-staged or a pre-commit hook removed code that is actually needed (e.g. a field "unused" at commit time but consumed by later code). Inspect the captured diff and `git diff`/`git log -p` for the worktree branch and restore the needed code by an explicit file write. **Do NOT `git stash pop` inside the worktree** — `refs/stash` is globally shared across worktrees (`$GIT_COMMON_DIR`), so a stash created or popped in a worktree can corrupt another worktree's state (see Phase 4 WORKTREE COMMIT RULE). If you need to set work aside in a worktree, make a clearly-labelled WIP commit and record its hash in the tracker for later squash, never a stash.
    When spawning a fix agent: scope it exclusively to this card's Edit-allowed files (from `## File Ownership Map`) — it MUST NOT touch files owned by other cards. Pass the fix agent: the **path** to the captured gate log (`/tmp/<gate>-<CARD-ID>.txt` — it Reads the log itself; do NOT inline-paste the full log into its prompt), the error category, and the explicit list of files it may edit. Do NOT ask the user — just fix and re-run. Fix the code, not the tests (unless the test itself is wrong). Repeat up to **3 times**. **Stuck-loop guard**: compare the failing error's fingerprint (file:line + message) between retries; if the SAME error reproduces on 2 consecutive retries, the fix is not converging (often a constraint outside the card's ownership map) — stop early, log `[STUCK-LOOP] <error>` in `## Issues & Flags`, and escalate to the user rather than burning the 3rd retry on an identical failure.
 10. If still failing after 3 retries (or on a stuck loop), log the failure in `## Issues & Flags` and ask the user before continuing.

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -203,22 +203,38 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
       **even though `/mw` already removed the worktree directory** (the broker is matched by its `--cwd`
       token / state-hash, both of which survive the dir removal):
       ```bash
-      WORKTREE="$MAIN/<relative Path from tracker ## Worktree>"   # absolute worktree path
-      npx baldart teardown-codex-broker --cwd "$WORKTREE" 2>/dev/null || true
+      WORKTREE="$MAIN/<relative Path from tracker ## Worktree>"   # absolute path — resolve $MAIN in THIS shell
+      # Capture stderr — do NOT mask with 2>/dev/null (that silently hid a real leak: a consumer whose
+      # installed CLI predates the subcommand got `unknown command`, swallowed, and the broker survived).
+      TD_OUT="$(npx baldart teardown-codex-broker --cwd "$WORKTREE" 2>&1)"
+      if printf '%s' "$TD_OUT" | grep -qi "unknown command"; then
+        # CLI/framework version skew: the prose ships via the git subtree (current), but `npx baldart`
+        # resolves the separately-installed CLI, which may be older and lack this subcommand. Don't leak
+        # silently — warn + kill the broker directly by cwd so its MCP children orphan to init and the
+        # reap-orphans line below sweeps them.
+        echo "AUTO: codex-teardown CLI unavailable — installed baldart predates v4.62.0; run \`npm i -g baldart@latest\`. Falling back to a direct broker kill."
+        pkill -f "app-server-broker\.mjs.*--cwd $WORKTREE" 2>/dev/null || true
+      else
+        printf '%s\n' "$TD_OUT"   # one-line summary (method / killed N) for the log
+      fi
       ```
       This is **scoped strictly by cwd** — it ends ONLY this worktree's broker (graceful plugin shutdown
       when the broker.json is present, else a signal to the cwd-matched broker subtree). It NEVER touches
       a broker serving another worktree or the user's interactive Codex session on the main repo (a
       different cwd). Do NOT run this per-card — the broker is shared and warm across the batch; ending it
       mid-batch would force a cold re-spawn for the next card.
-   2. **Then the cumulative orphan sweep** (second line) — mop up any MCP server already orphaned to init
-      (ppid 1) by an earlier broker death this session:
+   2. **Then the cumulative orphan sweep + assert** (second line) — mop up any MCP server orphaned to init
+      (ppid 1), then VERIFY this worktree's broker is actually gone (so a skewed CLI / partial kill is
+      surfaced, not silently tolerated):
       ```bash
       npx baldart reap-orphans 2>/dev/null || true
+      ps -eo command | grep -q "app-server-broker\.mjs.*--cwd $WORKTREE" \
+        && echo "WARN: a Codex broker for $WORKTREE is STILL alive after teardown — update baldart (npm i -g baldart@latest) and/or re-run reap-orphans." || true
       ```
       `reap-orphans` reaps ONLY orphaned MCP servers (ppid 1 ⇒ their broker is already dead ⇒ stdio is
-      broken ⇒ dead weight); it NEVER kills a live broker.
-   Never gate the close on either — any error or a "nothing to do" result is fine; capture each one-line
+      broken ⇒ dead weight); it NEVER kills a live broker. The assert is the safety net for the skew bug
+      (FEAT-0042: 5 brokers survived because `teardown-codex-broker` was masked as a no-op on an old CLI).
+   Never gate the close on these — any error or a "nothing to do" result is fine; capture each one-line
    summary for the log.
 
 6. **Log and exit**:

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

@@ -326,7 +326,13 @@ returns when the batch is done. It returns:
    # 1. Proactive, cwd-scoped teardown FIRST — end the broker bound to THIS batch's worktree.
    #    `worktreePath` is the workflow return's worktreePath (preflight); the broker matches by --cwd /
    #    state-hash, so this works even though the workflow already merged + removed the worktree dir.
-   npx baldart teardown-codex-broker --cwd "<worktreePath from the workflow result>" 2>/dev/null || true
+   #    Capture stderr (NOT 2>/dev/null) — a CLI older than the framework lacks this subcommand and would
+   #    silently no-op (the FEAT-0042 leak); detect it, warn, and kill the broker by cwd as fallback.
+   WT="<worktreePath from the workflow result>"
+   TD="$(npx baldart teardown-codex-broker --cwd "$WT" 2>&1)"
+   printf '%s' "$TD" | grep -qi "unknown command" \
+     && { echo "AUTO: codex-teardown CLI unavailable — run npm i -g baldart@latest; killing broker by cwd"; pkill -f "app-server-broker\.mjs.*--cwd $WT" 2>/dev/null || true; } \
+     || printf '%s\n' "$TD"
    # 2. Then the cumulative orphan sweep (second line) — mop up any MCP already orphaned to init.
    npx baldart reap-orphans 2>/dev/null || true
    ```

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

@@ -152,6 +152,13 @@ Before presenting the PRD:
 - Verify canonical sources resolve through ssot-registry or valid backlog links.
 - Flag any `REGISTRY_GAP` (feature not yet in ssot-registry).
 - Remove temp/local/absolute paths from canonical sections.
+- **Markdown hygiene (prevents the markdownlint debt that surfaces downstream in `/new`).** A literal
+  `|` inside prose or a table CELL is parsed as a column delimiter and breaks the table / trips
+  markdownlint (FEAT-0043: `isManagerOf||isOwner` in a cell). Escape any literal pipe in a cell as `\|`,
+  or wrap the expression in an inline code span (`` `isManagerOf || isOwner` ``). Also: a table needs a
+  delimiter row and a blank line before/after (MD058). If a `markdownlint` config is present in the repo,
+  run it on the generated docs before commit and fix any finding — do not ship markdown debt for `/new`'s
+  doc-review to catch later.
 
 ## Step 4.5 — API Performance Gate
 

package/framework/agents/i18n-protocol.md

@@ -135,6 +135,15 @@ Three enforcement layers (mirrors the design-system discipline): **per-task**
 context/orphans on new keys) → **weekly** (`i18n-align` routine audits + aligns
 target languages). The on-demand `/i18n audit` covers off-cadence checks.
 
+**Per-card translation fill in `/new` (resolves the source-only ↔ parity-gate tension).** The
+`coder` writes the SOURCE locale only (it never translates). But a project may run its OWN
+**locale-parity test** as part of its `test`/`build` gate, which fails on a source-only commit. These
+are not in conflict: in a `/new` run, when `features.has_i18n` AND a card's diff adds new source-locale
+keys, the orchestrator runs a **planned `i18n-translator` fill pass after the coder and before the
+parity gate** (`new/references/implement.md` Phase 2 step 9) — so parity holds first-try, the coder
+still never translates, and the weekly `i18n-align` remains the steady-state aligner. A parity failure
+is therefore an `i18n-translator` task, NEVER a `coder` retry.
+
 ## Ownership (strict specialization)
 
 - **`coder`** — externalizes strings + writes the registry STUB (`source`+`context`+`domain`).

package/package.json

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

package/src/commands/doctor.js

@@ -39,6 +39,7 @@ const ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
+const { cmpVersions } = require('../utils/semver-lite');
 
 const FRAMEWORK_DIR = '.framework';
 const CONFIG_FILE = 'baldart.config.yml';
@@ -238,6 +239,20 @@ async function detectState(cwd, opts = {}) {
       };
     }
 
+    // CLI ↔ framework version skew (since v4.63.0). The framework PROSE ships via the git
+    // subtree (tracks repo HEAD, always current), but `npx baldart` resolves the SEPARATELY-
+    // installed CLI. When that CLI is OLDER than the framework, any prose calling a NEW
+    // `npx baldart` subcommand (e.g. `teardown-codex-broker`, added v4.62.0) silently fails as
+    // `unknown command` — a real, invisible regression (FEAT-0042: leaked Codex brokers/MCP
+    // every run). Surface it so the user updates the global CLI.
+    state.cliFrameworkSkew = null;
+    try {
+      if (state.frameworkVersion && cliPackageJson.version &&
+          cmpVersions(cliPackageJson.version, state.frameworkVersion) < 0) {
+        state.cliFrameworkSkew = { cli: cliPackageJson.version, framework: state.frameworkVersion };
+      }
+    } catch (_) { /* version parse failure → no skew claim */ }
+
     state.remote = await describeRemote(git, ledger.framework_repo || State.DEFAULT_REPO, !!opts.offline);
     state.commitsAhead = await commitsAheadOfRemote(git, state.remote);
     state.workingTreeDirty = await localFrameworkChanges(git);
@@ -1140,6 +1155,14 @@ function renderDiagnostic(state) {
     state.cliUpdate ? 'warn' : 'ok'
   ));
 
+  if (state.cliFrameworkSkew) {
+    console.log(statusLine(
+      'CLI↔framework',
+      `CLI v${state.cliFrameworkSkew.cli} < framework v${state.cliFrameworkSkew.framework} — new \`npx baldart\` subcommands (e.g. teardown-codex-broker) silently fail. Run: npm i -g baldart@latest`,
+      'warn'
+    ));
+  }
+
   console.log(statusLine('Git repo', state.isGitRepo ? 'yes' : 'no', state.isGitRepo ? 'ok' : 'err'));
 
   if (!state.isGitRepo) return;