@hone-ai/cli 1.8.1 → 1.10.0

package/hone-cli.js

@@ -25,6 +25,8 @@ const crypto       = require('crypto');
 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 program = new Command();
 
 // ── Config resolution ─────────────────────────────────────────────────────────
@@ -362,10 +364,16 @@ program
     console.log('Running setup-ai-pipeline.sh v3.1...');
     console.log('');
 
+    // Auto-detect non-TTY (CI, piped, Claude Code) and add --non-interactive
+    const isNonInteractive = opts.nonInteractive || !process.stdin.isTTY;
+    if (isNonInteractive && !opts.nonInteractive) {
+      console.log('  (non-TTY detected — running in non-interactive mode)');
+    }
+
     const flags = [
       `--source "${path.join(tmpDir, 'enterprise-github')}"`,
-      opts.dryRun        ? '--dry-run'         : '',
-      opts.nonInteractive? '--non-interactive'  : '',
+      opts.dryRun      ? '--dry-run'         : '',
+      isNonInteractive ? '--non-interactive'  : '',
     ].filter(Boolean).join(' ');
 
     try {
@@ -4144,13 +4152,14 @@ program
   .option('--contracts', 'Run contract validation between pipeline agents')
   .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)')
   .action(async (opts) => {
     const path = require('path');
     const fs = require('fs');
     const yaml = require('js-yaml');
 
-    // Load agent prompts from seed-agent-prompts.js
-    const seedPath = path.resolve(__dirname, '..', 'scripts', 'seed-agent-prompts.js');
+    // Load agent prompts from seed-agent-prompts.js (HC-019n-hotfix: moved into /server/)
+    const seedPath = path.resolve(__dirname, '..', 'server', 'scripts', 'seed-agent-prompts.js');
     const { AGENT_PROMPTS } = require(seedPath);
     const evalDir = opts.evalsDir || path.resolve(__dirname, '..', 'evals');
 
@@ -4205,7 +4214,84 @@ program
       process.exit(results.failed > 0 ? 1 : 0);
     }
 
-    // Scenario evaluation mode
+    // LLM-judge mode (HC-019i / #268)
+    if (opts.judge) {
+      const { loadScenarios, formatResults } = require('./lib/eval-runner');
+      const { runJudgeScenario } = require('./lib/eval-llm-judge');
+
+      const apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        console.error('ANTHROPIC_API_KEY required for --judge mode. Set: export ANTHROPIC_API_KEY=sk-ant-...');
+        process.exit(1);
+      }
+
+      const scenarios = loadScenarios({
+        evalDir, agent: opts.agent, tag: opts.tag, scenarioId: opts.scenario,
+        readFile: (p) => fs.readFileSync(p, 'utf8'),
+        listDir: (p) => fs.readdirSync(p), isDir: (p) => fs.statSync(p).isDirectory(),
+        parseYaml: (text) => yaml.load(text),
+      });
+
+      const judgeScenarios = scenarios.filter(s => s.grading?.mode === 'llm-judge');
+      if (judgeScenarios.length === 0) {
+        console.log('No llm-judge scenarios found. Add grading.mode: llm-judge to eval YAML files.');
+        process.exit(0);
+      }
+
+      // 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',
+          max_tokens: 2048,
+          system: systemPrompt,
+          messages: [{ role: 'user', content: userPrompt }],
+        }, {
+          headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json',
+          },
+          timeout: 60000,
+        });
+        return data.content?.[0]?.text || '';
+      }
+
+      console.log(`Running ${judgeScenarios.length} LLM-judge scenario(s)...`);
+      console.log('');
+
+      const results = [];
+      for (const scenario of judgeScenarios) {
+        const agentName = scenario.evalAgent || scenario.agent;
+        const promptText = AGENT_PROMPTS[agentName];
+        if (!promptText) {
+          results.push({ id: scenario.id, agent: agentName, result: 'error',
+            checks: 0, checks_passed: 0, failures: [{ type: 'missing_prompt', passed: false, detail: `agent "${agentName}" not found` }] });
+          continue;
+        }
+        try {
+          const result = await runJudgeScenario({ scenario, agentPrompt: promptText, callLLM });
+          results.push(result);
+        } catch (e) {
+          results.push({ id: scenario.id, agent: agentName, result: 'error',
+            checks: 0, checks_passed: 0, failures: [{ type: 'llm_error', passed: false, detail: e.message }] });
+        }
+
+        if (opts.failFast && results[results.length - 1].result !== 'pass') break;
+      }
+
+      const summary = {
+        total: results.length,
+        passed: results.filter(r => r.result === 'pass').length,
+        failed: results.filter(r => r.result === 'fail').length,
+        errors: results.filter(r => r.result === 'error').length,
+        scenarios: results,
+      };
+
+      console.log(formatResults(summary, opts.format));
+      process.exit(summary.failed + summary.errors > 0 ? 1 : 0);
+    }
+
+    // Scenario evaluation mode (deterministic)
     const { loadScenarios, runAllScenarios, formatResults } = require('./lib/eval-runner');
 
     if (!fs.existsSync(evalDir)) {
@@ -4429,7 +4515,379 @@ process.on('SIGINT', () => {
   process.exit(0);
 });
 
+// ── HC-053: Batch story queue (Epic 6 — Autonomous Mode) ─────────────────────
+//
+// Fire-and-forget submission of N stories. Each story runs as an autonomous
+// workflow in 'batch' mode (auto-approves early gates per workflow-dag).
+// One failure does NOT halt siblings.
+//
+//   hone queue-stories --file stories.txt
+//   hone queue-stories --status <batchId>
+//   hone queue-stories --list
+program
+  .command('queue-stories')
+  .description('Queue a batch of stories for autonomous (overnight) execution')
+  .option('--file <path>', 'Text file with one story ID per line (cap: 50 lines, 16KB)')
+  .option('--repo <name>', 'Repository name applied to every story (default: directory name)')
+  .option('--branch <name>', 'Git branch applied to every story (default: current branch)')
+  .option('--status <batchId>', 'Show status of a previously submitted batch')
+  .option('--report <batchId>', 'Fetch the morning report for a batch (markdown by default)')
+  .option('--save <path>', 'When used with --report, save markdown to a file instead of stdout')
+  .option('--list', 'List recent batches for this org')
+  .option('--limit <n>', 'Number of batches to list (default 20, max 100)', '20')
+  .option('--format <fmt>', 'Output format: pretty or json (with --report, also: md)', 'pretty')
+  // HC-054: Night Shift mode. Conditional auto-approve at step_4/step_5
+  // when the agent output passes isCleanOutput's positive allowlist +
+  // inverse blocklist. Extended LLM timeout (480s), orchestrator watchdog
+  // (900s/step), default token budget of 400K × story_count when none
+  // explicitly set. Cap of 25 stories per overnight batch.
+  .option('--overnight', 'Enable Night Shift mode (conditional auto-approve, longer timeouts, max 25 stories)', false)
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+
+    // Enforce mutually-exclusive modes — combining e.g. --list with --report
+    // would silently drop one. Explicit error is friendlier than 'silently
+    // did nothing' or 'silently did the wrong thing'.
+    const modes = [];
+    if (opts.list)   modes.push('--list');
+    if (opts.status) modes.push('--status');
+    if (opts.report) modes.push('--report');
+    if (opts.file)   modes.push('--file');
+    if (modes.length > 1) {
+      console.error(`These flags are mutually exclusive: ${modes.join(', ')}`);
+      console.error('Specify only one of --file, --status, --report, --list.');
+      process.exit(1);
+    }
+
+    // ── --list ────────────────────────────────────────────────
+    if (opts.list) {
+      try {
+        const { data } = await client.get(`/orchestrate/batch`, { params: { limit: opts.limit } });
+        if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+        if (!data.batches || data.batches.length === 0) {
+          console.log('No batches found.');
+          return;
+        }
+        console.log('');
+        console.log('Recent batches:');
+        for (const b of data.batches) {
+          console.log(`  ${b.batchId}  status=${b.status}  stories=${b.storyCount}  created=${b.createdAt}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error(`Failed: ${e.response?.data?.error || e.message}`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    // ── --report <batchId> (HC-055) ──────────────────────────
+    if (opts.report) {
+      try {
+        const format = opts.format === 'json' ? 'json' : 'md';
+        const { data, headers } = await client.get(
+          `/orchestrate/batch/${opts.report}/report`,
+          { params: { format }, responseType: 'text', transformResponse: [(d) => d] }
+        );
+        if (format === 'json') {
+          // JSON path — parse and pretty-print, or save raw.
+          if (opts.save) {
+            fs.writeFileSync(opts.save, data, 'utf8');
+            console.log(`Saved JSON report to ${opts.save}`);
+          } else {
+            try { console.log(JSON.stringify(JSON.parse(data), null, 2)); }
+            catch { console.log(data); }
+          }
+        } else {
+          // Markdown path.
+          if (opts.save) {
+            fs.writeFileSync(opts.save, data, 'utf8');
+            const cached = headers['x-report-cached'] === 'true' ? ' (cached)' : '';
+            console.log(`Saved markdown report${cached} to ${opts.save}`);
+          } else {
+            // Guard: axios with responseType:'text' is expected to return a
+            // string, but a server regression or unusual proxy could send
+            // an empty/undefined body. Don't crash trying to print it.
+            const text = typeof data === 'string' ? data : (data == null ? '' : String(data));
+            process.stdout.write(text);
+            if (!text.endsWith('\n')) process.stdout.write('\n');
+          }
+        }
+      } catch (e) {
+        if (e.response?.status === 404) {
+          console.error('Batch not found.');
+        } else {
+          // responseType:'text' keeps the body as a raw string even for JSON
+          // error responses, so e.response.data is the unparsed `{"error":...}`
+          // and `.error` would be undefined. Parse string bodies before reading.
+          let serverError;
+          const rawData = e.response?.data;
+          if (typeof rawData === 'string') {
+            try { serverError = JSON.parse(rawData)?.error; } catch { /* not JSON */ }
+          } else {
+            serverError = rawData?.error;
+          }
+          console.error(`Failed: ${serverError || e.message}`);
+        }
+        process.exit(1);
+      }
+      return;
+    }
+
+    // ── --status <batchId> ────────────────────────────────────
+    if (opts.status) {
+      try {
+        const { data } = await client.get(`/orchestrate/batch/${opts.status}`);
+        if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+        console.log('');
+        console.log(`Batch:    ${data.batchId}`);
+        console.log(`Status:   ${data.status}`);
+        console.log(`Stories:  ${data.storyCount}`);
+        console.log(`Tokens:   ${(data.totalTokens || 0).toLocaleString()}`);
+        const c = data.counts || {};
+        console.log(`Counts:   completed=${c.completed||0}  running=${c.running||0}  paused=${c.paused||0}  queued=${c.queued||0}  failed=${c.failed||0}  killed=${c.killed||0}  stalled=${c.stalled||0}`);
+        console.log('');
+        console.log('Runs:');
+        for (const r of (data.runs || [])) {
+          const icon = r.status === 'completed' ? '✓'
+                     : r.status === 'running'   ? '⏳'
+                     : r.status === 'paused'    ? '⏸'
+                     : r.status === 'failed'    ? '✗'
+                     : r.status === 'killed'    ? '☠'
+                     : r.status === 'stalled'   ? '⚠'
+                     : '⬜';
+          const step = r.currentStep ? `  @${r.currentStep}` : '';
+          const err = r.errorMessage ? `  err=${r.errorMessage}` : '';
+          console.log(`  ${icon} ${r.storyId}  (${r.repoName})  ${r.status}${step}${err}`);
+        }
+        console.log('');
+      } catch (e) {
+        if (e.response?.status === 404) console.error('Batch not found.');
+        else console.error(`Failed: ${e.response?.data?.error || e.message}`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    // ── Submit a new batch from --file ─────────────────────────
+    if (!opts.file) {
+      console.error('Specify --file <path>, --status <batchId>, --report <batchId>, or --list.');
+      console.error('Example: hone queue-stories --file stories.txt');
+      process.exit(1);
+    }
+
+    let storyIds;
+    try {
+      const stat = fs.statSync(opts.file);
+      if (stat.size > 16 * 1024) {
+        console.error(`File too large: ${stat.size} bytes (max 16KB).`);
+        process.exit(1);
+      }
+      // Strip UTF-8 BOM (U+FEFF) that Windows editors prepend; trim()
+      // does not remove it, so without this the first storyId becomes
+      // an invisible-prefixed string that fails downstream lookups.
+      const raw = fs.readFileSync(opts.file, 'utf8').replace(/^\uFEFF/, '');
+      // HC-059: each non-comment line is `STORY-ID` OR
+      // `STORY-ID depends:DEP1,DEP2`. Whitespace tolerant. Empty lines and
+      // lines starting with # are ignored.
+      storyIds = raw.split(/\r?\n/)
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith('#'));
+    } catch (e) {
+      console.error(`Cannot read --file: ${e.message}`);
+      process.exit(1);
+    }
+    if (storyIds.length === 0) {
+      console.error('No story IDs found in file.');
+      process.exit(1);
+    }
+    if (storyIds.length > 50) {
+      console.error(`Too many stories: ${storyIds.length} (max 50 per batch).`);
+      process.exit(1);
+    }
+
+    const repoName = opts.repo || path.basename(process.cwd());
+    let branch = opts.branch;
+    if (!branch) {
+      try { branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim(); }
+      catch { branch = null; }
+    }
+
+    // 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).
+    const stories = storyIds.map(line => {
+      const depsMatch = line.match(/^(\S+)\s+depends:(\S+)\s*$/);
+      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 };
+    });
+
+    // 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 };
+    if (opts.overnight) {
+      body.config = { overnight: true };
+    }
+
+    try {
+      const { data } = await client.post('/orchestrate/batch', body);
+
+      if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+
+      console.log('');
+      console.log(`Batch queued: ${data.batchId}`);
+      console.log(`Stories: ${data.storyCount}  Enqueued: ${data.enqueued}` +
+                  (data.enqueueFailed ? `  Enqueue-failed: ${data.enqueueFailed}` : ''));
+      console.log('');
+      console.log('Stories will run autonomously in batch mode (early gates auto-approve).');
+      console.log('Steps that require human approval (step_4, step_5) will pause those runs.');
+      console.log('');
+      console.log(`Check progress: hone queue-stories --status ${data.batchId}`);
+      console.log(`Per-story:      hone run-story <runId> --status`);
+      console.log('');
+    } catch (e) {
+      if (e.response?.status === 429) {
+        console.error(`Org concurrency limit reached: ${e.response.data.error}`);
+      } else if (e.response?.status === 400) {
+        console.error(`Rejected: ${e.response.data.error}`);
+      } else {
+        console.error(`Failed: ${e.response?.data?.error || e.message}`);
+      }
+      process.exit(1);
+    }
+  });
+
+// ── HC-056: Schedule install (GitHub Actions overnight template) ────────────
+//
+// Installs a parameterized .github/workflows/<name>.yml that runs `hone
+// queue-stories` on a cron schedule. workflow_dispatch trigger gives
+// on-demand execution from the GitHub Actions UI or `gh workflow run`.
+//
+//   hone schedule install
+//   hone schedule install --name overnight --cron "0 18 * * 1-5" --file stories.txt
+//
+// Future server-side cron is filed as HC-075. For now the workflow lives
+// in the adopter's repo, which gives them version control on the schedule
+// + free history in the GitHub Actions UI.
+program
+  .command('schedule')
+  .description('Manage overnight batch schedules (GitHub Actions templates)')
+  .argument('<action>', 'Action to perform: install')
+  .option('--name <name>', 'Schedule name (used as workflow filename)', 'overnight')
+  .option('--cron <cron>', 'Cron expression (UTC). Default: weekdays 6pm', '0 18 * * 1-5')
+  .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)
+  .action(async (action, opts) => {
+    if (action !== 'install') {
+      console.error(`Unknown schedule action: ${action}. Supported: install`);
+      console.error('(Server-side scheduling is filed as HC-075.)');
+      process.exit(1);
+    }
+
+    // Basic cron validation — five whitespace-separated fields.
+    // Catches the most common mistakes (six fields, single token, etc.)
+    // without trying to validate semantics.
+    const fields = String(opts.cron).trim().split(/\s+/);
+    if (fields.length !== 5) {
+      console.error(`Invalid cron expression: "${opts.cron}"`);
+      console.error('Expected 5 fields: minute hour day-of-month month day-of-week.');
+      console.error('GitHub Actions does NOT support aliases like @daily / @hourly — use the 5-field form.');
+      console.error('Test with https://crontab.guru');
+      process.exit(1);
+    }
+
+    // Name → workflow filename. Reject path traversal / slashes.
+    if (!/^[a-z0-9][a-z0-9_-]{0,40}$/i.test(opts.name)) {
+      console.error(`Invalid --name "${opts.name}". Use letters, digits, hyphens, underscores (max 41 chars).`);
+      process.exit(1);
+    }
+
+    const config = getConfig();
+    const client = api(config);
+
+    // 1. Fetch the template from the server.
+    let template;
+    try {
+      const { data } = await client.get('/scripts/overnight-schedule-template', {
+        responseType: 'text', transformResponse: [(d) => d],
+      });
+      template = data;
+    } catch (e) {
+      // responseType:'text' keeps JSON error bodies as raw strings — parse
+      // before reading .error so the user sees the server's actual message
+      // (e.g. "overnight-schedule.yml not bundled") instead of axios's
+      // generic "Request failed with status code 503".
+      let serverError;
+      const rawData = e.response?.data;
+      if (typeof rawData === 'string') {
+        try { serverError = JSON.parse(rawData)?.error; } catch { /* not JSON */ }
+      } else {
+        serverError = rawData?.error;
+      }
+      console.error(`Failed to fetch template: ${e.response?.status || ''} ${serverError || e.message}`);
+      process.exit(1);
+    }
+
+    // 2. Substitute placeholders. Use replace-all so any future template
+    // additions referencing the same placeholder are handled.
+    const populated = template
+      .replace(/\{\{NAME\}\}/g, opts.name)
+      .replace(/\{\{CRON\}\}/g, opts.cron)
+      .replace(/\{\{STORIES_FILE\}\}/g, opts.file);
+
+    // 3. Decide output path. Default writes to `.github/workflows/<name>.yml`.
+    const outDir = path.resolve(process.cwd(), opts.out);
+    const outFile = path.join(outDir, `${opts.name}.yml`);
+
+    if (fs.existsSync(outFile) && !opts.force) {
+      console.error(`File already exists: ${outFile}`);
+      console.error('Use --force to overwrite, or pick a different --name.');
+      process.exit(1);
+    }
+
+    // 4. Ensure output dir exists.
+    fs.mkdirSync(outDir, { recursive: true });
+
+    // 5. Write the file.
+    fs.writeFileSync(outFile, populated, 'utf8');
+
+    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('');
+    console.log('Next steps:');
+    console.log('  1. Ensure repo secret HONE_TOKEN is set');
+    console.log('     (Settings → Secrets and variables → Actions → New repository secret)');
+    console.log('  2. Commit and push the workflow file:');
+    console.log(`     git add ${path.relative(process.cwd(), outFile)} && git commit -m "feat: nightly Hone batch" && git push`);
+    console.log(`  3. Test on-demand: gh workflow run ${opts.name}.yml --field dry_run=true`);
+    console.log(`     Or: GitHub Actions UI → "${opts.name}" → Run workflow`);
+    console.log('');
+    console.log('Test the cron expression at https://crontab.guru');
+    console.log('');
+  });
+
 // ── Release Review (pre-deployment holistic review) ──────────────────────────
+// parseReviewJSON is extracted to cli/lib/parse-review-json.js for unit
+// coverage. See that file's docstring for the three-shape extraction strategy.
+
 program
   .command('release-review')
   .description('Holistic code review of all changed files before deployment (runs Opus)')
@@ -4437,15 +4895,49 @@ program
   .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')
   .action(async (opts) => {
     const { execSync } = require('child_process');
     const fs = require('fs');
     const repoRoot = process.cwd();
 
+    // When emitting JSON to stdout, route banner/status output to stderr so
+    // `tee file.json` in CI captures pure JSON. Otherwise the artifact ends
+    // up with `Hone AI — Production Review\n=====\n...` mixed in front of
+    // the JSON envelope, breaking JSON.parse. (HC-080a-spike PR #313 data
+    // point 1 found this — both lanes' artifacts were unparseable.)
+    //
+    // Normalize the format value defensively — `--format JSON` or
+    // `--format=json ` (trailing space) would otherwise silently fall into
+    // pretty-mode and re-pollute the artifact.
+    const isJsonOut = String(opts.format || '').trim().toLowerCase() === 'json';
+    const banner = (line) => (isJsonOut ? console.error(line) : console.log(line));
+
+    // emitStatusEnvelope is for non-success exit paths in JSON mode (no
+    // changes, auth failure, rate limit, empty response). Ensures the
+    // artifact is ALWAYS valid JSON, never zero-byte. The status field
+    // tells compare-reviews.js to treat this row as a known non-finding
+    // outcome rather than an unparseable file.
+    const emitStatusEnvelope = (status, extra = {}) => {
+      if (!isJsonOut) return;
+      console.log(JSON.stringify({
+        status,
+        base: opts.base,           // raw user input — preserved for audit
+        provider: opts.provider,
+        ...extra,
+      }, null, 2));
+    };
+
+    // Normalize the base ref to avoid the double-`origin/` prefix bug. The
+    // CI step passes `--base origin/main` and the previous code prefixed
+    // again → `origin/origin/main` → git rejected → silent fallback to
+    // `HEAD~10`. Both lanes reviewed the wrong diff in PR #313 first run.
+    const baseRef = resolveBaseRef(opts.base);
+
     // 1. Get changed files
     let changedFiles;
     try {
-      const raw = execSync(`git diff --name-only origin/${opts.base}...HEAD`, { encoding: 'utf8', cwd: repoRoot });
+      const raw = execSync(`git diff --name-only ${baseRef}...HEAD`, { encoding: 'utf8', cwd: repoRoot });
       changedFiles = raw.trim().split('\n').filter(Boolean);
     } catch {
       try {
@@ -4458,7 +4950,8 @@ program
     }
 
     if (changedFiles.length === 0) {
-      console.log('No changed files found. Nothing to review.');
+      banner('No changed files found. Nothing to review.');
+      emitStatusEnvelope('no_changes', { resolvedBase: baseRef });
       process.exit(0);
     }
 
@@ -4472,32 +4965,49 @@ program
     const maxFiles = parseInt(opts.maxFiles, 10) || 40;
     const filesToReview = sourceFiles.slice(0, maxFiles);
 
-    console.log('');
-    console.log('Hone AI — Production Review');
-    console.log('================================');
-    console.log(`Base: ${opts.base}`);
-    console.log(`Changed files: ${changedFiles.length} total, ${sourceFiles.length} source, ${filesToReview.length} to review`);
-    console.log('');
+    banner('');
+    banner('Hone AI — Production Review');
+    banner('================================');
+    banner(`Base: ${baseRef}`);
+    banner(`Changed files: ${changedFiles.length} total, ${sourceFiles.length} source, ${filesToReview.length} to review`);
+    banner('');
 
     if (opts.dryRun) {
-      console.log('Source files that would be reviewed:');
-      for (const f of filesToReview) console.log(`  ${f}`);
-      if (sourceFiles.length > maxFiles) console.log(`  ... and ${sourceFiles.length - maxFiles} more (increase --max-files)`);
+      banner('Source files that would be reviewed:');
+      for (const f of filesToReview) banner(`  ${f}`);
+      if (sourceFiles.length > maxFiles) banner(`  ... and ${sourceFiles.length - maxFiles} more (increase --max-files)`);
       process.exit(0);
     }
 
-    // 3. Check for API key
-    const apiKey = process.env.ANTHROPIC_API_KEY;
-    if (!apiKey) {
-      console.error('ANTHROPIC_API_KEY not set. Required for production review (Opus model).');
-      console.error('Set it: export ANTHROPIC_API_KEY=sk-ant-...');
+    // 3. Provider validation + credential check
+    if (opts.provider !== 'opus' && opts.provider !== 'gh-models') {
+      console.error(`Invalid --provider: ${opts.provider}. Use 'opus' or 'gh-models'.`);
       process.exit(1);
     }
 
+    let apiKey, providerLabel;
+    if (opts.provider === 'gh-models') {
+      apiKey = process.env.GITHUB_TOKEN;
+      providerLabel = 'GitHub Models (openai/gpt-4.1)';
+      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>.');
+        process.exit(1);
+      }
+    } else {
+      apiKey = process.env.ANTHROPIC_API_KEY;
+      providerLabel = 'Anthropic Opus (claude-opus-4-20250514)';
+      if (!apiKey) {
+        console.error('ANTHROPIC_API_KEY not set. Required for --provider opus.');
+        console.error('Set it: export ANTHROPIC_API_KEY=sk-ant-...');
+        process.exit(1);
+      }
+    }
+
     // 4. Build the diff content (truncated per-file to stay within context)
     let diffContent;
     try {
-      diffContent = execSync(`git diff origin/${opts.base}...HEAD -- ${filesToReview.map(f => `'${f}'`).join(' ')}`, {
+      diffContent = execSync(`git diff ${baseRef}...HEAD -- ${filesToReview.map(f => `'${f}'`).join(' ')}`, {
         encoding: 'utf8', cwd: repoRoot, maxBuffer: 10 * 1024 * 1024,
       });
     } catch {
@@ -4509,10 +5019,13 @@ program
       }
     }
 
-    // Truncate if over 100k chars (~25k tokens) to stay within budget
-    const MAX_DIFF_CHARS = 100000;
+    // Provider-specific truncation. GH Models GPT-4.1 has an 8K-token
+    // request-body cap via models.github.ai/inference — 100K chars overflows.
+    // See cli/lib/release-review-config.js for the budget math.
+    const MAX_DIFF_CHARS = getMaxDiffChars(opts.provider);
     if (diffContent.length > MAX_DIFF_CHARS) {
-      diffContent = diffContent.slice(0, MAX_DIFF_CHARS) + '\n\n[... diff truncated at 100k chars ...]';
+      diffContent = diffContent.slice(0, MAX_DIFF_CHARS) +
+        `\n\n[... diff truncated at ${MAX_DIFF_CHARS} chars for --provider ${opts.provider} ...]`;
     }
 
     // 5. Build the prompt
@@ -4569,72 +5082,166 @@ program
       'Review ALL files holistically. Return findings as JSON.',
     ].join('\n');
 
-    console.log('Calling Anthropic API (claude-opus-4-20250514)...');
-    console.log('');
+    banner(`Calling ${providerLabel}...`);
+    banner('');
 
-    // 6. Call Anthropic Messages API
+    // 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
+    // safe ceiling for openai/gpt-4.1 via GH Models; Opus supports more but
+    // running it with 4096 keeps the comparison apples-to-apples.
+    const MAX_OUTPUT_TOKENS = 4096;
+    const startedAt = Date.now();
     try {
-      const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-        model: 'claude-opus-4-20250514',
-        max_tokens: 8192,
-        system: systemPrompt,
-        messages: [{ role: 'user', content: userPrompt }],
-      }, {
-        headers: {
-          'x-api-key': apiKey,
-          'anthropic-version': '2023-06-01',
-          'content-type': 'application/json',
-        },
-        timeout: 120000,
-      });
+      let responseText, inputTokens, outputTokens, modelLabel;
+
+      if (opts.provider === 'gh-models') {
+        // GitHub Models — free LLM inference using GITHUB_TOKEN. Mirrors the
+        // path used by server/scripts/ai-reviewer.js for per-PR review.
+        const { data } = await axios.post(
+          'https://models.github.ai/inference/chat/completions',
+          {
+            model: 'openai/gpt-4.1',
+            messages: [
+              { role: 'system', content: systemPrompt },
+              { role: 'user',   content: userPrompt },
+            ],
+            max_tokens: MAX_OUTPUT_TOKENS,
+          },
+          {
+            headers: {
+              'Authorization': `Bearer ${apiKey}`,
+              'Content-Type': 'application/json',
+            },
+            timeout: 120000,
+          }
+        );
+        responseText = data.choices?.[0]?.message?.content || '';
+        inputTokens  = data.usage?.prompt_tokens || 0;
+        outputTokens = data.usage?.completion_tokens || 0;
+        modelLabel   = 'openai/gpt-4.1';
+      } else {
+        const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
+          model: 'claude-opus-4-20250514',
+          max_tokens: MAX_OUTPUT_TOKENS,
+          system: systemPrompt,
+          messages: [{ role: 'user', content: userPrompt }],
+        }, {
+          headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json',
+          },
+          timeout: 120000,
+        });
+        responseText = data.content?.[0]?.text || '';
+        inputTokens  = data.usage?.input_tokens || 0;
+        outputTokens = data.usage?.output_tokens || 0;
+        modelLabel   = 'claude-opus-4-20250514';
+      }
 
-      const responseText = data.content?.[0]?.text || '';
+      const elapsedMs = Date.now() - startedAt;
+
+      // Empty-response detection: some providers return HTTP 200 with empty
+      // choices/content (content-filter trip, soft quota limit, model alias
+      // typo). Without this guard the CLI would silently exit 0 and the CI
+      // artifact would look like a clean pass — a false-negative on the
+      // entire review.
+      if (!responseText || responseText.trim().length === 0) {
+        console.error(`Empty response from --provider ${opts.provider}. ` +
+                      `Possible causes: content filter, quota exhausted, or model name rejected.`);
+        emitStatusEnvelope('empty_response', {
+          resolvedBase: baseRef,
+          model: modelLabel,
+          inputTokens,
+          outputTokens,
+          elapsedMs: Date.now() - startedAt,
+        });
+        process.exit(1);
+      }
 
-      // 7. Parse and display results
-      if (opts.format === 'json') {
-        // Try to extract JSON from response
-        const jsonMatch = responseText.match(/\{[\s\S]*\}/);
-        if (jsonMatch) {
-          try {
-            const parsed = JSON.parse(jsonMatch[0]);
-            console.log(JSON.stringify({
-              base: opts.base,
-              totalFiles: changedFiles.length,
-              sourceFiles: sourceFiles.length,
-              reviewedFiles: filesToReview.length,
-              model: 'claude-opus-4-20250514',
-              inputTokens: data.usage?.input_tokens || 0,
-              outputTokens: data.usage?.output_tokens || 0,
-              ...parsed,
-            }, null, 2));
-          } catch {
-            console.log(JSON.stringify({ raw: responseText }, null, 2));
-          }
+      // Parse the response once, robustly. Try the full string first (the
+      // happy path when the LLM emits clean JSON), then fall back to greedy
+      // brace extraction. A failed parse leaves parsed = null and downstream
+      // code uses raw.
+      const parsed = parseReviewJSON(responseText);
+
+      // 7. Output envelope + content. Envelope fields are spread LAST so an
+      // LLM cannot rewrite audit fields (provider, model, inputTokens, etc.)
+      // via prompt injection in the diff content.
+      //
+      // base (raw user input) is preserved alongside resolvedBase (the actual
+      // git revision that was diffed) so audit trails are complete and
+      // comparison tooling can distinguish "the operator passed `main`" from
+      // "the operator passed `origin/main`."
+      if (isJsonOut) {
+        const envelope = {
+          status: 'reviewed',
+          base: opts.base,
+          resolvedBase: baseRef,
+          provider: opts.provider,
+          totalFiles: changedFiles.length,
+          sourceFiles: sourceFiles.length,
+          reviewedFiles: filesToReview.length,
+          model: modelLabel,
+          inputTokens,
+          outputTokens,
+          elapsedMs,
+        };
+        if (parsed) {
+          console.log(JSON.stringify({ ...parsed, ...envelope }, null, 2));
         } else {
-          console.log(JSON.stringify({ raw: responseText }, null, 2));
+          console.log(JSON.stringify({ ...envelope, raw: responseText }, null, 2));
         }
       } else {
         console.log(responseText);
       }
 
-      // 8. Exit code based on findings
-      const hasCritical = responseText.includes('"CRITICAL"') || responseText.includes('"critical"');
-      const recommendation = responseText.includes('DO_NOT_DEPLOY');
-      if (hasCritical || recommendation) {
-        console.log('');
-        console.log('CRITICAL issues found. Fix before deploying.');
+      // 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
+      //       emit markdown-formatted CRITICAL findings without strict JSON).
+      let hasCritical = false, doNotDeploy = false;
+      if (parsed) {
+        hasCritical = (parsed.summary?.critical || 0) > 0 ||
+                      (Array.isArray(parsed.findings) &&
+                       parsed.findings.some(f => String(f.severity).toUpperCase() === 'CRITICAL'));
+        doNotDeploy = parsed.recommendation === 'DO_NOT_DEPLOY';
+      }
+      if (!hasCritical) {
+        // Loose match — case-insensitive, no quote requirement. False-positive
+        // tolerance is acceptable here because the cost of a false-positive is
+        // "CI shows yellow, human looks at the report"; the cost of a false-
+        // negative is "real CRITICAL bug ships to prod undetected".
+        hasCritical = /\bCRITICAL\b/.test(responseText);
+      }
+      if (!doNotDeploy) {
+        doNotDeploy = /\bDO_NOT_DEPLOY\b/.test(responseText);
+      }
+      if (hasCritical || doNotDeploy) {
+        banner('');
+        banner('CRITICAL issues found. Fix before deploying.');
         process.exit(1);
       }
     } catch (e) {
       const status = e.response?.status;
       const msg = e.response?.data?.error?.message || e.message;
-      if (status === 401) {
-        console.error('Invalid ANTHROPIC_API_KEY. Check your key and try again.');
+      let kind = 'http_error';
+      if (status === 401 || status === 403) {
+        console.error(`Invalid auth for --provider ${opts.provider}. Check credential and try again.`);
+        kind = 'auth_error';
       } else if (status === 429) {
-        console.error('Rate limited by Anthropic API. Try again shortly.');
+        console.error(`Rate limited by ${opts.provider}. Try again shortly.`);
+        kind = 'rate_limited';
       } else {
-        console.error(`Production review failed: ${msg}`);
+        console.error(`Production review failed (${opts.provider}): ${msg}`);
       }
+      emitStatusEnvelope(kind, {
+        resolvedBase: baseRef,
+        httpStatus: status || null,
+        errorMessage: msg,
+        elapsedMs: Date.now() - startedAt,
+      });
       process.exit(1);
     }
   });

package/lib/compare-reviews.js

@@ -0,0 +1,279 @@
+'use strict';
+/**
+ * compare-reviews.js — HC-080a-spike side-by-side comparison helper.
+ *
+ * Reads two release-review JSON artifacts (Opus + GH Models GPT-4.1) and
+ * prints a markdown comparison table that can be pasted into the decision
+ * record in docs/architecture/release-review-llm-provider-decision.md.
+ *
+ * Usage:
+ *   node cli/lib/compare-reviews.js <opus-findings.json> <gh-models-findings.json>
+ *
+ * Both files should be JSON envelopes produced by `hone release-review --format json`
+ * (see cli/hone-cli.js release-review handler — both providers emit the same
+ * envelope shape).
+ *
+ * The script is intentionally tolerant of partial/raw outputs: if a provider
+ * returned a non-JSON response, the comparison still shows what's there and
+ * flags the format problem in the rubric.
+ *
+ * Exit codes:
+ *   0 — both files parsed, comparison printed
+ *   1 — missing file, invalid JSON, or other unrecoverable error
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+// Normalize file paths for cross-provider equality. Strips leading "./",
+// converts backslashes, and removes duplicate separators. Coarse: does NOT
+// resolve symlinks, just compares string-equivalent paths.
+function normalizePath(p) {
+  if (typeof p !== 'string') return '';
+  let n = p.replace(/\\/g, '/').replace(/^\.\//, '').trim();
+  // collapse repeated slashes but preserve leading slash
+  n = n.replace(/\/+/g, '/');
+  return n;
+}
+
+// Escape a string for safe interpolation into a markdown table cell or bullet.
+// Replaces pipes (`|` — breaks table column count), backticks (corrupt code
+// spans), and newlines (break bullet lines). Backticks are removed (rather
+// than backslash-escaped) because backslash-escapes inside code spans are NOT
+// honored by CommonMark — replacing with a similar-looking char preserves
+// rendering. This is defense against LLM-emitted content that may contain
+// any of these chars in `issue` / `file` strings.
+function escapeMd(s) {
+  if (s == null) return '';
+  return String(s)
+    .replace(/\|/g, '\\|')
+    .replace(/`/g, '‘')      // ` → left single quote (visually close)
+    .replace(/\r?\n/g, ' ');      // newlines → spaces inside a cell
+}
+
+function loadEnvelope(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { error: `file not found: ${filePath}` };
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    return { error: `JSON parse failed: ${e.message}`, raw };
+  }
+}
+
+function bucketSeverity(findings) {
+  const buckets = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, OTHER: 0 };
+  if (!Array.isArray(findings)) return buckets;
+  for (const f of findings) {
+    const sev = String(f.severity || '').toUpperCase();
+    if (sev in buckets) buckets[sev]++;
+    else buckets.OTHER++;
+  }
+  return buckets;
+}
+
+function describe(env) {
+  if (env.error) {
+    return {
+      ok: false,
+      error: env.error,
+      status: 'unparseable',
+      provider: 'unknown',
+      model: 'unknown',
+      counts: bucketSeverity([]),
+      totalFindings: 0,
+      cost: { inputTokens: 0, outputTokens: 0 },
+      elapsedMs: null,
+      recommendation: 'n/a',
+      formatOk: false,
+    };
+  }
+  const findings = Array.isArray(env.findings) ? env.findings : [];
+  const counts = bucketSeverity(findings);
+  // `status` field (added by HC-080a-spike fix pass) tells operators whether
+  // this row is a real review, a known error envelope, or an unknown shape.
+  // Status values produced by the CLI: 'reviewed' | 'no_changes' |
+  // 'empty_response' | 'auth_error' | 'rate_limited' | 'http_error'.
+  // Default to 'reviewed' if absent so older artifacts still display.
+  const status = env.status || (findings.length > 0 ? 'reviewed' : 'unknown');
+  return {
+    ok: true,
+    status,
+    provider: env.provider || 'unknown',
+    model: env.model || 'unknown',
+    counts,
+    totalFindings: findings.length,
+    cost: {
+      inputTokens: env.inputTokens || 0,
+      outputTokens: env.outputTokens || 0,
+    },
+    elapsedMs: typeof env.elapsedMs === 'number' ? env.elapsedMs : null,
+    recommendation: env.recommendation || (env.raw ? 'raw-output' : 'n/a'),
+    formatOk: !env.raw,
+    summary: env.summary || null,
+    findings,
+    httpStatus: env.httpStatus ?? null,
+    errorMessage: env.errorMessage || null,
+  };
+}
+
+// ── Findings overlap detection ────────────────────────────────────────────
+//
+// Two findings are considered the "same" bug if they reference the same
+// normalized file path AND both have explicit line numbers within ±3 of each
+// other. Findings without explicit line numbers are NOT auto-merged — two
+// unrelated file-level findings on the same file would otherwise collapse
+// into a false overlap.
+//
+// This is coarse — a precise match would require semantic similarity scoring,
+// which is overkill for a 5-release spike. The output is meant to anchor
+// manual review, not auto-decide.
+function findOverlap(aFindings, bFindings) {
+  const overlap = [];
+  const aOnly = [];
+  const bUsed = new Set();
+
+  for (const a of aFindings) {
+    let matched = false;
+    const aFile = normalizePath(a.file);
+    const aLine = Number.isFinite(a.line) ? a.line : null;
+    for (let i = 0; i < bFindings.length; i++) {
+      if (bUsed.has(i)) continue;
+      const b = bFindings[i];
+      const bFile = normalizePath(b.file);
+      const bLine = Number.isFinite(b.line) ? b.line : null;
+      if (aFile !== bFile || aFile === '') continue;
+      // Require both lines to be explicit AND nearby. Two undefined lines
+      // do NOT count as a match — they're treated as distinct file-level
+      // findings until a human merges them manually in the rubric.
+      if (aLine === null || bLine === null) continue;
+      if (Math.abs(aLine - bLine) > 3) continue;
+      overlap.push({ a, b });
+      bUsed.add(i);
+      matched = true;
+      break;
+    }
+    if (!matched) aOnly.push(a);
+  }
+  const bOnly = bFindings.filter((_, i) => !bUsed.has(i));
+  return { overlap, aOnly, bOnly };
+}
+
+function renderMarkdown(opus, gh) {
+  const lines = [];
+  lines.push('# Release-Review Provider Comparison (HC-080a-spike)');
+  lines.push('');
+  lines.push(`_Generated: ${new Date().toISOString()}_`);
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Dimension | Opus (Anthropic) | GPT-4.1 (GitHub Models) |');
+  lines.push('|---|---|---|');
+  lines.push(`| Provider | ${opus.provider} | ${gh.provider} |`);
+  lines.push(`| Status | ${opus.status} | ${gh.status} |`);
+  lines.push(`| Model | ${opus.model} | ${gh.model} |`);
+  lines.push(`| Format OK | ${opus.formatOk ? 'yes' : 'NO (raw)'} | ${gh.formatOk ? 'yes' : 'NO (raw)'} |`);
+  lines.push(`| Latency (ms) | ${opus.elapsedMs ?? 'n/a'} | ${gh.elapsedMs ?? 'n/a'} |`);
+  lines.push(`| Input tokens | ${opus.cost.inputTokens} | ${gh.cost.inputTokens} |`);
+  lines.push(`| Output tokens | ${opus.cost.outputTokens} | ${gh.cost.outputTokens} |`);
+  lines.push(`| Total findings | ${opus.totalFindings} | ${gh.totalFindings} |`);
+  lines.push(`| Findings: CRITICAL | ${opus.counts.CRITICAL} | ${gh.counts.CRITICAL} |`);
+  lines.push(`| Findings: HIGH | ${opus.counts.HIGH} | ${gh.counts.HIGH} |`);
+  lines.push(`| Findings: MEDIUM | ${opus.counts.MEDIUM} | ${gh.counts.MEDIUM} |`);
+  lines.push(`| Findings: LOW | ${opus.counts.LOW} | ${gh.counts.LOW} |`);
+  lines.push(`| Recommendation | ${opus.recommendation} | ${gh.recommendation} |`);
+  lines.push('');
+
+  if (!opus.ok || !gh.ok) {
+    lines.push('## Errors');
+    lines.push('');
+    if (!opus.ok) lines.push(`- Opus envelope: ${opus.error}`);
+    if (!gh.ok)   lines.push(`- GH Models envelope: ${gh.error}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const { overlap, aOnly: opusOnly, bOnly: ghOnly } = findOverlap(opus.findings, gh.findings);
+
+  lines.push('## Overlap analysis (coarse: same file + line ±3)');
+  lines.push('');
+  lines.push(`- Shared findings (both providers caught): ${overlap.length}`);
+  lines.push(`- Opus-only findings: ${opusOnly.length}`);
+  lines.push(`- GH Models-only findings: ${ghOnly.length}`);
+  lines.push('');
+
+  if (overlap.length) {
+    lines.push('### Shared findings (sample, up to 5)');
+    lines.push('');
+    for (const { a, b } of overlap.slice(0, 5)) {
+      lines.push(`- **${escapeMd(a.file)}:${a.line}** — Opus says: _${escapeMd(a.issue)}_ — GPT says: _${escapeMd(b.issue)}_`);
+    }
+    lines.push('');
+  }
+
+  if (opusOnly.length) {
+    lines.push('### Opus-only findings (POTENTIAL QUALITY GAP if real bugs)');
+    lines.push('');
+    for (const f of opusOnly.slice(0, 10)) {
+      lines.push(`- [${escapeMd(f.severity)}] **${escapeMd(f.file)}:${f.line ?? '?'}** — ${escapeMd(f.issue)}`);
+    }
+    if (opusOnly.length > 10) lines.push(`- ... and ${opusOnly.length - 10} more`);
+    lines.push('');
+  }
+
+  if (ghOnly.length) {
+    lines.push('### GH Models-only findings');
+    lines.push('');
+    for (const f of ghOnly.slice(0, 10)) {
+      lines.push(`- [${escapeMd(f.severity)}] **${escapeMd(f.file)}:${f.line ?? '?'}** — ${escapeMd(f.issue)}`);
+    }
+    if (ghOnly.length > 10) lines.push(`- ... and ${ghOnly.length - 10} more`);
+    lines.push('');
+  }
+
+  lines.push('## Decision rubric — fill after manual review');
+  lines.push('');
+  lines.push('- [ ] Did GH Models catch ≥80% of Opus HIGH/MEDIUM findings on this release?');
+  lines.push('- [ ] Were any Opus-only findings actually real bugs (not noise)?');
+  lines.push('- [ ] Were any GH Models-only findings actually real bugs that Opus missed?');
+  lines.push('- [ ] Was the output format clean for both providers?');
+  lines.push('');
+  lines.push('Append this comparison row to the rubric in');
+  lines.push('`docs/architecture/release-review-llm-provider-decision.md`.');
+
+  return lines.join('\n');
+}
+
+function main(argv) {
+  if (argv.length < 2) {
+    console.error('Usage: node cli/lib/compare-reviews.js <opus-findings.json> <gh-models-findings.json>');
+    console.error('');
+    console.error('Download both artifacts from a release CI run, then run this script.');
+    process.exit(1);
+  }
+  const opusFile = path.resolve(argv[0]);
+  const ghFile   = path.resolve(argv[1]);
+  const opus = describe(loadEnvelope(opusFile));
+  const gh   = describe(loadEnvelope(ghFile));
+  console.log(renderMarkdown(opus, gh));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = {
+  loadEnvelope,
+  describe,
+  findOverlap,
+  bucketSeverity,
+  renderMarkdown,
+  normalizePath,
+  escapeMd,
+};

package/lib/parse-review-json.js

@@ -0,0 +1,87 @@
+'use strict';
+/**
+ * parse-review-json.js — HC-080a-spike extraction helper.
+ *
+ * Robust JSON extraction from LLM output. Used by `hone release-review` to
+ * parse the structured `{ findings, summary, recommendation }` response from
+ * either Anthropic Opus or GitHub Models GPT-4.1.
+ *
+ * Why this exists: LLMs don't reliably emit pure JSON. The function tries
+ * three shapes in order:
+ *
+ *   1. Pure JSON — the whole response IS valid JSON.
+ *   2. Code-fenced — ```json { ... } ``` block somewhere in the response.
+ *   3. Forward-scan balanced — find every balanced `{...}` span in the
+ *      response and JSON.parse the LONGEST one (LLMs that emit a schema
+ *      example before their real answer would otherwise corrupt a naive
+ *      greedy regex; the real answer is almost always the largest block).
+ *
+ * The function returns the parsed object, or null on failure. Callers should
+ * use the loose substring fallback (e.g., `/\bCRITICAL\b/`) on the raw text
+ * when this returns null — that's the safety net against silent CRITICAL
+ * passes on non-JSON output.
+ */
+
+/**
+ * @param {string} text  Raw LLM response.
+ * @returns {object|null}  Parsed JSON, or null if no parseable JSON found.
+ */
+function parseReviewJSON(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  // Shape 1: try the whole string. Cheap; happens when the LLM follows the
+  // "Output as JSON" instruction strictly.
+  try { return JSON.parse(text); } catch { /* fall through */ }
+
+  // Shape 2: ```json ... ``` fenced block. Common when the LLM emits prose
+  // commentary before the structured answer.
+  const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
+  if (fenced) {
+    try { return JSON.parse(fenced[1]); } catch { /* fall through */ }
+  }
+
+  // Shape 3: forward-scan for balanced `{...}` spans, then try parsing each
+  // from longest to shortest. This handles LLMs that emit a schema example
+  // then their real answer (we'd otherwise capture both as one bad blob if
+  // we used a greedy `/\{[\s\S]*\}/` regex).
+  //
+  // The scanner tracks whether we're inside a JSON string literal so braces
+  // inside strings don't disrupt depth counting. Escape handling: a `\`
+  // inside a string marks the next character as escaped, so `\"` doesn't
+  // terminate the string.
+  const spans = [];
+  let depth = 0, start = -1, inString = false, escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (escaped) { escaped = false; continue; }
+    if (inString) {
+      if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === '{') {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        spans.push([start, i + 1]);
+        start = -1;
+      } else if (depth < 0) {
+        // Recover from malformed input — extra `}` without matching `{`.
+        depth = 0;
+      }
+    }
+  }
+
+  // Try longest spans first — the LLM's real answer is usually the largest
+  // block in the response.
+  spans.sort((a, b) => (b[1] - b[0]) - (a[1] - a[0]));
+  for (const [a, b] of spans) {
+    try { return JSON.parse(text.slice(a, b)); } catch { /* try next span */ }
+  }
+  return null;
+}
+
+module.exports = { parseReviewJSON };

package/lib/release-review-config.js

@@ -0,0 +1,98 @@
+'use strict';
+/**
+ * release-review-config.js — HC-080a-spike helpers extracted for unit coverage.
+ *
+ * Two helpers exist here because they were sources of bugs in the first
+ * spike CI run (PR #313 data point 1):
+ *
+ *   1. resolveBaseRef() — the CI step passes `--base origin/main` and the
+ *      CLI was prefixing `origin/` again, producing `origin/origin/main`
+ *      which `git diff` rejects. Either calling convention (`main` or
+ *      `origin/main`) should now work.
+ *
+ *   2. getMaxDiffChars() — GH Models GPT-4.1 enforces an 8000-token cap
+ *      on the REQUEST BODY (input). The previous 100k-char truncation
+ *      worked fine for Opus (200k context) but failed every GH Models call
+ *      with "Request body too large." Provider-specific truncation fixes it.
+ *      See the function's docstring for budget math + the input-only vs
+ *      total-body interpretation.
+ */
+
+/**
+ * Resolve a base ref to a stable `origin/<branch>` form regardless of
+ * whether the caller already prefixed it.
+ *
+ * Examples:
+ *   resolveBaseRef('main')             // → 'origin/main'
+ *   resolveBaseRef('origin/main')      // → 'origin/main'  (no double prefix)
+ *   resolveBaseRef('refs/remotes/origin/main')  // → 'origin/main'
+ *
+ * @param {string} base  User-supplied base branch.
+ * @returns {string}     Normalized git revision suitable for `git diff <ref>...HEAD`.
+ */
+function resolveBaseRef(base) {
+  if (!base || typeof base !== 'string') return 'origin/main';
+  const trimmed = base.trim();
+  if (trimmed.startsWith('refs/remotes/origin/')) {
+    return 'origin/' + trimmed.slice('refs/remotes/origin/'.length);
+  }
+  if (trimmed.startsWith('origin/')) return trimmed;
+  return 'origin/' + trimmed;
+}
+
+/**
+ * Provider-specific max diff size (in chars). Models with smaller input
+ * windows need more aggressive truncation.
+ *
+ * ## Budget math
+ *
+ * GH Models `openai/gpt-4.1` via `models.github.ai/inference` enforces an
+ * 8000-token cap on the REQUEST BODY (everything in the JSON payload sent
+ * to /chat/completions: system message + user message + model name + the
+ * `max_tokens` integer). The OUTPUT cap (`max_tokens: 4096`) is counted
+ * separately by the model and does NOT consume the 8000-token request
+ * budget — that 4096 governs how many tokens the response is allowed to
+ * have, not how many tokens our request can include.
+ *
+ * Decomposition of the 8000-token input budget (typical):
+ *   system prompt           ~600 tokens (~2400 chars)
+ *   user prompt template    ~200 tokens (~800 chars)
+ *   file list (40 entries)  ~400 tokens (~1600 chars)
+ *   safety headroom         ~800 tokens (~3200 chars)
+ *   -------------------------------
+ *   diff budget             ~6000 tokens ≈ 24000 chars
+ *
+ * We use 20000 chars (≈5000 tokens) as a conservative cap to leave room
+ * for prompt drift if we evolve the system/user templates. If GH Models
+ * documentation later confirms the cap is TOTAL (input + output) instead
+ * of input-only, drop this number AND `max_tokens` together.
+ *
+ * Anthropic Opus `claude-opus-4-20250514`: 200K context window. The 100K
+ * char cap is generous and unchanged from the original implementation.
+ *
+ * ## Default behavior — FAIL CLOSED
+ *
+ * Unknown providers receive the SMALLEST known cap (20000), not the
+ * largest. Reasoning: if a future small-context provider (haiku, mini,
+ * flash) is added and a developer forgets to add a switch case here,
+ * the 20000 default truncates safely. Falling back to 100000 would
+ * re-introduce exactly the bug class this helper exists to fix.
+ *
+ * @param {string} provider  'opus' or 'gh-models'.
+ * @returns {number}         Max diff chars to send to this provider.
+ */
+function getMaxDiffChars(provider) {
+  switch (provider) {
+    case 'opus':
+      return 100000;
+    case 'gh-models':
+      return 20000;
+    default:
+      return 20000;
+  }
+}
+
+module.exports = {
+  resolveBaseRef,
+  getMaxDiffChars,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {