@hone-ai/cli 1.36.0 → 1.38.0

package/hone-cli.js

@@ -39,9 +39,18 @@ 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 } = require('./lib/run-target'); // HC-GF-270-followup-1
+const { runArgsError, orchestratePath, apiPath } = require('./lib/run-target'); // HC-GF-270-followup-1, -2
+const { normalizeQuestion, questionLines, gateQuestionLines, countPhrase } = require('./lib/operator-question'); // HC-GF-234
 const program = new Command();
 
+// HC-GF-331: spawnSync's default stdout/stderr buffer is 1 MiB. A verification suite over that
+// (this repo's own `make ci`) overflowed it, spawnSync returned status: null with error.code
+// ENOBUFS, and verdictFromRun/classifyGateRun read that null status as a plain test failure —
+// not as "the output could not be captured." Generous relative to any suite measured so far
+// (`make ci` prints low hundreds of KB; 64 MiB is two orders of magnitude of headroom) without
+// holding an unbounded amount of memory for a runaway command.
+const VERIFY_MAX_BUFFER = 64 * 1024 * 1024;
+
 // ── Config resolution ─────────────────────────────────────────────────────────
 const RC_PATH = path.join(os.homedir(), '.honerc');
 
@@ -1746,7 +1755,7 @@ program
       await sleep(pollMs);
       process.stdout.write('.');
       try {
-        const r = await client.get(`/derive/${jobId}`);
+        const r = await client.get(apiPath('derive', [jobId]));
         if (r.data.status === 'complete') {
           result = r.data;
           break;
@@ -1983,6 +1992,10 @@ program
   .requiredOption('--job <jobId>', 'Job ID returned by "hone derive --refresh"')
   .option('--changes <mode>',     'Which changes to apply: all (default)', 'all')
   .action(async (opts) => {
+    // HC-GF-270-followup-2: this GETs the job named by `--job` and then POSTs its approval, so the id is
+    // checked before any config read or request: `drv_x/../../orchestrate/<run>/approve?` became a POST
+    // to another endpoint's approval.
+    refuseBadRunArgs([{ label: '--job', kind: 'deriveJobId', value: opts.job }]);
     const config = getConfig();
     const client = api(config);
 
@@ -1991,7 +2004,7 @@ program
     // Verify job is ready
     let jobData;
     try {
-      const r = await client.get(`/derive/${opts.job}`);
+      const r = await client.get(apiPath('derive', [opts.job]));
       jobData  = r.data;
     } catch (e) {
       console.error(`Failed to fetch job: ${e.response?.data?.error || e.message}`);
@@ -2009,7 +2022,7 @@ program
 
     // Apply changes
     try {
-      const r = await client.post(`/derive/${opts.job}/approve`, {
+      const r = await client.post(apiPath('derive', [opts.job, 'approve']), {
         approvedChanges: opts.changes,
       });
       console.log('✓ Changes approved and applied');
@@ -2505,6 +2518,7 @@ program
   .option('--with-learnings-report', 'Also fetch promoted-learnings report + update local YAML status (H-013)')
   .option('--force',           'Overwrite local edits (default: skip files with local changes — H-024)')
   .action(async (opts) => {
+    refuseBadRunArgs([{ label: '--repo', kind: 'pathName', value: opts.repo, optional: true }]); // HC-GF-270-followup-2
     const config   = getConfig();
     const client   = api(config);
     const repoName = opts.repo || path.basename(process.cwd());
@@ -2540,7 +2554,7 @@ program
     // ── 1. Sync derived skills ──────────────────────────────────────────────
     if (!opts.agentsOnly) {
       try {
-        const r = await client.get(`/skills/${repoName}/derived`);
+        const r = await client.get(apiPath('skills', [repoName, 'derived']));
         const { skills } = r.data;
         if (!skills.length) {
           console.log('No derived skills found. Run "hone derive" first.');
@@ -2620,7 +2634,7 @@ program
             content = editorStubContent(agent);
             console.log(`  → ${agent}: editor mode — syncing runtime stub (full prompt served ephemerally)`);
           } else {
-            const r = await client.get(`/prompts/${agent}`, {
+            const r = await client.get(apiPath('prompts', [agent]), {
               responseType: 'text',
               headers: { Accept: 'text/markdown' },
             });
@@ -2931,8 +2945,7 @@ program
       // The default request is byte-identical to the one that shipped — no query string at all —
       // so nothing that already calls this path shifts, including HC-GF-210's pin on it. The
       // parameter appears only when the operator asked for a status other than the default.
-      const qs = status === 'promoted' ? '' : `?status=${encodeURIComponent(status)}`;
-      const { data } = await client.get(`/learnings/promoted${qs}`);
+      const { data } = await client.get(apiPath('learnings', ['promoted'], { status: status === 'promoted' ? undefined : status }));
       const all = Array.isArray(data.learnings) ? data.learnings : [];
       // The two ways a promoted row reaches no run. `targetKind` is 'unrouted' when HC-GF-159a's
       // router found no target; a row promoted before that story carries neither field at all.
@@ -5950,11 +5963,7 @@ program
     const config = getConfig();
     const client = api(config);
     try {
-      const params = new URLSearchParams();
-      if (opts.status) params.set('status', opts.status);
-      if (opts.limit) params.set('limit', opts.limit);
-      const qs = params.toString();
-      const { data } = await client.get(`/orchestrate${qs ? `?${qs}` : ''}`);
+      const { data } = await client.get(apiPath('orchestrate', [], { status: opts.status, limit: opts.limit }));
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       if (!data.runs.length) { console.log('No workflow runs found.'); return; }
       const age = (ts) => {
@@ -6138,7 +6147,7 @@ function runContextIo(apiConfig) {
       }
     },
     fetchStoryContext: async (storyId) => {
-      const { data } = await api(apiConfig).get(`/stories/${encodeURIComponent(storyId)}/context`);
+      const { data } = await api(apiConfig).get(apiPath('stories', [storyId, 'context']));
       return data;
     },
     recentlyModifiedOverlap: (touched) =>
@@ -6165,6 +6174,8 @@ program
   .option('--kill', 'Kill a run: pass a run ID, or a story ID for that story\'s latest run in this repository')
   .option('--axes <axes>', 'Comma-separated classifier axes for this run (e.g. shared-chokepoint) — composition input (HC-COMM-010 C0)')
   .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0) on a run ID, or on a story ID\'s latest run in this repository. Exit codes: 2 = paused at a human gate, 3 = parked for your editor (execution.mode: editor)')
+  .option('--reject <step>', 'HC-GF-323: send a paused gate BACK for a re-run instead of approving it or killing the whole run (e.g., --reject step_4). Requires --reason. Steps before it are left approved; only this step re-runs, with the reason in its context.')
+  .option('--reason <text>', 'With --reject: why this attempt is being sent back. Required, and reaches the re-run as feedback the same way a code-reviewer\'s FAIL verdict does.')
   .option('--no-verify', 'HC-GF-064: do not run verify-patch automatically when the run pauses at step_4')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .option('--poll-interval <s>', 'Poll interval in seconds', '5')
@@ -6409,6 +6420,16 @@ program
             console.log(`  (auto-verify skipped: ${e.message})`);
           }
 
+          // HC-GF-234: show what the step ASKED where the operator decides. Approving records
+          // `approved` and moves on — it does not answer the question, and until now nothing at
+          // this prompt said there was one. Printed last, right above the prompt (auto-verify's
+          // output above can run to pages), and in both the gate and the exhausted branch: the
+          // step's question rides on the attempt the operator is about to decide about.
+          // Never throws: a print must not end a poll loop.
+          try {
+            for (const line of gateQuestionLines(status, d.stepKey)) console.log(line);
+          } catch { /* a print must never end a poll loop */ }
+
           if (process.stdin.isTTY) {
             const readline = require('readline');
             const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -6471,6 +6492,14 @@ program
           // step says so instead of listing a stale failed row above a completed one.
           const tries = (s.attempts || 1) > 1 ? `  [attempt ${s.attempt} of ${s.attempts}]` : '';
           console.log(`  ${icon} ${s.stepKey}  (${s.agent})  ${s.status}${gate}${tries}`);
+          // HC-GF-234: `status: completed` / `gateResult: approved` alone cannot tell "did its
+          // work" apart from "asked a question nobody answered" — batch mode has no human gate
+          // on steps 0-3b, so this line is the only place that question ever surfaces here.
+          const asked = normalizeQuestion(s.operatorQuestion);
+          if (asked) {
+            console.log(`      asked ${countPhrase(asked.count)} nobody answered:`);
+            for (const l of questionLines(asked, { max: 120 })) console.log(`        ${l}`);
+          }
         }
         if (data.awaitingApproval && isEditorParked(data)) {
           console.log('');
@@ -6479,6 +6508,7 @@ program
           console.log('');
           console.log(`Awaiting approval at ${data.currentStep}.`);
           console.log(`Approve: hone run-story ${data.runId} --approve ${data.currentStep}`);
+          console.log(`Reject:  hone run-story ${data.runId} --reject ${data.currentStep} --reason "<why>"`);
         }
         console.log('');
         // HC-GF-016: at a TERMINAL state, print the report unasked. The whole
@@ -6548,6 +6578,37 @@ program
       return;
     }
 
+    // Reject mode (HC-GF-323)
+    if (opts.reject) {
+      if (!opts.reason || !String(opts.reason).trim()) {
+        console.error('--reject requires --reason <text>');
+        process.exit(1);
+      }
+      let rejectId;
+      try {
+        rejectId = await existingRunId(`--reject ${opts.reject}`);
+        await client.post(orchestratePath([rejectId, 'reject']),
+          { stepKey: opts.reject, reason: opts.reason });
+        console.log(`Gate ${opts.reject} rejected. Re-running with the reason. Workflow resuming.`);
+      } catch (e) {
+        console.error(`Failed: ${e.response?.data?.error || e.message}`);
+        process.exit(1);
+      }
+      // HC-GF-070: same FOLLOW behaviour as --approve — a caller told to poll does not.
+      if (opts.follow === false) {
+        console.log(`Poll: hone run-story ${rejectId} --status`);
+        return;
+      }
+      try {
+        await pollUntilDecision(rejectId);
+      } catch (e) {
+        console.error(`Rejected, but following the run failed: ${e.message}`);
+        console.error(`Poll: hone run-story ${rejectId} --status`);
+        process.exit(1);
+      }
+      return;
+    }
+
     // Start workflow (storyId required, runId not accepted for starting)
     if (isUuid) {
       console.error('Cannot start workflow with a runId. Use a story ID like HC-042.');
@@ -7651,6 +7712,16 @@ showCmd
       console.log(`  startedAt:   ${s.startedAt || '(not started)'}`);
       console.log(`  completedAt: ${s.completedAt || '(not completed)'}`);
       if (s.tokenUsage) console.log(`  tokenUsage:  ${JSON.stringify(s.tokenUsage)}`);
+      // HC-GF-234: `status`/`gateResult` above read identically whether this step did its
+      // work or ended by asking the operator something nobody answered — surface it here so
+      // an operator does not have to read raw step output to find out.
+      const asked = normalizeQuestion(s.operatorQuestion);
+      if (asked) {
+        console.log(``);
+        console.log(`── operator question(s) — asked, not answered ──────────`);
+        console.log(`  asked ${asked.count} question(s):`);
+        for (const l of questionLines(asked)) console.log(`    ${l}`);
+      }
       if (s.errorContext) {
         console.log(``);
         console.log(`── error_context (retry feedback) ──────────────────────`);
@@ -7881,7 +7952,11 @@ program
       verifiedAttempt = r.data?.attempt != null ? Number(r.data.attempt) : undefined;
       // best-effort: pull the run's ci_local_command for the default
       try {
-        const runR = await client.get(orchestratePath([workflowId]));
+        // HC-GF-302-followup-1: on a connection of its own. This GET follows the step GET at once, and
+        // on the socket that one pooled a server closing it idle resets the request - a failed config
+        // read, so the provenance gate below refused a trusted run (exit 9). Nothing is retried: a read
+        // that fails on its own connection still refuses.
+        const runR = await client.get(orchestratePath([workflowId]), require('./lib/fresh-connection').freshConnection());
         // HC-GF-270 (security review BLOCKER-1): the id is ENCODED above, so a crafted
         // `<uuid>/step/step_4?` cannot turn this into a fetch of some other endpoint that answers
         // 200 with no config. And a body that is not THIS run is not this run's config.
@@ -8185,9 +8260,10 @@ program
           cwd: wt, shell: true, encoding: 'utf8',
           timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
           stdio: ['ignore', 'pipe', 'pipe'],
+          maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: a >1 MiB suite (this repo's own `make ci`) must not ENOBUFS
         });
         const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced }, provAll);
+        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced, error: run.error }, provAll);
         // HC-GF-077: nothing was applied when HEAD already held the step — say what the command actually ran on.
         if (alreadyInHead && v.verdict === 'pass') v.detail = "tests passed on HEAD, which already contains the step's files";
         const sym = v.verdict === 'pass' ? '✓' : v.verdict === 'pass_narrowed' ? '⚠' : v.verdict === 'timeout' ? '⏱' : v.verdict === 'unresolved' ? '○' : '✗';
@@ -8243,6 +8319,7 @@ program
               cwd: wt, shell: true, encoding: 'utf8',
               timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
               stdio: ['ignore', 'pipe', 'pipe'],
+              maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: shares the shape at :8184 — same fix
             });
             const c = classifyGateRun({
               code: gr.status, error: gr.error,
@@ -8523,7 +8600,8 @@ program
       output = r.data?.output;
       stepAttempt = Number.isInteger(r.data?.attempt) ? r.data.attempt : null;
       try {
-        const runR = await client.get(orchestratePath([workflowId]));
+        // HC-GF-302-followup-1: its own connection, as verify-patch's (see there).
+        const runR = await client.get(orchestratePath([workflowId]), require('./lib/fresh-connection').freshConnection());
         // HC-GF-270 (security review BLOCKER-1): see verify-patch — encoded id, and a body that
         // is not THIS run does not count as its config.
         if (runR.data?.runId && !sameRun(runR.data.runId)) throw new Error('run id mismatch');
@@ -8738,9 +8816,10 @@ program
             cwd: wt, shell: true, encoding: 'utf8',
             timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
             stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: emit-pr's verify shares verify-patch's spawnSync shape
           });
           const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced }, provAll);
+          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced, error: run.error }, provAll);
           // HC-GF-223: the mapping lives in cli/lib/emit-pr.js so it is testable. Before it, a
           // narrowed verdict fell into the else below, which printed "verify failed, no branch
           // emitted" and then exited with that verdict's own exit code — zero. A failure path that

package/lib/asset-fetch-list.js

@@ -11,6 +11,10 @@
  * network or a filesystem.
  */
 
+// HC-GF-270-followup-2: every path goes through the one builder. The derived set's repository is the
+// checkout's directory name, which can hold `?`, `#` or `%`; hand-built, `x?y` fetched `/skills/x`.
+const { apiPath } = require('./run-target');
+
 /**
  * @param {object} args
  * @param {string[]} args.agents      agent names
@@ -39,12 +43,12 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
   return [
     ...agents.map(agent => ({
       key: `${agent}.agent.md`,
-      promise: get(`/scripts/agent-stub/${agent}`),
+      promise: get(apiPath('scripts', ['agent-stub', agent])),
       write: (data) => writeAgent(agent, data),
     })),
     ...skills.map(skill => ({
       key: `skills/${skill}/SKILL.md`,
-      promise: get(`/skills/${skill}`),
+      promise: get(apiPath('skills', [skill])),
       write: (data) => writeSkill(skill, data),
     })),
     // ── HC-GF-184: the per-repo DERIVED set ────────────────────────────────────────────────────
@@ -59,7 +63,7 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
     // derived, so setup behaves exactly as before for them.
     ...(derivedRepo ? [{
       key: `skills/<derived for ${derivedRepo}>`,
-      promise: get(`/skills/${derivedRepo}/derived`),
+      promise: get(apiPath('skills', [derivedRepo, 'derived'])),
       // Tolerant by construction: this runs mid-setup, AFTER the baseline has landed, so a shape
       // change at the endpoint must not abort an adopter's install half-written.
       write: (data) => {

package/lib/bundle-mount-follow.js

@@ -0,0 +1,118 @@
+'use strict';
+/**
+ * bundle-mount-follow.js — HC-GF-325.
+ *
+ * `cli/lib/bundle-paths.js` bundles only paths the story NAMES — it has no mount, prefix or
+ * import following. step_2 (API test writer) then has no way to know a router file's routes are
+ * served under a prefix, because nothing in the bundle says so. Measured live: step_2 wrote 7
+ * tests against `/properties` for an app that mounts every router under `/api/v1`
+ * (`app.include_router(properties.router, prefix=settings.api_prefix)`); all 7 failed on a 404.
+ *
+ * This module answers one question given a bundled file's path and content: "if this file
+ * defines routes, which OTHER tracked file mounts it, and which existing test already exercises
+ * a router mounted the same way?" Both answers are returned as extra paths for the caller to
+ * bundle alongside the file the story named — it does not read the filesystem itself, so it stays
+ * as pure/testable as the rest of `cli/lib`.
+ */
+
+const path = require('path');
+
+// A file DEFINES routes when it either builds a router object (FastAPI's `APIRouter()`, Express's
+// `Router()`) or decorates/registers at least one HTTP verb against one (`@router.get(...)`,
+// `router.get(...)`) — the object alone (an empty router) is not enough to justify following it.
+const DEFINES_ROUTER_OBJECT = /\bAPIRouter\s*\(|\b(?:express\.)?Router\s*\(\s*\)/;
+const REGISTERS_A_ROUTE = /@\w+\.(get|post|put|delete|patch)\s*\(|\b\w+\.(get|post|put|delete|patch)\s*\(\s*['"`]/i;
+
+function definesRoutes(content) {
+  const text = String(content || '');
+  return DEFINES_ROUTER_OBJECT.test(text) && REGISTERS_A_ROUTE.test(text);
+}
+
+// Where an app typically registers its routers/routes — bounded, so following a mount never
+// means reading every tracked file's content. FastAPI/Flask/Express conventions only; a repo
+// using neither simply gets no mount file, same as today.
+const ENTRYPOINT_NAME_RE = /(^|\/)(main|app|asgi|wsgi|server|index|__init__)\.(py|js|mjs|cjs|ts)$/i;
+
+// `app.include_router(...)` (FastAPI/Starlette) or `app.use(...)` (Express) — the call that
+// registers a router built elsewhere. Requires the SAME file to also reference the router
+// file's module name, so a coincidental `app.use(` for an unrelated router does not match.
+const MOUNT_CALL_RE = /\b\w+\.include_router\s*\(|\b\w+\.use\s*\(/;
+
+function baseModuleName(filePath) {
+  return path.posix.basename(String(filePath || ''), path.posix.extname(String(filePath || '')));
+}
+
+function mentionsModule(content, moduleName) {
+  if (!moduleName) return false;
+  const re = new RegExp(`\\b${moduleName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+  return re.test(String(content || ''));
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.routeFilePath   the bundled file being checked
+ * @param {string} o.routeFileContent
+ * @param {string[]} o.repoFiles     every tracked path (the caller's git ls-files list)
+ * @param {(p:string)=>string} o.readFile  reads a candidate mount file; the caller's disk I/O
+ * @returns {string|null} the path of the file that mounts routeFilePath's router, or null
+ */
+function findMountFile({ routeFilePath, routeFileContent, repoFiles, readFile }) {
+  if (!definesRoutes(routeFileContent)) return null;
+  const moduleName = baseModuleName(routeFilePath);
+  const candidates = (Array.isArray(repoFiles) ? repoFiles : [])
+    .filter((p) => p !== routeFilePath && ENTRYPOINT_NAME_RE.test(p));
+  for (const candidate of candidates) {
+    let content;
+    try { content = readFile(candidate); } catch { continue; }
+    if (MOUNT_CALL_RE.test(content) && mentionsModule(content, moduleName)) return candidate;
+  }
+  return null;
+}
+
+// The same directory-prefix + name convention `cli/lib/layout-detect.js` uses for a test root —
+// kept independent (not imported) because this module's job is narrower: ONE existing file to
+// show the test writer the mounted-prefix convention, not a directory computation.
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$/i;
+// A test that actually drives an HTTP client — the convention worth copying — over one that
+// merely lives in a test directory (a fixtures or conftest file, say).
+const API_TEST_SIGNAL_RE = /\bTestClient\s*\(|\bsupertest\s*\(|\brequest\s*\(\s*app\s*\)|\bclient\.(get|post|put|delete|patch)\s*\(/;
+
+function topLevelDir(filePath) {
+  const norm = String(filePath || '').replace(/^\.\//, '');
+  return norm.includes('/') ? norm.split('/')[0] : '';
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.routeFilePath
+ * @param {string[]} o.repoFiles
+ * @param {(p:string)=>string} o.readFile
+ * @returns {string|null} an existing test file demonstrating the same kind of route testing
+ */
+function findExistingApiTest({ routeFilePath, repoFiles, readFile }) {
+  const dir = topLevelDir(routeFilePath);
+  const candidates = (Array.isArray(repoFiles) ? repoFiles : [])
+    .filter((p) => p !== routeFilePath && (!dir || p.startsWith(dir + '/')) && TEST_PATH_RE.test(p));
+  for (const candidate of candidates) {
+    let content;
+    try { content = readFile(candidate); } catch { continue; }
+    if (API_TEST_SIGNAL_RE.test(content)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The one entry point `run-context.js` calls per already-bundled ("present") file.
+ * @returns {string[]} zero, one or two extra paths to bundle (mount file, existing API test)
+ */
+function followRouterMount({ routeFilePath, routeFileContent, repoFiles, readFile }) {
+  if (!definesRoutes(routeFileContent)) return [];
+  const extra = [];
+  const mountFile = findMountFile({ routeFilePath, routeFileContent, repoFiles, readFile });
+  if (mountFile) extra.push(mountFile);
+  const testFile = findExistingApiTest({ routeFilePath, repoFiles, readFile });
+  if (testFile) extra.push(testFile);
+  return extra;
+}
+
+module.exports = { definesRoutes, findMountFile, findExistingApiTest, followRouterMount };

package/lib/bundle-paths.js

@@ -464,8 +464,19 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // The radius is sized before any window exists, so it prices the marker at its widest:
     // the longest label among the sites, with line numbers at the file's own width.
     const widest = { startLine: totalLines, endLine: totalLines, totalLines };
+    // HC-GF-334: the footer repeats `filePath` in EVERY kept window (see `footer` above), so
+    // sizing `radius` off its real length made window boundaries — and therefore which sites
+    // and collapsed hits are reachable — depend on how long the file's path happens to be.
+    // Measured: with real files and roadmap rows, a fake path fixed at length 80 or 90 dropped
+    // a hit that lengths 10-70 and 100-200 all kept, for the SAME content and story — a path a
+    // few characters different flips whether a window's char-radius snaps past a line boundary.
+    // Reserve a fixed, generous footer cost for SIZING the radius instead of the real one, so
+    // the estimate — and the windows it produces — no longer shift with path length. `costOf`
+    // and `budget()` below still charge the REAL footer length, so the cap is still never
+    // exceeded even for a path longer than this reserve; it only stops falling short of it.
+    const FOOTER_SIZING_RESERVE_CHARS = 300;
     const markerCost = Math.max(...chosen.map((s) => header(widest, s.anchor, totalLines).length))
-      + footer.length + 1;
+      + Math.max(footer.length, FOOTER_SIZING_RESERVE_CHARS) + 1;
     // HC-GF-288: the 800 covers ONE window's marker, and every further window brings its
     // own. Sized from `limit - 800` alone, n windows overran the cap from n = 3 — so the
     // LAST region was always dropped however much room the rest left. Measured on

package/lib/layout-detect.js

@@ -20,6 +20,14 @@ const EXCLUDE = /(^|\/)(node_modules|dist|build|coverage|\.git|\.next|vendor|__p
 const SOURCE_EXT = /\.(js|mjs|cjs|jsx|ts|tsx|py|java|kt|rb|go|rs|php|cs|scala|swift|cls|trigger|apex)$/i;
 const TEST_HINT = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$/i;
 
+// HC-GF-020-followup-1: a documentation directory routinely carries a handful of genuinely
+// source-extension files (Sphinx's conf.py, a docs-site build script) that clear MIN_FILES on
+// extension count alone — measured live: a docs/ of mostly .html/.svg pages qualified as a
+// source dir because it also held two .py files. Extension MIX, not source-extension COUNT, is
+// what tells a docs directory apart from a package: if a top-level dir's tracked files are more
+// documentation than source, it is documentation, however many stray source-ext files it holds.
+const DOC_EXT = /\.(md|mdx|rst|adoc|txt|html?|svg|png|jpe?g|gif|ico|pdf)$/i;
+
 // Directories whose NAME means "this is where the code is". A repo that puts code directly at the
 // root of a package still gets that package dir, via the manifest-dir fallback below.
 const SOURCE_DIR_NAMES = /^(src|lib|app|source|server|client|api|packages|apps|core)$/i;
@@ -61,6 +69,27 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
   const srcFiles = paths.filter(p => SOURCE_EXT.test(p) && !TEST_HINT.test(p));
   const testFiles = paths.filter(p => SOURCE_EXT.test(p) && TEST_HINT.test(p));
 
+  // Extension mix per top-level dir, over EVERY tracked path (not just the source-ext-filtered
+  // srcFiles/testFiles) — a docs/ directory's defining feature is the files roll() never looks
+  // at otherwise (its .html/.svg pages), so the doc-vs-source comparison needs the full list.
+  const extCountsByTop = new Map();
+  for (const p of paths) {
+    const top = p.includes('/') ? p.split('/')[0] : '.';
+    if (!extCountsByTop.has(top)) extCountsByTop.set(top, { doc: 0, src: 0 });
+    const c = extCountsByTop.get(top);
+    if (DOC_EXT.test(p)) c.doc += 1;
+    else if (SOURCE_EXT.test(p)) c.src += 1;
+  }
+  function isDocumentationOnly(top) {
+    // A dotdir (.github, .storybook, .devcontainer, ...) is tooling/config by convention, never
+    // a published-docs directory, even when it holds far more Markdown records (pipeline history,
+    // learnings) than source-ext scripts — hone-server's OWN .github/scripts/ is real code that
+    // must stay visible (HC-DF-005) alongside .github/pipeline/'s hundreds of Markdown records.
+    if (top.startsWith('.')) return false;
+    const c = extCountsByTop.get(top);
+    return !!c && c.doc > c.src;
+  }
+
   function roll(files, nameRe = SOURCE_DIR_NAMES) {
     const byTop = new Map();
     for (const f of files) {
@@ -71,6 +100,7 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
     const out = [];
     for (const [top, list] of byTop) {
       if (top === '.') continue; // root-level scripts are not a source ROOT
+      if (isDocumentationOnly(top)) continue; // docs/ with a stray conf.py is still docs/
       const qualifies = nameRe.test(top) || manifestDirs.has(top) || list.length >= minFiles;
       if (!qualifies) continue;
       // Descend one level when this is a container of packages, or when a conventional source
@@ -83,14 +113,23 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
       // Files sitting DIRECTLY in this dir (cli/hone-cli.js). If any exist, the dir itself is
       // the source root — descending would silently drop them, which is how an early cut of this
       // rule emitted `cli/lib` and lost cli/hone-cli.js (5.8k lines, the whole CLI surface).
-      // Descend ONLY into a package container (packages/, apps/). Anywhere else, prefer the
-      // PARENT: a wider scope is the safe error for grounding, a narrower one hides real files.
-      // An earlier rule descended into conventional children and emitted `server/src`, which
-      // dropped `server/scripts/` — the exact residual the followup-42 dogfood run hit, where the
-      // planner could not see the agent prompts and proposed inventing them elsewhere.
       const direct = list.filter(f => f.split('/').length === 2).length;
       const container = /^(packages|apps|services|modules)$/i.test(top);
-      if (container && kids.size > 0 && direct === 0) { out.push(...[...kids.keys()]); continue; }
+      // HC-GF-020-followup-1: TEST dirs alone also descend into a sole, unambiguous child (a repo's
+      // real test dir was reported as `backend` because every test sat under `backend/tests`, a name
+      // this rule never recognized). Deliberately NOT extended to source dirs: an earlier rule
+      // descended into ANY conventional child regardless of ambiguity and emitted `server/src`,
+      // which dropped `server/scripts/` — the exact residual the followup-42 dogfood run hit, where
+      // the planner could not see the agent prompts and proposed inventing them elsewhere. `server/`
+      // has both `server/src` and `server/scripts` (2 kids) so it is unaffected either way, but a
+      // repo where `server/` holds ONLY `server/src` must still stay at `server` for source dirs —
+      // measured by this file's own regression pins — so the single-kid case is test-dirs-only.
+      // ...and only when `top` itself is NOT already a conventionally-named test root: a `tests/`
+      // dir with a single `tests/integration` child is intentionally left at `tests` — descending
+      // would report a narrower, equally-arbitrary name in place of the convention that already
+      // says exactly what this directory is.
+      const soleUnambiguousTestChild = nameRe === TEST_DIR_NAMES && !nameRe.test(top) && kids.size === 1 && direct === 0;
+      if ((container || soleUnambiguousTestChild) && kids.size > 0 && direct === 0) { out.push(...[...kids.keys()]); continue; }
       out.push(top);
     }
     return [...new Set(out)].sort();

package/lib/operator-question.js

@@ -0,0 +1,94 @@
+/**
+ * operator-question.js — HC-GF-234: render the operator question(s) a step asked and nobody answered.
+ *
+ * A step that ends by asking the operator something used to be recorded exactly like a step that
+ * did its work (`status: completed`, `gateResult: approved`). The server now stores
+ * `{ count, questions }` on the step's attempt row and carries it as `operatorQuestion` on
+ * `GET /orchestrate/:runId` and `.../step/:stepKey`. Four CLI surfaces print it — `--status`,
+ * `show step`, the human-gate prompt, and the NEEDS YOU list — and they share this module so the
+ * wording and the two honesty rules below cannot drift apart.
+ *
+ * PURE: data in, strings out. No fs, no console, no process — a leaf, so run-report.js can keep
+ * its "derived, never narrated" contract and require it.
+ *
+ * TWO HONESTY RULES.
+ *   - `count` is the TRUE number of questions the step asked; `questions` holds at most the first
+ *     five. When count exceeds what is stored, the surfaces say "+N more not stored" instead of
+ *     letting a short list read as the whole of it.
+ *   - The text is AGENT-WRITTEN and goes to a terminal. The server scrubs control characters
+ *     before storing, but this CLI may talk to an older or different server, so it scrubs again
+ *     at the point of printing: C0/C1 controls, DEL, and the bidirectional controls that reorder
+ *     what a terminal draws.
+ *
+ * TOLERANT OF AN OLDER SERVER BY CONSTRUCTION: a missing key, null, or a payload of the wrong
+ * shape normalises to null, which is today's output (nothing printed).
+ */
+
+// U+061C ARABIC LETTER MARK is the third bidi mark beside LRM/RLM (review round 3 F3). Written as
+// \u escapes: a literal bidi character in this source would reorder how THIS file reads.
+// eslint-disable-next-line no-control-regex -- the whole point is to match control chars.
+const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+function scrub(text) {
+  return String(text == null ? '' : text).replace(TERMINAL_UNSAFE_RE, '');
+}
+
+/**
+ * @param {*} oq  a step's `operatorQuestion`, straight off the network (not trusted to have a shape)
+ * @returns {{count:number, questions:string[], more:number}|null}  null = the step did not ask
+ */
+function normalizeQuestion(oq) {
+  if (!oq || typeof oq !== 'object') return null;
+  const count = Math.floor(Number(oq.count));
+  if (!Number.isFinite(count) || count < 1) return null;
+  const questions = (Array.isArray(oq.questions) ? oq.questions : []).map(scrub);
+  return { count, questions, more: Math.max(0, count - questions.length) };
+}
+
+// Clips by CODE POINT, not UTF-16 unit (review round 3 F4): a `.slice(0, max)` that lands between
+// the halves of an emoji prints a lone surrogate, which a terminal draws as U+FFFD.
+function clip(text, max) {
+  if (!Number.isFinite(max)) return text;
+  const points = Array.from(text);
+  return points.length > max ? `${points.slice(0, max).join('')}...` : text;
+}
+
+/**
+ * One entry per stored question (`- <question>`, clipped to `max` chars) and, when the step asked
+ * more than was stored, a closing `+ N more not stored`. Callers add their own indentation.
+ */
+function questionLines(asked, { max = Infinity } = {}) {
+  if (!asked) return [];
+  const lines = asked.questions.map((q) => `- ${clip(q, max)}`);
+  if (asked.more > 0) lines.push(`+ ${asked.more} more not stored`);
+  return lines;
+}
+
+function countPhrase(count) {
+  return `${count} question${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * The block printed at the human gate, right before "Approve?" — the one place the operator
+ * decides, and where approving silently consumes the question without answering it.
+ *
+ * SCOPED TO THE STEP THE RUN IS PAUSED AT (`stepKey`), the same discipline as
+ * hard-pause-remedy.js's remedyFor: the column is durable, so a question step_3b asked must not
+ * be re-printed as if it belonged to an unrelated step_4 gate.
+ *
+ * @param {object} status  a GET /orchestrate/:runId payload
+ * @param {string} stepKey the step the gate is for
+ * @returns {string[]} lines to print (empty when that step asked nothing)
+ */
+function gateQuestionLines(status, stepKey) {
+  const steps = status && Array.isArray(status.steps) ? status.steps : [];
+  const step = steps.find((x) => x && typeof x === 'object' && x.stepKey === stepKey);
+  const asked = step ? normalizeQuestion(step.operatorQuestion) : null;
+  if (!asked) return [];
+  return [
+    `  ${stepKey} asked ${countPhrase(asked.count)} that nobody has answered — approving does not answer ${asked.count === 1 ? 'it' : 'them'}:`,
+    ...questionLines(asked, { max: 240 }).map((l) => `    ${l}`),
+  ];
+}
+
+module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase };

package/lib/run-context.js

@@ -30,6 +30,7 @@ const {
   extractPathRefs, extractBareRefs, resolveBareName, alreadyCovered, planFileExcerpt,
 } = require('./bundle-paths');
 const { selectBundle, auditLines } = require('./bundle-context');
+const { followRouterMount } = require('./bundle-mount-follow');
 const { parseIncludePaths, partitionIncludeTargets, statedAnchorsFor, anchorWarnings } = require('./include-paths');
 const { buildRepoTree, allDirs, MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS } = require('./repo-tree');
 const { classifyStory } = require('./story-classifier');
@@ -497,7 +498,24 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
       // HC-GF-073: what exists, what is pending, plus repo-level signal files and existing
       // neighbours of the pending paths. Order is priority order: the char cap cuts from the end.
       const selection = selectBundle({ named: [...candidates], repoFiles: repoCtx.repoFiles, exists: io.exists });
-      const ordered = [...selection.present, ...selection.signal, ...selection.siblings];
+      // HC-GF-325: a present file that DEFINES routes says nothing about where they are MOUNTED —
+      // step_2 wrote 7 tests against `/properties` for an app that serves every router under
+      // `/api/v1`. Right after `present`, so a mount file and an existing API test of the same
+      // kind get priority over signal files and siblings within the char budget, same as a path
+      // the story named directly would.
+      const alreadySelected = new Set([...selection.present, ...selection.signal, ...selection.siblings]);
+      const mountFollowed = [];
+      for (const p of selection.present) {
+        let content;
+        try { content = io.readFile(p); } catch { continue; }
+        for (const extra of followRouterMount({ routeFilePath: p, routeFileContent: content, repoFiles: repoCtx.repoFiles, readFile: io.readFile })) {
+          if (alreadySelected.has(extra)) continue;
+          alreadySelected.add(extra);
+          mountFollowed.push(extra);
+          pre.push(info(`  → bundled ${extra} — mounts/tests the router in ${p} (HC-GF-325)`));
+        }
+      }
+      const ordered = [...selection.present, ...mountFollowed, ...selection.signal, ...selection.siblings];
       const codebaseFiles = [];
       let totalChars = 0;
       let budgetSpent = false; // HC-GF-288: so a not-bundled warning can say WHY

package/lib/run-report.js

@@ -16,6 +16,10 @@
  * Rendering is separate so both are testable without a server.
  */
 
+// HC-GF-234: the one wording for a step's unanswered question, shared with `--status`, `show
+// step` and the human-gate prompt. A pure leaf module, so this file stays pure.
+const { normalizeQuestion, questionLines, countPhrase } = require('./operator-question');
+
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
 
@@ -324,6 +328,31 @@ function buildReport(run, extra = {}) {
     }
   }
 
+  // 1e. HC-GF-234: a step that ended by asking the operator something.
+  //
+  // `status: completed` / `gateResult: approved` cannot say this: batch mode has no human gate on
+  // steps 0-3b, and approving a gate records `approved` whether or not the question was read. The
+  // step row carries the question on its own column; this is the only place a TERMINAL run's
+  // report can tell "did its work" from "asked, and nobody here answered".
+  //
+  // Says only what is MEASURED — the step asked, and the run has no answer to it. It does not say
+  // the step produced no deliverable or that the run proceeded on a guess: nothing checks either.
+  //
+  // ADVISORY (HC-026c: a new signal REPORTS before it GATES): `hone run-report` exits 1 on any
+  // non-advisory item, and an agent that asks one benign question must not turn an adopter's
+  // passing script red overnight. Visible in the report, absent from the exit code.
+  for (const s of steps) {
+    const asked = normalizeQuestion(s.operatorQuestion);
+    if (!asked) continue;
+    needsYou.push({
+      what: `${s.stepKey} (${s.agent || 'agent'}) asked ${countPhrase(asked.count)} that nothing in this run answered`,
+      detail: questionLines(asked, { max: 200 }),
+      how: `hone show step ${run.runId} ${s.stepKey}`,
+      howLabel: 'inspect',
+      advisory: true,
+    });
+  }
+
   // 2. The last verification is ONE event, so it becomes ONE item with sub-lines.
   //    Listing "verification failed" and "lint failed" separately gave two entries
   //    for one problem resolved by one fix — and NEEDS YOU is a list of DISTINCT

package/lib/run-target.js

@@ -104,17 +104,26 @@ async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
 const isStepKey = (s) => typeof s === 'string' && /^step_[0-9a-z_]+$/i.test(s);
 const isAttempt = (s) => (typeof s === 'string' || typeof s === 'number') && /^[1-9]\d{0,8}$/.test(String(s));
 const isBatchId = isRunId;
+// HC-GF-270-followup-2: POST /derive is the only producer of a derive job id (server/src/routes/derive.js),
+// and it issues `drv_` + 12 lower-case hex characters into a TEXT key compared exactly, so no other shape
+// can name a job. `hone approve --job` GETs and then POSTs under that id.
+const isDeriveJobId = (s) => typeof s === 'string' && /^drv_[0-9a-f]{12}$/.test(s);
+// A name that becomes ONE path segment, such as a repository name. Encoding makes any other character
+// safe; these three it cannot, because `new URL()` resolves `.` and `..` as directory steps.
+const isPathName = (s) => typeof s === 'string' && s !== '' && s !== '.' && s !== '..';
 
 const KINDS = {
   runId: { ok: isRunId, why: 'must be a run ID (a UUID)', hint: ' — run IDs: hone workflows' },
   batchId: { ok: isBatchId, why: 'must be a batch ID (a UUID)', hint: ' — batch IDs: hone queue-stories --list' },
   stepKey: { ok: isStepKey, why: 'must name a step, like step_4', hint: '' },
   attempt: { ok: isAttempt, why: 'must be a whole number from 1, like 2', hint: '' },
+  deriveJobId: { ok: isDeriveJobId, why: 'must be a derive job ID, like drv_0123456789ab', hint: ' — the ID "hone derive --refresh" printed' },
+  pathName: { ok: isPathName, why: 'must be a name, not empty, "." or ".."', hint: '' },
 };
 
 /**
  * The first failed check's message, or null when every check passes.
- * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt', value: any, optional?: boolean }>} checks
+ * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt'|'deriveJobId'|'pathName', value: any, optional?: boolean }>} checks
  *   `label` is the flag or positional as the operator typed it. An `optional` check passes when the value
  *   is undefined (a flag that was not given); an empty string is always checked.
  */
@@ -130,23 +139,29 @@ function runArgsError(checks) {
 }
 
 /**
- * The one way a CLI verb builds an `/orchestrate/…` path. Each segment is encoded exactly once, and the
- * segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied value
- * has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that are
- * null, undefined, false or '' are dropped; the rest go through URLSearchParams.
+ * The one way the CLI builds a path on the Hone API: `/<prefix>/<segment>/…?<query>`. `prefix` is a
+ * literal resource name (`derive`, `skills`, …), never a value. Each segment is encoded exactly once, and
+ * the segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied
+ * value has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that
+ * are null, undefined, false or '' are dropped; the rest go through URLSearchParams.
  *
  * Callers pass raw values. A pre-encoded segment would be encoded twice (`%` becomes `%25`), and the
- * HC-GF-270-followup-1 scan fails on one.
+ * HC-GF-270-followup-2 scan fails on one.
+ *
+ * HC-GF-270-followup-2: generalized from orchestratePath. HC-GF-270-followup-1 closed the defect under
+ * `/orchestrate/`; `/derive/`, `/skills/`, `/prompts/`, `/scripts/` and `/stories/` were still built by
+ * hand, and `hone approve --job` POSTed under an id nothing checked.
  */
-function orchestratePath(segments, query) {
-  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+function apiPath(prefix, segments, query) {
+  if (typeof prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(prefix)) throw new TypeError(`apiPath: prefix must be a resource name, got ${JSON.stringify(prefix)}`);
+  if (!Array.isArray(segments)) throw new TypeError('apiPath: segments must be an array');
   const parts = segments.map((v, i) => {
-    if (v === null || v === undefined) throw new TypeError(`orchestratePath: segment ${i} is ${v}`);
+    if (v === null || v === undefined) throw new TypeError(`apiPath: segment ${i} is ${v}`);
     const s = String(v);
-    if (s === '' || s === '.' || s === '..') throw new TypeError(`orchestratePath: segment ${i} is ${JSON.stringify(s)}`);
+    if (s === '' || s === '.' || s === '..') throw new TypeError(`apiPath: segment ${i} is ${JSON.stringify(s)}`);
     return encodeURIComponent(s);
   });
-  const base = ['', 'orchestrate', ...parts].join('/');
+  const base = ['', prefix, ...parts].join('/');
   const qs = new URLSearchParams();
   for (const [k, v] of Object.entries(query || {})) {
     if (v === null || v === undefined || v === false || v === '') continue;
@@ -156,7 +171,13 @@ function orchestratePath(segments, query) {
   return q ? `${base}?${q}` : base;
 }
 
+/** An `/orchestrate/…` path: `apiPath('orchestrate', …)` with at least one segment (HC-GF-270-followup-1). */
+function orchestratePath(segments, query) {
+  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+  return apiPath('orchestrate', segments, query);
+}
+
 module.exports = {
   resolveRunTarget, isRunId, LOOKUP_LIMIT,
-  isStepKey, isAttempt, isBatchId, runArgsError, orchestratePath,
+  isStepKey, isAttempt, isBatchId, isDeriveJobId, isPathName, runArgsError, apiPath, orchestratePath,
 };

package/lib/verify-patch.js

@@ -196,7 +196,7 @@ function verifyCommandEnv(base = process.env) {
  * Pass the `command` that ran and the resolver's `source` for it: without them an absent command is
  * indistinguishable from a failing one (HC-GF-008), and the CLI's two executors both do.
  *
- * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string, command?: string, source?: string }} run
+ * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string, command?: string, source?: string, error?: { code?: string } }} run
  * @returns {{ verdict: 'pass'|'fail'|'timeout'|'unresolved', exitCode: number, detail: string }}
  */
 function verdictFromRun(run, provisioning = null) {
@@ -216,6 +216,18 @@ function verdictFromRun(run, provisioning = null) {
   if (run.timedOut) {
     return { verdict: 'timeout', exitCode: EXIT.TIMEOUT, detail: 'test command exceeded the timeout' };
   }
+  // HC-GF-331: spawnSync kills the child and reports status: null with error.code ENOBUFS when
+  // its stdout/stderr exceed maxBuffer. A null status otherwise falls through to the generic
+  // "tests failed (exit null)" path below — the suite may have passed; nothing conclusive was
+  // observed about it either way, so this is its own outcome, never a reported failure.
+  if (run.error && run.error.code === 'ENOBUFS') {
+    return {
+      verdict: 'unresolved',
+      exitCode: EXIT.UNRESOLVED,
+      detail: 'test output exceeded the capture buffer (ENOBUFS) — nothing conclusive was observed '
+        + 'about this change; raise maxBuffer or have the command print less',
+    };
+  }
   if (run.code === 0) {
     // HC-GF-223: a pass under an operator-supplied command is evidence about a SUBSET. Measured on
     // run `437246a7`: `--command "node --test <3 files>"` reported `pass` to the server and the same
@@ -401,6 +413,11 @@ function classifyGateRun(run) {
     return { verdict: 'unavailable', detail: 'command not found — gate NOT run' };
   }
   if (run.timedOut) return { verdict: 'unavailable', detail: 'timed out — gate NOT run to completion' };
+  // HC-GF-331: shares verdictFromRun's shape — a null status from an ENOBUFS overflow is not a
+  // finding, it is the gate not having run to a readable conclusion.
+  if (run.error && run.error.code === 'ENOBUFS') {
+    return { verdict: 'unavailable', detail: 'output exceeded the capture buffer (ENOBUFS) — gate NOT run to completion' };
+  }
   if (run.code === 0) return { verdict: 'pass', detail: 'clean' };
   const sum = summarizeFailure(run, { maxLines: 6 });
   // A linter prints its findings from the TOP, so unlike a test runner the most

package/package.json

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