baldart 4.89.1 → 4.92.0

package/framework/docs/WORKFLOWS.md

@@ -15,12 +15,17 @@ workflows are unavailable behaves exactly as before.
 | :--- | :--- | :--- |
 | `new-final-review` | `/new` Final Review (Step F.1.5) | Runs the read-only cross-batch review fan-out — architecture baseline + Codex ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel — then adversarially verifies low-confidence findings and returns them classified. Applies no fixes (the skill owns fix application + user gates). **v4.17.1+:** Codex availability is resolved by a **deterministic pre-flight glob + background poll** (no false negatives from a synchronous-run timeout); a **single-card batch** slims the breadth finders **per-finder, coverage-gated** (caller-supplied `slimDoc`/`slimApi`): it drops a duplicate Claude reviewer only when that reviewer already ran per-card on the same card — `new2` drops both doc + api (it runs both per-card, relevance-gated); classic `/new` drops only `doc-reviewer` (when Phase 3 ran it) and **keeps `api-perf-cost-auditor`** (deferred-to-final by design — the final is its only run). Codex + qa gates always run. Backward-compatible: callers without the flags get the full reviewer set. |
 | `new-card-review` (v4.34.0) | `/new` per-card review cluster — sequential (`review-cycle.md` § Phase 2.5x) **and** team-mode (`team-mode.md` D.1.6) | Hosts the **per-wave** review-cluster OUTSIDE the orchestrator context — the biggest prefix-growth source on long epics. Takes **1..N co-located cards** (1 = sequential per-card; N = a team-mode group, so it runs **once per wave, not per card**) and fans out the finders per card: Simplify + cross-model Codex (agent-launched binary, `code-reviewer` fallback) + qa-sentinel (group max tier) + security-reviewer (high-risk only), each specialist FP-checking its own findings. Then **ONE `coder` applies all VERIFIED code/perf/security/simplify findings in a single pass** (files disjoint by ownership) and re-verifies lint/tsc/build. Returns a compact `{perCard:{fixesApplied,residual}, gateTable, summary}` — the minority `residual` (doc, needs-manual, scope, unconverged) the skill resolves with the right specialist / user gate. **Doc-review and E2E stay in the skill** (doc is write-mode + must see final code; E2E is human-gated + nests a skill); **api-perf is deferred to the Final FULL gate**. Maps to `review-cycle.md` Phase 2.55+3.5+3.7. |
