@hone-ai/cli 1.17.0 → 1.19.0

package/lib/eval-evidence.js

@@ -0,0 +1,213 @@
+'use strict';
+/**
+ * eval-evidence.js — HC-RC-001 CLI-side evidence file producer.
+ *
+ * When the adopter passes `--evidence-mode local` to `hone eval`, this
+ * module writes `.hone/eval-evidence.json` containing a signed payload
+ * the CI gate can verify offline (no Anthropic API call).
+ *
+ * The HMAC secret is sourced from `process.env.HONE_EVIDENCE_SECRET` at
+ * adopter-machine call time and NEVER leaves the machine. Server stores
+ * only the ciphertext form (envelope-encrypted via byo-key-crypto). CI
+ * fetches the same secret from its own org-scoped vault.
+ *
+ * When the env var is missing, the CLI prints a one-line warning and
+ * SKIPS the evidence file (does NOT throw — `hone eval` still exits with
+ * the eval result code; evidence is opportunistic).
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const SIGNER_PATH = path.resolve(__dirname, '..', '..', 'server', 'src', 'services', 'evidence-signer.js');
+const { buildEvidence, computeScenarioSetHash } = require(SIGNER_PATH);
+
+const DEFAULT_OUTPUT_REL = path.join('.hone', 'eval-evidence.json');
+const ENV_SECRET = 'HONE_EVIDENCE_SECRET';
+const ENV_GRADER_VERSION = 'HONE_GRADER_VERSION';
+const ENV_PROMPT_SET_VERSION = 'HONE_PROMPT_SET_VERSION';
+const ENV_MODEL = 'HONE_EVIDENCE_MODEL';
+const ENV_DIFF_FILE = 'HONE_DIFF_FILE';
+const ENV_ORG_ID = 'HONE_ORG_ID';
+
+const SUPPORTED_MODES = ['local', 'off'];
+
+/**
+ * Normalize the --evidence-mode flag. Unknown values fall through to
+ * 'off' with a warning to stderr (NOT a hard fail — adopters in older
+ * scripts shouldn't break on typos that pre-date this story).
+ *
+ * @param {string|undefined} raw
+ * @returns {string}
+ */
+function normalizeEvidenceMode(raw) {
+  if (raw === undefined || raw === null || raw === '') return 'off';
+  const v = String(raw).toLowerCase().trim();
+  if (SUPPORTED_MODES.includes(v)) return v;
+  process.stderr.write(
+    `[hone eval] warning: unknown --evidence-mode value "${raw}" — falling back to "off"\n`,
+  );
+  return 'off';
+}
+
+/**
+ * Read the diff that the evidence covers.
+ *
+ * Single source today: `process.env.HONE_DIFF_FILE` path. Callers that want
+ * to pipe via stdin must materialize to a temp file and set the env var;
+ * stdin streaming inside an async commander action is footgun-prone (would
+ * require parking on process.stdin before the eval starts, complicating
+ * error handling). Empty return → caller should refuse to produce evidence.
+ *
+ * HC-RC-001 pass-1 (LOW-2): docstring no longer claims stdin fallback that
+ * the implementation didn't honor.
+ *
+ * @param {{readFileSync?: Function}=} deps
+ * @returns {string}
+ */
+function readDiffInput(deps = {}) {
+  const readFileSync = deps.readFileSync || fs.readFileSync;
+  const envPath = process.env[ENV_DIFF_FILE];
+  if (envPath && envPath.length > 0) {
+    return readFileSync(envPath, 'utf8');
+  }
+  return '';
+}
+
+/**
+ * Build the evidence file payload from eval results + env-supplied
+ * metadata. Returns the canonical record or null when prerequisites
+ * are missing.
+ *
+ * Reasons we return null (not throw): adopter scripts that pass
+ * `--evidence-mode local` opportunistically must not crash on a
+ * missing secret. We log a warning to stderr and continue.
+ *
+ * @param {{
+ *   results: object,
+ *   mode: string,
+ *   diff?: string,
+ *   secret?: string,
+ *   model?: string,
+ *   graderVersion?: string,
+ *   promptSetVersion?: string,
+ *   now?: Date,
+ *   warn?: Function
+ * }} input
+ * @returns {object|null}
+ */
+function buildEvidenceFromEval(input) {
+  if (!input || typeof input !== 'object') return null;
+  const warn = input.warn || ((msg) => process.stderr.write(`[hone eval] ${msg}\n`));
+  if (input.mode !== 'local') return null;
+
+  // Trim env-sourced secret to defeat trailing-newline mismatches between
+  // CLI signer and server verifier (e.g. Windows `setx` adds \r\n).
+  const rawSecret = input.secret || process.env[ENV_SECRET] || '';
+  const secret = String(rawSecret).trim();
+  if (secret.length === 0) {
+    warn(`evidence-mode=local but ${ENV_SECRET} is not set — skipping evidence file`);
+    return null;
+  }
+  const diff = typeof input.diff === 'string' ? input.diff : readDiffInput();
+  if (diff.length === 0) {
+    warn(`evidence-mode=local but no diff input (set ${ENV_DIFF_FILE}) — skipping evidence file`);
+    return null;
+  }
+  const model = input.model || process.env[ENV_MODEL] || '';
+  const graderVersion = input.graderVersion || process.env[ENV_GRADER_VERSION] || '';
+  const promptSetVersion = input.promptSetVersion || process.env[ENV_PROMPT_SET_VERSION] || '';
+  // HC-RC-001 pass-1 (CRIT-2): orgId is REQUIRED to bind evidence to a
+  // specific org. Cross-org replay is otherwise possible.
+  const orgId = input.orgId || process.env[ENV_ORG_ID] || '';
+  if (!model || !graderVersion || !promptSetVersion || !orgId) {
+    warn(
+      `evidence-mode=local missing metadata ` +
+      `(model=${ENV_MODEL}, graderVersion=${ENV_GRADER_VERSION}, ` +
+      `promptSetVersion=${ENV_PROMPT_SET_VERSION}, orgId=${ENV_ORG_ID}) — skipping evidence file`,
+    );
+    return null;
+  }
+  if (!input.results || typeof input.results !== 'object') {
+    warn('evidence-mode=local but eval results are missing — skipping evidence file');
+    return null;
+  }
+  // HC-RC-001 pass-1 (HIGH-3): bind which scenarios were actually run so an
+  // adopter cannot cherry-pick a passing subset and present as full evidence.
+  // Caller passes scenarioIds; if missing, derive from results.scenarios[].id
+  // (the eval-runner output shape).
+  const scenarioIds = Array.isArray(input.scenarioIds)
+    ? input.scenarioIds
+    : (Array.isArray(input.results.scenarios)
+        ? input.results.scenarios.map((s) => s && s.id).filter((id) => typeof id === 'string' && id.length > 0)
+        : []);
+  if (scenarioIds.length === 0) {
+    warn('evidence-mode=local but no scenario IDs available — skipping evidence file');
+    return null;
+  }
+  let scenarioSetHash;
+  try {
+    scenarioSetHash = computeScenarioSetHash(scenarioIds);
+  } catch (e) {
+    warn(`evidence-mode=local scenarioSetHash failed: ${e.message} — skipping evidence file`);
+    return null;
+  }
+  try {
+    return buildEvidence({
+      diff,
+      model,
+      graderVersion,
+      promptSetVersion,
+      orgId,
+      scenarioSetHash,
+      results: input.results,
+      secret,
+      now: input.now,
+    });
+  } catch (e) {
+    warn(`evidence-mode=local but buildEvidence failed: ${e.message} — skipping evidence file`);
+    return null;
+  }
+}
+
+/**
+ * Write the evidence record to .hone/eval-evidence.json relative to a
+ * given root. Creates the .hone/ directory if missing.
+ *
+ * @param {object} record — output of buildEvidenceFromEval
+ * @param {{
+ *   root?: string,
+ *   outputPath?: string,
+ *   mkdirSync?: Function,
+ *   writeFileSync?: Function
+ * }=} deps
+ * @returns {string} the absolute path written
+ */
+function writeEvidenceFile(record, deps = {}) {
+  if (!record || typeof record !== 'object') {
+    throw new Error('writeEvidenceFile: record must be an object');
+  }
+  const root = deps.root || process.cwd();
+  const rel = deps.outputPath || DEFAULT_OUTPUT_REL;
+  const abs = path.isAbsolute(rel) ? rel : path.join(root, rel);
+  const mkdirSync = deps.mkdirSync || fs.mkdirSync;
+  const writeFileSync = deps.writeFileSync || fs.writeFileSync;
+  mkdirSync(path.dirname(abs), { recursive: true });
+  writeFileSync(abs, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  return abs;
+}
+
+module.exports = {
+  normalizeEvidenceMode,
+  readDiffInput,
+  buildEvidenceFromEval,
+  writeEvidenceFile,
+  DEFAULT_OUTPUT_REL,
+  ENV_SECRET,
+  ENV_GRADER_VERSION,
+  ENV_PROMPT_SET_VERSION,
+  ENV_MODEL,
+  ENV_DIFF_FILE,
+  ENV_ORG_ID,
+  SUPPORTED_MODES,
+};

package/lib/git-env.js

@@ -0,0 +1,94 @@
+'use strict';
+/**
+ * git-env.js — SC-002-followup-2.
+ *
+ * Sanitized environment for `git` subprocesses that target an EXPLICIT
+ * repository (i.e. any call that passes `cwd`).
+ *
+ * ── The problem ──────────────────────────────────────────────────────────────
+ * Git exports a set of variables to the processes it spawns — most notably to
+ * hooks. `GIT_DIR` and `GIT_WORK_TREE` take precedence over the working
+ * directory, so a child `git` invocation is silently retargeted at whatever
+ * repository the ambient environment names, regardless of the `cwd` the caller
+ * asked for:
+ *
+ *     GIT_DIR=/elsewhere/.git git -C /my/repo log -- file.js
+ *     # reads /elsewhere, NOT /my/repo
+ *
+ * This is live for Hone: the hook templates in `cli/lib/hook-templates/`
+ * invoke `hone` from pre-commit, so CLI code genuinely runs with `GIT_DIR`
+ * set in adopter repos. The failure is quiet — most call sites wrap git in a
+ * try/catch that degrades to `null`/`false`, so a retargeted read surfaces as
+ * a plausible wrong answer rather than an error.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────
+ * If a git call passes `cwd`, it means "this repository" and MUST also pass
+ * `env: gitEnv()`. If it deliberately means "whatever repo the caller is in"
+ * (no `cwd`), leave the ambient environment alone — under a hook, inheriting
+ * GIT_DIR is then the correct behavior.
+ *
+ * Pinned by tests/regression/SC-002-followup-2-git-env-sanitization.test.js,
+ * which walks the source for `cwd`-bearing git calls that lack `env:`.
+ */
+
+/**
+ * Repository-selecting variables. These override `cwd`, so they must go.
+ * @see https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables
+ */
+const REPO_SELECTING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+];
+
+/**
+ * Deliberately NOT stripped.
+ *
+ * GIT_CEILING_DIRECTORIES limits how far up the tree git will search for a
+ * repository — it constrains discovery rather than selecting a repo. Removing
+ * it is strictly worse on both counts: git may ascend past an operator's
+ * ceiling and report data from an unrelated parent repository (where it would
+ * previously have failed cleanly), and it reintroduces the slow-network-mount
+ * stall the variable exists to prevent.
+ */
+const PRESERVED_VARS = ['GIT_CEILING_DIRECTORIES'];
+
+/**
+ * Identity/date variables. A hook-invoked `hone` inherits the in-flight
+ * commit's dates; any child command that reads or writes history should not
+ * be steered by them.
+ */
+const IDENTITY_VARS = [
+  'GIT_AUTHOR_DATE',
+  'GIT_COMMITTER_DATE',
+];
+
+const STRIPPED_VARS = [...REPO_SELECTING_VARS, ...IDENTITY_VARS];
+
+/**
+ * Build an env for a `git` subprocess that targets an explicit `cwd`.
+ *
+ * @param {NodeJS.ProcessEnv} [extra]  Additional vars to set (merged last).
+ * @param {NodeJS.ProcessEnv} [base]   Base env; defaults to process.env.
+ *                                     Injectable so tests need not mutate the
+ *                                     real process environment.
+ * @returns {NodeJS.ProcessEnv}
+ */
+function gitEnv(extra, base) {
+  const env = { ...(base || process.env) };
+  for (const key of STRIPPED_VARS) delete env[key];
+  return extra ? { ...env, ...extra } : env;
+}
+
+module.exports = {
+  gitEnv,
+  STRIPPED_VARS,
+  REPO_SELECTING_VARS,
+  IDENTITY_VARS,
+  PRESERVED_VARS,
+};

