@hone-ai/cli 1.18.0 → 1.19.0

package/hone-cli.js

@@ -27,6 +27,7 @@ const { execSync } = require('child_process');
 const pkg     = require('./package.json');
 const { parseReviewJSON } = require('./lib/parse-review-json');
 const { resolveBaseRef, getMaxDiffChars } = require('./lib/release-review-config');
+const { gitEnv } = require('./lib/git-env');
 const program = new Command();
 
 // ── Config resolution ─────────────────────────────────────────────────────────
@@ -61,6 +62,12 @@ function getConfig() {
 // exit so the warning lands AFTER the command's normal output and
 // doesn't fight for attention with whatever the user is doing.
 let _outdatedWarning = null;
+// HC-101-followup-3: server-side recommendation buckets, surfaced via
+// the X-Hone-Recommendation response header. Same printing rules as
+// _outdatedWarning (queued during interceptor, flushed at process.exit).
+// Stored as a Set to dedupe when one CLI invocation makes multiple
+// requests that return the same recommendation.
+const _serverRecommendations = new Set();
 
 function _compareSemverMinor(a, b) {
   // Returns true if `a` is strictly older than `b` for major.minor.patch.
@@ -97,10 +104,25 @@ function api(config) {
             `  ⚠ @hone-ai/cli ${latest} is available — you have ${pkg.version}\n` +
             `    Run: npm install -g @hone-ai/cli@latest`;
         }
+        // HC-101-followup-3: server can recommend config changes via
+        // X-Hone-Recommendation (e.g. ci.gate=none → "consider gate=local").
+        // Queue the text; print at exit so it lands after normal output.
+        const rec = response?.headers?.['x-hone-recommendation'];
+        if (rec && typeof rec === 'string' && rec.trim()) {
+          _serverRecommendations.add(rec.trim());
+        }
       } catch { /* never break the response path */ }
       return response;
     },
-    (error) => Promise.reject(error)
+    (error) => {
+      try {
+        const rec = error?.response?.headers?.['x-hone-recommendation'];
+        if (rec && typeof rec === 'string' && rec.trim()) {
+          _serverRecommendations.add(rec.trim());
+        }
+      } catch { /* swallow */ }
+      return Promise.reject(error);
+    }
   );
   return client;
 }
@@ -111,20 +133,217 @@ process.on('exit', () => {
   if (_outdatedWarning) {
     try { console.error('\n' + _outdatedWarning); } catch { /* swallow */ }
   }
+  // HC-101-followup-3: flush any server-side recommendations queued by
+  // the response interceptor (e.g. ci.gate=none → setup-local-ci nudge).
+  if (_serverRecommendations.size > 0) {
+    try {
+      for (const rec of _serverRecommendations) {
+        console.error('\n  ⚠ ' + rec);
+      }
+    } catch { /* swallow */ }
+  }
 });
 