-| `new2` (v4.17.2) | `/new2` skill (the whole batch) | **EXPERIMENTAL A/B variant of `/new`.** Hosts the ENTIRE batch in the background runtime so subagent output never enters the main context. A **dependency-gated DAG scheduler** runs a card only when all in-batch deps are *committed* (and blocks transitive dependents of a failed dep instead of routing them to resolve); each card uses its **owner_agent** + a **specialized review fan-out** (not general-purpose); the worktree is kept **atomic per card** (rollback-to-HEAD on failure); transient API errors are retried and a sustained **outage degrades cleanly** (`degraded` return + durable resume via the skill); a **run ledger** dedups resolves and records accepted deferrals (no re-routing loop); the **merge is integrity-gated** (never force-DONE, never `git add` unreviewed code, never merge an incomplete/degraded batch); the commit step runs on **Haiku** while **follow-up cards are written by `prd-card-writer`**; telemetry carries real **cost** (`total_tokens` via `budget.spent()`, `agent_count`, skill-stamped `wall_clock_s`) + `degraded`. **v4.17.2:** the pre-flight **G3 cross-card Codex check is deterministic** (glob-first + background poll, skipped on single-card batches; `codex_resolved` in telemetry); a non-transient card crash is terminal-with-residual (no orphaned self-healing). Agents Read `/new`'s reference modules for semantics. |
+| `new2` (v4.17.2, promoted v4.90.0) | `/new2` skill (the whole batch) **+ `/new -auto` via its delegation gate** | **Workflow-hosted batch engine of `/new`.** Hosts the ENTIRE batch in the background runtime so subagent output never enters the main context. A **dependency-gated DAG scheduler** runs a card only when all in-batch deps are *committed* (and blocks transitive dependents of a failed dep instead of routing them to resolve); each card uses its **owner_agent** + a **specialized review fan-out** (not general-purpose); the worktree is kept **atomic per card** (rollback-to-HEAD on failure); transient API errors are retried and a sustained **outage degrades cleanly** (`degraded` return + durable resume via the skill); a **run ledger** dedups resolves and records accepted deferrals (no re-routing loop); the **merge is integrity-gated** (never force-DONE, never `git add` unreviewed code, never merge an incomplete/degraded batch); the commit step runs on **Haiku** while **follow-up cards are written by `prd-card-writer`**; telemetry carries real **cost** (`total_tokens` via `budget.spent()`, `agent_count`, skill-stamped `wall_clock_s`) + `degraded`. **v4.17.2:** the pre-flight **G3 cross-card Codex check is deterministic** (glob-first + background poll, skipped on single-card batches; `codex_resolved` in telemetry); a non-transient card crash is terminal-with-residual (no orphaned self-healing). Agents Read `/new`'s reference modules for semantics. |
 | `new2-resolve` (v4.17.2) | `new2` (self-healing) | Resolution pass for any gate that would otherwise need a human (`ac-unmet · blocker · qa-fail · e2e-blocked · merge-blocker · scope-expansion`). A **terminal short-circuit** skips the costly multi-attempt when the problem is impossible-by-definition (`out-of-ownership` verified in JS; other terminal reasons ratified by a judge); a **MANDATORY adversarial judge** cross-checks every `verified` claim — the judge independently greps the files and the workflow verifies **at least one** falls inside MAY-EDIT (`.some()`, so listing adjacent changed files is not mistaken for fabrication); accepts a **batched `findings` list** (one resolve per fix-area). **The domain is normalized** (freeform `documentation`→`doc`, …) before routing the **fixer** (doc→doc-reviewer, ui→ui-expert, security→security-reviewer, else coder) and judge, and a **doc finding gets doc-tree MAY-EDIT** (not the card's code scope); the 3-angle Tier-2 fan-out is reserved for code domains (single retry for doc/test). Follow-ups are written by **`prd-card-writer`**, offline-safe (deferred to the skill if no agent can write). |
 
-> **`new2` is an experiment, not a replacement.** It exists to A/B-test the
-> context-economy of workflow-hosting `/new`. `/new` remains the SSOT, the
-> cross-tool default, and the recovery-safe path. `new2` is Claude-only and its
+> **`new2` is the engine, `/new` is the SSOT.** Since v4.90.0 `/new -auto`
+> delegates the whole batch here by default (AUTONOMOUS OFF-CONTEXT DELEGATION
+> GATE — measured driver: 53–59% of an inline `-auto` run's billed tokens is the
+> orchestrator's own turn-tax; escape hatch `-inline`; `-auto-ship`, declared
+> migrations, interactive runs and every Codex run stay on the classic inline
+> path). `/new` remains the semantic SSOT and the cross-tool default — `new2`'s
+> agents Read `/new`'s reference modules; the gate map in `new2.js` encodes only
+> orchestration shape + deterministic policy. `new2` is Claude-only and its
 > skill HALTs with a pointer to `/new` when the `Workflow` tool is unavailable.
 
 ## How distribution works

package/framework/scripts/structural-compare.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// structural-compare.mjs — deterministic STRUCTURAL pre-gate for the mockup→code
+// fidelity chain (T1.B, framework v4.90.0). Zero-dep, heuristic, CONSERVATIVE.
+//
+// Compares a code-form mockup (an .html file, or a design_src dir of .jsx/.tsx/.css)
+// against the implementation files on a small set of CLEAR structural signals:
+//   - landmark census (header/nav/aside/main/footer present in mockup, absent in impl)
+//   - max grid column count (multi-column mockup built single-column — the FEAT-0061 class)
+//   - responsive signals (@media breakpoints / Tailwind responsive prefixes present in
+//     the mockup, entirely absent in the impl)
+//
+// SEMANTICS — signals, not verdicts. The implementation may COMPOSE primitives (a
+// `<SplitView>` that owns the grid, a `<TopBar>` that renders the <header>), and this
+// script only sees the card-touched files — so a "divergence" here is a deterministic
+// SIGNAL with a per-finding `confidence`, never a standalone verdict:
+//   - in-build (ui-expert self-check): the builder judges each signal — it knows which
+//     primitives it composed — and fixes what is real BEFORE returning.
+//   - in Phase 2.7 (/e2e-review): the signals are passed to `markup-fidelity-verifier`
+//     as `deterministic_signals` focus hints; the verifier confirms or dismisses each
+//     (it can read the composed primitives). The verifier spawn is NEVER skipped on a
+//     "match" — a regex match is necessary, not sufficient.
+//
+// Contract:
+//   node structural-compare.mjs --mockup <file-or-dir> --impl <f1> <f2> ...
+//   → one JSON line: { status: "match" | "divergence" | "skipped",
+//                      mockup_signature, impl_signature,
+//                      findings:[{category,severity,description,expected,actual}] }
+//   Exit: 0 = match/skipped (nothing provable), 3 = divergence (findings are evidence).
+//   Internal errors fail OPEN ({status:"skipped"}, exit 0) — pre-gate, not tribunal.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function emit(obj, code) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const a = { mockup: null, impl: [] };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--mockup') a.mockup = argv[++i];
+    else if (argv[i] === '--impl') {
+      while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) a.impl.push(argv[++i]);
+    }
+  }
+  return a;
+}
+
+function readSources(target) {
+  const texts = [];
+  const push = (p) => { try { texts.push(fs.readFileSync(p, 'utf8')); } catch { /* fail-open per file */ } };
+  try {
+    const st = fs.statSync(target);
+    if (st.isDirectory()) {
+      for (const f of fs.readdirSync(target)) {
+        if (/\.(html?|jsx?|tsx?|css|scss|svelte|vue)$/i.test(f)) push(path.join(target, f));
+      }
+    } else push(target);
+  } catch { /* absent target → empty */ }
+  return texts;
+}
+
+// Count top-level tracks in a grid-template-columns value: "repeat(2, minmax(0,1fr))" → 2,
+// "1fr 320px" → 2. Parens-aware split; `repeat(N, ...)` contributes N (integer N only).
+function countTracks(value) {
+  const v = value.trim();
+  if (!v || /^(subgrid|none|inherit|initial|unset)/.test(v)) return 0;
+  const parts = [];
+  let depth = 0, cur = '';
+  for (const ch of v) {
+    if (ch === '(') { depth++; cur += ch; }
+    else if (ch === ')') { depth--; cur += ch; }
+    else if (/\s/.test(ch) && depth === 0) { if (cur) { parts.push(cur); cur = ''; } }
+    else cur += ch;
+  }
+  if (cur) parts.push(cur);
+  let n = 0;
+  for (const p of parts) {
+    const rep = p.match(/^repeat\(\s*(\d+)\s*,/);
+    if (rep) n += parseInt(rep[1], 10);
+    else if (/^\[.*\]$/.test(p)) continue; // named grid line, not a track
+    else n += 1;
+  }
+  return n;
+}
+
+function signature(texts) {
+  const sig = {
+    landmarks: { header: 0, nav: 0, aside: 0, main: 0, footer: 0 },
+    grid_cols_max: 0,
+    grid_cols_responsive_max: 0, // max cols behind a responsive gate (md:/lg:/@media)
+    has_media_queries: false,
+    has_responsive_prefixes: false,
+    files: texts.length,
+  };
+  for (const t of texts) {
+    for (const lm of Object.keys(sig.landmarks)) {
+      const m = t.match(new RegExp(`<${lm}[\\s/>]`, 'gi'));
+      if (m) sig.landmarks[lm] += m.length;
+    }
+    // CSS: grid-template-columns (also inside <style> blocks / .css files / inline style=)
+    for (const m of t.matchAll(/grid-template-columns\s*:\s*([^;"'}]+)/gi)) {
+      sig.grid_cols_max = Math.max(sig.grid_cols_max, countTracks(m[1]));
+    }
+    // @media-scoped multi-col: approximate — a grid-template-columns inside a file that
+    // also has @media counts as responsive-capable (regex cannot scope blocks reliably).
+    if (/@media[^{]*\(\s*(min|max)-width/i.test(t)) {
+      sig.has_media_queries = true;
+      for (const m of t.matchAll(/grid-template-columns\s*:\s*([^;"'}]+)/gi)) {
+        sig.grid_cols_responsive_max = Math.max(sig.grid_cols_responsive_max, countTracks(m[1]));
+      }
+    }
+    // Tailwind: grid-cols-N (+ responsive variants), incl. arbitrary grid-cols-[a_b]
+    for (const m of t.matchAll(/(?:^|[\s"'`])(?:(sm|md|lg|xl|2xl):)?grid-cols-(\d+|\[[^\]]+\])/g)) {
+      const cols = m[2].startsWith('[') ? m[2].split('_').length : parseInt(m[2], 10);
+      sig.grid_cols_max = Math.max(sig.grid_cols_max, cols);
+      if (m[1]) {
+        sig.has_responsive_prefixes = true;
+        sig.grid_cols_responsive_max = Math.max(sig.grid_cols_responsive_max, cols);
+      }
+    }
+    if (/(?:^|[\s"'`])(?:sm|md|lg|xl|2xl):[\w[-]/m.test(t)) sig.has_responsive_prefixes = true;
+  }
+  return sig;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.mockup || args.impl.length === 0) emit({ status: 'skipped', reason: 'usage: --mockup <file-or-dir> --impl <files...>' }, 0);
+
+  const mockTexts = readSources(args.mockup);
+  if (mockTexts.length === 0) emit({ status: 'skipped', reason: 'mockup unreadable: ' + args.mockup }, 0);
+  const implTexts = args.impl.flatMap((f) => readSources(f));
+  if (implTexts.length === 0) emit({ status: 'skipped', reason: 'no readable implementation files' }, 0);
+
+  const mock = signature(mockTexts);
+  const impl = signature(implTexts);
+  const findings = [];
+
+  // Confidence encodes the composition caveat: the impl files are the card-touched set,
+  // and grids/landmarks may live INSIDE a reused primitive this scan cannot see.
+  // 1. Multi-column mockup built single-column (the FEAT-0061 layout-break class).
+  if (mock.grid_cols_max >= 2 && impl.grid_cols_max <= 1) {
+    findings.push({
+      category: 'layout-break', severity: 'critical', confidence: 'medium',
+      description: `mockup declares a ${mock.grid_cols_max}-column grid; implementation files declare no multi-column grid (unless a composed primitive owns it — verify)`,
+      expected: `grid with ${mock.grid_cols_max} columns (mockup)`, actual: `max ${impl.grid_cols_max} column(s) found in touched files`,
+    });
+  }
+  // 2. Mockup gates multi-col behind a breakpoint; impl has NO responsive machinery at all.
+  if ((mock.has_media_queries || mock.has_responsive_prefixes) && !impl.has_media_queries && !impl.has_responsive_prefixes) {
+    findings.push({
+      category: 'responsiveness-break', severity: 'major', confidence: 'medium',
+      description: 'mockup is breakpoint-aware (@media / responsive prefixes); implementation files have neither (unless a composed primitive owns the breakpoints — verify)',
+      expected: 'breakpoint-gated layout as in the mockup', actual: 'no @media, no responsive class prefixes in touched files',
+    });
+  }
+  // 3. Landmark regions present in the mockup, entirely absent in the implementation.
+  //    LOW confidence by construction: component-based impls render landmarks inside
+  //    reused shell primitives (<TopBar> → <header>) invisible to this scan.
+  for (const lm of Object.keys(mock.landmarks)) {
+    if (mock.landmarks[lm] > 0 && impl.landmarks[lm] === 0) {
+      findings.push({
+        category: 'component-missing', severity: 'minor', confidence: 'low',
+        description: `mockup contains <${lm}> landmark region(s); none in the touched files (may be rendered by a composed shell primitive — verify)`,
+        expected: `<${lm}> region (mockup has ${mock.landmarks[lm]})`, actual: 'absent from touched files',
+      });
+    }
+  }
+
+  emit(
+    { status: findings.length ? 'divergence' : 'match', mockup_signature: mock, impl_signature: impl, findings },
+    findings.length ? 3 : 0
+  );
+}
+
+try { main(); } catch (e) { emit({ status: 'skipped', reason: 'internal error: ' + (e && e.message) }, 0); }

package/package.json

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

package/src/commands/update.js

@@ -120,22 +120,67 @@ function scaffoldOverlaysForCommits(commits) {
 
 // Path prefixes BALDART itself writes during install/update. Anything outside
 // these patterns is treated as user-owned and never auto-staged.
+//
+// INVARIANT (do not let this list drift again): this allowlist MUST cover the
+// FULL set of payloads BALDART writes to a consumer's tree — every runtime, not
+// just Claude. A path BALDART generates but that is absent here is classified
+// `userOwned`, never auto-committed, and resurfaces as an untracked/modified
+// file in every other clone of the repo (the exact "commit never happens →
+// other terminals see churn" bug). When you add ANY new written payload — a new
+// `.claude/*` payload kind, a Codex artifact under `.codex/` or `.agents/`, a
+// root file, an i18n/toolchain config — add its pattern here in the SAME change
+// (parity twin of the schema-change propagation rule). See CHANGELOG v4.89.2.
 const BALDART_MANAGED_PATTERNS = [
   /^\.framework(\/|$)/,
   /^AGENTS\.md$/,
   /^CLAUDE\.md$/,
   /^agents(\.backup)?(\/|$)/,
-  /^\.claude\/(agents|commands|skills|workflows|hooks|routines|settings\.json)(\/|$)/,
+  // Claude payload kinds (incl. output-styles, v4.50.0).
+  /^\.claude\/(agents|commands|skills|workflows|hooks|routines|output-styles|settings\.json)(\/|$)/,
+  // Codex-native payloads: skill symlinks (v3.7.0), transpiled agents (v4.80.0),
+  // native hooks (v4.88.0). Only exist when `tools.enabled ∋ codex`, so listing
+  // them unconditionally is safe — absent means never dirty.
+  /^\.agents\/skills(\/|$)/,
+  /^\.codex(\/|$)/,
   /^\.baldart(\/|$)/,
   /^baldart\.config\.yml$/,
   /^docs\/references\/(ui-guidelines\.template\.md|brand-guidelines\.md)$/,
   /^templates(\/|$)/,
   /^\.github\/workflows\/baldart-/,
-  /^scripts\/routines(\/|$)/
+  /^scripts\/routines(\/|$)/,
+  // i18n gate configs written by src/utils/i18n-gate.js (flat + legacy).
+  /^eslint\.i18n\.config\.mjs$/,
+  /^\.eslintrc\.i18n\.json$/
 ];
 
-function isBaldartManagedPath(p) {
-  return BALDART_MANAGED_PATTERNS.some((rx) => rx.test(p));
+// The i18n context registry path is consumer-configurable (paths.i18n_registry),
+// so its containing directory can't be a static literal — derive it from config
+// so the registry file BALDART writes is auto-committed like every other managed
+// payload. Falls back to the template default (docs/i18n/) when unset/unreadable.
+function i18nRegistryPatterns(cwd = process.cwd()) {
+  let rel = 'docs/i18n/registry.yml';
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (fs.existsSync(cfgPath)) {
+      const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+      const v = cfg && cfg.paths && cfg.paths.i18n_registry;
+      if (typeof v === 'string' && v.trim()) rel = v.trim();
+    }
+  } catch (_) { /* fall back to the template default */ }
+  const norm = rel.replace(/\\/g, '/');
+  const out = [new RegExp('^' + norm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$')];
+  const dir = norm.replace(/\/[^/]*$/, '');
+  if (dir && dir !== norm) {
+    out.push(new RegExp('^' + dir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(\\/|$)'));
+  }
+  return out;
+}
+
+function isBaldartManagedPath(p, extra = []) {
+  return BALDART_MANAGED_PATTERNS.some((rx) => rx.test(p)) || extra.some((rx) => rx.test(p));
 }
 
 // Re-generate the root primitives (AGENTS.md + CLAUDE.md) from the versioned
@@ -206,10 +251,11 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   const seen = new Set();
   const managed = [];
   const userOwned = [];
+  const extraPatterns = i18nRegistryPatterns();
   for (const p of allDirty) {
     if (!p || seen.has(p)) continue;
     seen.add(p);
-    (isBaldartManagedPath(p) ? managed : userOwned).push(p);
+    (isBaldartManagedPath(p, extraPatterns) ? managed : userOwned).push(p);
   }
   if (managed.length === 0) {
     return;