@hone-ai/cli 1.39.0 → 1.41.0

package/hone-cli.js

@@ -598,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) => {
@@ -717,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
@@ -750,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).
@@ -841,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;
@@ -957,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.
@@ -1129,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) {
@@ -5823,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'.`);
@@ -5966,6 +6038,8 @@ program
       if (!opts.file && !opts.fromTree) { console.error('Provide the output via --file <path> (the text your editor produced), or --from-tree to render it from the working tree.'); process.exit(1); }
       const fs = require('fs');
       let output;
+      let reviewDiff = null;
+      let warned = false;
       if (opts.fromTree) {
         const { renderFromTree } = require('./lib/tree-artifact');
         const rendered = renderFromTree({ repoRoot: process.cwd(), testReport: opts.testReport });
@@ -5974,15 +6048,32 @@ program
         // artifact does not is a decision the operator has to be able to see.
         for (const s2 of rendered.skipped) console.error(`not included: ${s2.path} — ${s2.reason}`);
         console.error(`from-tree: ${rendered.files.length} file(s), ${rendered.deletes.length} deletion(s), ${rendered.skipped.length} skipped`);
+        // HC-GF-390: for a build, the base diff of each file emitted whole whose original the reviewers saw only in
+        // windows. Sent beside the artifact, stored apart from it, and never a reason this submit fails.
+        if (stepKey === 'step_4') {
+          try {
+            const { computeReviewDiff } = require('./lib/review-diff');
+            reviewDiff = computeReviewDiff({ repoRoot: process.cwd(), rendered,
+              warn: (line) => { warned = true; console.error(line); } });
+          } catch (e) { reviewDiff = null; warned = true; console.error(`review diff not sent: ${e.message}`); }
+          if (reviewDiff) {
+            console.error(`review diff: ${reviewDiff.stats.files} file(s), ${reviewDiff.notes.length} note(s), against ${reviewDiff.headSha.slice(0, 12)}`);
+            for (const n of reviewDiff.notes) console.error(`  review diff note: ${n}`);
+          } else {
+            console.error(warned ? 'review diff: none (see above)' : 'review diff: none (no modified file over the bundle cap)');
+          }
+        }
       } else {
         output = fs.readFileSync(opts.file, 'utf8');
       }
       const { data } = await client.post(
         orchestratePath([runId, 'step', stepKey, 'editor-output']),
-        { contractVersion: opts.contract, output }
+        { contractVersion: opts.contract, output,
+          ...(reviewDiff ? { reviewDiff: require('./lib/review-diff').toWire(reviewDiff) } : {}) }
       );
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(`Step ${data.stepKey} completed (executed_by: ${data.executedBy}); gate: ${data.gateResult}.`);
+      if (data.reviewDiffIgnored) console.error(`review diff not stored: ${data.reviewDiffIgnored} (the reviewers see the files unverified, as before)`);
       console.log(`Approve when reviewed: hone run-story ${runId} --approve ${data.stepKey}`);
       console.log('Verification is unchanged — check-patch/verify-patch judge this output, not trust.');
     } catch (e) {
@@ -6035,10 +6126,6 @@ function runContextIo(apiConfig) {
     e2eSpecMode: () => pc.readE2eSpecMode(cwd),
     verificationGate: () => pc.readVerificationGateConfig(cwd),
     verificationGateSources: () => pc.readVerificationGateSources(cwd),
-    readPlanText: () => {
-      const planPath = path.join(cwd, '.github', 'EXECUTION_PLAN.yml');
-      return fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
-    },
     exists: (rel) => { const abs = inRepo(rel); return !!abs && fs.existsSync(abs); },
     isDirectory: (rel) => { const abs = inRepo(rel); try { return !!abs && fs.statSync(abs).isDirectory(); } catch { return false; } },
     readFile: (rel) => {
@@ -6128,6 +6215,7 @@ program
   .option('--include-paths <paths>', 'Source file paths to bundle into the codebase context (HC-019n-followup-12). Comma-separated, and the flag may be repeated; both forms accumulate. Augments auto-detected paths from the issue body.', collectIncludePaths, [])
   .option('--e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) ON for this run (overrides e2e.spec_generation config)')
   .option('--skip-e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) OFF for this run (overrides e2e.spec_generation config)')
+  .option('--consult-architect', 'HC-GF-397: run the architect consult (step_0b) even when the groomer says architect_engaged: false. It can only add the consult, never skip it.')
   .action(async (storyIdOrRunId, opts) => {
     const config = getConfig();
     const client = api(config);
@@ -6606,6 +6694,7 @@ program
       explicitSource: opts.storyFile ? { kind: 'file', label: path.basename(String(opts.storyFile)) } : { kind: 'description' },
       includePaths: opts.includePaths,
       axes: opts.axes,
+      consultArchitect: opts.consultArchitect,
     });
     printRunContextNotes(storyCtx.notes.pre);
     printRunContextNotes(repoCtx.notes);
@@ -7266,7 +7355,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-...');
@@ -7376,7 +7465,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 {
@@ -7439,15 +7528,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 }],
@@ -7457,12 +7554,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;
 
@@ -7470,16 +7570,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);
       }