+// ── SETUP-LOCAL-CI command (HC-101-followup-3) ─────────────────────────────────
+//
+// Scaffolds HC-101's local-CI assets into the adopter's repo so they can
+// switch `ci.gate: local` and avoid burning GitHub Actions minutes. Pairs
+// with the X-Hone-Recommendation header the server emits when an adopter
+// posts a job with ci.gate=none — both nudge toward "real safety net via
+// local-mode" instead of "no safety net via none-mode".
+//
+// What this command does:
+//   1. Pulls the Makefile template + compose.local-ci.yml template from
+//      GET /scripts/local-ci/{makefile,compose} (lives inside /server/
+//      so it ships with Railway deploys per HC-019y-followup-3-railway-path).
+//   2. Writes them to the adopter's repo root. Existing files are backed
+//      up to `<file>.hone-backup` to avoid clobbering adopter customizations.
+//   3. Flips `.pipeline-config.yml`'s `ci.gate` to `local` so the very next
+//      `hone run-story` uses the new gate. Existing pipeline-config is
+//      required (run `hone setup` first); the command refuses to scaffold
+//      otherwise so the gate flip doesn't dangle without a config.
+//   4. Prints a copy-paste checklist of next steps (customize Makefile
+//      targets, run `make ci`, etc.).
+program
+  .command('setup-local-ci')
+  .description('Scaffold HC-101 Makefile + compose.local-ci.yml + flip ci.gate=local (HC-101-followup-3)')
+  .option('--force', 'Overwrite existing Makefile / compose.local-ci.yml without backing up')
+  .option('--dry-run', 'Show what would change without writing any files')
+  .action(async (opts) => {
+    const fs   = require('fs');
+    const path = require('path');
+    const yaml = require('js-yaml');
+
+    const config = getConfig();
+    const client = api(config);
+    const repoRoot = process.cwd();
+
+    console.log('Hone AI — Setup Local CI (HC-101-followup-3)');
+    console.log('============================================');
+    console.log('');
+
+    // 1. Verify .pipeline-config.yml exists AND has a ci: block. Pick
+    //    the file that ACTUALLY carries the ci: block — readCIGateConfig
+    //    falls through to the second candidate when the first lacks one,
+    //    so the write must target the same file the reader will pick or
+    //    the flip is a silent no-op.
+    const configCandidates = [
+      path.join(repoRoot, '.pipeline-config.yml'),
+      path.join(repoRoot, '.github/.pipeline-config.yml'),
+    ];
+    let pipelineConfigPath = null;
+    for (const p of configCandidates) {
+      if (!fs.existsSync(p)) continue;
+      let raw;
+      try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+      let parsedPeek;
+      try { parsedPeek = yaml.load(raw); } catch { continue; }
+      if (parsedPeek && typeof parsedPeek === 'object' && parsedPeek.ci && typeof parsedPeek.ci === 'object') {
+        pipelineConfigPath = p;
+        break;
+      }
+    }
+    // Fall back to the FIRST existing file if none has a ci: block — the
+    // flip will add one. This still avoids the write/read divergence
+    // because if neither candidate has a ci: block, the reader returns
+    // defaults anyway.
+    if (!pipelineConfigPath) {
+      pipelineConfigPath = configCandidates.find((p) => fs.existsSync(p)) || null;
+    }
+    if (!pipelineConfigPath) {
+      console.error('  ✗ No .pipeline-config.yml found in this repo.');
+      console.error('    Run `hone setup` first to scaffold the pipeline, then re-run this command.');
+      process.exit(1);
+    }
+    console.log(`  ✓ Found pipeline config at ${path.relative(repoRoot, pipelineConfigPath)}`);
+
+    // 2. Fetch the two assets from the server.
+    const assets = [
+      { remote: '/scripts/local-ci/makefile', local: 'Makefile' },
+      { remote: '/scripts/local-ci/compose',  local: 'compose.local-ci.yml' },
+    ];
+    const fetched = [];
+    for (const a of assets) {
+      try {
+        const { data } = await client.get(a.remote, { responseType: 'text', transformResponse: [(d) => d] });
+        fetched.push({ ...a, content: String(data) });
+        console.log(`  ✓ Pulled ${a.local} from server (${data.length} bytes)`);
+      } catch (e) {
+        const msg = e?.response?.status === 404 ? `404 — server has no ${a.local} asset` : (e?.message || String(e));
+        console.error(`  ✗ Failed to fetch ${a.local}: ${msg}`);
+        process.exit(1);
+      }
+    }
+
+    if (opts.dryRun) {
+      console.log('');
+      console.log('Dry-run: would write the following files:');
+      for (const f of fetched) {
+        const target = path.join(repoRoot, f.local);
+        const exists = fs.existsSync(target);
+        console.log(`  ${exists ? '⚠' : '✓'} ${f.local}${exists ? ' (existing file would be backed up)' : ''}`);
+      }
+      console.log('  ✓ Would flip ci.gate -> local in pipeline config');
+      console.log('');
+      console.log('Re-run without --dry-run to apply.');
+      return;
+    }
+
+    // 3. Write the assets, backing up any existing files. If the default
+    //    .hone-backup already exists (re-run of setup-local-ci), use a
+    //    timestamped suffix so the FIRST run's backup — the only one that
+    //    has the adopter's actual original — is preserved.
+    function pickBackupPath(target) {
+      const def = target + '.hone-backup';
+      if (!fs.existsSync(def)) return def;
+      // .hone-backup-YYYYMMDD-HHMMSS — sortable, unique per second
+      const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15);
+      return target + `.hone-backup-${ts}`;
+    }
+    for (const f of fetched) {
+      const target = path.join(repoRoot, f.local);
+      if (fs.existsSync(target) && !opts.force) {
+        const backup = pickBackupPath(target);
+        fs.copyFileSync(target, backup);
+        console.log(`  ✓ Backed up existing ${f.local} → ${path.relative(repoRoot, backup)}`);
+      }
+      fs.writeFileSync(target, f.content);
+      console.log(`  ✓ Wrote ${f.local}`);
+    }
+
+    // 4. Flip ci.gate -> local in the existing pipeline config. CRITICAL:
+    //    `yaml.dump(parsed)` would strip every comment + reformat every
+    //    array/string — but `.pipeline-config.yml` is the file the
+    //    adopter is told to hand-edit, and our own generated config has
+    //    instructional comments. Instead, do a targeted in-place text
+    //    edit on the `gate:` line under `ci:` — preserve comments and
+    //    every other byte verbatim. A backup is written first so the
+    //    adopter can always recover.
+    const configBackup = pipelineConfigPath + (fs.existsSync(pipelineConfigPath + '.hone-backup')
+      ? `.hone-backup-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15)}`
+      : '.hone-backup');
+    fs.copyFileSync(pipelineConfigPath, configBackup);
+    console.log(`  ✓ Backed up pipeline config → ${path.relative(repoRoot, configBackup)}`);
+
+    const raw = fs.readFileSync(pipelineConfigPath, 'utf8');
+    let parsedPeek = null;
+    try { parsedPeek = yaml.load(raw); } catch { /* keep raw, work with regex */ }
+
+    // Detect prevGate via parse (best effort) — purely for the operator log line.
+    const prevGate = parsedPeek?.ci?.gate;
+
+    let updated;
+    if (/^ci:\s*$/m.test(raw)) {
+      // ci: block exists. Find it, see if `gate:` is inside; if yes, replace
+      // its value. Preserve any trailing `# comment` on the same line —
+      // adopters may have annotated the gate choice and we shouldn't lose it.
+      // If no gate: key inside the block, insert `gate: local` right after `ci:`.
+      const ciIdx = raw.search(/^ci:\s*$/m);
+      // Match: (head incl. ci: line) (indent + gate:) (value: word chars only) (trailing whitespace+comment+newline)
+      const gateInBlock = /^(ci:[\s\S]*?\n)(\s+gate:\s*)([A-Za-z0-9_-]+)(\s*(?:#[^\n]*)?\n)/m;
+      if (gateInBlock.test(raw.slice(ciIdx, ciIdx + 1500))) {
+        updated = raw.replace(gateInBlock, (_m, head, indent, _oldVal, trailing) =>
+          `${head}${indent}local${trailing}`,
+        );
+      } else {
+        // ci: block exists but no gate key. Insert it right after `ci:`.
+        updated = raw.replace(/^(ci:\s*\n)/m, `$1  gate: local\n  local_command: make ci\n`);
+      }
+    } else {
+      // No ci: block at all — append it at the end with the required keys.
+      updated = raw.replace(/\s*$/, '') + '\n\nci:\n  gate: local\n  local_command: make ci\n';
+    }
+
+    fs.writeFileSync(pipelineConfigPath, updated);
+    console.log(`  ✓ Flipped ci.gate: ${prevGate || '(absent)'} → local in pipeline config`);
+
+    // 5. Operator next steps. The label is unique-per-command (not the
+    //    shared "Next steps" string) so the H-012 post-setup anchor that
+    //    indexOf-scans for the post-setup checklist doesn't latch here.
+    console.log('');
+    console.log('Local CI next steps:');
+    console.log('  1. Open Makefile + replace the TODO sections with your stack\'s commands');
+    console.log('     (unit / regression / integration / e2e — `make help` lists every target)');
+    console.log('  2. Run `make ci` locally to verify every gate passes');
+    console.log('  3. Your next `hone run-story` will use local-mode CI gating —');
+    console.log('     step_5c will trust your local `make ci` instead of polling GitHub Actions');
+    console.log('');
+    console.log('Revert: set ci.gate back to "github" in your pipeline-config.yml');
+  });
+
 // ── SETUP command ─────────────────────────────────────────────────────────────
 program
   .command('setup')
   .description('Run setup-ai-pipeline.sh v3.1 — detects stack, scaffolds agents + skills')
   .option('--dry-run',         'Preview what would be created without writing files')
   .option('--non-interactive', 'Use detected defaults without prompting')
-  .option('--stack <stack>',   'Override stack detection (node|java|python|dotnet|salesforce)')
+  .option('--stack <stack>',   'Override stack detection (node|java|python|dotnet|salesforce|netsuite)')
   .option('--install-tests',   'Install unit test framework (vitest/jest/pytest) + create config')
   .option('--e2e',             'Also install Playwright E2E framework (use with --install-tests)')
   .option('--no-e2e',          'Skip Playwright even when --install-tests is set')
   .option('--no-branch-protection', 'Skip installing GitHub branch protection on the default branch (H-001)')
   .option('--refresh',           'Re-scan platform metadata without re-running full setup (HC-013c)')
+  .option('--ci-gate <mode>',    'HC-RC-004: CI gating mode (github | local | mixed | none). Skips interactive prompt.')
   .action(async (opts) => {
     const config = getConfig();
     const client = api(config);
@@ -417,23 +636,102 @@ program
       console.log('  (non-TTY detected — running in non-interactive mode)');
     }
 
+    // HC-RC-004: pick the ci.gate mode (interactive prompt with cost
+    // trade-off, --ci-gate flag, env var, or auto-detect — whichever
+    // applies). The chosen mode is passed via CI_GATE env var which
+    // setup-ai-pipeline.sh already reads (HC-101-followup-3 auto-detect
+    // path uses the same var as override). Choosing `local` ALSO
+    // triggers the setup-local-ci scaffold flow after setup completes,
+    // so the adopter ends the command with a working local-CI stack
+    // ready to use instead of having to know about the second command.
+    const { chooseCIGate } = require('./lib/ci-gate-chooser');
+    const ciGateChoice = await chooseCIGate({
+      flagMode: opts.ciGate,
+      nonInteractive: isNonInteractive,
+      repoRoot: process.cwd(),
+    });
+    console.log(`  ✓ ci.gate = ${ciGateChoice.mode} (source: ${ciGateChoice.source})`);
+    // HC-RC-004 pass-1 (MED-2): only lecture about ci.gate=none when the
+    // adopter LANDED there via auto-detect fallback (i.e. they didn't
+    // explicitly pick it). Explicit choices (--ci-gate=none, env, prompt)
+    // mean they know what they want — don't re-warn on every setup re-run.
+    if (ciGateChoice.mode === 'none' && ciGateChoice.source === 'auto-detect') {
+      console.log('  ⚠ ci.gate=none means NO CI verification. Run `hone setup-local-ci` later');
+      console.log('    to switch to local-mode (real safety net at $0 CI cost).');
+    }
+
     const flags = [
       `--source "${path.join(tmpDir, 'enterprise-github')}"`,
       opts.dryRun      ? '--dry-run'         : '',
       isNonInteractive ? '--non-interactive'  : '',
     ].filter(Boolean).join(' ');
 
+    // HC-RC-004 pass-1 (HIGH-1): when source==='auto-detect', LEAVE
+    // CI_GATE unset so the bash script's existing detected_ci_default
+    // logic owns the call. Defense against JS+bash detector drift —
+    // they have to agree forever if both decide. Only force CI_GATE when
+    // the adopter explicitly chose (flag / env / prompt).
+    const setupEnv = { ...process.env };
+    if (ciGateChoice.source !== 'auto-detect') {
+      setupEnv.CI_GATE = ciGateChoice.mode;
+    }
     try {
       execSync(`bash "${scriptPath}" ${flags}`, {
         stdio: 'inherit',
         cwd: process.cwd(),
-        env: { ...process.env },
+        env: setupEnv,
       });
     } catch (e) {
       console.error('Setup script failed:', e.message);
       process.exit(1);
     }
 
+    // HC-RC-004: if the adopter chose `local`, run the setup-local-ci
+    // scaffold inline so they end the setup command with a working
+    // local-CI stack (Makefile + compose) instead of having to know
+    // about a second command. Skipped on --dry-run + when a Makefile
+    // already exists at the repo root (auto-detect would have picked
+    // `local`; nothing more to scaffold).
+    if (ciGateChoice.mode === 'local' && !opts.dryRun) {
+      const repoRootForScaffold = process.cwd();
+      const makefileExists = fs.existsSync(path.join(repoRootForScaffold, 'Makefile'));
+      if (!makefileExists) {
+        console.log('');
+        console.log('HC-RC-004: scaffolding HC-101 Makefile + compose.local-ci.yml for local mode...');
+        try {
+          const assets = [
+            { remote: '/scripts/local-ci/makefile', local: 'Makefile' },
+            { remote: '/scripts/local-ci/compose',  local: 'compose.local-ci.yml' },
+          ];
+          // HC-RC-004 pass-1 (MED-1): each asset gets the same
+          // backup-on-exist treatment setup-local-ci uses (HC-101-followup-3
+          // timestamped-backup lesson). The Makefile branch is already
+          // gated above; the compose file also needs the same defense so
+          // an adopter who hand-rolled compose.local-ci.yml first then
+          // re-ran setup doesn't lose customizations.
+          for (const a of assets) {
+            const target = path.join(repoRootForScaffold, a.local);
+            if (fs.existsSync(target)) {
+              const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15);
+              const backup = `${target}.hone-backup-${ts}`;
+              fs.copyFileSync(target, backup);
+              console.log(`  ✓ Backed up existing ${a.local} → ${path.basename(backup)}`);
+            }
+            const { data } = await client.get(a.remote, { responseType: 'text', transformResponse: [(d) => d] });
+            fs.writeFileSync(target, String(data));
+            console.log(`  ✓ Wrote ${a.local}`);
+          }
+          console.log('  → Customize Makefile TODO sections, then run `make ci` to verify');
+        } catch (e) {
+          console.log(`  ⚠ Could not scaffold local-CI assets: ${e.message}`);
+          console.log('    Run `hone setup-local-ci` to retry the scaffold step.');
+        }
+      } else {
+        console.log('  ℹ Existing Makefile detected — skipping local-CI scaffold');
+        console.log('    (the auto-detect path already picked `local` for you)');
+      }
+    }
+
     // ── Phase 1b: Install CLAUDE.md ──────────────────────────────────────────
     // HC-019y: removed the install-time .github/agents/ -> .claude/agents/
     // mirror. The bash setup script now writes agents directly to
@@ -1160,6 +1458,11 @@ program
       if (result.skills) {
         let preservedCount = 0;
         let sidecarCount = 0;
+        let evalScenariosCount = 0;
+        // HC-010d pass-2 HIGH: per-skill eval-scenarios.json payload.
+        const evalScenarios = (result.evalScenarios && typeof result.evalScenarios === 'object')
+          ? result.evalScenarios
+          : {};
         for (const [skillName, content] of Object.entries(result.skills)) {
           if (!content || content.length < 50) continue;
           const skillDir  = path.join(repoRoot, '.github', 'skills', skillName);
@@ -1183,6 +1486,19 @@ program
               console.log(`  ✓ .github/skills/${skillName}/SKILL.md`);
             }
           }
+          // HC-010d pass-2 HIGH: write eval-scenarios.json sibling if the
+          // server validated one for this skill. Skip null/undefined/empty
+          // (parseOutput validator dropped malformed blocks already).
+          const scenarios = evalScenarios[skillName];
+          const isEmpty = !scenarios
+            || (Array.isArray(scenarios) && scenarios.length === 0)
+            || (typeof scenarios === 'object' && Object.keys(scenarios).length === 0);
+          if (!isEmpty) {
+            const evalFile = path.join(skillDir, 'eval-scenarios.json');
+            fs.writeFileSync(evalFile, JSON.stringify(scenarios, null, 2) + '\n');
+            evalScenariosCount++;
+            console.log(`  ✓ .github/skills/${skillName}/eval-scenarios.json`);
+          }
         }
         if (preservedCount > 0) {
           console.log(`\n  Preserved adopter REPO-SPECIFIC content in ${preservedCount} skill(s).`);
@@ -1194,6 +1510,10 @@ program
           console.log(`  To opt into automatic splice protection on the next derive, add a`);
           console.log(`  '<!-- REPO-SPECIFIC -->' marker to the original file.`);
         }
+        if (evalScenariosCount > 0) {
+          console.log(`\n  Wrote ${evalScenariosCount} eval-scenarios.json file(s) (HC-010d).`);
+          console.log(`  Future executor (hone skill-eval, HC-010d-followup-1) will probe these.`);
+        }
       }
 
       // H-022: surface parser warnings so silent drops become VISIBLE failures.
@@ -2209,7 +2529,7 @@ program
     const branchSamples = [];
     try {
       const out = execSync('git for-each-ref --sort=-committerdate --count=30 --format=%(refname:short) refs/heads/ refs/remotes/', {
-        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
       });
       branchSamples.push(...out.split('\n').filter(Boolean));
     } catch { /* not a git repo — skip */ }
@@ -2320,6 +2640,26 @@ program
     const repoRoot = process.cwd();
     const results = [];
 
+    // Pass-2 review LOW (HC-020e): validate --check against the
+    // allowlist of known sub-checks. Before this, a typo (e.g.,
+    // `--check architectur`) silently ran nothing and exited 0,
+    // which is the worst doctor outcome ("looks healthy" but
+    // actually skipped everything).
+    const KNOWN_CHECKS = new Set([
+      'all',
+      'docs',
+      'admin-merge',
+      'bind-default',
+      'placeholders',
+      'skill-staleness',
+      'architecture',
+    ]);
+    if (!KNOWN_CHECKS.has(opts.check)) {
+      const known = [...KNOWN_CHECKS].sort().join(', ');
+      console.error(`✗ --check: unknown name "${opts.check}". Known checks: ${known}`);
+      process.exit(2);
+    }
+
     // Read .pipeline-config.yml to learn the stack
     let stack = 'unknown';
     try {
@@ -2394,6 +2734,15 @@ program
       results.push(checkSkillStaleness({ repoRoot }));
     }
 
