@hone-ai/cli 1.18.0 → 1.20.0

package/lib/patch-apply.js

@@ -0,0 +1,108 @@
+'use strict';
+/**
+ * patch-apply.js — HC-019n-followup-20 (pipeline-recovery condition 5).
+ *
+ * The true closed loop: does step_4's diff actually APPLY to a real working
+ * tree? The server can only check that the output LOOKS like a diff
+ * (patch-validator, condition 4) because it has no adopter tree. Only the CLI,
+ * running inside the repo, can run `git apply --check`.
+ *
+ * This module is the pure half — extract a diff from agent output and interpret
+ * a `git apply --check` result. The git invocation itself lives in the command
+ * (hone-cli.js) so this stays I/O-free and unit-testable.
+ *
+ * Condition 4 (well-formed) and condition 5 (applies) are genuinely different:
+ * run c122c92a produced a diff that PASSED the server validator and FAILED to
+ * apply — the agent emitted `@@ -0,0 +1,54 @@` (create-file) for a file that
+ * already existed. Structure is not applicability.
+ */
+
+/**
+ * Pull the unified diff out of a code-builder artifact.
+ *
+ * Prefers a fenced ```diff block (what the HC-019n-followup-19 prompt asks
+ * for). Falls back to a bare diff — headers through the last hunk-ish line —
+ * so a model that forgets the fence but emits a real patch is still checkable.
+ *
+ * @param {string} output  raw step_4 output
+ * @returns {{ diff: string|null, source: 'fenced'|'bare'|null, noChanges: boolean }}
+ */
+function extractDiff(output) {
+  const text = String(output || '');
+
+  // Honest "no changes" escape from the prompt — a first-class signal, not a
+  // failure. Anchored to the ## Patch section so prose elsewhere can't trip it.
+  const patchIdx = text.indexOf('## Patch');
+  if (patchIdx !== -1) {
+    const section = text.slice(patchIdx, patchIdx + 400);
+    if (/NO CHANGES\b/i.test(section)) {
+      return { diff: null, source: null, noChanges: true };
+    }
+  }
+
+  // Fenced ```diff … ``` (allow ```patch too; both are used in the wild).
+  const fenced = text.match(/```(?:diff|patch)\r?\n([\s\S]*?)\r?\n```/);
+  if (fenced && /^---[ \t]/m.test(fenced[1])) {
+    return { diff: normalize(fenced[1]), source: 'fenced', noChanges: false };
+  }
+
+  // Bare fallback: from the first `diff --git` or `--- ` header to the end.
+  const headerMatch = text.match(/^(?:diff --git |--- )/m);
+  if (headerMatch) {
+    const start = text.indexOf(headerMatch[0]);
+    let body = text.slice(start);
+    // Trim a trailing prose tail: keep up to the last line that looks like part
+    // of a patch (context/add/remove/header/hunk). Anything after is commentary.
+    const lines = body.split('\n');
+    let lastPatchLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^(?:diff --git |index |--- |\+\+\+ |@@ |[ +\-\\])/.test(lines[i]) || lines[i] === '') {
+        lastPatchLine = i;
+      } else if (lastPatchLine !== -1 && lines[i].trim() !== '') {
+        // a non-patch, non-blank line after we've seen patch content → stop
+        break;
+      }
+    }
+    if (lastPatchLine === -1) return { diff: null, source: null, noChanges: false };
+    body = lines.slice(0, lastPatchLine + 1).join('\n');
+    return { diff: normalize(body), source: 'bare', noChanges: false };
+  }
+
+  return { diff: null, source: null, noChanges: false };
+}
+
+/** A unified diff must end with exactly one trailing newline for `git apply`. */
+function normalize(diff) {
+  return diff.replace(/\s*$/, '') + '\n';
+}
+
+/**
+ * Interpret a `git apply --check` result into a verdict.
+ *
+ * @param {{ code: number, stderr: string }} result  from running git
+ * @returns {{ applies: boolean, verdict: 'clean'|'offset'|'failed', detail: string }}
+ */
+function interpretApplyCheck({ code, stderr }) {
+  const err = String(stderr || '');
+  if (code === 0) {
+    // `--check` succeeds even with fuzz; surface offsets as a softer signal
+    // because they mean the agent's line numbers drifted from the real file.
+    const offset = /offset \d+ line/i.test(err);
+    return {
+      applies: true,
+      verdict: offset ? 'offset' : 'clean',
+      detail: offset ? 'applies, but with line-number offset (context drift)' : 'applies cleanly',
+    };
+  }
+  // Extract the most useful line: git's "patch failed" / "does not apply" / etc.
+  const firstError = (err.split('\n').find(l => /error:|patch failed|does not apply/i.test(l)) || err.split('\n')[0] || '')
+    .replace(/^error:\s*/i, '')
+    .trim();
+  return {
+    applies: false,
+    verdict: 'failed',
+    detail: firstError || 'git apply --check reported failure',
+  };
+}
+
+module.exports = { extractDiff, interpretApplyCheck, normalize };

