@hone-ai/cli 1.38.1 → 1.40.0

package/hone-cli.js

@@ -33,13 +33,16 @@ const { parseTimeoutSeconds } = require('./lib/timeout-option.js');
 // HC-GF-143 batch: both mappings were computed inline and asserted by nothing (HC-GF-136).
 const { promotePayload } = require('./lib/promote-payload');
 const { assetFetchList } = require('./lib/asset-fetch-list');
+// HC-CI-019-followup-3: no suite asserted a field of either, and this file cannot be required.
+const { detectExistingTestFramework } = require('./lib/detect-test-framework');
+const { classifySpec } = require('./lib/classify-spec');
 
 const pkg     = require('./package.json');
 const { parseReviewJSON } = require('./lib/parse-review-json');
 const { resolveBaseRef, getMaxDiffChars } = require('./lib/release-review-config');
 const { gitEnv } = require('./lib/git-env');
 const { collectIncludePaths } = require('./lib/include-paths');
-const { runArgsError, orchestratePath, apiPath, storyDir: storyDirIn, isGitRev } = require('./lib/run-target'); // HC-GF-270-followup-1, -2, -3
+const { runArgsError, orchestratePath, apiPath, storyDir: storyDirIn, isGitRev, isStoryId } = require('./lib/run-target'); // HC-GF-270-followup-1, -2, -3, -4
 const { normalizeQuestion, questionLines, gateQuestionLines, countPhrase } = require('./lib/operator-question'); // HC-GF-234
 const program = new Command();
 
@@ -595,6 +598,10 @@ program
   .option('--e2e',             'Also install Playwright E2E framework (use with --install-tests)')
   .option('--no-e2e',          'Skip Playwright even when --install-tests is set')
   .option('--no-branch-protection', 'Skip installing GitHub branch protection on the default branch (H-001)')