+    // HC-020e: architecture staleness check — flags drift in
+    // docs/sdlc/ARCHITECTURE.md based on the `<!-- Generated by
+    // derive-domain-skills on YYYY-MM-DD -->` marker the derive prompt
+    // now emits (companion change in this PR).
+    if (opts.check === 'all' || opts.check === 'architecture') {
+      const { checkArchitectureStaleness } = require('./lib/doctor-architecture');
+      results.push(checkArchitectureStaleness({ repoRoot }));
+    }
+
     // Render
     if (opts.json) {
       console.log(JSON.stringify({ checks: results }, null, 2));
@@ -2406,7 +2755,9 @@ program
           : r.status === 'drift' ? '✗'
           : r.status === 'info' ? 'ℹ'
           : '⚠';
-        const label = r.name === 'docs' ? 'Docs freshness' : r.name;
+        const label = r.name === 'docs' ? 'Docs freshness'
+                    : r.name === 'architecture' ? 'Architecture staleness'
+                    : r.name;
         console.log(`${icon} ${label} — ${r.reason}`);
         if (r.suggestedFix) {
           console.log(`  Fix: ${r.suggestedFix}`);
@@ -4102,7 +4453,7 @@ program
     let branchName = '';
     try {
       branchName = execSync('git rev-parse --abbrev-ref HEAD',
-        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
     } catch { /* defensive */ }
     const storyId = cmdOpts.storyId || extractStoryIdFromBranch(branchName);
     if (!storyId) {
@@ -4115,12 +4466,12 @@ program
     let diff = '';
     try {
       diff = execSync(`git diff origin/${baseBranch}...HEAD`,
-        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
+        { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
     } catch {
       // Fallback: no remote tracking — try local base
       try {
         diff = execSync(`git diff ${baseBranch}...HEAD`,
-          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
+          { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
       } catch { /* leave empty */ }
     }
 
@@ -4248,6 +4599,7 @@ program
   .option('--snapshot', 'Save current eval + contract results as regression baseline')
   .option('--regression', 'Compare current results against saved baseline (detect drift)')
   .option('--judge', 'Run LLM-as-judge scenarios (requires ANTHROPIC_API_KEY, costs tokens)')
+  .option('--evidence-mode <mode>', 'HC-RC-001 editor-LLM evidence transfer: "local" writes .hone/eval-evidence.json (signed); "off" disables (default)')
   .action(async (opts) => {
     const path = require('path');
     const fs = require('fs');
@@ -4336,7 +4688,27 @@ program
       // LLM call function using Anthropic API
       async function callLLM(systemPrompt, userPrompt) {
         const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-          model: 'claude-sonnet-4-20250514',
+          // MODEL CHOICE (per feedback_model_choice_cost_amplifier): Sonnet tier,
+          // deliberately NOT Opus. The eval judge is not one of the three
+          // load-bearing SDLC agents on the OPUS_AGENTS allowlist (architect,
+          // security, code-reviewer — HC-COMM-007); it grades eval scenarios,
+          // where Sonnet is sufficient and Opus would be a 2.5x input-cost
+          // escalation on a call site that can run once per scenario.
+          //
+          // Previously a dated 2025-05-14 Sonnet id, which Anthropic deprecated
+          // with a 2026-06-15 deadline. The #507 Opus 4.8 sweep missed this call
+          // site because it searched only for opus ids. Pinned by
+          // tests/regression/opus-4-8-upgrade.test.js — note that suite forbids
+          // the retired id even inside comments, so name it descriptively here.
+          model: 'claude-sonnet-5',
+          // Sonnet 5 runs ADAPTIVE THINKING when `thinking` is omitted, unlike
+          // the dated Sonnet 4 model this replaced. Two consequences if left
+          // default, both silent: content[0] becomes a `thinking` block (so a
+          // [0].text read returns undefined and every judge criterion fails to
+          // parse), and thinking tokens share max_tokens with the answer.
+          // The judge returns a short structured verdict, so keep it off and
+          // preserve the previous cost/latency profile.
+          thinking: { type: 'disabled' },
           max_tokens: 2048,
           system: systemPrompt,
           messages: [{ role: 'user', content: userPrompt }],
@@ -4348,7 +4720,10 @@ program
           },
           timeout: 60000,
         });
-        return data.content?.[0]?.text || '';
+        // Select the first TEXT block rather than content[0]: any future model
+        // or config that emits a leading thinking block must not silently
+        // degrade every scenario to "could not parse response".
+        return (data.content || []).find(b => b?.type === 'text')?.text || '';
       }
 
       console.log(`Running ${judgeScenarios.length} LLM-judge scenario(s)...`);
@@ -4413,9 +4788,232 @@ program
     const results = runAllScenarios(scenarios, AGENT_PROMPTS, { failFast: opts.failFast });
     console.log(formatResults(results, opts.format));
 
+    // HC-RC-001: optionally write signed eval-evidence so CI can short-circuit
+    // the LLM-cost gate. No-op when --evidence-mode is omitted or "off", or
+    // when prerequisites (HONE_EVIDENCE_SECRET + diff input + metadata) are
+    // missing. Skips with stderr warning rather than failing the eval run.
+    try {
+      const {
+        normalizeEvidenceMode,
+        buildEvidenceFromEval,
+        writeEvidenceFile,
+      } = require('./lib/eval-evidence');
+      const mode = normalizeEvidenceMode(opts.evidenceMode);
+      if (mode === 'local') {
+        const record = buildEvidenceFromEval({ results, mode });
+        if (record) {
+          const out = writeEvidenceFile(record);
+          process.stderr.write(`[hone eval] evidence-mode=local wrote ${out}\n`);
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`[hone eval] evidence-mode error: ${e.message}\n`);
+    }
+
     process.exit(results.failed + results.errors > 0 ? 1 : 0);
   });
 
+// ── HC-010d-followup-1: hone skill-eval runtime executor ────────────────────
+//
+// Consumes the eval-scenarios.json artifacts that HC-010d emits next to
+// every derived <stack>-developer/SKILL.md and <stack>-architect/SKILL.md.
+// Distinct from `hone eval` (HC-019d) which grades AGENT PROMPTS
+// deterministically — `hone skill-eval` grades DERIVED SKILL OUTPUTS by
+// calling an LLM and scoring against expected_output_keywords +
+// expected_output_format heuristics. Two systems, two different
+// questions; coexist.
+//
+// Provider defaults to gh-models (free GH PAT inference) per the
+// [Pipeline LLM Cost Reduction] memory — adopters must not be
+// double-billed for what their pipeline already invoked.
+program
+  .command('skill-eval <skillName>')
+  .description('Run derived-skill eval scenarios against an LLM (HC-010d-followup-1)')
+  .option('--provider <name>', 'LLM provider: gh-models (default, $0) | claude-haiku (paid)', 'gh-models')
+  .option('--scenario <id>', 'Run a single scenario by id (e.g., SF-DEV-EVAL-001)')
+  .option('--tag <tag>', 'Filter scenarios by HC-010c rule-id tag (e.g., SF-SEC-001)')
+  .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
+  .option('--fail-fast', 'Stop on first non-pass scenario')
+  .option('--no-llm', 'Dry run: validate scenarios + print plan without calling the LLM')
+  .option('--repo-root <path>', 'Override the repo root used for SKILL.md / eval-scenarios.json lookup')
+  .action(async (skillName, opts) => {
+    const fsLocal   = require('fs');
+    const pathLocal = require('path');
+    const repoRoot  = opts.repoRoot || process.cwd();
+
+    const { validateScenarios } = require(
+      pathLocal.resolve(__dirname, '..', 'server', 'src', 'services', 'eval-scenarios')
+    );
+    const {
+      loadSkillEvalScenarios,
+      runAllSkillScenarios,
+      formatResults,
+    } = require('./lib/skill-eval-runner');
+
+    const loaded = loadSkillEvalScenarios({
+      repoRoot, skillName, fs: fsLocal, path: pathLocal, validateScenarios,
+    });
+    if (!loaded.ok) {
+      console.error(`✗ hone skill-eval: cannot load ${skillName}`);
+      for (const e of loaded.errors) {
+        console.error(`  ${e.path}: ${e.message}`);
+      }
+      process.exit(2);
+    }
+
+    // Apply --scenario / --tag filters.
+    let scenarios = loaded.scenarios;
+    if (opts.scenario) {
+      scenarios = scenarios.filter((s) => s.id === opts.scenario);
+      if (scenarios.length === 0) {
+        console.error(`✗ no scenario with id "${opts.scenario}" in ${loaded.scenariosPath}`);
+        process.exit(2);
+      }
+    }
+    if (opts.tag) {
+      scenarios = scenarios.filter((s) => (s.tags || []).includes(opts.tag));
+      if (scenarios.length === 0) {
+        console.error(`✗ no scenarios tagged "${opts.tag}" in ${loaded.scenariosPath}`);
+        process.exit(2);
+      }
+    }
+
+    // --no-llm: validate + print plan, exit 0. Lets adopters check shape
+    // without spending tokens or burning CI minutes (per the memory
+    // [CI Minutes Budget]).
+    //
+    // commander.js converts `--no-llm` to opts.llm = false.
+    if (opts.llm === false) {
+      console.log(`Hone Skill Eval — dry run (--no-llm)`);
+      console.log('====================================');
+      console.log(`Skill:           ${loaded.skill}`);
+      console.log(`SKILL.md:        ${loaded.skillPath}`);
+      console.log(`eval-scenarios:  ${loaded.scenariosPath}`);
+      console.log(`Scenarios:       ${scenarios.length} matched`);
+      console.log('');
+      for (const s of scenarios) {
+        const tagStr = s.tags?.length ? `  [${s.tags.join(', ')}]` : '';
+        console.log(`  ${s.id}  ${s.category.padEnd(16)} ${s.name}${tagStr}`);
+      }
+      process.exit(0);
+    }
+
+    // Provider wiring — gh-models default. Inline + per-provider so a
+    // future provider addition lives in one switch.
+    const axios = require('axios');
+    // Pass-2 review caught the original 32000-char slice collided with
+    // GH Models' documented 8000-token request-body cap (see
+    // `cli/lib/release-review-config.js:49-68`). A real adopter
+    // SKILL.md after years of derivations is plausibly 20-40K chars;
+    // 32K leaves zero budget for scenario.input + JSON envelope, so
+    // GH Models returns HTTP 400 and every scenario errors. 8000
+    // chars ≈ ~2000 tokens for the system slot, leaving ~6000 tokens
+    // for scenario.input + envelope — comfortable under GH Models'
+    // cap while still preserving enough of the skill body to evaluate
+    // adopter patterns.
+    const MAX_SKILL_PROMPT_CHARS = 8000;
+    let apiKey, modelLabel, callLLM;
+    if (opts.provider === 'gh-models') {
+      apiKey = process.env.GITHUB_TOKEN;
+      if (!apiKey) {
+        console.error('✗ GITHUB_TOKEN not set. Required for --provider gh-models.');
+        console.error('  In CI: GITHUB_TOKEN is auto-injected. Locally: export GITHUB_TOKEN=<your PAT>.');
+        // Exit 2 — operator config error, NOT a skill regression.
+        // Pass-2 review caught: exit 1 collided with the CI-gate exit
+        // code for eval failures, so a missing secret was reported
+        // as "skill regression" by the CI gate. The convention from
+        // the regression at line 172-188 is exit 2 for operator
+        // errors, exit 1 for eval failures.
+        process.exit(2);
+      }
+      modelLabel = 'openai/gpt-4.1';
+      callLLM = async (systemPrompt, userPrompt) => {
+        const { data } = await axios.post(
+          'https://models.github.ai/inference/chat/completions',
+          {
+            model: modelLabel,
+            messages: [
+              { role: 'system', content: systemPrompt.slice(0, MAX_SKILL_PROMPT_CHARS) },
+              { role: 'user',   content: userPrompt },
+            ],
+            max_tokens: 2048,
+          },
+          {
+            headers: {
+              'Authorization': `Bearer ${apiKey}`,
+              'Content-Type': 'application/json',
+            },
+            timeout: 120000,
+          }
+        );
+        return data.choices?.[0]?.message?.content || '';
+      };
+    } else if (opts.provider === 'claude-haiku') {
+      apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        console.error('✗ ANTHROPIC_API_KEY not set. Required for --provider claude-haiku.');
+        console.error('  Set: export ANTHROPIC_API_KEY=sk-ant-...');
+        // Exit 2 — operator config error (see gh-models branch).
+        process.exit(2);
+      }
+      modelLabel = 'claude-haiku-4-5-20251001';
+      callLLM = async (systemPrompt, userPrompt) => {
+        const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
+          model: modelLabel,
+          max_tokens: 2048,
+          system: systemPrompt.slice(0, MAX_SKILL_PROMPT_CHARS),
+          messages: [{ role: 'user', content: userPrompt }],
+        }, {
+          headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json',
+          },
+          timeout: 120000,
+        });
+        return data.content?.[0]?.text || '';
+      };
+    } else {
+      console.error(`✗ Invalid --provider: ${opts.provider}. Use 'gh-models' or 'claude-haiku'.`);
+      process.exit(2);
+    }
+
+    // Stream progress so the operator sees a heartbeat on long runs
+    // (8-15 dev scenarios × ~5-20s LLM round-trip = 1-5 min per skill).
+    const onProgress = (cur, total, lastResult) => {
+      if (opts.format === 'json') return; // JSON mode is silent until the final dump
+      const icon = lastResult.result === 'pass' ? '✓'
+                 : lastResult.result === 'fail' ? '✗'
+                 : '!';
+      process.stderr.write(
+        `  [${cur}/${total}] ${icon} ${lastResult.id} — ${lastResult.name}\n`
+      );
+    };
+
+    if (opts.format !== 'json') {
+      console.log(`Hone Skill Eval — ${loaded.skill}`);
+      console.log(`Provider: ${opts.provider} (${modelLabel})`);
+      console.log(`Scenarios: ${scenarios.length}`);
+      console.log('');
+    }
+
+    const summary = await runAllSkillScenarios({
+      scenarios,
+      skillContent: loaded.skillContent,
+      callLLM,
+      failFast: opts.failFast,
+      onProgress,
+    });
+
+    console.log(formatResults(summary, opts.format));
+
+    // Exit 1 on any non-pass so CI (HC-019f-style gate) can wire this
+    // as a required check. Per the [Pipeline LLM Cost Reduction]
+    // memory, this gate can run in CI on the gh-models default with
+    // zero adopter cost.
+    process.exit(summary.failed + summary.errors > 0 ? 1 : 0);
+  });
+
 // ── HC-041: Run Story (Orchestrator) ─────────────────────────────────────────
 program
   .command('run-story <storyId>')
@@ -4523,8 +5121,16 @@ program
     // fail, private repo without auth): warn and proceed without context.
     // The existing HC-019n-followup-7 hard_pause safety net catches the
     // resulting placeholder cascade at step_1.
+    //
+    // HC-019b-followup-1 F1: when invoked with an issue number, also try
+    // to extract a canonical story-id (e.g. HC-019b) from the issue title.
+    // Used by the architect-config read below — without this, the lookup
+    // keys on '104' instead of 'HC-019b' and silently bypasses every
+    // architect-engaged story whose EXECUTION_PLAN.yml entry uses the
+    // canonical id (which is the common adopter case).
     const orchestrateConfig = {};
     let issueBodyForFiles = null;
+    let resolvedStoryId = storyIdOrRunId; // canonical id for architect-config lookup
     if (/^\d+$/.test(storyIdOrRunId)) {
       try {
         const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf8' }).trim();
@@ -4540,10 +5146,25 @@ program
         orchestrateConfig.story_description = desc;
         issueBodyForFiles = `${issue.title}\n${issue.body || ''}`;
         console.log(`  → fetched GitHub issue #${storyIdOrRunId} for story context (${desc.length} chars)`);
+        // HC-019b-followup-1 F1: extract the canonical story-id from the
+        // issue title. extractStoryIdFromBranch's regex (STORY_ID_PATTERN
+        // in pipeline-status.js) handles HC-NNN, HC-NNN-A, H-NNNb, E22-D,
+        // and HC-NNN-followup-N shapes after H-029-followup-2.
+        try {
+          const { extractStoryIdFromBranch } = require('./lib/pipeline-status');
+          const titleId = extractStoryIdFromBranch(issue.title);
+          if (titleId) {
+            resolvedStoryId = titleId;
+            console.log(`  → resolved issue #${storyIdOrRunId} → canonical story id '${titleId}' for architect-config lookup`);
+          } else {
+            console.warn(`  ⚠ could not extract canonical story id from issue title '${issue.title}' — architect-config lookup will use '${storyIdOrRunId}' (likely silent miss)`);
+          }
+        } catch { /* extractor missing/throws → fall back to numeric id */ }
       } catch (e) {
         const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
         console.warn(`  ⚠ could not fetch GitHub issue context: ${msg}`);
         console.warn('  → proceeding without story_description; step_0 may produce placeholder output');
+        console.warn(`  ⚠ architect-config lookup will use '${storyIdOrRunId}' (likely silent miss)`);
       }
     }
 
@@ -4625,6 +5246,49 @@ program
       }
     }
 
