baldart 4.54.1 → 4.55.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.55.0] - 2026-06-19
+
+**The i18n anti-hardcoded gate now also runs as a guarded lefthook pre-commit command — closing the direct-commit hole for projects that have BOTH the toolchain and i18n enabled.** Until now the gate ran only inside the BALDART workflows (`/new`, `/new2`, `/qa`, qa-sentinel, routine), so a *direct* `git commit` (a human, or an agent editing outside `/new`) bypassed it. When `features.has_toolchain` AND `features.has_i18n` are both true, a fresh `lefthook.yml` now gains an `i18n` pre-commit command that runs the standalone anti-hardcoded gate over `{staged_files}`. It is **guarded** (`sh -c 'if [ -f eslint.i18n.config.mjs ] || …; then exec <cmd> "$@"; fi'`): the gate's non-zero exit propagates (a hardcoded JSX string fails the commit), but when the gate config is absent it is a clean no-op (exit 0) — never a spurious block. Bypassable with `git commit --no-verify` (a strong default, not a wall); covers JSX text + allowlisted attributes (`jsx-only`); the non-JSX backstop stays with `code-reviewer`; consumers without the toolchain keep the `/new`/qa-sentinel gates as enforcement.
+
+**Scope discipline (adversarial-reviewed).** The original idea also included a deterministic *registry-membership* pre-commit check (every `t('key')` must be in the registry). A 3-reviewer adversarial pass **rejected it** and it is NOT shipped: `I18N_REGISTRY_DRIFT` is already triple-covered (coder STEP 9 + code-reviewer + doc-reviewer); the `extract_command` activation gate was a fake proxy (the enumerator is a regex, and `extract_command` is auto-populated only for i18next/lingui/react-intl → off for the mainstream next-intl/vue/custom); the static-key regex would false-block correct commits (`useTranslation('ns')` + `t('key')`, overlay-overridable conventions); and it would break inside `/new` git worktrees (`.claude/skills/` is untracked there). The pre-commit hook was likewise scoped down — it rides the **existing** toolchain lefthook (no new installer, no new config key, no husky branch, no installing lefthook on a non-toolchain project, no js-yaml round-trip of user files).
+
+**MINOR** (extends the toolchain lefthook's fresh-config behaviour, gated on existing flags; no new agent/skill/command, no new `baldart.config.yml` key, no install/layout change).
+
+### Added / Changed
+
+- **`src/utils/toolchain-adapters/lefthook.js`** — `initConfig(cwd, opts)` accepts `opts.i18nCommand`; a fresh `lefthook.yml` gains the guarded `i18n` pre-commit command alongside `biome`. Non-destructive behaviour unchanged (writes only when absent).
+- **`src/utils/toolchain-installer.js`** — `install()` / `initConfigs()` forward `opts.i18nCommand` to the adapters.
+- **`src/commands/configure.js`** — the toolchain block resolves `i18nCommand` from `features.has_i18n` (the diff-scoped gate command, trailing ` .` stripped) and passes it through.
+- **`src/commands/doctor.js`** — WARN-only backfill: when `has_toolchain` + `has_i18n` and `lefthook.yml` has no i18n command (toolchain predating v4.55.0), surface the exact snippet to paste. doctor never mutates a user-owned `lefthook.yml`.
+- **`framework/agents/i18n-protocol.md`** — documents the pre-commit layer (gated on `has_toolchain`, `--no-verify` caveat) and records why the registry-membership check was rejected.
+
 ## [4.54.1] - 2026-06-19
 
 **Two bugs in the Codex relay of the `/new` review workflows — found live as a ~20-minute "freeze".** During a real `/new FEAT-0037` the Codex step of `new-card-review` appeared stuck; on-disk diagnosis (`/tmp/codexreview-wave-FEAT-0037*.md` + `ps`) showed **Codex had actually finished 9 minutes earlier** (full review, zero actionable findings) but the relay couldn't detect it, because of two independent, compounding bugs:

package/VERSION

@@ -1 +1 @@
-4.54.1
+4.55.0

package/framework/agents/i18n-protocol.md

@@ -96,6 +96,22 @@ Translations are NOT stored here — they live in the native locale files.
    routine — run whole-repo (`.`) by design, because they reconcile the entire
    codebase, not a single change. A diff-scoped gate failure is therefore always a
    string the change itself introduced — never baseline noise to triage.
+
+   **Pre-commit layer (since v4.55.0) — only when `features.has_toolchain` is also
+   on.** The gates above run inside the BALDART workflows; a **direct** `git commit`
+   (a human, or an agent editing outside `/new`) bypasses them. So when BOTH
+   `features.has_i18n` and `features.has_toolchain` are true, the curated lefthook
+   pre-commit gains a **guarded `i18n` command** that runs the anti-hardcoded gate
+   over `{staged_files}` on every commit. It is wired automatically into a fresh
+   `lefthook.yml` by `baldart configure`/`add`; for a toolchain installed before
+   v4.55.0, `baldart doctor` surfaces the snippet to paste (it never mutates a
+   user-owned `lefthook.yml`). The command is guarded (no-op when the gate config is
+   absent) and **bypassable with `git commit --no-verify`** — a strong default, not
+   a wall. Consumers WITHOUT the toolchain are not covered at direct-commit time;
+   the `/new` + `qa-sentinel` gates remain their enforcement. (A deterministic
+   registry-membership pre-commit check was evaluated and rejected: it is already
+   triple-covered by the review owners below, its key-enumeration is fragile across
+   stacks, and it breaks inside `/new` git worktrees.)
 2. **Semantic backstop (review)** — non-JSX imperative strings are OUTSIDE the
    linter's deterministic reach, so `code-reviewer` flags them as **HIGH**,
    **syntactically scoped**:

package/package.json

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

package/src/commands/configure.js

@@ -981,6 +981,16 @@ async function interactivePrompts(merged, detected) {
       const migs = ti.migrations();          // curated tools blocked by an incumbent
       const toInstall = [];
 
+      // i18n pre-commit gate (since v4.55.0) — when has_i18n, a FRESH lefthook.yml
+      // also gets a guarded i18n command (the anti-hardcoded gate over staged
+      // files), so direct commits are caught too. Resolve + strip the trailing
+      // full-sweep ` .` (consistent with the diff-scoped gates). null when i18n off
+      // → lefthook stays Biome-only. Existing lefthook.yml is never mutated here
+      // (doctor WARNs with the snippet instead).
+      const i18nCmd = merged.features.has_i18n
+        ? I18nGate.commandForCwd(process.cwd()).replace(/\s+\.$/, '')
+        : null;
+
       // Clean path — preselect (default Y).
       if (recommended.length) {
         const want = await UI.confirm(`Install the curated toolchain (${recommended.join(', ')}) as devDependencies now?`, true);
@@ -1001,7 +1011,7 @@ async function interactivePrompts(merged, detected) {
       }
 
       if (toInstall.length) {
-        const res = ti.install({ tools: toInstall });
+        const res = ti.install({ tools: toInstall, i18nCommand: i18nCmd });
         for (const t of res.installed) UI.success(`Installed ${t}.`);
         for (const f of res.failed) UI.warning(`Install failed for ${f.tool}: ${f.error}`);
         for (const s of res.skipped) UI.info(`Skipped ${s.tool}: ${s.reason}`);
@@ -1010,7 +1020,7 @@ async function interactivePrompts(merged, detected) {
       // Resolve the active tool set (every in-scope tool usable now) → configs + commands.
       const active = ti.activeTools();
       if (active.length) {
-        const cfgRes = ti.initConfigs({ tools: active });
+        const cfgRes = ti.initConfigs({ tools: active, i18nCommand: i18nCmd });
         for (const c of cfgRes) {
           if (c.status === 'written') UI.success(`Wrote default ${c.tool} config.`);
           else if (c.status === 'skipped' && c.reason === 'exists') UI.info(`Kept existing ${c.tool} config (not overwritten).`);

package/src/commands/doctor.js

@@ -446,6 +446,21 @@ async function detectState(cwd, opts = {}) {
           && (!I18nGate.isConfigPresent(cwd) || !I18nGate.depsInstalled(cwd))) {
           state.i18nGateMissing = true;
         }
+        // i18n pre-commit gate wired into lefthook? (since v4.55.0) — only when
+        // the toolchain (lefthook) is in play. WARN-only: a fresh lefthook.yml
+        // gets the guarded i18n command at configure time, but a consumer whose
+        // toolchain was installed before v4.55.0 has a Biome-only one. doctor
+        // NEVER mutates a user lefthook.yml — it surfaces the snippet to add.
+        state.i18nPrecommitSnippetNeeded = false;
+        if (config.features.has_toolchain === true) {
+          const lhPath = path.join(cwd, 'lefthook.yml');
+          if (fs.existsSync(lhPath)) {
+            const lh = fs.readFileSync(lhPath, 'utf8');
+            if (!/eslint\.i18n\.config\.mjs/.test(lh) && !/\.eslintrc\.i18n\.json/.test(lh)) {
+              state.i18nPrecommitSnippetNeeded = true;
+            }
+          }
+        }
       }
     } catch (_) { /* never block doctor on i18n probe */ }
 
@@ -942,6 +957,26 @@ function planActions(state) {
       },
     });
   }
+  if (state.i18nEnabled && state.i18nPrecommitSnippetNeeded) {
+    const i18nCmd = I18nGate.commandForCwd(state.cwd).replace(/\s+\.$/, '');
+    const snippet = [
+      '  commands:',
+      '    i18n:',
+      '      glob: "*.{js,jsx,ts,tsx,mjs,cjs}"',
+      `      run: sh -c 'if [ -f eslint.i18n.config.mjs ] || [ -f .eslintrc.i18n.json ]; then exec ${i18nCmd} "$@"; fi' _ {staged_files}`,
+    ].join('\n');
+    actions.push({
+      key: 'i18n-precommit-snippet',
+      label: 'Add the i18n anti-hardcoded gate to your lefthook pre-commit (manual — snippet shown)',
+      why: 'features.has_i18n + the toolchain are both on, but lefthook.yml has no i18n command, so a DIRECT `git commit` (outside /new) is not gated for hardcoded user-facing strings. A fresh install wires this automatically; your toolchain predates v4.55.0. doctor will NOT edit your lefthook.yml — it shows the block to paste under pre-commit.',
+      autoOk: false, // never mutates a user-owned lefthook.yml — surfaces the snippet only
+      run: async () => {
+        UI.info('Add this under your `pre-commit:` block in lefthook.yml (merge into the existing `commands:` map):');
+        UI.info(snippet);
+        UI.info('The gate is guarded (no-op if the eslint.i18n config is absent) and bypassable with `git commit --no-verify`. The /new + qa-sentinel gates remain regardless.');
+      },
+    });
+  }
 
   // External-tool version currency (since v4.38.0). One non-blocking upgrade
   // action per managed tool confirmed behind upstream — the tool-dependency

package/src/utils/toolchain-adapters/lefthook.js

@@ -37,11 +37,22 @@ class LefthookAdapter {
   /**
    * Write a minimal lefthook.yml (pre-commit → Biome on staged files) only when
    * absent. Never overwrites. Returns `{ status, reason?, path }`. Never throws.
+   *
+   * `opts.i18nCommand` (since v4.55.0) — when set (only on a `features.has_i18n`
+   * project, resolved + trailing-` .`-stripped by the caller), the fresh config
+   * ALSO gains an `i18n` pre-commit command that runs the standalone
+   * anti-hardcoded gate over `{staged_files}`. It is **guarded**: it runs the gate
+   * only if the gate's config file exists on disk and `exec`s it so the gate's
+   * exit code propagates (a hardcoded JSX string fails the commit); when the
+   * config is absent (e.g. the user declined gate setup, or it runs before the
+   * gate is written in the same `configure` pass) it is a clean no-op (exit 0),
+   * never a spurious block. Closes the direct-commit hole for toolchain+i18n
+   * consumers — see agents/i18n-protocol.md.
    */
-  initConfig(cwd = this.cwd) {
+  initConfig(cwd = this.cwd, opts = {}) {
     const target = path.join(cwd, this.configFile);
     if (fs.existsSync(target)) return { status: 'skipped', reason: 'exists', path: target };
-    const yml = [
+    const lines = [
       '# Managed by BALDART toolchain layer — customize freely.',
       '# Runs Biome over staged files before each commit. Edit/remove as needed.',
       'pre-commit:',
@@ -50,8 +61,20 @@ class LefthookAdapter {
       '    biome:',
       '      glob: "*.{js,ts,jsx,tsx,json,jsonc,css}"',
       '      run: npx biome check --no-errors-on-unmatched {staged_files}',
-      '',
-    ].join('\n');
+    ];
+    if (opts.i18nCommand) {
+      // Guarded: skip when the gate config is absent (exit 0), else exec so the
+      // gate's non-zero exit blocks the commit. Single-quoted sh -c is a plain
+      // YAML scalar (no `: `/`#`) — verified to round-trip exactly.
+      const guard = `sh -c 'if [ -f eslint.i18n.config.mjs ] || [ -f .eslintrc.i18n.json ]; then exec ${opts.i18nCommand} "$@"; fi' _ {staged_files}`;
+      lines.push(
+        '    i18n:',
+        '      glob: "*.{js,jsx,ts,tsx,mjs,cjs}"',
+        `      run: ${guard}`,
+      );
+    }
+    lines.push('');
+    const yml = lines.join('\n');
     try {
       fs.writeFileSync(target, yml, 'utf8');
       return { status: 'written', path: target };

package/src/utils/toolchain-installer.js

@@ -93,7 +93,7 @@ class ToolchainInstaller {
    * `{ ok, installed:[], failed:[{tool,error}], skipped:[{tool,reason}] }`.
    * Never throws. NOT run in CI / `--non-interactive` by the command layer.
    */
-  install({ tools = this.recommend(), spinner = true } = {}) {
+  install({ tools = this.recommend(), spinner = true, i18nCommand = null } = {}) {
     if (!this.hasPackageJson()) {
       return { ok: false, installed: [], failed: [], skipped: tools.map((t) => ({ tool: t, reason: 'no package.json' })) };
     }
@@ -113,7 +113,7 @@ class ToolchainInstaller {
         // commented-out example, then register no hooks) sees OURS — a biome
         // pre-commit — and registers it. Non-destructive (skips if present).
         if (typeof adapter.initConfig === 'function') {
-          try { adapter.initConfig(this.cwd); } catch (_) { /* non-fatal */ }
+          try { adapter.initConfig(this.cwd, { i18nCommand }); } catch (_) { /* non-fatal */ }
         }
         execSync(adapter.installCommand(), { cwd: this.cwd, stdio: 'pipe', timeout: 300000 });
         if (this._toolUsable(name)) {
@@ -144,14 +144,14 @@ class ToolchainInstaller {
    * Write each tool's default config when absent (non-destructive). Returns
    * `[{ tool, status:'written'|'skipped'|'noop', reason?, path? }]`. Never throws.
    */
-  initConfigs({ tools = this.inScope() } = {}) {
+  initConfigs({ tools = this.inScope(), i18nCommand = null } = {}) {
     const out = [];
     for (const name of tools) {
       let adapter;
       try { adapter = adapters.getAdapter(name, this.cwd); }
       catch { out.push({ tool: name, status: 'noop', reason: 'unknown adapter' }); continue; }
       if (typeof adapter.initConfig !== 'function') { out.push({ tool: name, status: 'noop' }); continue; }
-      try { out.push({ tool: name, ...adapter.initConfig(this.cwd) }); }
+      try { out.push({ tool: name, ...adapter.initConfig(this.cwd, { i18nCommand }) }); }
       catch (err) { out.push({ tool: name, status: 'noop', reason: (err.message || '').split('\n')[0] }); }
     }
     return out;