package/lib/pipeline-config.js

@@ -32,6 +32,10 @@ const path = require('node:path');
 
 const KNOWN_THRESHOLD_KEYS = ['estimate_full_sdlc', 'recently_modified_window_days'];
 
+const CI_GATE_MODES = ['github', 'local', 'both', 'none'];
+const KNOWN_CI_GATE_KEYS = ['gate', 'local_command'];
+const DEFAULT_CI_LOCAL_COMMAND = 'make ci';
+
 /**
  * Read story-classifier thresholds from .pipeline-config.yml.
  *
@@ -77,7 +81,303 @@ function readStoryClassifierConfig(repoRoot) {
   return {};
 }
 
+/**
+ * Normalize raw ci.gate input. Validates against CI_GATE_MODES. Returns
+ * the normalized lower-case mode string, OR 'github' (backward-compat
+ * default) when input is missing/empty/invalid. Warns to stderr on
+ * non-empty input that doesn't match a valid mode, so a typo (e.g.
+ * `gate: githhub`) surfaces at queue time instead of silently degrading.
+ *
+ * @param {unknown} raw  raw value from the YAML
+ * @returns {'github'|'local'|'both'|'none'}
+ */
+function normalizeCIGate(raw) {
+  if (raw === undefined || raw === null || raw === '') return 'github';
+  if (typeof raw !== 'string') {
+    console.warn(`[pipeline-config] ci.gate must be a string; got ${typeof raw}, defaulting to 'github'`);
+    return 'github';
+  }
+  const lower = raw.trim().toLowerCase();
+  if (CI_GATE_MODES.includes(lower)) return lower;
+  console.warn(`[pipeline-config] ci.gate '${raw}' is not one of ${CI_GATE_MODES.join('|')} — defaulting to 'github'`);
+  return 'github';
+}
+
+/**
+ * Read the CI-gate configuration from .pipeline-config.yml's `ci:` block.
+ * Backward-compatible: returns the safe defaults (gate='github', local_command='make ci')
+ * when the config is missing or omits these keys. New for HC-101-followup-2.
+ *
+ * @param {string} repoRoot
+ * @returns {{ gate: 'github'|'local'|'both'|'none', local_command: string }}
+ */
+function readCIGateConfig(repoRoot) {
+  const defaults = { gate: 'github', local_command: DEFAULT_CI_LOCAL_COMMAND };
+  if (!repoRoot || typeof repoRoot !== 'string') return defaults;
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); }
+    catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.ci;
+    if (!block || typeof block !== 'object') {
+      // No ci: block in THIS candidate — try the next one (e.g., adopter
+      // might keep a slim top-level .pipeline-config.yml and put the ci
+      // block in .github/.pipeline-config.yml). Returning defaults here
+      // would silently drop the second-candidate's ci block.
+      continue;
+    }
+
+    const gate = normalizeCIGate(block.gate);
+    const cmd  = (typeof block.local_command === 'string' && block.local_command.trim())
+      ? block.local_command.trim()
+      : DEFAULT_CI_LOCAL_COMMAND;
+    return { gate, local_command: cmd };
+  }
+
+  return defaults;
+}
+
+// ── HC-019n-followup-28: E2E spec-generation mode ─────────────────────────────
+// step_3b (e2e-test-spec-writer) writes the Playwright specs. It was defined but
+// dormant (no activation path). This makes it an adopter preference, like ci.gate:
+//   auto  (default) → run step_3b when the story requires an E2E plan (step_0
+//                     emitted `Requires E2E Plan: yes`); skip otherwise.
+//   never           → never run step_3b (the original "manual E2E mode only").
+// A per-run --e2e-specs / --no-e2e-specs flag overrides the config (flag > config
+// > default), exactly the ci.gate precedence.
+const E2E_SPEC_MODES = ['auto', 'never'];
+const DEFAULT_E2E_SPEC_MODE = 'auto';
+
+/** Normalize an e2e.spec_generation value to a known mode, defaulting to auto. */
+function normalizeE2eSpecMode(v) {
+  const s = String(v == null ? '' : v).toLowerCase().trim();
+  return E2E_SPEC_MODES.includes(s) ? s : DEFAULT_E2E_SPEC_MODE;
+}
+
+/**
+ * Read the E2E spec-generation mode from .pipeline-config.yml's `e2e:` block.
+ * Same candidate order + graceful degradation as readCIGateConfig.
+ *
+ * @param {string} repoRoot
+ * @returns {'auto'|'never'} default 'auto' when config is missing/malformed.
+ */
+function readE2eSpecMode(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return DEFAULT_E2E_SPEC_MODE;
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.e2e;
+    if (!block || typeof block !== 'object') continue; // try the next candidate
+    if (block.spec_generation === undefined) continue;
+    return normalizeE2eSpecMode(block.spec_generation);
+  }
+
+  return DEFAULT_E2E_SPEC_MODE;
+}
+
+// ── HC-019n-followup-34: closed-loop verification gate ────────────────────────
+// The CLI verbs (verify-patch/verify-pr) EXECUTE and report a verdict to the
+// server. `verification.gate` controls what the server does with it:
+//   advisory (default) → record the verdict, never change flow;
+//   enforce            → (follow-up) a red verdict blocks the run.
+// Mirrors ci.gate: adopter preference in .pipeline-config.yml, default-safe.
+const VERIFICATION_GATE_MODES = ['advisory', 'enforce'];
+const DEFAULT_VERIFICATION_GATE = 'advisory';
+
+/** Normalize a verification.gate value, defaulting to advisory. */
+function normalizeVerificationGate(v) {
+  const s = String(v == null ? '' : v).toLowerCase().trim();
+  return VERIFICATION_GATE_MODES.includes(s) ? s : DEFAULT_VERIFICATION_GATE;
+}
+
+/**
+ * Read the verification gate mode from .pipeline-config.yml's `verification:`
+ * block. Same candidate order + graceful degradation as readCIGateConfig.
+ *
+ * @param {string} repoRoot
+ * @returns {'advisory'|'enforce'} default 'advisory' when missing/malformed.
+ */
+function readVerificationGateConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return DEFAULT_VERIFICATION_GATE;
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.verification;
+    if (!block || typeof block !== 'object') continue;
+    if (block.gate === undefined) continue;
+    return normalizeVerificationGate(block.gate);
+  }
+
+  return DEFAULT_VERIFICATION_GATE;
+}
+
+// ── HC-COMM-011-followup-6: which verdict sources may DRIVE the step_4 gate ────
+// under enforce. Default: verify-patch only (the executed-test gate) — so enabling
+// enforce never silently lets agent-eval (which verifies BEHAVIOUR, not tests)
+// auto-advance the build. An adopter doing prompt-work opts agent-eval in.
+// verify-pr is not gate-eligible (step_5c has no gate) and is rejected here.
+const KNOWN_GATE_SOURCES = ['verify-patch', 'agent-eval'];
+const DEFAULT_GATE_SOURCES = ['verify-patch'];
+
+function normalizeGateSources(raw) {
+  if (!Array.isArray(raw)) {
+    console.warn(`[pipeline-config] verification.gate_sources must be a list; got ${typeof raw}, defaulting to ${DEFAULT_GATE_SOURCES.join(',')}`);
+    return [...DEFAULT_GATE_SOURCES];
+  }
+  const valid = [...new Set(raw.filter((s) => KNOWN_GATE_SOURCES.includes(s)))];
+  if (valid.length === 0) {
+    console.warn(`[pipeline-config] verification.gate_sources had no known source (allowed: ${KNOWN_GATE_SOURCES.join('|')}); defaulting to ${DEFAULT_GATE_SOURCES.join(',')}`);
+    return [...DEFAULT_GATE_SOURCES];
+  }
+  return valid;
+}
+
+/**
+ * Read verification.gate_sources from .pipeline-config.yml. Default-safe:
+ * ['verify-patch']. Any-of semantics — under enforce, any authorized source's
+ * green verdict advances step_4; any authorized source's red blocks.
+ * @returns {string[]}
+ */
+function readVerificationGateSources(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return [...DEFAULT_GATE_SOURCES];
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    let parsed;
+    try { parsed = require('js-yaml').load(raw); } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.verification;
+    if (!block || typeof block !== 'object' || block.gate_sources === undefined) continue;
+    return normalizeGateSources(block.gate_sources);
+  }
+  return [...DEFAULT_GATE_SOURCES];
+}
+
+// ── HC-COMM-011-followup-1: Agent eval config reader ──────────────────────────
+/**
+ * Read agent eval targets from .pipeline-config.yml's `agent_eval:` block.
+ * Same candidate order + graceful degradation as readCIGateConfig.
+ * 
+ * @param {string} repoRoot
+ * @returns {{ targets: Array<{name, invoke: {command}}> }} default {targets: []}
+ */
+function readAgentEvalConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return { targets: [] };
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.agent_eval;
+    if (!block || typeof block !== 'object') continue;
+
+    const targets = [];
+    if (Array.isArray(block.targets)) {
+      for (const target of block.targets) {
+        if (!target || typeof target !== 'object') continue;
+        if (typeof target.name !== 'string' || !target.name.trim()) {
+          console.warn(`[agent-eval-config] target has no valid name, skipping`);
+          continue;
+        }
+        if (!target.invoke || typeof target.invoke !== 'object' || typeof target.invoke.command !== 'string' || !target.invoke.command.trim()) {
+          console.warn(`[agent-eval-config] target "${target.name}" has no valid invoke.command, skipping`);
+          continue;
+        }
+        targets.push({
+          name: target.name.trim(),
+          invoke: { command: target.invoke.command.trim() },
+        });
+      }
+    }
+
+    return { targets };
+  }
+
+  return { targets: [] };
+}
+
 module.exports = {
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
+  readCIGateConfig,
+  normalizeCIGate,
+  CI_GATE_MODES,
+  KNOWN_CI_GATE_KEYS,
+  DEFAULT_CI_LOCAL_COMMAND,
+  readE2eSpecMode,
+  normalizeE2eSpecMode,
+  E2E_SPEC_MODES,
+  DEFAULT_E2E_SPEC_MODE,
+  readVerificationGateConfig,
+  normalizeVerificationGate,
+  VERIFICATION_GATE_MODES,
+  DEFAULT_VERIFICATION_GATE,
+  readVerificationGateSources,
+  normalizeGateSources,
+  KNOWN_GATE_SOURCES,
+  DEFAULT_GATE_SOURCES,
+  readAgentEvalConfig,
 };