+    // HC-101-followup-2: pass the adopter's CI gate config to the
+    // orchestrator so step_5c can branch (github / local / both / none).
+    // Defaults to gate=github + local_command='make ci' when the config
+    // is missing — backward-compat for adopters whose .pipeline-config.yml
+    // predates this field.
+    try {
+      const { readCIGateConfig } = require('./lib/pipeline-config');
+      const ciGate = readCIGateConfig(process.cwd());
+      orchestrateConfig.ci_gate = ciGate.gate;
+      orchestrateConfig.ci_local_command = ciGate.local_command;
+      console.log(`  → CI gate mode: ${ciGate.gate}${ciGate.gate !== 'github' ? ` (local_command: ${ciGate.local_command})` : ''}`);
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`  ⚠ CI gate config read failed (non-fatal, defaulting to gate=github): ${msg}`);
+      orchestrateConfig.ci_gate = 'github';
+      orchestrateConfig.ci_local_command = 'make ci';
+    }
+
+    // HC-019b: read per-story architect flags from .github/EXECUTION_PLAN.yml
+    // and plumb them into workflow_runs.config. The orchestrator's
+    // validateStepPreConditions (server/src/services/workflow-dag.js:340)
+    // BLOCKS step_1 when architect_consulted=true but checklist_b_completed=false.
+    // Without this plumbing, the HC-019a flags written by the architect prompt
+    // never reach the server and every architect-engaged story deadlocks.
+    // Defaults to {false, false} when the file/story/config is missing —
+    // i.e., assume the architect was not consulted (no block).
+    //
+    // Code-review F2/F3: malformed YAML or missing story entry was previously
+    // silent. The helper now returns a `diagnostic` string for those cases;
+    // we surface it as a console.warn so operators see the silent-bypass.
+    // HC-019b-followup-1 F1: use the resolved canonical story-id (HC-NNN)
+    // not the raw `storyIdOrRunId` which is the issue number when invoked
+    // as `hone run-story 104`. The HC-019n-followup-11 block above sets
+    // resolvedStoryId to the title-extracted id when it can.
+    const { readArchitectConfig } = require('./lib/architect-config');
+    const arch = readArchitectConfig(process.cwd(), resolvedStoryId);
+    orchestrateConfig.architect_consulted  = arch.architect_consulted;
+    orchestrateConfig.checklist_b_completed = arch.checklist_b_completed;
+    if (arch.diagnostic) console.warn(`  ⚠ ${arch.diagnostic}`);
+    if (arch.architect_consulted) {
+      console.log(`  → architect_consulted: true, checklist_b_completed: ${arch.checklist_b_completed}`);
+    }
+
     try {
       const { data } = await client.post('/orchestrate', {
         storyId: storyIdOrRunId, repoName, branch, mode: opts.mode, config: orchestrateConfig,
@@ -4923,33 +5587,94 @@ program
       catch { branch = null; }
     }
 
+    // HC-019b: read EXECUTION_PLAN.yml ONCE up front so the per-story lookup
+    // doesn't re-stat the disk for each line. Empty text \u2192 all stories get
+    // the {false, false} default per architect-config.js. Try/catch keeps
+    // the batch path resilient if the file is missing or unreadable.
+    let planText = '';
+    try {
+      const planPath = path.join(process.cwd(), '.github', 'EXECUTION_PLAN.yml');
+      if (fs.existsSync(planPath)) planText = fs.readFileSync(planPath, 'utf8');
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`\u26a0 EXECUTION_PLAN.yml read failed for batch (non-fatal, architect flags default to {false, false}): ${msg}`);
+    }
+    const { readArchitectConfigFromText } = require('./lib/architect-config');
+
     // HC-059: parse `STORY-A depends:STORY-B,STORY-C` per-line syntax. The
     // `depends:` token is case-sensitive and must come AFTER the storyId.
     // Multiple deps separated by commas, whitespace tolerant. Lines without
     // `depends:` yield no `dependsOn` (server validates absence vs empty).
+    // HC-019b: attach per-story `config: { architect_consulted, checklist_b_completed }`
+    // \u2014 the server's createBatch (batch-store.js:218) spreads s.config into each
+    // workflow_runs.config row, so this is the load-bearing plumbing for
+    // validateStepPreConditions (workflow-dag.js:340) in batch mode.
     const stories = storyIds.map(line => {
       const depsMatch = line.match(/^(\S+)\s+depends:(\S+)\s*$/);
+      let storyId, dependsOn;
       if (depsMatch) {
         const [, id, depsCsv] = depsMatch;
-        const dependsOn = depsCsv.split(',').map(s => s.trim()).filter(Boolean);
-        return { storyId: id, repoName, branch, dependsOn };
-      }
-      // Reject ambiguous lines (storyId followed by garbage) \u2014 better than
-      // silently treating `STORY-A something` as just `STORY-A`.
-      if (/\s/.test(line)) {
-        console.error(`Malformed line in --file: "${line}"`);
-        console.error(`  Expected: "STORY-ID"  OR  "STORY-ID depends:STORY-B,STORY-C"`);
-        process.exit(1);
-      }
-      return { storyId: line, repoName, branch };
+        storyId = id;
+        dependsOn = depsCsv.split(',').map(s => s.trim()).filter(Boolean);
+      } else {
+        // Reject ambiguous lines (storyId followed by garbage) \u2014 better than
+        // silently treating `STORY-A something` as just `STORY-A`.
+        if (/\s/.test(line)) {
+          console.error(`Malformed line in --file: "${line}"`);
+          console.error(`  Expected: "STORY-ID"  OR  "STORY-ID depends:STORY-B,STORY-C"`);
+          process.exit(1);
+        }
+        storyId = line;
+        dependsOn = undefined;
+      }
+      const arch = readArchitectConfigFromText(planText, storyId);
+      // Code-review F2/F3: surface silent-bypass diagnostics per story in
+      // the batch path too. Multi-story batches with one bad plan line
+      // would previously disable the contract for ALL stories silently.
+      if (arch.diagnostic) console.warn(`  ⚠ [${storyId}] ${arch.diagnostic}`);
+      const obj = {
+        storyId,
+        repoName,
+        branch,
+        config: {
+          architect_consulted:  arch.architect_consulted,
+          checklist_b_completed: arch.checklist_b_completed,
+        },
+      };
+      if (Array.isArray(dependsOn) && dependsOn.length > 0) obj.dependsOn = dependsOn;
+      return obj;
     });
 
     // HC-054: Night Shift opt-in. config.overnight=true plumbs end-to-end
     // (server validates the 25-story cap + applies default token budget +
     // denormalizes flag into each child's workflow_runs.config).
     const body = { stories };