@@ -8358,11 +8464,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.
+// 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). 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')
+  // 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')
@@ -8444,6 +8555,16 @@ program
         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;

package/lib/anthropic-response.js

@@ -0,0 +1,58 @@
+'use strict';
+/**
+ * HC-GF-337f — read an Anthropic Messages response without losing half of it.
+ *
+ * Every CLI path used to take `data.content[0].text`. Once a model can emit a thinking block
+ * FIRST, block 0 is `{type: 'thinking'}` and that expression is `undefined`: an empty review or
+ * verdict reported as a content filter or a quota trip. The HC-GF-085 defect, on the CLI side.
+ *
+ * Returns a discriminated result; the caller owns its own exit semantics (skill-eval throws inside
+ * callLLM, release-review emits a status envelope, the judge throws so the scenario is an error and
+ * not a failed criterion). Nothing here throws, so the outcomes can be asserted in one table.
+ *
+ *   { ok: true,  text, stopReason }
+ *   { ok: false, kind: 'refusal',   category, stopReason, message }   // HTTP 200, stop_reason "refusal"
+ *   { ok: false, kind: 'truncated', stopReason, partialText, message } // cut off at the cap; partialText is null when there is none
+ *   { ok: false, kind: 'no_text',   stopReason, message }             // blocks, but none with text
+ *
+ * Order is part of the contract: a refusal is decided FIRST (it can arrive with a thinking block and
+ * no text, and must never read as `no_text`). Then `max_tokens`: a response cut off at the cap is
+ * `truncated` EVEN WHEN it carries text, because a cut-off answer can be well-formed and wrong (a review
+ * cut off before its verdict). A caller whose success means approval (release-review) therefore gets
+ * the safe answer by default. A caller for which a partial answer is harmless (a judge verdict that
+ * defaults to NO, a skill-eval answer that fails its keywords) opts in with `allowPartial: true` and
+ * then gets the text back as `ok`. The first non-blank text block wins otherwise.
+ *
+ * Every non-ok message names the label, `stop_reason:` and, when the API gave one, the refusal category.
+ * Messages begin `<label> returned no text (stop_reason: ...)` when there is no text at all: callers and
+ * tests match that prefix.
+ *
+ * ADOPTER SURFACE (HC-LC-001): this file ships in the published CLI. It is a pure classifier: no
+ * I/O, no local Claude binary.
+ *
+ * @param {object} data   the parsed response body
+ * @param {{label?: string, allowPartial?: boolean}} [opts]  label: who is asking, so three call sites read
+ *   differently in a log. allowPartial: accept text from a response cut off at max_tokens (default false).
+ */
+function readAnthropicText(data, { label, allowPartial = false } = {}) {
+  const who = label || 'the provider';
+  const stopReason = (data && data.stop_reason) || 'unknown';
+  const category = (data && data.stop_details && data.stop_details.category) || null;
+  const blocks = Array.isArray(data && data.content) ? data.content : [];
+  const cause = `stop_reason: ${stopReason}${category ? `, category: ${category}` : ''}`;
+
+  if (stopReason === 'refusal') {
+    return { ok: false, kind: 'refusal', category, stopReason, message: `${who} returned no text (${cause}): the model declined the request` };
+  }
+  const block = blocks.find((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.trim().length > 0);
+  if (stopReason === 'max_tokens' && !(block && allowPartial)) {
+    const message = block
+      ? `${who} returned an incomplete answer (${cause}): it was cut off at max_tokens and may be missing its ending; raise max_tokens`
+      : `${who} returned no text (${cause}): the answer was cut off at max_tokens before any text, thinking included; raise max_tokens`;
+    return { ok: false, kind: 'truncated', stopReason, partialText: block ? block.text : null, message };
+  }
+  if (block) return { ok: true, text: block.text, stopReason };
+  return { ok: false, kind: 'no_text', stopReason, message: `${who} returned no text (${cause})` };
+}
+
+module.exports = { readAnthropicText };

package/lib/architect-config.js

@@ -20,6 +20,11 @@
  *
  * Pure helper — caller wraps fs.readFileSync + path resolution so the
  * helper is unit-testable with stubs.
+ *
+ * HC-GF-030: NO PRODUCTION CODE CALLS THIS ANY MORE. `architect_consulted` and `checklist_b_completed`
+ * are server-owned (workflow-store.js SERVER_OWNED_CONFIG_KEYS; run-context.js SERVER_OWNED_KEYS): the
+ * server writes them when its step_0b consult is approved, and a plan file's claim is not evidence that
+ * a consult ran on THIS story. The module stays as the documented reader of the plan's shape.
  */
 
 const path = require('node:path');