+  // HC-GF-337g: opt-in. The positive flag MUST be declared first — declared second, Commander
+  // defaults aiReviewer to true and every adopter gets the reviewer again (cli/lib/reviewer-optin.js).
+  .option('--ai-reviewer',       'Install the AI code reviewer workflow (runs on your own ANTHROPIC_API_KEY repo secret; carries the H-019 learnings gate)')
+  .option('--no-ai-reviewer',    'Do not install the AI code reviewer (the default)')
   .option('--refresh',           'Re-scan platform metadata without re-running full setup (HC-013c)')
   .option('--ci-gate <mode>',    'HC-RC-004: CI gating mode (github | local | mixed | none). Skips interactive prompt.')
   .action(async (opts) => {
@@ -714,6 +721,15 @@ program
     fs.mkdirSync(workflowsDir, { recursive: true });
     fs.mkdirSync(scriptsEntDir, { recursive: true });
 
+    // HC-GF-337g: the reviewer is opt-in. Its scripts are left out of the list without the flag, and
+    // that absence is the whole opt-out: setup-ai-pipeline.sh installs ai-review.yml either way (its
+    // other gates — secret scan, tracker, metrics check, E2E healer — are not the reviewer's), copies
+    // the script, the learnings gate and the ESM package.json only when the script arrived, stamps the
+    // workflow so its ai-review job runs only then, and generate_config records ai_review.installed
+    // from that same file.
+    const { shouldInstallReviewer, reviewerNotice, workflowReviewerState } = require('./lib/reviewer-optin');
+    const installReviewer = shouldInstallReviewer(opts);
+
     // Build parallel fetch list
     const fetches = [
       // Agent stubs and skill files. HC-GF-136's gate found `key`, `promise` and `write` here
@@ -747,38 +763,42 @@ program
         promise: client.get('/scripts/copilot-instructions').then(r => r.data),
         write: (data) => fs.writeFileSync(path.join(enterpriseGH, 'copilot-instructions.md'), data),
       },
-      // AI review workflow template
+      // AI review workflow template — installed with or without the reviewer (HC-GF-337g)
       {
         key: 'workflows/ai-review.yml',
         promise: client.get('/scripts/workflow-template', { responseType: 'text', headers: { Accept: 'text/yaml' } }).then(r => r.data),
         write: (data) => fs.writeFileSync(path.join(workflowsDir, 'ai-review.yml'), data),
       },
-      // AI reviewer script
-      {
-        key: 'scripts/ai-reviewer.js',
-        promise: client.get('/scripts/reviewer-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
-        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'ai-reviewer.js'), data),
-      },
-      // H-007: Learnings gate helper (imported by ai-reviewer at CI time).
-      // Both files are ESM. The .github/scripts/package.json (next entry below)
-      // declares ESM scope for this directory so node treats both .js files as
-      // ES modules regardless of the adopter's root package.json (see #16).
-      {
-        key: 'scripts/check-learnings-gate.js',
-        promise: client.get('/scripts/learnings-gate-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
-        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'check-learnings-gate.js'), data),
-      },
-      // H-007: Subdir package.json declares ESM scope for .github/scripts/.
-      // Both ai-reviewer.js and check-learnings-gate.js use `import` syntax;
-      // without this file, node treats them as CommonJS (the npm-init default)
-      // and the workflow fails with `Cannot use import statement outside a
-      // module`. Subdir package.json scope OVERRIDES the adopter's root —
-      // adopter's main project module semantics are unaffected. See #16.
-      {
-        key: 'scripts/package.json',
-        promise: Promise.resolve('{"type": "module"}\n'),
-        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'package.json'), data),
-      },
+      // HC-GF-337g: the reviewer's three entries, requested only on `--ai-reviewer` — not fetched and
+      // discarded, so a repository that did not opt in makes no reviewer request at all.
+      ...(installReviewer ? [
+        // AI reviewer script
+        {
+          key: 'scripts/ai-reviewer.js',
+          promise: client.get('/scripts/reviewer-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
+          write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'ai-reviewer.js'), data),
+        },
+        // H-007: Learnings gate helper (imported by ai-reviewer at CI time).
+        // Both files are ESM. The .github/scripts/package.json (next entry below)
+        // declares ESM scope for this directory so node treats both .js files as
+        // ES modules regardless of the adopter's root package.json (see #16).
+        {
+          key: 'scripts/check-learnings-gate.js',
+          promise: client.get('/scripts/learnings-gate-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
+          write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'check-learnings-gate.js'), data),
+        },
+        // H-007: Subdir package.json declares ESM scope for .github/scripts/.
+        // Both ai-reviewer.js and check-learnings-gate.js use `import` syntax;
+        // without this file, node treats them as CommonJS (the npm-init default)
+        // and the workflow fails with `Cannot use import statement outside a
+        // module`. Subdir package.json scope OVERRIDES the adopter's root —
+        // adopter's main project module semantics are unaffected. See #16.
+        {
+          key: 'scripts/package.json',
+          promise: Promise.resolve('{"type": "module"}\n'),
+          write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'package.json'), data),
+        },
+      ] : []),
       // H-004: Auto-promote workflow template (installed at setup time;
       // adopters customize {{BRANCHES}} via .pipeline-config.yml's
       // ci.trigger_branches setting via setup-ai-pipeline.sh substitution).
@@ -838,6 +858,12 @@ program
         process.stdout.write(`  ⚠ ${key} — ${result.reason?.message || 'failed'}\n`);
       }
     });
+    // HC-GF-337g: read both facts NOW — what was received (the file generate_config records from),
+    // and whether an earlier setup left a reviewer — and report them after the script has run (or,
+    // with --dry-run, as what it would do). No adopter file is deleted.
+    const reviewerReceived = fs.existsSync(path.join(scriptsEntDir, 'ai-reviewer.js'));
+    const reviewerAlreadyPresent = !installReviewer &&
+      fs.existsSync(path.join(process.cwd(), '.github', 'scripts', 'ai-reviewer.js'));
 
     // 6. Download setup-ai-pipeline.sh, verify HMAC, write to tmp
     let scriptContent;
@@ -954,6 +980,22 @@ program
       process.exit(1);
     }
 
+    // HC-GF-337g: after the script, so "installed" is never claimed before the installer ran. A dry
+    // run reports what it would do; a real run reports what is now in the repository — including the
+    // workflow, which an earlier setup may have left without the job that skips without a key.
+    const reviewerWorkflowPath = path.join(process.cwd(), '.github', 'workflows', 'ai-review.yml');
+    console.log(reviewerNotice(
+      opts.dryRun ? reviewerReceived
+        : reviewerReceived && fs.existsSync(path.join(process.cwd(), '.github', 'scripts', 'ai-reviewer.js')),
+      {
+        requested: installReviewer, alreadyPresent: reviewerAlreadyPresent, dryRun: !!opts.dryRun,
+        // A dry run writes nothing, so a missing workflow is "absent" only if its template did not arrive.
+        workflow: opts.dryRun && !fs.existsSync(reviewerWorkflowPath) && fs.existsSync(path.join(workflowsDir, 'ai-review.yml'))
+          ? 'off'
+          : workflowReviewerState(fs.existsSync(reviewerWorkflowPath) ? fs.readFileSync(reviewerWorkflowPath, 'utf8') : null),
+      },
+    ));
+
     // HC-GF-320: every phase below writes (CLAUDE.md, config grounding, test
     // packages, GitHub branch protection). A dry run stops here and says what
     // they would do.