+    body.config = body.config || {};
     if (opts.overnight) {
-      body.config = { overnight: true };
+      body.config.overnight = true;
+    }
+
+    // HC-101-followup-2: plumb the adopter's CI gate config to every story
+    // in the batch. Without this, the batch path would silently default to
+    // gate=github on the server even when .pipeline-config.yml says local/none —
+    // exactly the "silent skip" the design warned against. Same try/catch
+    // pattern as the run-story path (cli/hone-cli.js ~L4628).
+    try {
+      const { readCIGateConfig, DEFAULT_CI_LOCAL_COMMAND } = require('./lib/pipeline-config');
+      const ciGate = readCIGateConfig(process.cwd());
+      body.config.ci_gate = ciGate.gate;
+      body.config.ci_local_command = ciGate.local_command;
+      if (ciGate.gate !== 'github') {
+        console.log(`CI gate mode for batch: ${ciGate.gate} (local_command: ${ciGate.local_command})`);
+      }
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`⚠ CI gate config read failed for batch (non-fatal, defaulting to gate=github): ${msg}`);
+      body.config.ci_gate = 'github';
+      try {
+        const { DEFAULT_CI_LOCAL_COMMAND } = require('./lib/pipeline-config');
+        body.config.ci_local_command = DEFAULT_CI_LOCAL_COMMAND;
+      } catch { body.config.ci_local_command = 'make ci'; }
     }
 
     try {
@@ -4980,6 +5705,71 @@ program
     }
   });
 
