baldart 3.34.0 → 3.35.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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).
 
+## [3.35.1] - 2026-05-30
+
+Fixes a **HIGH-severity** bug where `baldart update --reset` could leave a consumer **committed-without-`.framework/`** (broken install, manual recovery only). The reset path wiped `.framework/`, committed the deletion, then handed off to `add()` **programmatically with no repository** — the bin-layer default (`antbald/BALDART`) only applies on the CLI path, so `repo` arrived `undefined`, crashing at `repo.startsWith(...)` ("Cannot read properties of undefined") *after* the wipe was already committed. Three layers now make this unreachable: (1) repo resolved **before** any destructive step, (2) reinstall failures roll back to the pre-reset backup tag, (3) defensive guards + legible errors. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.
+
+### Fixed — `update --reset` never leaves the consumer without `.framework/`
+
+- **[src/commands/update.js](src/commands/update.js)** (`runReset`): the upstream repo is now resolved via `State.resolveRepo()` **before** the backup tag / `rm -rf` / reset commit, then threaded **explicitly** into `add()` (was `addCmd(undefined, { yes: true })` — the root cause). The stale v3.28.1 comment claiming "undefined → use default from package.json" (which never existed in `add.js`) is corrected.
+- **[src/commands/update.js](src/commands/update.js)**: the reinstall is wrapped in a `try/catch` that, on **any** failure (undefined repo, network, ignored path, missing hooks), auto-runs `git reset --hard <backupTag>` to restore the pre-reset `.framework/` and prints an explicit recovery command. Safe because reset is gated on a clean working tree — the backup tag holds everything but the reset commit.
+- **[src/commands/add.js](src/commands/add.js)**: new `options.throwOnError` makes `add()` **re-throw** instead of `process.exit(1)` at every reachable failure point (download catch, gitignore-still-ignored, hooks-missing post-flight), so a programmatic caller can recover. CLI behavior is unchanged (flag absent → historical exit-1). Also resolves a falsy `repo` from the ledger as a last resort and fails fast **before** download with a recovery hint.
+- **[src/utils/git.js](src/utils/git.js)** (`normalizeRepoUrl`): guards a falsy/non-string `repo` with a legible `Error` ("repository non specificato …") instead of the cryptic `Cannot read properties of undefined (reading 'startsWith')`.
+
+### Changed — shared repo resolver (de-dup)
+
+- **[src/utils/state.js](src/utils/state.js)**: new exported `resolveRepo(cwd)` (cascade `state.framework_repo → DEFAULT_REPO`, never `undefined`, preserves a consumer's fork) + exported `DEFAULT_REPO` constant. `recordInstall` now uses the constant.
+- **[src/commands/version.js](src/commands/version.js)**: drops its local `REPO_DEFAULT` duplicate in favor of the shared `State.DEFAULT_REPO`.
+
+### Known follow-up (separate fix)
+
+- `--on-divergence` (v3.29.0) is rejected by an **older global CLI** with "unknown option" *before* the `npx baldart@latest` auto-relaunch can self-upgrade (commander validates options first). Tracked separately — workaround: `npm i -g baldart@latest` before using new flags.
+
+## [3.35.0] - 2026-05-30
+
+De-duplicates the review chain in `/new` and adds a **Review Profile Selector** so the per-card pre-merge gate scales its *depth* by risk instead of running the full multi-agent `/codexreview` on every card — including trivial ones. The per-card gate stays **unconditional** (it always runs); only its breadth varies, and the safety-critical Codex adversarial pass + false-positive gate run on every card regardless of profile. Copertura invariata: every line is still code-reviewed once, every doc doc-reviewed once. **No new `baldart.config.yml` keys** — the profile is computed at runtime from signals already present (the Phase 3.7 high-risk-trigger detector + the QA profile), and lean mode is an internal caller→skill file contract, so the schema-propagation rule does not apply.
+
+### Changed — `/new` review chain (de-dup, coverage-invariant)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** + **[framework/.claude/commands/codexreview.md](framework/.claude/commands/codexreview.md)**: per-card Phase 3.7 (and Team Mode D.4b) now hand `/codexreview` a lean contract file (`/tmp/codexreview-lean-<CARD-ID>.json`) so it **reuses the Phase-1 architecture baseline** (`/tmp/arch-baseline-<CARD-ID>.md`) instead of re-spawning `codebase-architect`, and **skips the duplicate `doc-reviewer`** (Phase 3 already audits the same diff). `/codexreview` gains a backward-compatible **Step -0.5 (lean-mode detection)** with consume-once semantics; standalone `/codexreview <CARD-ID>` (no contract file) behaves exactly as before.
+- **doc-reviewer lens-merge**: Phase 3's `doc-reviewer` mandate now also carries the *spec/docs-drift → bug* lens that was previously exclusive to `/codexreview` agent #4 — so dropping the duplicate loses no coverage.
+- **Final review de-dup**: single-card batches short-circuit F.1–F.4 (the lone card already passed Phase 3.7 unchanged) while still running the F.5 final build; multi-card batches scope the cross-card review to a **computed** surface (files touched by ≥2 cards ∪ `depends_on`-linked pairs), never a model-decided skip.
+- **Team Mode doc-reviewer collapse**: `doc-reviewer` went from ~3× per card (D.2 + D.4a + D.4b) to ~1× per group — D.2 attributes findings per-card, D.4a consumes them (no re-spawn), D.4b skips its copy via the lean contract.
+
+### Added — Review Profile Selector (data-gated)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: Phase 3.7 Step C selects `light` ⟺ (0 high-risk triggers AND QA profile ∈ {skip, light}), else `full`. `light` drops the breadth agents (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + Step 3.5 CoVe but ALWAYS keeps `code-reviewer` + Codex adversarial + the false-positive gate (BUG-0530 invariant preserved — `light` ≠ skip). Mirrors the existing QA Profile Selector pattern. Ships behind a **data gate**: the mapping stays hard-coded to `full` until consumer telemetry (`docs/metrics/` Fix Application Log) confirms `light`-eligible cards have not historically produced verified BLOCKER/HIGH at full depth.
+
 ## [3.34.0] - 2026-05-30
 
 Adds an **assert-active git-hooks health check** to `baldart doctor` and the `worktree-manager` verify step. A consumer had `core.hooksPath` pointing at `.git/hooks` (empty) while the repo's versioned hooks lived in `scripts/git-hooks/` — the pre-commit schema guard and pre-push were **silently inactive for days**. The existing worktree-manager verify (`git config core.hooksPath || true`) only *read* the value without asserting anything, so it never caught the drift. Same class as the LSP bug: the framework "verifies" by reading a proxy instead of asserting the real state. This moves it from read-only to assert-active. **WARN-only** — the check never mutates `core.hooksPath` (a wrong heuristic + auto-fix would be worse than the original bug); it surfaces the exact remediation command and lets the user apply it. **No new `baldart.config.yml` keys** — it's a universal, always-on, filesystem-autodetected check, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.34.0
+3.35.1

package/framework/.claude/commands/codexreview.md

@@ -27,6 +27,48 @@ Deduplicate, then:
 
 ---
 
+## Step -0.5 — Lean Mode Detection (caller-supplied contract)
+
+`/new` invokes this skill per-card as a pre-merge gate (Phase 3.7 / Team D.4b) and passes an
+out-of-band **contract file** so it can reuse work already done in earlier phases and scale review
+depth. Detection is deterministic and applies to THIS run only.
+
+For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`.
+
+- **Absent** → **full mode**. This is the default for standalone `/codexreview <CARD-ID>`
+  invocations — nothing below is skipped; behave exactly as documented in Steps 0–4.
+- **Present** → parse it:
+
+  ```json
+  {
+    "profile": "light" | "full",
+    "arch_baseline_path": "/tmp/arch-baseline-<CARD-ID>.md",
+    "diff_summary_path": "<completion-report or git-diff path>",
+    "skip_doc_reviewer": true
+  }
+  ```
+
+  Apply:
+  - `arch_baseline_path` readable → **skip Step 1** (do NOT re-spawn `codebase-architect`); load the
+    baseline from that file and ALSO attach the `diff_summary_path` contents to every review agent so
+    they see what changed against the existing-architecture map. *(A1)*
+  - `skip_doc_reviewer: true` → **omit agent #4 (`doc-reviewer`)** in Step 2. Doc concerns are covered
+    by `/new` Phase 3, which runs `doc-reviewer` (with the spec/docs-drift lens) on the same diff
+    immediately before this gate. *(A2)*
+  - `profile: "light"` → ALSO omit agent #2 (`qa-sentinel`) and agent #3 (`api-perf-cost-auditor`),
+    and **skip Step 3.5 (CoVe)**. Agent #1 (`code-reviewer`), agent #5 (**Codex adversarial**), and
+    the Step 3 false-positive gate ALWAYS run. *(B1)*
+  - `profile: "full"` (or missing) → full agent set, minus #4 if `skip_doc_reviewer`.
+
+**Invariant**: lean mode NEVER suppresses the run itself — at minimum `code-reviewer` + Codex
+adversarial + Step 3 FP-gate execute on every card. If the contract file is malformed/unreadable,
+fall back to **full mode** and note it. **Consume-once**: delete `/tmp/codexreview-lean-<CARD-ID>.json`
+immediately after parsing it, so a later standalone `/codexreview <CARD-ID>` on the same card never
+inherits a stale lean contract from a prior `/new` run. Record the resolved mode in the Step 4 report
+`Method` section, e.g. `lean: profile=light, architect=reused, doc-reviewer=skipped(Phase 3), cove=skipped`.
+
+---
+
 ## Step 0 — Resolve Scope
 
 For each provided card ID:
@@ -49,6 +91,11 @@ If a card cannot be found, mark it as `UNKNOWN` and ask the user before continui
 
 ## Step 1 — Architecture Baseline (MUST)
 
+> **Lean skip (Step -0.5)**: if a contract file resolved `arch_baseline_path`, SKIP this step
+> entirely — read the baseline from that file instead of invoking `codebase-architect`, carry it
+> (plus the attached `diff_summary_path`) as the mandatory context for downstream agents, and go to
+> Step 2. In full mode (no contract file), run this step as written.
+
 Before running any review agents, invoke `codebase-architect` (via Task tool) for each card scope to map:
 
 - Existing architecture and critical patterns
@@ -96,6 +143,10 @@ Launch these agents in parallel for each card:
 4. `doc-reviewer` — spec/docs drift that can cause incorrect behavior
 5. **Codex (GPT-5.5)** — adversarial review via `codex-companion.mjs`
 
+> **Lean agent set (Step -0.5)**: when a contract file is active, launch only the agents the resolved
+> mode permits — `skip_doc_reviewer` omits #4; `profile: light` additionally omits #2 and #3. Agents
+> #1 (`code-reviewer`) and #5 (Codex) ALWAYS launch. In full mode (no contract file), launch all five.
+
 **Codex invocation rules (agent #5):**
 
 Codex is NOT invoked via the `Agent` tool (the `codex:codex-rescue` subagent_type is not registered in the harness). Instead, invoke it directly with Bash:
@@ -152,6 +203,10 @@ Only `VERIFIED` findings can be reported as bugs.
 
 ## Step 3.5 — Cross-Agent CoVe Pass (MUST — anti-echo, anti-ripple)
 
+> **Lean skip (Step -0.5)**: when the contract file resolved `profile: light`, SKIP this CoVe pass.
+> Light profile is only ever selected for 0-trigger + QA-light cards (small, non-refactor diffs)
+> where the ripple surface is minimal. Full profile (and all standalone runs) execute it as written.
+
 After Step 3 false-positive gating, the orchestrator runs ONE additional Chain-of-Verification pass on the consolidated VERIFIED pool. This catches two failure modes the per-agent CoVe doesn't:
 
 1. **Cross-agent echo allucination**: 2+ agents independently produce the same hallucinated finding (e.g. wrong file path that "looks plausible") and reinforce each other through Step 3 cross-validation.
@@ -183,7 +238,7 @@ Write one consolidated report per run to `/tmp/codexreview-report-<TIMESTAMP>.md
 Report structure:
 
 1. `Scope Reviewed`
-2. `Method` (agents used + validation flow; note whether Codex was available or `CODEX_UNAVAILABLE`; note whether Step 3.5 CoVe ran fully or hit budget cap)
+2. `Method` (agents used + validation flow; note whether Codex was available or `CODEX_UNAVAILABLE`; note whether Step 3.5 CoVe ran fully or hit budget cap; in lean mode, record the resolved contract — `lean: profile=<light|full>, architect=<reused|spawned>, doc-reviewer=<skipped(Phase 3)|run>, cove=<skipped|run>`)
 3. `Verified Bugs` (ordered: BLOCKER -> HIGH -> MEDIUM -> LOW; tag findings with `[codex]` if originating from Codex; tag `[ripple-expanded]` if Step 3.5 added `ripple_files`; tag `[cove_unverified]` if Step 3.5 budget exhausted before reaching it)
 4. `Needs Manual Confirmation`
 5. `False Positives Discarded` (with reason)

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

@@ -374,6 +374,7 @@ For each card, execute these phases in order:
    - If **FIXES NEEDED**: apply corrections to the tracker notes for this card (do NOT modify the backlog YAML). Carry the corrected requirements into the Phase 2 briefing.
    - If **PASS**: proceed.
 5. **Update tracker**: phase = "1-claim DONE", log codebase-architect key findings (1-2 lines) and plan-auditor result (PASS or corrections applied).
+5b. **Persist the architecture baseline for reuse (since v3.35.0)** — write the FULL codebase-architect findings (file paths, type signatures, patterns, high-risk paths) to `/tmp/arch-baseline-<CARD-ID>.md`. Phase 3.7's per-card `/codexreview` reuses this file instead of re-spawning `codebase-architect` (lean mode), so capture enough detail to ground a reviewer — not just the 1-2 tracker lines.
 
 ### Phase 2 — Implement (self-healing, up to 3 retries)
 6. **Update tracker**: phase = "2-implement".
@@ -1151,6 +1152,12 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     - Check each invariant in the checklist above and flag any that are unmet
     - Flag any doc in "Related docs to check" that should be stale but isn't marked yet
     - Run your standard doc audit on all changed files
+    - **Spec/docs-drift → bug lens (MANDATORY since v3.35.0)**: flag any place where the
+      implementation contradicts a documented contract/spec in a way that can cause incorrect
+      behavior (response shape diverging from `api/<module>.md`, field semantics diverging from
+      `data-model.md`, etc.). This lens was previously exclusive to `/codexreview` agent #4; the
+      per-card Phase 3.7 gate now skips that duplicate (lean mode), so THIS pass MUST carry it.
+      Report as a doc finding with the conflicting code location + the doc it violates.
     ```
     Doc-reviewer collects findings WITHOUT making changes.
 14. **Obsidian Corpus Dispatch**: Parse section H from doc-reviewer findings. If `Trigger: YES`, dispatch the `obsidian-sync` agent (`.claude/agents/obsidian-sync.md`) with the listed paths after all fixes are applied (step 16). If `Trigger: NO`, skip. This is non-blocking -- do not wait for obsidian-sync to complete before proceeding.
@@ -1265,15 +1272,46 @@ Log the detector output in the tracker for traceability. **This step never short
 
 #### Step C — Invoke per-card `/codexreview` (ALWAYS)
 
-For EVERY card (no conditional skip):
+For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
+
+0. **Select the review profile (deterministic — Review Profile Selector, since v3.35.0)** from
+   signals ALREADY computed (no new thresholds):
+   - **`light`** ⟺ Step A matched **zero** high-risk triggers **AND** this card's QA profile
+     (Phase 3.5) ∈ {`skip`, `light`}.
+   - **`full`** ⟺ otherwise (any trigger matched, OR QA ∈ {`balanced`, `deep`}).
+
+   `light` is **NOT** a skip: `/codexreview` still runs `code-reviewer` + Codex adversarial + the
+   Step 3 false-positive gate. It drops only the breadth agents (qa-sentinel, api-perf-cost-auditor,
+   doc-reviewer) and Step 3.5 CoVe — exactly the passes that yield ~nothing on a 0-trigger, QA-light
+   diff. The BUG-0530 invariant ("never miss a blocker on a low-risk path") holds because the Codex
+   adversarial pass — the one that catches those — always runs.
+   **DATA GATE (BLOCKING for `light`)**: until the consumer's telemetry (`docs/metrics/` Fix
+   Application Log) confirms that `light`-eligible cards have NOT historically produced verified
+   BLOCKER/HIGH at FULL depth, hard-code `profile = full` here. Flip to the selector only after the
+   data passes (no config key — change the line).
+
+   Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
+   ```bash
+   cd <worktree-path>
+   git diff develop...HEAD -- <card files from ownership map> > /tmp/diff-<CARD-ID>.txt 2>/dev/null \
+     || git diff HEAD~1 > /tmp/diff-<CARD-ID>.txt
+   ```
+   Write `/tmp/codexreview-lean-<CARD-ID>.json`:
+   ```json
+   { "profile": "light|full", "arch_baseline_path": "/tmp/arch-baseline-<CARD-ID>.md",
+     "diff_summary_path": "/tmp/diff-<CARD-ID>.txt", "skip_doc_reviewer": true }
+   ```
+   `skip_doc_reviewer` is ALWAYS true: Phase 3 already ran `doc-reviewer` on this diff (with the
+   spec/docs-drift→bug lens since v3.35.0), so `/codexreview` agent #4 would be a duplicate.
 
 1. **Log gate invocation** in the tracker under `## Pre-Merge Codex Review`:
 
    ```
    ## Pre-Merge Codex Review
    - Triggered: unconditional (mandatory pre-merge gate)
+   - Profile: light | full — reason: <triggers=0, qa=light | trigger #N matched | qa=deep>
    - Matched high-risk triggers: <list from detector, or "none">
-   - Action: invoking /codexreview <CARD-ID> (per-card, pre-merge gate)
+   - Action: invoking /codexreview <CARD-ID> (per-card, pre-merge gate; lean contract written)
    ```
 
 2. **Invoke `/codexreview`** for the single card via the Skill tool:
@@ -1283,7 +1321,10 @@ For EVERY card (no conditional skip):
    args: <CARD-ID>
    ```
 
-   The orchestrator's `/codexreview` skill runs all 5 review agents (incl. adversarial Codex) + Step 3 false-positive gate + Step 3.5 cross-agent CoVe + Step 4 consolidated report. This is the same pipeline used post-batch in Phase 7 — here it runs per-card and BEFORE commit.
+   `/codexreview` Step -0.5 consumes `/tmp/codexreview-lean-<CARD-ID>.json`: reuses the Phase-1
+   architecture baseline (no re-spawn), drops the duplicate doc-reviewer, and for `profile: light`
+   also drops qa-sentinel + api-perf-cost-auditor + Step 3.5 CoVe. Codex adversarial + Step 3
+   FP-gate + Step 4 report ALWAYS run. (`full` = standard pipeline minus the duplicate doc-reviewer.)
 
 3. **Read the consolidated report** from `/tmp/codexreview-report-<TIMESTAMP>.md`. Extract:
    - Verified BLOCKER count
@@ -1359,6 +1400,21 @@ Never block the pipeline indefinitely — recover and continue per the rules abo
 
 Once ALL cards are committed in the worktree:
 
+> **Final-review scope gate (deterministic, since v3.35.0)** — the per-card Phase 3.7 `/codexreview`
+> gate has ALREADY reviewed every card individually before its commit. The final review exists to
+> catch what a per-card pass structurally cannot: **cross-card interactions**. Branch on batch size:
+>
+> - **Single card (N=1)**: SKIP Steps F.1–F.4 (the lone card is byte-identical to what Phase 3.7
+>   already passed — re-review adds nothing). Log:
+>   `"Final review (F.1–F.4) skipped — single card already passed /codexreview at Phase 3.7 (PASS), code unchanged since commit"`.
+>   Then jump to **Step F.5 and RUN the final build** (`npm run lint && npx tsc --noEmit && npm run build`)
+>   — that gate is NOT skipped.
+> - **Multiple cards (N>1)**: run F.1–F.5 but **scope the review to the cross-card surface only**
+>   (computed, not discretionary) — see F.1 step 4. If that surface is empty, log
+>   `"cross-card review: no shared surface (intersection=∅, depends_on=∅) — F.3 limited to integration sanity"`
+>   and run a minimal integration pass (build + type-check across the union) instead of a full
+>   per-line re-review. This is a computed scope reduction, NEVER a model-decided skip.
+
 ### Step F.1 — Resolve scope
 
 1. **Read the tracker file** to get the full picture: card IDs, files changed, commit hashes.
@@ -1368,7 +1424,11 @@ Once ALL cards are committed in the worktree:
    git diff --name-only <base-branch>...HEAD
    ```
 3. Read each card's backlog YAML to collect `acceptance_criteria`, `files_likely_touched`.
-4. Build `review_scope_files` as union of card-indicated files + git-touched files.
+4. Build `review_scope_files` as union of card-indicated files + git-touched files. **For N>1 (per
+   the Final-review scope gate above), then REDUCE `review_scope_files` to the cross-card subset**:
+   files appearing in ≥2 cards' File Ownership Map entries ∪ files of any `depends_on`-linked card
+   pair. Record both the full union and the reduced set in the tracker; downstream F.3 reviews the
+   reduced set.
 
 ### Step F.2 — Architecture baseline
 
@@ -2020,6 +2080,11 @@ 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
 
 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.
@@ -2112,7 +2177,7 @@ 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. If build fails, identify which card's changes broke it (from `git diff` per card), spawn a targeted fix-coder for those files only.
 
-2. **D.2 — Combined static review (group)** — Invoke **code-reviewer** + **doc-reviewer** IN PARALLEL (read-only, same as Phase 3) across ALL changes in the group. This is ONE combined review, not per-card — efficient and catches cross-card issues. Per-card doc-review still runs in D.4a.
+2. **D.2 — Combined static review (group)** — Invoke **code-reviewer** + **doc-reviewer** IN PARALLEL (read-only) across ALL changes in the group. ONE combined pass — catches cross-card issues. The doc-reviewer MUST **attribute every finding to a specific card** (by file → ownership map) and apply the full Phase 3 mandate INCLUDING the spec/docs-drift→bug lens (since v3.35.0), so this single pass satisfies each card's doc gate. D.4a consumes these per-card findings (no second doc-reviewer spawn).
 
 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.
 
@@ -2124,9 +2189,9 @@ After ALL agents in the group complete successfully:
 
 4. **D.4 — QA gate (group)** — Select the HIGHEST QA profile across all cards in the group (e.g., if one card is BALANCED and another is DEEP, use DEEP). Invoke **qa-sentinel** once for the group.
 
-4a. **D.4a — Phase 3 Doc Review per-card** — For EACH card in the group, invoke `doc-reviewer` scoped to that card's File Ownership Map + card YAML (mirrors Phase 3 of the sequential path). If findings exist, spawn a targeted fix-coder for that card only. This is in addition to the combined D.2 doc-reviewer pass — D.2 catches cross-card issues, D.4a verifies each card meets its own doc gate before commit.
+4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0)** — Do NOT re-spawn `doc-reviewer`. For EACH card in the group, take that card's doc findings from D.2's per-card-attributed output; if any exist, spawn a targeted fix-coder for that card only. (Previously D.4a re-ran doc-reviewer per card — a duplicate of D.2; collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so doc-review now runs once per group instead of ~3× per card.)
 