@@ -1126,17 +1168,51 @@ program
       opts.branchProtection === false ||
       /^(1|true|yes)$/i.test(process.env.HONE_SKIP_BRANCH_PROTECTION || '');
 
+    // HC-GF-348: require only what this repository's workflows report, under the names read from them.
+    // HC-GF-354: the served secret scan too, and only checks whose workflow is sure to run on pull requests
+    // to the protected branch — which only `gh repo view` names, so the list is a function of the branch.
+    // HC-GF-352: plus `ci.required_checks`, under the same two rules. Every name the workflows report is
+    // passed too, so the legacy `ai-code-review` an earlier setup required is removed only when nothing
+    // in the repository reports it. HC-GF-353: the review count is decided inside, from the writers.
     const { installBranchProtection } = require('./lib/branch-protection');
+    const { requiredChecksPlan, reportedChecksInDir } = require('./lib/required-checks');
+    const protWorkflowsDir = path.join(process.cwd(), '.github', 'workflows');
+    const protReviewerYml = path.join(protWorkflowsDir, 'ai-review.yml');
+    const protReviewerText = fs.existsSync(protReviewerYml) ? fs.readFileSync(protReviewerYml, 'utf8') : null;
+    const protConfigYml = path.join(process.cwd(), '.github', '.pipeline-config.yml');
+    // Unreadable config: no configured checks, rather than a failed setup after everything was written.
+    let protConfigText = null;
+    try { protConfigText = fs.existsSync(protConfigYml) ? fs.readFileSync(protConfigYml, 'utf8') : null; } catch { protConfigText = null; }
+    let protPlan = null;
     const protResult = await installBranchProtection({
       log: console.log,
       opts: {
         skip: skipBranchProtection,
-        requiredChecks: ['ai-code-review'],
+        requiredChecks: (branch) => {
+          const plan = requiredChecksPlan({
+            reviewerState: workflowReviewerState(protReviewerText),
+            reviewerWorkflowText: protReviewerText,
+            workflowsDir: protWorkflowsDir,
+            configText: protConfigText,
+            branch,
+          });
+          if (branch != null) protPlan = plan;
+          return plan.required;
+        },
+        reportedChecks: reportedChecksInDir(protWorkflowsDir),
       },
     });
     console.log('');
     if (protResult.status === 'installed') {
       console.log(`  ✓ Branch protection installed on '${protResult.branch}'`);
+      const req = protResult.requiredChecks || [];
+      console.log(req.length
+        ? `    Required status checks: ${req.join(', ')}`
+        : '    No status check is required.');
+      console.log(`    Required approving reviews: ${protResult.reviewCount} (${protResult.reviewReason})`);
+      for (const d of (protPlan && protPlan.dropped) || []) {
+        console.log(`    Not required: ${d.name} — ${d.reason}`);
+      }
     } else if (protResult.status === 'skipped') {
       console.log(`  ⚠ Branch protection skipped: ${protResult.reason}`);
       if (protResult.manualCommand) {
@@ -1177,45 +1253,6 @@ function describeSandboxDisposition(runConfig) {
   }
 }
 
-function detectExistingTestFramework(repoRoot) {
-  const pkgPath = path.join(repoRoot, 'package.json');
-  if (!fs.existsSync(pkgPath)) return { stack: 'unknown', testFw: null, pkgMgr: null };
-
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-
-  // Detect stack
-  let stack = 'node';
-  if (allDeps['react']) stack = allDeps['vite'] ? 'react-vite' : 'react';
-  if (allDeps['next']) stack = 'nextjs';
-  if (allDeps['@nestjs/core']) stack = 'nestjs';
-
-  // Detect existing test framework
-  let testFw = null;
-  if (allDeps['vitest']) testFw = 'vitest';
-  else if (allDeps['jest']) testFw = 'jest';
-  else if (allDeps['mocha']) testFw = 'mocha';
-
-  // Detect Playwright
-  const hasPlaywright = !!allDeps['@playwright/test'];
-
-  // Detect package manager
-  let pkgMgr = 'npm';
-  if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) pkgMgr = 'yarn';
-  if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) pkgMgr = 'pnpm';
-
-  // Detect existing configs
-  const hasTestConfig = ['vitest.config.js', 'vitest.config.ts', 'jest.config.js', 'jest.config.ts', 'jest.config.cjs']
-    .some(f => fs.existsSync(path.join(repoRoot, f)));
-  const hasPlaywrightConfig = fs.existsSync(path.join(repoRoot, 'playwright.config.js'))
-    || fs.existsSync(path.join(repoRoot, 'playwright.config.ts'));
-
-  // Detect existing test script
-  const hasTestScript = !!pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1';
-
-  return { stack, testFw, hasPlaywright, pkgMgr, hasTestConfig, hasPlaywrightConfig, hasTestScript, pkg };
-}
-
 function getInstallPackages(stack) {
   const packages = {
     'react-vite': {
@@ -2727,7 +2764,15 @@ program
           if (!e || !e.id || !e.status) continue;
           // Map E13-A-L1 → E13-A (story id strips trailing -L<n>)
           const storyId = String(e.id).replace(/-L\d+$/i, '');
-          const yamlPath = path.join(learningsRoot, `${storyId}.yml`);
+          // HC-GF-270-followup-4: the id and the status come from the server — the id is a file name an org member
+          // uploaded — and they choose and rewrite a local file. An id that is not a story id is skipped and the
+          // path is contained; the status must be one word, because it is written into the YAML as text.
+          if (!isStoryId(storyId) || !/^[a-z][a-z_-]{0,31}$/.test(String(e.status))) {
+            console.log(`  ⚠ skipped a report entry whose id is not a story id or whose status is not one word: ${JSON.stringify({ id: e.id, status: e.status })}`);
+            skippedCount++;
+            continue;
+          }
+          const yamlPath = `${storyDirIn(learningsRoot, storyId)}.yml`;
           if (!fs.existsSync(yamlPath)) {
             console.log(`  ⚠ no local learnings file for ${storyId} — skip`);
             skippedCount++;
@@ -3890,63 +3935,6 @@ function scanForSpecs(dir, repoRoot, results) {
   } catch {}
 }
 
-function classifySpec(file, repoRoot) {
-  let content = '';
-  try { content = fs.readFileSync(file.fullPath, 'utf8'); } catch { }
-
-  const hasPage = /page\.(goto|click|locator|fill|waitFor|getBy)/.test(content);
-  const hasRequest = /request\.(get|post|put|delete|patch)\(/.test(content);
-  const hasExpectResponse = /response\.(status|json|ok|body)/.test(content) ||
-                            /expect\(resp/.test(content);
-
-  // Detect type
-  let type = 'UNKNOWN';
-  if (hasPage && (hasRequest || hasExpectResponse)) type = 'HYBRID';
-  else if (hasPage) type = 'BROWSER';
-  else if (hasRequest || hasExpectResponse) type = 'API';
-  else if (/import.*playwright|from.*@playwright/.test(content)) type = 'BROWSER';
-  else if (/import.*supertest|from.*supertest/.test(content)) type = 'API';
-
-  // Detect module from filename or content
-  // Detect module — filename takes priority over content, most specific first
-  let module = 'general';
-  const name = file.name.toLowerCase();
-  const contentLower = content.toLowerCase();
-
-  // Pass 1: check filename (strongest signal)
-  if (/auth|login|signup|oauth|session/.test(name)) module = 'auth';
-  else if (/trade|order|execution/.test(name)) module = 'trading';
-  else if (/position|portfolio|pnl|p&l/.test(name)) module = 'portfolio';
-  else if (/alert|notification/.test(name)) module = 'alerts';
-  else if (/dashboard|widget|overview/.test(name)) module = 'dashboard';
-  else if (/scanner|scan|market/.test(name)) module = 'market';
-  else if (/setting|config|preference/.test(name)) module = 'settings';
-
-  // Pass 2: fallback to content (if filename didn't match)
-  if (module === 'general') {
-    if (/login|authenticate|sign.?in/.test(contentLower)) module = 'auth';
-    else if (/trading|order|execute/.test(contentLower)) module = 'trading';
-    else if (/portfolio/.test(contentLower)) module = 'portfolio';
-    else if (/alert|notification/.test(contentLower)) module = 'alerts';
-    else if (/dashboard/.test(contentLower)) module = 'dashboard';
-    else if (/market|scanner/.test(contentLower)) module = 'market';
-  }
-
-  // Determine destination
-  let destination;
-  if (type === 'API') {
-    destination = `e2e/api/${file.name}`;
-  } else {
-    destination = `e2e/regression/${module}/${file.name}`;
-  }
-
-  // Smoke candidate: login, auth, critical navigation, app loads
-  const smoke = /login|auth|app.load|critical|smoke|health/.test(name) ||
-                /login|authenticate/.test(contentLower);
-
-  return { ...file, type, module, destination, smoke };
-}
-
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function bundleDirectory(dir, root, files, maxFiles, currentCount) {
   if (currentCount >= maxFiles) return;
@@ -5908,13 +5896,12 @@ program
           },
           timeout: 120000,
         });
-        const text = data.content?.[0]?.text;
         // An empty answer is a provider failure the runner records as an error, not a scenario
-        // that failed its assertions.
-        if (typeof text !== 'string' || !text.trim()) {
-          throw new Error(`claude-haiku returned no text (stop_reason: ${data.stop_reason || 'unknown'})`);
-        }
-        return text;
+        // that failed its assertions. HC-GF-337f: read the first TEXT block, not block 0, so a response
+        // that opens with a thinking block is not an empty one; a refusal names its category.
+        const r = require('./lib/anthropic-response').readAnthropicText(data, { label: 'claude-haiku', allowPartial: true }); // a cut-off answer fails its keywords
+        if (!r.ok) throw new Error(r.message);
+        return r.text;
       };
     } else {
       console.error(`✗ Invalid --provider: ${opts.provider}. Use 'claude-haiku'.`);
@@ -6172,6 +6159,8 @@ function runContextIo(apiConfig) {
     },
     recentlyModifiedOverlap: (touched) =>
       require('./lib/story-classifier-extract').extractRecentlyModifiedOverlap(cwd, touched, 14),
+    // HC-GF-217: the compound symbols the story names, searched in THIS checkout (the server has none to search).
+    callSites: (storyText) => require('./lib/call-sites').collectCallSites({ cwd, storyText }),
   };
 }
 