+// ── HC-054g: Night-shift retroactive revert command ─────────────────────────
+//
+// Two-step operator workflow after rejected_rate drift (HC-054c) flags a
+// batch of bad overnight auto-approves:
+//
+//   1. `hone night-shift revert <runId> --step-key <key> --revert-pr <url>`
+//   2. CLI calls POST /night-shift/runs/:runId/retroactive-reject (if not yet)
+//      then POST /night-shift/runs/:runId/revert with the revert PR URL.
+//
+// We deliberately don't take repo write access; the operator runs the git
+// revert themselves and passes the resulting revert-PR URL. This keeps the
+// server side free of GitHub credentials + repo-specific permissions while
+// still giving the audit log the revert provenance.
+const nightShiftCmd = program.command('night-shift').description('HC-054 night-shift audit + revert workflow');
+nightShiftCmd
+  .command('revert <runId>')
+  .description('Record a revert action for a retroactively-rejected overnight auto-approve')
+  .requiredOption('--step-key <stepKey>', 'The step_key whose auto-approve produced the bad output (e.g. step_4 or step_5)')
+  .requiredOption('--revert-pr <url>', 'GitHub PR URL of the revert commit (https://github.com/.../pull/<n>)')
+  .option('--reason <reason>', 'Free-text reason for the retroactive rejection (recorded with the audit row)')
+  .action(async (runId, opts) => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      // Step 1: retroactively-reject if not yet rejected. The endpoint
+      // returns 409 if already rejected — we treat that as a no-op
+      // (operator may have done step 1 yesterday, run revert today).
+      try {
+        await client.post(`/night-shift/runs/${runId}/retroactive-reject`, {
+          stepKey: opts.stepKey,
+          reason: opts.reason,
+        });
+        console.log(`[night-shift] retroactively rejected (runId=${runId}, stepKey=${opts.stepKey})`);
+      } catch (e) {
+        const status = e.response?.status;
+        if (status === 409) {
+          console.log(`[night-shift] already retroactively rejected (continuing to revert step)`);
+        } else if (status === 404) {
+          console.error(`hone night-shift revert failed: no auto-approve audit row for (runId=${runId}, stepKey=${opts.stepKey})`);
+          process.exit(1);
+        } else {
+          throw e;
+        }
+      }
+
+      // Step 2: record the revert PR URL.
+      const r = await client.post(`/night-shift/runs/${runId}/revert`, {
+        stepKey: opts.stepKey,
+        revertPrUrl: opts.revertPr,
+      });
+      console.log(`[night-shift] revert recorded:`);
+      console.log(`  runId:             ${r.data.runId}`);
+      console.log(`  stepKey:           ${r.data.stepKey}`);
+      console.log(`  revertInitiatedAt: ${r.data.revertInitiatedAt}`);
+      console.log(`  revertPrUrl:       ${r.data.revertPrUrl}`);
+    } catch (e) {
+      const msg = e.response?.data?.error || e.message;
+      console.error(`hone night-shift revert failed: ${msg}`);
+      if (e.response?.data?.remediation) {
+        console.error(`Remediation: ${e.response.data.remediation}`);
+      }
+      process.exit(1);
+    }
+  });
+
 // ── HC-056: Schedule install (GitHub Actions overnight template) ────────────
 //
 // Installs a parameterized .github/workflows/<name>.yml that runs `hone
@@ -5001,6 +5791,9 @@ program
   .option('--file <path>', 'Default stories file path (relative to repo root)', 'stories.txt')
   .option('--out <dir>', 'Output directory for the workflow file', '.github/workflows')
   .option('--force', 'Overwrite existing workflow file', false)
+  .option('--overnight <mode>',
+    'Night Shift mode: auto (default — derives from cron hour) | yes | no (HC-054f)',
+    'auto')
   .action(async (action, opts) => {
     if (action !== 'install') {
       console.error(`Unknown schedule action: ${action}. Supported: install`);
@@ -5026,6 +5819,22 @@ program
       process.exit(1);
     }
 
+    // HC-054f: derive whether the workflow should pass --overnight to
+    // queue-stories. Defaults to 'auto' which inspects the cron hour.
+    // Pass-1 review HIGH #1 fix: validate the mode value UPFRONT and
+    // exit non-zero on typos — otherwise `--overnight YES` or
+    // `--overnight on` silently fell back to auto, contradicting
+    // adopter intent.
+    const { analyzeCron, resolveOvernight, isKnownOvernightMode } = require('./lib/schedule-cron');
+    if (!isKnownOvernightMode(opts.overnight)) {
+      console.error(`Invalid --overnight value "${opts.overnight}".`);
+      console.error('Accepted: auto (default — derives from cron hour) | yes | no');
+      console.error('Aliases: true/false/1/0/on/off/enable/disable also work (case-insensitive).');
+      process.exit(1);
+    }
+    const cronAnalysis = analyzeCron(opts.cron);
+    const overnightDecision = resolveOvernight(opts.overnight, cronAnalysis);
+
     const config = getConfig();
     const client = api(config);
 
@@ -5054,10 +5863,16 @@ program
 
     // 2. Substitute placeholders. Use replace-all so any future template
     // additions referencing the same placeholder are handled.
+    // HC-054f: {{OVERNIGHT_FLAG}} → either ` --overnight` (with leading
+    // space) or empty string. The leading space keeps the queue-stories
+    // command tidy when the flag is absent. Templates written before
+    // HC-054f don't carry the placeholder — replace-all is a no-op there.
+    const overnightFlag = overnightDecision.overnight ? ' --overnight' : '';
     const populated = template
       .replace(/\{\{NAME\}\}/g, opts.name)
       .replace(/\{\{CRON\}\}/g, opts.cron)
-      .replace(/\{\{STORIES_FILE\}\}/g, opts.file);
+      .replace(/\{\{STORIES_FILE\}\}/g, opts.file)
+      .replace(/\{\{OVERNIGHT_FLAG\}\}/g, overnightFlag);
 
     // 3. Decide output path. Default writes to `.github/workflows/<name>.yml`.
     const outDir = path.resolve(process.cwd(), opts.out);
@@ -5078,8 +5893,23 @@ program
     console.log('');
     console.log(`✓ Installed schedule: ${path.relative(process.cwd(), outFile)}`);
     console.log('');
-    console.log('  Schedule: ' + opts.cron + ' (UTC)');
-    console.log('  Stories:  ' + opts.file);
+    console.log('  Schedule:  ' + opts.cron + ' (UTC)');
+    console.log('  Stories:   ' + opts.file);
+    // HC-054f: surface the overnight decision + WHY so the adopter
+    // sees that a `0 2 * * 1-5` cron auto-enabled Night Shift without
+    // having to dig into the workflow file.
+    const overnightLabel = overnightDecision.overnight ? 'ENABLED' : 'disabled';
+    // HC-054f pass-1 review LOW: if the source enum ever grows, the
+    // `|| ''` fallback would emit a dangling trailing space. Use an
+    // explicit `unknown-source` marker so a future enum addition fails
+    // loudly in CI rather than silently degrading the output.
+    const sourceLabel = {
+      'explicit-yes':    '(--overnight yes)',
+      'explicit-no':     '(--overnight no)',
+      'auto-detect-yes': '(auto-detected: ' + cronAnalysis.reason + ')',
+      'auto-detect-no':  '(auto-detected: ' + cronAnalysis.reason + ')',
+    }[overnightDecision.source] || `(unknown-source:${overnightDecision.source})`;
+    console.log(`  Overnight: ${overnightLabel} ${sourceLabel}`);
     console.log('');
     console.log('Next steps:');
     console.log('  1. Ensure repo secret HONE_TOKEN is set');
@@ -5099,12 +5929,13 @@ program
 
 program
   .command('release-review')
-  .description('Holistic code review of all changed files before deployment (runs Opus)')
+  .description('Holistic code review of all changed files before deployment (default: GH Models, $0)')
   .option('--base <branch>', 'Base branch to diff against', 'main')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .option('--dry-run', 'Show what would be reviewed without calling the LLM', false)
   .option('--max-files <n>', 'Max source files to include in review', '40')
-  .option('--provider <name>', 'LLM provider: opus | gh-models (HC-080a-spike)', 'opus')
+  .option('--provider <name>', 'LLM provider: gh-models (default, $0) | opus (legacy, paid)', 'gh-models')
+  .option('--cache <mode>', 'HC-RC-002-followup-1 content-hash cache: on | off (default on)', 'on')
   .action(async (opts) => {
     const { execSync } = require('child_process');
     const fs = require('fs');
@@ -5146,11 +5977,11 @@ program
     // 1. Get changed files
     let changedFiles;
     try {
-      const raw = execSync(`git diff --name-only ${baseRef}...HEAD`, { encoding: 'utf8', cwd: repoRoot });
+      const raw = execSync(`git diff --name-only ${baseRef}...HEAD`, { encoding: 'utf8', cwd: repoRoot, env: gitEnv() });
       changedFiles = raw.trim().split('\n').filter(Boolean);
     } catch {
       try {
-        const raw = execSync('git diff --name-only HEAD~10', { encoding: 'utf8', cwd: repoRoot });
+        const raw = execSync('git diff --name-only HEAD~10', { encoding: 'utf8', cwd: repoRoot, env: gitEnv() });
         changedFiles = raw.trim().split('\n').filter(Boolean);
       } catch {
         console.error('Could not determine changed files. Run from a git repo.');
@@ -5205,7 +6036,7 @@ program
       }
     } else {
       apiKey = process.env.ANTHROPIC_API_KEY;
-      providerLabel = 'Anthropic Opus (claude-opus-4-20250514)';
+      providerLabel = 'Anthropic Opus (claude-opus-4-8)';
       if (!apiKey) {
         console.error('ANTHROPIC_API_KEY not set. Required for --provider opus.');
         console.error('Set it: export ANTHROPIC_API_KEY=sk-ant-...');
@@ -5217,11 +6048,11 @@ program
     let diffContent;
     try {
       diffContent = execSync(`git diff ${baseRef}...HEAD -- ${filesToReview.map(f => `'${f}'`).join(' ')}`, {
-        encoding: 'utf8', cwd: repoRoot, maxBuffer: 10 * 1024 * 1024,
+        encoding: 'utf8', cwd: repoRoot, env: gitEnv(), maxBuffer: 10 * 1024 * 1024,
       });
     } catch {
       try {
-        diffContent = execSync('git diff HEAD~10', { encoding: 'utf8', cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
+        diffContent = execSync('git diff HEAD~10', { encoding: 'utf8', cwd: repoRoot, env: gitEnv(), maxBuffer: 10 * 1024 * 1024 });
       } catch (e) {
         console.error(`Could not generate diff: ${e.message}`);
         process.exit(1);
@@ -5294,6 +6125,89 @@ program
     banner(`Calling ${providerLabel}...`);
     banner('');
 
+    // ── HC-RC-002-followup-1: content-hash cache check ──────────────────
+    //
+    // The contentHash is computed over (diff + systemPrompt + model). A
+    // hit means an earlier run of the SAME diff against the SAME model
+    // produced a review already — replay it for $0 Anthropic spend +
+    // ~50ms instead of ~30s for an Opus call. Pre-fix adopters paid
+    // ~\$1.50 per release-review × ~3 retries per PR.
+    //
+    // Cache is opportunistic: any lookup error falls through to the LLM.
+    // Stamp `cache_hit: true` and `billing_source: 'cache'` on the
+    // envelope so the CI artifact analyzer can distinguish cached from
+    // fresh runs.
+    const {
+      computeReviewContentHash,
+      lookupReviewCache,
+      storeReviewCache,
+      normalizeCacheFlag,
+    } = require('./lib/release-review-cache');
+    const cacheEnabled = normalizeCacheFlag(opts.cache);
+    const modelForCache = opts.provider === 'gh-models'
+      ? 'openai/gpt-4.1'
+      : 'claude-opus-4-8';
+    let cacheContentHash = null;
+    if (cacheEnabled) {
+      try {
+        cacheContentHash = computeReviewContentHash({
+          diff: diffContent,
+          systemPrompt,
+          model: modelForCache,
+        });
+      } catch (e) {
+        banner(`Cache disabled: contentHash computation failed: ${e.message}`);
+      }
+    }
+    if (cacheEnabled && cacheContentHash) {
+      const config = getConfig();
+      const apiBase = (config && config.apiBase) || process.env.HONE_API_BASE;
+      const token = (config && config.token) || process.env.HONE_TOKEN;
+      const cached = await lookupReviewCache({
+        axios,
+        apiBase,
+        token,
+        contentHash: cacheContentHash,
+        model: modelForCache,
+        banner,
+      });
+      if (cached && cached.hit === true) {
+        banner('');
+        banner(`✓ Cache HIT — replaying cached release-review response`);
+        banner(`  Cache key: ${cacheContentHash.slice(0, 16)}…  (hit_count: ${cached.hit_count})`);
+        banner(`  Saved: ~${cached.tokens_saved} tokens  •  billing_source: cache`);
+        banner('');
+        const elapsedMs = 50;  // approximate — actual lookup + response time
+        if (isJsonOut) {
+          const envelope = {
+            status: 'reviewed',
+            base: opts.base,
+            resolvedBase: baseRef,
+            provider: opts.provider,
+            totalFiles: changedFiles.length,
+            sourceFiles: sourceFiles.length,
+            reviewedFiles: filesToReview.length,
+            model: modelForCache,
+            inputTokens: 0,
+            outputTokens: 0,
+            elapsedMs,
+            cache_hit: true,
+            billing_source: 'cache',
+            tokens_saved: cached.tokens_saved,
+          };
+          // Cached responses are already JSON-parsed (server stores JSON);
+          // spread them in then overlay envelope so audit fields can't be
+          // poisoned by stored content.
+          console.log(JSON.stringify({ ...cached.response, ...envelope }, null, 2));
+        } else {
+          console.log(typeof cached.response === 'string'
+            ? cached.response
+            : JSON.stringify(cached.response, null, 2));
+        }
+        process.exit(0);
+      }
+    }
+
     // 6. Call LLM (provider-branched, HC-080a-spike)
     // max_tokens is held SYMMETRIC across providers so the HC-080a-spike
     // comparison measures model capability, not output budget. 4096 is the
@@ -5331,7 +6245,7 @@ program
         modelLabel   = 'openai/gpt-4.1';
       } else {
         const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-          model: 'claude-opus-4-20250514',
+          model: 'claude-opus-4-8',
           max_tokens: MAX_OUTPUT_TOKENS,
           system: systemPrompt,
           messages: [{ role: 'user', content: userPrompt }],
@@ -5346,7 +6260,7 @@ program
         responseText = data.content?.[0]?.text || '';
         inputTokens  = data.usage?.input_tokens || 0;
         outputTokens = data.usage?.output_tokens || 0;
-        modelLabel   = 'claude-opus-4-20250514';
+        modelLabel   = 'claude-opus-4-8';
       }
 
       const elapsedMs = Date.now() - startedAt;
@@ -5406,6 +6320,33 @@ program
         console.log(responseText);
       }
 
+      // HC-RC-002-followup-1: store the fresh response in the cache so
+      // future runs of the SAME diff hit cache instead of paying for
+      // another Opus call. Fire-and-forget — caller already has the
+      // response; a failed store is logged but doesn't change exit code.
+      // Total tokens billed for this run = inputTokens + outputTokens —
+      // those are the tokens a future hit would save.
+      if (cacheEnabled && cacheContentHash) {
+        const config = getConfig();
+        const apiBase = (config && config.apiBase) || process.env.HONE_API_BASE;
+        const token = (config && config.token) || process.env.HONE_TOKEN;
+        // Cache the parsed JSON when available (cleaner replay), otherwise
+        // wrap the raw text in { raw } so the cache always stores an object.
+        const responseForCache = parsed && typeof parsed === 'object'
+          ? parsed
+          : { raw: responseText };
+        storeReviewCache({
+          axios, apiBase, token,
+          contentHash: cacheContentHash,
+          model: modelForCache,
+          response: responseForCache,
+          tokensSaved: inputTokens + outputTokens,
+          banner,
+        }).then(({ stored }) => {
+          if (stored) banner(`✓ Cache stored: ${cacheContentHash.slice(0, 16)}…`);
+        }).catch(() => { /* logged inside helper */ });
+      }
+
       // 8. Exit code — defense in depth:
       //   (a) structured check against the parsed JSON, then
       //   (b) loose substring check on the raw response (catches LLMs that