-4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per 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.
+4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per 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`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate (subject to the same DATA GATE: keep `full` until telemetry confirms).
 
 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
@@ -2178,7 +2243,7 @@ Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If
 
 ### 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. No changes needed for these phases.
+After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Team mode is always N>1, so the Final Review applies its deterministic **cross-card-only scope** (per the Final-review scope gate) — not a full per-line re-review.
 
 ---
 

package/package.json

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

package/src/commands/add.js

@@ -14,6 +14,24 @@ async function add(repo, options) {
   // rm -rf `.framework/` themselves, so `git.frameworkExists()` is false
   // here and the destructive prompt is never reached.
   const nonInteractive = options && options.yes === true;
+  // When `add` is invoked programmatically (e.g. `update --reset`) the caller
+  // wants failures to bubble up so it can roll back, instead of add()'s default
+  // `process.exit(1)` which would kill the parent before it can recover.
+  const throwOnError = options && options.throwOnError === true;
+
+  // Repo resolution safety net. The CLI entrypoint (bin/baldart.js) defaults
+  // `repo` to the upstream before calling here, but programmatic callers may
+  // pass undefined. Resolve from the consumer's ledger (preserves forks) so
+  // we never reach git.addSubtree() with an undefined repo (the crash that
+  // broke `update --reset`: "Cannot read properties of undefined").
+  if (!repo) repo = State.resolveRepo();
+  if (!repo) {
+    UI.error('No framework repository to install from.');
+    UI.info('Expected from .baldart/state.json → framework_repo. Recover with:');
+    UI.info('  npx baldart add <owner/repo> --yes');
+    if (throwOnError) throw new Error('add: repository unresolved (state.json framework_repo empty)');
+    process.exit(1);
+  }
 
   try {
     // Step 1: Verify environment
@@ -114,10 +132,16 @@ async function add(repo, options) {
           UI.error('.framework/ is STILL ignored after auto-heal — install would fail.');
           UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
           UI.info('Resolve by removing that rule, then re-run `baldart add`.');
-          process.exit(1);
+          // Deliberate abort — flag it so the local catch propagates instead of
+          // downgrading to a warning, and let the single outer catch decide
+          // throw (throwOnError) vs process.exit (CLI).
+          const e = new Error('.framework/ still ignored after auto-heal');
+          e.fatalInstall = true;
+          throw e;
         }
       }
     } catch (err) {
+      if (err && err.fatalInstall) throw err;
       UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
     }
 
@@ -139,11 +163,12 @@ async function add(repo, options) {
         '  • No internet connection',
         '  • Repository not accessible',
         `  • Invalid repository: ${repo}`,
+        '    (resolved from .baldart/state.json → framework_repo, else default)',
         '',
         'Solution:',
         '  • Check your internet connection',
-        '  • Verify repository exists',
-        '  • Try again later'
+        '  • Verify the repository exists / is reachable',
+        '  • Recover with an explicit repo: npx baldart add <owner/repo> --yes'
       ]);
       throw error;
     }
@@ -293,6 +318,13 @@ async function add(repo, options) {
           : `Hooks missing after install: ${verify.missing.join(', ')}. Install is NOT complete.`
       );
       UI.info('Run `npx baldart doctor` to repair, then re-check `npx baldart status`.');
+      if (throwOnError) {
+        throw new Error(
+          verify.malformed
+            ? 'settings.json malformed — hooks unverifiable'
+            : `hooks missing after install: ${verify.missing.join(', ')}`
+        );
+      }
       process.exit(1);
     }
 
@@ -339,6 +371,9 @@ async function add(repo, options) {
 
   } catch (error) {
     UI.error(`Installation failed: ${error.message}`);
+    // Programmatic callers (update --reset) need the failure to bubble so they
+    // can roll back; the CLI entrypoint keeps the historical exit-1 behavior.
+    if (throwOnError) throw error;
     process.exit(1);
   }
 }

package/src/commands/doctor.js

@@ -36,7 +36,6 @@ const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
 
 const FRAMEWORK_DIR = '.framework';
-const REPO_DEFAULT = 'antbald/BALDART';
 const CONFIG_FILE = 'baldart.config.yml';
 
 // ──────────────────────────────────────────────────────────────────────
@@ -214,7 +213,7 @@ async function detectState(cwd, opts = {}) {
       };
     }
 
-    state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
+    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);
 
@@ -360,7 +359,9 @@ function planActions(state) {
       autoOk: false,
       run: async () => {
         const add = require('./add');
-        await add(REPO_DEFAULT, { branch: 'main' });
+        // Fork-aware: resolve from the ledger (preserves a consumer's fork)
+        // rather than hardcoding the upstream default.
+        await add(State.resolveRepo(state.cwd), { branch: 'main' });
       },
     });
     return actions;

package/src/commands/update.js

@@ -255,6 +255,15 @@ async function runReset(git, options, autoYes) {
     }
   }
 
+  // Resolve the upstream repo BEFORE anything destructive. The reinstall hands
+  // off to add() programmatically (no bin-layer default), so an unresolved repo
+  // would surface as "Downloading from undefined" / "Cannot read properties of
+  // undefined" AFTER .framework/ was already wiped and committed. Resolving here
+  // (state.framework_repo → default, never undefined) makes that unreachable and
+  // preserves a consumer's fork.
+  const repo = State.resolveRepo();
+  UI.info(`Reinstall source: ${repo}`);
+
   // Safety gate #3: backup tag before doing anything destructive.
   const backupTag = await git.createBackupTag();
   UI.success(`Backup tag created: ${backupTag}`);
@@ -310,12 +319,42 @@ async function runReset(git, options, autoYes) {
   UI.newline();
   UI.info('Re-installing framework via `baldart add`…');
   const addCmd = require('./add');
-  // `add(repo, options)` — first arg is the repo URL (undefined → use default
-  // from package.json). Pre-v3.28.1 we incorrectly passed `{ yes: true }` as
-  // the first arg, so `options` was undefined and every interactive prompt
-  // ("Install framework?", "Configure git aliases?", …) fired despite the
-  // parent `update --reset --yes --i-know` having already established intent.
-  await addCmd(undefined, { yes: true });
+  // `add(repo, options)` — the repo MUST be threaded explicitly: the bin-layer
+  // default ('antbald/BALDART') only applies when add is invoked from the CLI,
+  // not on this programmatic path (the v3.28.1 comment claiming "undefined →
+  // default from package.json" was wrong and caused the undefined-repo crash).
+  // `throwOnError` makes add() re-throw instead of process.exit(1), so a failed
+  // reinstall lands in the catch below and we can roll back to the backup tag —
+  // the consumer is NEVER left committed-without-.framework/.
+  try {
+    await addCmd(repo, { yes: true, throwOnError: true });
+  } catch (err) {
+    UI.newline();
+    UI.error(`Reinstall failed: ${err.message}`);
+    UI.warning('Rolling back to pre-reset state…');
+    try {
+      await git.git.raw(['reset', '--hard', backupTag]);
+      // The clean-tree gate (hasCleanWorkingTree → status.isClean(), which counts
+      // untracked) guaranteed ZERO untracked files at backup-tag time, so every
+      // untracked file now is partial-install cruft created by the failed add()
+      // (symlinks, copied templates) — safe to sweep. `-d` dirs, no `-x` so
+      // gitignored paths are left untouched. Non-fatal: .framework/ is already
+      // restored by the reset above regardless.
+      try {
+        await git.git.raw(['clean', '-fd']);
+      } catch (cleanErr) {
+        UI.warning(`Could not sweep partial-install leftovers (${cleanErr.message}). .framework/ is restored; run \`git clean -fd\` to tidy.`);
+      }
+      UI.success(`Restored .framework/ from ${backupTag}. Working tree back to pre-reset state.`);
+    } catch (rollbackErr) {
+      UI.error(`Auto-rollback FAILED: ${rollbackErr.message}`);
+      UI.info(`Recover manually: git reset --hard ${backupTag}`);
+    }
+    UI.newline();
+    UI.info('Then retry, or reinstall explicitly:');
+    UI.info(`  npx baldart add ${repo} --yes`);
+    process.exit(1);
+  }
 
   // Post-restore sanity check — confirm nothing user-owned got clobbered.
   const stillPresent = {

package/src/commands/version.js

@@ -3,7 +3,6 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const UpdateNotifier = require('../utils/update-notifier');
 
-const REPO_DEFAULT = 'antbald/BALDART';
 const FRAMEWORK_DIR = '.framework';
 
 function fmtDate(iso) {
@@ -61,7 +60,7 @@ async function version(opts = {}) {
     const verbose = opts.verbose === true;
 
     // SSOT (v3.25.0+): one query, version-compare authority.
-    const repo = state.framework_repo || REPO_DEFAULT;
+    const repo = state.framework_repo || State.DEFAULT_REPO;
     let status;
     if (opts.offline === true) {
       status = {

package/src/utils/git.js

@@ -144,6 +144,17 @@ class GitUtils {
     // - "https://github.com/owner/repo" -> "https://github.com/owner/repo.git"
     // - "https://github.com/owner/repo.git" -> unchanged
 
+    // Fail loud and legible instead of "Cannot read properties of undefined
+    // (reading 'startsWith')". A falsy repo here means a caller skipped repo
+    // resolution (see State.resolveRepo) — surface that, don't crash cryptically.
+    if (!repo || typeof repo !== 'string') {
+      throw new Error(
+        `normalizeRepoUrl: repository non specificato (got ${JSON.stringify(repo)}). ` +
+        `Risolvilo via .baldart/state.json → framework_repo o passalo esplicito ` +
+        `(es. npx baldart add <owner/repo> --yes).`
+      );
+    }
+
     if (repo.startsWith('http://') || repo.startsWith('https://')) {
       return repo.endsWith('.git') ? repo : `${repo}.git`;
     }

package/src/utils/state.js

@@ -35,6 +35,13 @@ const STATE_FILE = path.join(STATE_DIR, 'state.json');
 const STATE_VERSION = 1;
 const HISTORY_LIMIT = 20;
 
+// Upstream framework repository. SSOT for the "where do we install from"
+// default — duplicated literals in version.js / doctor.js / recordInstall
+// used to drift independently. Always resolve through `resolveRepo()` so a
+// consumer's fork (recorded in state.framework_repo at install time) is
+// preserved instead of being silently overridden by this constant.
+const DEFAULT_REPO = 'antbald/BALDART';
+
 function defaultState() {
   return {
     state_version: STATE_VERSION,
@@ -87,7 +94,7 @@ function recordInstall({ version, repo }, cwd = process.cwd()) {
   const now = new Date().toISOString();
   const wasFirstInstall = !state.installed_version;
   state.installed_version = version;
-  state.framework_repo = repo || state.framework_repo || 'antbald/BALDART';
+  state.framework_repo = repo || state.framework_repo || DEFAULT_REPO;
   if (wasFirstInstall) state.install_date = now;
   state.history = appendHistory(state, {
     event: wasFirstInstall ? 'install' : 'reinstall',
@@ -142,6 +149,20 @@ function recordPush({ from, to, description }, cwd = process.cwd()) {
   return state;
 }
 
+/**
+ * Resolve the upstream framework repository to install/update from. Cascade:
+ * `state.framework_repo` (recorded at install — preserves a consumer's fork)
+ * → DEFAULT_REPO. Never returns undefined, so callers that thread the result
+ * into git.addSubtree() / normalizeRepoUrl() can't trip the "undefined repo"
+ * crash that broke `update --reset` (it called add() with no repo).
+ *
+ * `baldart.config.yml` and the subtree's git remote are intentionally NOT
+ * consulted — neither stores the repo, so they'd be dead lookups.
+ */
+function resolveRepo(cwd = process.cwd()) {
+  return load(cwd).framework_repo || DEFAULT_REPO;
+}
+
 /**
  * Read the framework's VERSION file from .framework/VERSION. Used by version /
  * status commands to cross-check what the symlinked framework reports vs what
@@ -164,7 +185,9 @@ module.exports = {
   recordUpdate,
   recordPush,
   reconcileInstalledVersion,
+  resolveRepo,
   readFrameworkVersion,
+  DEFAULT_REPO,
   STATE_FILE,
   STATE_VERSION,
 };