package/lib/git-helpers.js

@@ -20,6 +20,7 @@
  * Issue: #143 (LC-004) — captured_at fallback to git log file mtime.
  */
 const { execSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
 const fs = require('node:fs');
 const path = require('node:path');
 
@@ -40,7 +41,7 @@ function getLastCommitTimestampSeconds(repoRoot, relativePath) {
   try {
     const out = execSync(
       `git log -1 --format=%ct -- ${JSON.stringify(relativePath)}`,
-      { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+      { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
     ).trim();
     if (!out) return null;
     const seconds = Number(out);
@@ -75,7 +76,7 @@ function getFirstCommitDateMs(repoRoot, relativePath) {
   try {
     const out = execSync(
       `git log --diff-filter=A --follow --format=%at -- ${JSON.stringify(relativePath)}`,
-      { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+      { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
     ).trim();
     if (!out) return null;
     // Multiple ADD events possible (file renames); take the OLDEST (last line)

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,83 @@ 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;
+}
+
 module.exports = {
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
+  readCIGateConfig,
+  normalizeCIGate,
+  CI_GATE_MODES,
+  KNOWN_CI_GATE_KEYS,
+  DEFAULT_CI_LOCAL_COMMAND,
 };

package/lib/pipeline-status.js

@@ -72,7 +72,18 @@ 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.
+const STORY_ID_PATTERN = /(E[0-9]+-[A-Z][A-Za-z0-9]*(?:-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
  *