package/lib/pipeline-status.js

@@ -15,7 +15,9 @@ const yaml = require('js-yaml');
 
 // ── Canonical step file naming convention (H-009/A2) ───────────────
 // Verified across .github/pipeline/H-001/, H-014/, H-029/, H-035/, H-076/.
-// step_3b is conditional (manual E2E mode only).
+// step_3b is conditional. HC-019n-followup-28 gave it an activation path:
+// run-story enables it (config.enableConditional) when e2e.spec_generation != 'never';
+// the orchestrator then runs it when the story requires an E2E plan, else skips it.
 // step_5b is conditional (SA-002 skill audit, present when story consults skills).
 // step_5c is conditional (H-076 CI gate, present after PR creation).
 //
@@ -72,7 +74,30 @@ const CONDITIONAL_STEPS = new Set(STEPS.filter(s => s.conditional).map(s => s.ke
 //   - `hone step-5b` (SA-002, this is what surfaced the bug — when run
 //     against OptionsFlow's feature/E34-A-* branches, story id was
 //     mis-extracted as "A-resolve")
-const STORY_ID_PATTERN = /(E[0-9]+-[A-Z][A-Za-z0-9]*|[A-Z]+[-_][A-Za-z0-9]+)/;
+//
+// H-029-followup-2 (2026-06-04): added `(?:-followup-[0-9]+[a-z]?(?=[-_]|$))?`
+// to both alternatives so `hone status` on `feat/HC-052d-followup-1-...`
+// shows the followup story id correctly instead of stopping at `HC-052d`.
+// Mirrors H-029-followup-1's fix to the learnings-gate regex. `[a-z]?`
+// covers the HC-019n family's parallel-iteration suffix shape (HC-019n-
+// followup-13a etc.) — real prod data, not speculation. Trailing
+// lookahead `(?=[-_]|$)` anchors the suffix so description tails don't
+// get gobbled. The adopter-facing setup-ai-pipeline.sh default stays as
+// the H-005-canonical `[A-Z]+[-_][A-Za-z0-9]+` — pinned by
+// tests/regression/H-005-pizza-tracker-non-jira-regex.test.js.
+// HC-CI-005: the middle alternative is NEW. `[A-Z]+[-_][A-Za-z0-9]+` stops at
+// the first segment, so a letters-letters-digits id read as only its first two
+// parts: HC-CI-003 -> "HC-CI", HC-COMM-007 -> "HC-COMM", HC-RC-002 -> "HC-RC".
+// That silently broke the HC-019b-followup-1 F1 architect-config lookup, which
+// keys on the extracted id — a miss looks identical to "no architect needed".
+//
+// The new alternative is deliberately NARROW: letters, letters, then DIGITS.
+// A generic trailing `(?:-[A-Za-z0-9]+)*` would be greedy and swallow branch
+// prose — `HC-052-add-uuid-validation` would extract "HC-052-add". Verified:
+// with this alternative that branch still yields "HC-052".
+// Order matters — regex alternation is first-match-wins, so this must precede
+// the general form or the general form shadows it.
+const STORY_ID_PATTERN = /(E[0-9]+-[A-Z][A-Za-z0-9]*(?:-followup-[0-9]+[a-z]?(?=[-_]|$))?|[A-Z]+[-_][A-Z]+[-_][0-9]+[a-z]?(?:-followup-[0-9]+[a-z]?(?=[-_]|$))?|[A-Z]+[-_][A-Za-z0-9]+(?:-followup-[0-9]+[a-z]?(?=[-_]|$))?)/;
 
 // ─────────────────────────────────────────────────────────────────────
 // extractStoryIdFromBranch — pure regex on branch name

package/lib/refresh-knowledge.js

@@ -25,6 +25,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { execSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
 
 // HC-019y (2026-05-29): removed `.github/agents` from refresh paths.
 // Agents live exclusively at `.claude/agents/` (Claude Code's read path)
@@ -47,8 +48,14 @@ const FRONTMATTER_MANAGED_RE = /^---[\s\S]*?managed_by:\s*\S+[\s\S]*?---/m;
 function defaultRunChannel(name, repoRoot) {
   const cliPath = path.resolve(__dirname, '..', 'hone-cli.js');
   try {
+    // SC-002-followup-2: this spawns the Hone CLI, whose own git calls mostly
+    // run WITHOUT a cwd (they mean "the repo I was invoked in"). If we handed
+    // down an ambient GIT_DIR — under a hook, `rebase -x`, or
+    // `submodule foreach` — the child would resolve those against the OUTER
+    // repo while we intended repoRoot. Sanitize at the boundary instead.
     const out = execSync(`node "${cliPath}" ${name}`, {
       cwd: repoRoot,
+      env: gitEnv(),
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 5 * 60 * 1000,

package/lib/release-review-cache.js

@@ -0,0 +1,162 @@
+'use strict';
+/**
+ * HC-RC-002-followup-1: CLI-side helper for the `hone release-review`
+ * content-hash cache integration.
+ *
+ * Pattern: compute a contentHash over (diff + systemPrompt + model). POST
+ * to the server's /llm-cache/lookup; on hit, return the cached response
+ * with cache_hit:true (zero LLM cost). On miss, the caller runs the LLM
+ * normally then POSTs back to /llm-cache/store.
+ *
+ * The cache_hit path produces an envelope that matches the post-LLM output
+ * shape so downstream tooling (compare-reviews.js, CI artifact parsers)
+ * see no difference between cached + fresh runs.
+ */
+
+const crypto = require('node:crypto');
+
+const GATE_NAME = 'release-review';
+// 14 days = HC-RC-002 default TTL. Held local so the CLI can tune
+// independently of server-side default if needed.
+const DEFAULT_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+
+/**
+ * Compute the contentHash for a release-review invocation. Bound to:
+ *   - diff: the git diff content under review
+ *   - systemPrompt: the reviewer instructions (bumping the prompt invalidates)
+ *   - model: which LLM (Opus vs GPT-4.1 give different reviews — separate keys)
+ *
+ * NOT bound (intentionally): user-supplied --max-files, --format, --base.
+ * These don't affect the LLM's review semantics — only output formatting.
+ *
+ * @param {{diff: string, systemPrompt: string, model: string}} input
+ * @returns {string} sha256 hex digest
+ */
+function computeReviewContentHash(input) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('computeReviewContentHash: input must be an object');
+  }
+  for (const k of ['diff', 'systemPrompt', 'model']) {
+    if (typeof input[k] !== 'string' || input[k].length === 0) {
+      throw new Error(`computeReviewContentHash: ${k} must be a non-empty string`);
+    }
+  }
+  // Sorted-key canonical JSON (HC-RC-001 + HC-RC-002 pattern). Avoids
+  // CLI-vs-server divergence from key-order quirks.
+  const canonical = '{'
+    + JSON.stringify('diff') + ':' + JSON.stringify(input.diff) + ','
+    + JSON.stringify('model') + ':' + JSON.stringify(input.model) + ','
+    + JSON.stringify('systemPrompt') + ':' + JSON.stringify(input.systemPrompt)
+    + '}';
+  return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+/**
+ * Look up a cached release-review response.
+ *
+ * Returns null on miss OR on any error (cache is opportunistic — caller
+ * falls through to the LLM). Logs failures to stderr so adopters can
+ * diagnose if hits never materialize.
+ *
+ * @param {{axios: object, apiBase: string, token: string, contentHash: string, model: string, banner?: Function}} opts
+ * @returns {Promise<object|null>}
+ */
+async function lookupReviewCache(opts) {
+  const { axios, apiBase, token, contentHash, model, banner } = opts;
+  const log = banner || ((msg) => process.stderr.write(`[release-review] ${msg}\n`));
+  if (!apiBase || !token) {
+    log('cache lookup skipped: missing apiBase/token');
+    return null;
+  }
+  try {
+    const { data } = await axios.post(
+      `${apiBase}/llm-cache/lookup`,
+      { contentHash, model, gateName: GATE_NAME },
+      {
+        headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+        timeout: 10_000,
+      },
+    );
+    if (data && data.hit === true) return data;
+    return null;
+  } catch (e) {
+    // 4xx (bad contentHash, bad model) shouldn't crash the run; 5xx
+    // shouldn't either. Cache is opportunistic.
+    log(`cache lookup failed (non-fatal): ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Store a fresh release-review response in the cache for future hits.
+ *
+ * Fire-and-forget by design — a failed store must not block the operator
+ * from seeing the review result. Returns a Promise that the caller MAY
+ * await for telemetry, but normal usage is .catch() + ignore.
+ *
+ * @param {{
+ *   axios: object,
+ *   apiBase: string,
+ *   token: string,
+ *   contentHash: string,
+ *   model: string,
+ *   response: object,
+ *   tokensSaved?: number,
+ *   ttlMs?: number,
+ *   banner?: Function
+ * }} opts
+ * @returns {Promise<{stored: boolean, error?: string}>}
+ */
+async function storeReviewCache(opts) {
+  const { axios, apiBase, token, contentHash, model, response, tokensSaved, ttlMs, banner } = opts;
+  const log = banner || ((msg) => process.stderr.write(`[release-review] ${msg}\n`));
+  if (!apiBase || !token) {
+    return { stored: false, error: 'missing apiBase/token' };
+  }
+  try {
+    await axios.post(
+      `${apiBase}/llm-cache/store`,
+      {
+        contentHash, model, gateName: GATE_NAME, response,
+        tokensSaved: tokensSaved || 0,
+        ttlMs: ttlMs || DEFAULT_TTL_MS,
+      },
+      {
+        headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+        timeout: 10_000,
+      },
+    );
+    return { stored: true };
+  } catch (e) {
+    log(`cache store failed (non-fatal): ${e.message}`);
+    return { stored: false, error: e.message };
+  }
+}
+
+/**
+ * Normalize the --cache flag value. Default ON.
+ *
+ * @param {string|undefined} raw
+ * @returns {boolean}
+ */
+function normalizeCacheFlag(raw) {
+  if (raw === undefined || raw === null) return true;
+  const v = String(raw).toLowerCase().trim();
+  if (v === 'off' || v === 'false' || v === '0' || v === 'no') return false;
+  if (v === 'on'  || v === 'true'  || v === '1' || v === 'yes') return true;
+  // Unknown → default to ON with a warning. Adopters shouldn't have to
+  // memorize keywords; fall to safe default.
+  process.stderr.write(
+    `[release-review] warning: unknown --cache value "${raw}" — defaulting to "on"\n`,
+  );
+  return true;
+}
+
+module.exports = {
+  computeReviewContentHash,
+  lookupReviewCache,
+  storeReviewCache,
+  normalizeCacheFlag,
+  GATE_NAME,
+  DEFAULT_TTL_MS,
+};

package/lib/release-review-config.js

@@ -67,8 +67,10 @@ function resolveBaseRef(base) {
  * 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.
+ * Anthropic Opus `claude-opus-4-8`: 1M context window (upgraded from
+ * the legacy 4-20250514's 200K). The 100K char cap is well below the
+ * model's headroom but kept conservative — the prompt + diff together
+ * comfortably fit, and bumping the cap is a separate decision.
  *
  * ## Default behavior — FAIL CLOSED
  *