@@ -6737,7 +6726,7 @@ process.on('SIGINT', () => {
 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('--file <path>', 'Text file with one story per line (cap: 50 lines, 16KB): STORY-ID, then optionally depends:STORY-B,STORY-C and paths:a.js,b.js (files to bundle into that story, as run-story --include-paths does)')
   .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')
@@ -6934,11 +6923,12 @@ program
 
     // HC-059: `STORY-A depends:STORY-B,STORY-C` per line. HC-GF-140 stage 2: the parse lives in
     // cli/lib so it is asserted by BEHAVIOUR. Every line is parsed before anything is resolved.
+    // HC-GF-351: and `paths:a.js,b.js` for the files that story's context must hold.
     const lines = storyIds.map(line => {
       const parsed = parseStoryLine(line);
       if (parsed.error) {
         console.error(parsed.error);
-        console.error(`  Expected: "STORY-ID"  OR  "STORY-ID depends:STORY-B,STORY-C"`);
+        console.error(`  Expected: "STORY-ID", optionally followed by depends:STORY-B,STORY-C and/or paths:a.js,b.js`);
         process.exit(1);
       }
       return parsed;
@@ -6979,7 +6969,8 @@ program
     await Promise.all(Array.from({ length: Math.min(RESOLVE_CONCURRENCY, lines.length) }, async () => {
       while (nextLine < lines.length) {
         const i = nextLine++;
-        resolved[i] = await resolveStoryContext(rcIo, repoCtx, lines[i].storyId);
+        // HC-GF-351: a line's `paths:` is that story's --include-paths, resolved by the same code.
+        resolved[i] = await resolveStoryContext(rcIo, repoCtx, lines[i].storyId, { includePaths: lines[i].paths });
       }
     }));
     // One summary line per story, and every warning labelled with its story. The info lines
@@ -6987,7 +6978,9 @@ program
     for (const ctx of resolved) {
       const { storyId } = ctx;
       const src = ctx.textSource ? `${ctx.textSource} text (${ctx.rawText.length} chars)` : 'no story text';
-      console.log(`  [${storyId}] ${src} · ${ctx.bundle.files} codebase file(s) bundled`);
+      const cs = ctx.config.call_sites;
+      const csNote = cs ? ` · ${cs.symbols.length} symbol(s) searched for call sites${cs.symbols.some((s) => s.status !== 'complete') ? ' (not all whole)' : ''}` : '';
+      console.log(`  [${storyId}] ${src} · ${ctx.bundle.files} codebase file(s) bundled${csNote}`);
       printRunContextNotes(ctx.notes.pre, { prefix: `[${storyId}]`, only: 'warn' });
       printRunContextNotes(ctx.notes.post, { prefix: `[${storyId}]`, only: 'warn' });
     }
@@ -7290,6 +7283,8 @@ program
       const raw = execFileSync('git', ['diff', '--name-only', `${baseRef}...HEAD`], { encoding: 'utf8', cwd: repoRoot, env: gitEnv() });
       changedFiles = raw.trim().split('\n').filter(Boolean);
     } catch {
+      // HC-GF-270-followup-4: the review covers a different range from here on, so it says so.
+      console.error(`⚠ git could not diff ${baseRef}...HEAD — reviewing the last 10 commits (HEAD~10) instead`);
       try {
         const raw = execSync('git diff --name-only HEAD~10', { encoding: 'utf8', cwd: repoRoot, env: gitEnv() });
         changedFiles = raw.trim().split('\n').filter(Boolean);
@@ -7343,7 +7338,7 @@ program
     }
 
     const apiKey = process.env.ANTHROPIC_API_KEY;
-    const providerLabel = 'Anthropic Opus (claude-opus-4-8)';
+    const providerLabel = 'Anthropic Opus (claude-opus-5-5)';
     if (!apiKey) {
       console.error('ANTHROPIC_API_KEY not set. Required for --provider opus.');
       console.error('Set it: export ANTHROPIC_API_KEY=sk-ant-...');
@@ -7355,10 +7350,13 @@ program
     try {
       // HC-GF-270-followup-3: each changed file is ONE argument after `--`. They were wrapped in single quotes
       // inside a shell string, so a file a PR author named with a `'` in it ran as a command.
-      diffContent = execFileSync('git', ['diff', `${baseRef}...HEAD`, '--', ...filesToReview], {
+      // HC-GF-270-followup-4: and each is read as a literal path. Without --literal-pathspecs a file named `*.js`
+      // matched every .js file, and one named `:(evil)x.js` made git exit, which fell back to HEAD~10 silently.
+      diffContent = execFileSync('git', ['--literal-pathspecs', 'diff', `${baseRef}...HEAD`, '--', ...filesToReview], {
         encoding: 'utf8', cwd: repoRoot, env: gitEnv(), maxBuffer: 10 * 1024 * 1024,
       });
     } catch {
+      console.error(`⚠ git could not diff the changed files against ${baseRef} — reviewing the last 10 commits (HEAD~10) instead`);
       try {
         diffContent = execSync('git diff HEAD~10', { encoding: 'utf8', cwd: repoRoot, env: gitEnv(), maxBuffer: 10 * 1024 * 1024 });
       } catch (e) {
@@ -7450,7 +7448,7 @@ program
       normalizeCacheFlag,
     } = require('./lib/release-review-cache');
     const cacheEnabled = normalizeCacheFlag(opts.cache);
-    const modelForCache = 'claude-opus-4-8';
+    const modelForCache = 'claude-opus-5-5';
     let cacheContentHash = null;
     if (cacheEnabled) {
       try {
@@ -7513,15 +7511,23 @@ program
     }
 
     // 6. Call LLM (provider-branched, HC-080a-spike)
-    // max_tokens stays at 4096, the value the HC-080a-spike comparison with GPT-4.1 held constant,
-    // so a review's output budget has not changed now that Opus is the only provider.
-    const MAX_OUTPUT_TOKENS = 4096;
+    // HC-GF-337f: 16000, not the 4096 the HC-080a-spike comparison with GPT-4.1 held constant (that comparison
+    // ended when Opus became the only provider). Claude Opus 5.5 always thinks, and thinking tokens share
+    // max_tokens, so a small cap can be spent before any text is written. A 16000-token answer can take
+    // longer than 120 s, so the request timeout is 300 s.
+    const MAX_OUTPUT_TOKENS = 16000;
     const startedAt = Date.now();
     try {
       let responseText, inputTokens, outputTokens, modelLabel;
 
+      // Thinking and effort are two SIBLING fields: `thinking: {type: 'adaptive'}` and
+      // `output_config: {effort: 'medium'}` (medium is this model's default; it is sent so the choice is
+      // visible). Thinking cannot be disabled on this model (HTTP 400), and no sampling parameter or
+      // forced tool_choice is sent: both are a 400 here as well.
       const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-        model: 'claude-opus-4-8',
+        model: 'claude-opus-5-5',
+        thinking: { type: 'adaptive' },
+        output_config: { effort: 'medium' },
         max_tokens: MAX_OUTPUT_TOKENS,
         system: systemPrompt,
         messages: [{ role: 'user', content: userPrompt }],
@@ -7531,12 +7537,15 @@ program
           'anthropic-version': '2023-06-01',
           'content-type': 'application/json',
         },
-        timeout: 120000,
+        timeout: 300000,
       });
-      responseText = data.content?.[0]?.text || '';
+      // The first TEXT block, never block 0: a response that opens with a thinking block is not an empty
+      // one (the HC-GF-085 defect on this side). The classification is kept for the failure message.
+      const read = require('./lib/anthropic-response').readAnthropicText(data, { label: `--provider ${opts.provider}` });
+      responseText = read.ok ? read.text : '';
       inputTokens  = data.usage?.input_tokens || 0;
       outputTokens = data.usage?.output_tokens || 0;
-      modelLabel   = 'claude-opus-4-8';
+      modelLabel   = 'claude-opus-5-5';
 
       const elapsedMs = Date.now() - startedAt;
 
@@ -7544,16 +7553,22 @@ program
       // 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.
+      // entire review. HC-GF-337f: the cause is the classified one (a refusal with its category, a
+      // cut-off at max_tokens, or no text block), not a guess.
       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', {
+        // A review cut off at max_tokens is NOT a review: exit 0 here means "deploy", and a cut-off JSON
+        // review can pass the loose CRITICAL / DO_NOT_DEPLOY match. It gets its own status. `kind` and
+        // `category` are additive, so a refusal can be told from an empty response in the CI artifact.
+        const truncated = read.kind === 'truncated';
+        console.error(`${truncated ? 'Incomplete' : 'Empty'} response from --provider ${opts.provider}. ${read.message}`);
+        emitStatusEnvelope(truncated ? 'truncated' : 'empty_response', {
           resolvedBase: baseRef,
           model: modelLabel,
           inputTokens,
           outputTokens,
           elapsedMs: Date.now() - startedAt,
+          kind: read.kind || null,
+          category: read.category ?? null,
         });
         process.exit(1);
       }
@@ -8432,10 +8447,16 @@ program
 // The server cannot execute, so a batch queued at night reached step_4 and waited for a person to type
 // check-patch, verify-patch and emit-pr. This is the I/O around cli/lib/batch-follow.js, which makes every
 // decision. The verbs run as children of THIS CLI, one at a time, so the loop runs exactly what a person runs.
-// Exit: 0 the batch completed, 1 fatal (refused, unknown batch, unreachable), 2 something needs you, 3 deadline.
+// HC-GF-363: a step_4 attempt whose verify-patch verdict is a measured `fail` under verification.gate: enforce is sent back
+// to the builder with the failing tests as the reason (POST /orchestrate/:runId/reject), at most twice per run, counted from
+// the server's own rows; the third failure is named for a person.
+// Exit: 0 the batch completed, 1 fatal (refused, unknown batch, unreachable), 2 something needs you (HC-GF-351: or every
+// unfinished run is waiting on a person, named with its step and why), 3 deadline.
 program
   .command('follow-batch <batchId>')
-  .description('Follow a queued batch: check and verify each step_4 patch, and emit each completed run (HC-GF-098)')
+  // Short text for the top-level `hone --help` (HC-GF-363): the full text below is shown by `hone follow-batch --help`.
+  .summary('Follow a queued batch: check and verify each step_4 patch, and emit each completed run (HC-GF-098). A run hard-paused for files it was not given is re-served once with them (HC-GF-351); every pause it cannot act on is named, and it exits 2 when only people are left to act')
+  .description('Follow a queued batch: check and verify each step_4 patch, and emit each completed run (HC-GF-098). A run hard-paused for files it was not given is re-served once with them (HC-GF-351); every pause it cannot act on is named, and it exits 2 when only people are left to act. Under verification.gate: enforce, a step_4 attempt whose verify-patch verdict is a failed test run is rejected back to the builder with the failing tests (HC-GF-363), at most twice per run; the two rejects use step_4\'s retry budget (max_retries_per_step), and a run refused before you upgraded is rejected on the first poll')
   .option('--poll-interval <sec>', 'Seconds between polls', '30')
   .option('--deadline <min>', 'Stop after this many minutes, even if the batch is still running')
   .option('--max-offline <min>', 'Give up once the server has been unreachable this long', '15')
@@ -8450,7 +8471,7 @@ program
       console.error(badBatch);
       process.exit(EXIT.FATAL);
     }
-    const { spawn, spawnSync } = require('child_process');
+    const { spawn, spawnSync, execFileSync } = require('child_process');
     const positive = (raw, flag, unit) => {
       const n = Number(raw);
       if (!Number.isFinite(n) || n <= 0) {
@@ -8481,12 +8502,52 @@ program
     const io = {
       fetchBatch: async (id) => (await client.get(orchestratePath(['batch', id]))).data,
       fetchRun: async (id) => (await client.get(orchestratePath([id]))).data,
-      runVerb: (argv) => new Promise((resolve) => {
+      // `capture` also returns the child's stdout (the tail of it), for the one verb whose answer the loop reads
+      // (queue-stories, HC-GF-351). Either way the child's output reaches this process's own stdout.
+      runVerb: (argv, { capture = false } = {}) => new Promise((resolve) => {
         const child = spawn(process.execPath, [process.argv[1], ...argv],
-          { cwd: process.cwd(), env: process.env, stdio: ['ignore', 'inherit', 'inherit'] });
-        child.on('error', (e) => resolve({ code: null, error: e }));
-        child.on('close', (code) => resolve({ code }));
+          { cwd: process.cwd(), env: process.env, stdio: ['ignore', capture ? 'pipe' : 'inherit', 'inherit'] });
+        let stdout = '';
+        if (capture) child.stdout.on('data', (d) => { process.stdout.write(d); stdout = (stdout + d).slice(-262144); });
+        child.on('error', (e) => resolve({ code: null, error: e, stdout }));
+        child.on('close', (code) => resolve({ code, stdout }));
       }),
+      // HC-GF-351: what a re-serve needs. The regular files git tracks in THIS checkout, listed with their modes so
+      // a tracked symlink (which the bundler would follow out of the checkout) is not among them. Run where the
+      // bundler runs, so the paths are the ones it resolves.
+      trackedPaths: () => require('./lib/context-reserve').trackedRegularFiles(execFileSync('git', ['ls-files', '-z', '-s'], {
+        cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], timeout: 60_000,
+      })),
+      // Where a requested path resolves on the disk NOW, relative to this checkout, or null: the index cannot see a
+      // file or a directory that was replaced by a symlink after the commit, and the bundler reads through it.
+      realPath: (rel) => require('./lib/context-reserve').repoRealPath(process.cwd(), rel),
+      // Was this story served already? A kill that failed, or a crash between the queue and the kill, leaves no marker
+      // and only a newer run of the same story, so the server's own run list is asked (GET /orchestrate?storyId=&repoName=).
+      priorServe: (action) => require('./lib/context-reserve').findServe({
+        listRuns: async (storyId, repo) => (await client.get(apiPath('orchestrate', [], { storyId, repoName: repo, limit: 100 }))).data.runs,
+        listBatches: async () => (await client.get(orchestratePath(['batch'], { limit: 20 }))).data.batches,
+        fetchBatch: async (id) => (await client.get(orchestratePath(['batch', id]))).data,
+      }, action),
+      // One line, in a directory only this invocation can read, for `queue-stories --file`.
+      writeStoriesFile: (text) => {
+        const t = require('./lib/private-temp').privateTempFile('hone-reserve', 'stories.txt');
+        fs.writeFileSync(t.file, text, { mode: 0o600 });
+        return t;
+      },
+      killRun: async (runId, reason) => {
+        if (!require('./lib/run-target').isRunId(runId)) throw new Error('not a run id');
+        await client.post(orchestratePath([runId, 'kill']), { reason });
+      },
+      // HC-GF-363: send a step_4 attempt that failed verification under enforce back to the builder. The loop re-reads
+      // the run and counts its earlier rejects from `fetchStep` (an attempt's stored reject reason) before it calls this.
+      rejectRun: async (runId, body) => {
+        if (!require('./lib/run-target').isRunId(runId)) throw new Error('not a run id');
+        return (await client.post(orchestratePath([runId, 'reject']), body)).data;
+      },
+      fetchStep: async (runId, stepKey, attempt) => {
+        if (!require('./lib/run-target').isRunId(runId)) throw new Error('not a run id');
+        return (await client.get(orchestratePath([runId, 'step', stepKey], { attempt }))).data;
+      },
       // The consent and provenance rule run-story applies before it runs a patch (HC-GF-064, HC-GF-270).
       verifyDecision: (run) => {
         let assessment;