@hone-ai/cli 1.34.0 → 1.35.0

package/lib/run-context.js

@@ -0,0 +1,698 @@
+'use strict';
+/**
+ * HC-GF-097 — the one place a pipeline run's config is built.
+ *
+ * `hone run-story` assembled fourteen config keys inline, one try/catch at a time, and
+ * `hone queue-stories` was written beside it with two of them. Nothing noticed, because each key
+ * lived in the control flow of one command rather than in a value both could share: a queued
+ * story ran with no story text, no codebase bundle, no repository tree, and — through the server's
+ * default — `ci_gate: github` whatever `.pipeline-config.yml` said. The fix makes the config a
+ * VALUE produced here and consumed by both commands, so the two cannot drift again:
+ *
+ *   const repo   = resolveRepoContext(io, opts);                 // once per command
+ *   const story  = await resolveStoryContext(io, repo, id, o);   // once per story
+ *   const config = buildRunConfig(repo, story);                  // the only assembler
+ *
+ * Pure in the `cli/lib` sense: every read of the disk, git, GitHub and the Hone server arrives
+ * through `io`, and nothing here prints or exits. Each step's outcome — including every
+ * fail-open default — comes back as a note `{ level: 'info'|'warn', text }`, and the command
+ * decides how to show it. The texts are the ones run-story printed before the move, so its output
+ * is unchanged.
+ *
+ * The no-text POLICY is deliberately not here. run-story warns and proceeds on a story with no
+ * text (HC-019n-followup-18); queue-stories refuses the batch. This module reports `rawText`
+ * and `hasStoryText` answers the question; each command decides what an empty answer means.
+ */
+
+const { composeStoryDescription } = require('./story-compose');
+const { extractStoryIdFromBranch } = require('./pipeline-status');
+const {
+  extractPathRefs, extractBareRefs, resolveBareName, alreadyCovered, planFileExcerpt,
+} = require('./bundle-paths');
+const { selectBundle, auditLines } = require('./bundle-context');
+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');
+const {
+  extractType, extractSecurityImplications, extractCrossRepoDependency,
+} = require('./story-classifier-extract');
+const { readArchitectConfigFromText } = require('./architect-config');
+const { remoteHostFromUrl } = require('./story-provenance');
+const path = require('path');
+
+/**
+ * Keys the SERVER owns in a run's config. None may come out of here. The server strips them from
+ * whatever a client sends (workflow-store.js SERVER_OWNED_CONFIG_KEYS, HC-GF-097-followup-1) and
+ * refuses a per-story `overnight` outright; refusing here as well makes an assembler that emits one
+ * fail loudly instead of losing the value on the server. The two lists are pinned equal by
+ * tests/regression/HC-GF-097-followup-1-server-owned-keys.test.js.
+ */
+const SERVER_OWNED_KEYS = Object.freeze([
+  'batchTokenBudget', 'batchFailureThreshold', 'dependsOnRunIds', 'monthlyTokenBudget', 'overnight',
+]);
+
+// HC-019n-followup-13d: the bundle caps. OptionsFlow #96 hit 49,783 of the old 50,000 with six
+// files, so the next slightly larger story silently dropped one. 30 / 150K / 25K.
+const BUNDLE_MAX_FILES = 30;
+const BUNDLE_MAX_TOTAL_CHARS = 150_000;
+const BUNDLE_MAX_PER_FILE_CHARS = 25_000;
+
+const info = (text) => ({ level: 'info', text });
+const warn = (text) => ({ level: 'warn', text });
+const firstLine = (e) => ((e && e.message) ? e.message.split('\n')[0] : String(e));
+
+// ── Story provenance (HC-GF-270) ─────────────────────────────────────────────────────────────
+// Where a story's text came from, recorded as raw facts on the run config (`story_source`). Trust
+// is DERIVED from them in one place, cli/lib/story-provenance.js: a patch built from text an
+// outside party wrote must not execute as the operator before a human reads it. HC-GF-270 stamped
+// this inline in run-story; HC-GF-097 moved run-story's config assembly here, so it is stamped
+// here, and queue-stories, which now fetches the same issue text, records the same facts.
+
+/**
+ * Why a provenance lookup failed, as a CLASSIFICATION, never gh's raw stderr: `workflow_runs.config`
+ * outlives the run and validateConfig inspects key NAMES only, so a stderr line that echoed a token
+ * or a signed URL would be persisted server-side (HC-GF-270 review LOW-7). Reads the error code and
+ * gh's stderr, never the `Command failed: <cmd>` line, and removes the repository name before
+ * matching, so `acme/auth-service` is not an auth failure (review LOW-2, second review LOW-3).
+ */
+function classifyProvenanceFailure(err, ownerRepo) {
+  if (err && err.code === 'HC_URL_MISMATCH') return 'the issue text and its provenance record name different issues';
+  let detail = [
+    // An async execFile timeout reports `killed` with no code; without this it reads as a generic
+    // failure. (A child killed for overflowing its buffer carries its own code, which wins.)
+    err && (err.code || (err.killed ? 'ETIMEDOUT' : null)),
+    err && err.stderr && String(err.stderr),
+    err && err.message && String(err.message).replace(/^Command failed:[^\n]*\n?/, ''),
+  ].filter(Boolean).join('\n') || String(err);
+  if (ownerRepo) detail = detail.split(ownerRepo).join('<repo>');
+  return /timed? ?out|ETIMEDOUT/i.test(detail) ? 'the gh api call timed out'
+    : /rate limit|HTTP 403/i.test(detail) ? 'gh api refused the request (rate limit or forbidden)'
+    : /HTTP 404|not found/i.test(detail) ? 'gh api could not find that issue (HTTP 404)'
+    : /auth|credential|gh auth login|HTTP 401/i.test(detail) ? 'gh is not authenticated for this host'
+    : /ENOTFOUND|ENETUNREACH|ECONNREFUSED|dial tcp/i.test(detail) ? 'the gh api call could not reach the network'
+    : /JSON|Unexpected token/i.test(detail) ? 'gh api returned output that is not JSON'
+    : 'the gh api call failed';
+}
+
+/**
+ * The `story_source` of an issue-sourced story, from a SECOND gh call: `gh issue view --json` does
+ * not expose author_association (measured on gh 2.92). A failure is recorded, untrusted, with its
+ * classified reason, so it PAUSES the run rather than letting it proceed. gh's own first line goes
+ * to the operator as a note (printed locally) and is never persisted.
+ * @returns {Promise<{ source: object, notes: object[] }>}
+ */
+async function issueStorySource(io, issueNumber, issue) {
+  const number = String(issueNumber);
+  let where = null;
+  try {
+    const got = await io.fetchIssueProvenance(number);
+    where = got;
+    const api = (got && got.issue) || {};
+    // The text came from the first call and the trust from the second, so they must name the SAME
+    // issue. A disagreement is never resolved in favour of trust (review LOW-5).
+    if (issue && issue.url && api.html_url && issue.url !== api.html_url) {
+      throw Object.assign(new Error('issue text and provenance name different issues'), { code: 'HC_URL_MISMATCH' });
+    }
+    const source = {
+      kind: 'issue',
+      ref: { owner: got.owner, repo: got.repo, number },
+      label: `${got.owner}/${got.repo}#${number}`,
+      author: (api.user && api.user.login) || null,
+      association: api.author_association,
+      html_url: api.html_url,
+      remoteHost: remoteHostFromUrl(got.remoteUrl),
+    };
+    return { source, notes: [info(`  → story provenance: ${source.author || 'unknown'} (author_association: ${source.association || 'unknown'})`)] };
+  } catch (e) {
+    where = where || (e && e.where) || null;
+    const classified = classifyProvenanceFailure(e, where ? `${where.owner}/${where.repo}` : null);
+    const ghSaid = e && e.stderr ? String(e.stderr).split('\n').map((l) => l.trim()).find(Boolean) : null;
+    return {
+      source: {
+        kind: 'issue',
+        ref: where ? { owner: where.owner, repo: where.repo, number } : null,
+        label: where ? `${where.owner}/${where.repo}#${number}` : `#${number}`,
+        error: classified,
+      },
+      notes: [
+        warn(`  ⚠ could not establish issue provenance: ${classified}${ghSaid ? ` — gh said: ${ghSaid}` : ` (${firstLine(e)})`}`),
+        warn('  → this run will NOT auto-verify; you will be asked to read the patch first'),
+      ],
+    };
+  }
+}
+
+/**
+ * Everything a run's config takes from the REPOSITORY rather than the story. Computed once per
+ * command, so a 50-story batch lists the repository once, not fifty times.
+ *
+ * @param {object} io
+ * @param {() => string[]} io.listFiles                 tracked paths; throws when git cannot list
+ * @param {(trackedPaths: string[]) => {source_dirs:string[],test_dirs:string[],repaired?:boolean,dropped?:string[],detected?:boolean}} io.sourceDirs
+ * @param {() => {include_paths:string[]}} io.codebaseDefaults
+ * @param {() => {gate:string,local_command:string}} io.ciGate
+ * @param {() => {raw:string|null,mode:string,recognized:boolean}} io.executionMode
+ * @param {string} io.consentNote                        shown when editor mode is used
+ * @param {() => {overlays:object[],skipped:string[]}} io.ruleOverlays
+ * @param {() => string} io.e2eSpecMode
+ * @param {() => string} io.verificationGate
+ * @param {() => string[]} io.verificationGateSources
+ * @param {() => string} io.readPlanText                 EXECUTION_PLAN.yml text, '' when absent
+ * @param {{ e2eSpecs?: boolean, skipE2eSpecs?: boolean, treeByteCap?: number }} [opts]  run-story's per-run
+ *   flags; `treeByteCap` is queue-stories' byte cap on the tree's path lists (none for run-story)
+ */
+function resolveRepoContext(io, opts = {}) {
+  const config = {};
+  const notes = [];
+
+  // HC-DF-001: config-level default include paths, merged with the story's own paths below.
+  let defaultIncludePaths = [];
+  try {
+    const d = io.codebaseDefaults();
+    defaultIncludePaths = Array.isArray(d && d.include_paths) ? d.include_paths : [];
+  } catch (e) {
+    notes.push(warn(`  ⚠ codebase.default_include_paths read failed (non-fatal): ${firstLine(e)}`));
+  }
+
+  // One listing serves both the bundle's bare-ref resolution and the tree. It used to be taken
+  // twice, with different buffers (64 MB and the 1 MB default), so a repository whose path list
+  // passed 1 MB bundled its files but silently lost its tree.
+  let repoFiles = [];
+  let listError = null;
+  try { repoFiles = io.listFiles(); } catch (e) { listError = e; }
+
+  // HC-019n-followup-42: repository-structure grounding. Bundling FILES is not grounding — with
+  // no tree in the prompt the groomer invents a layout and the planner inherits it (dogfood run
+  // f276fe00). Fail-open.
+  try {
+    if (listError) throw listError;
+    // The listing just taken is handed on, so a stale config's self-heal does not list git again.
+    const dirs = io.sourceDirs(repoFiles);
+    // HC-DF-002: readSourceDirs self-heals a stale config; say so, or the operator sees a
+    // confident success line built from directories that do not exist.
+    if (dirs.repaired) {
+      notes.push(info(`  ⚠ source dirs in .pipeline-config.yml not found on disk: ${dirs.dropped.join(', ')}`));
+      notes.push(info(`     using ${dirs.detected ? 'detected' : 'the surviving'} dirs instead: ${dirs.source_dirs.join(', ') || '(none)'}`));
+      notes.push(info('     fix it permanently: hone detect-layout, then set codebase.source_dirs in .github/.pipeline-config.yml'));
+    }
+    const tree = buildRepoTree(repoFiles, {
+      sourceDirs: dirs.source_dirs, testDirs: dirs.test_dirs, maxTransportBytes: opts.treeByteCap,
+    });
+    if (tree.selected_total > 0) {
+      config.repo_tree = tree;
+      const scope = dirs.source_dirs.length ? dirs.source_dirs.join(', ') : 'all tracked';
+      notes.push(info(`  → repository structure: ${tree.shown} of ${tree.selected_total} paths under ${scope} (${(Buffer.byteLength(tree.text, 'utf8') / 1024).toFixed(1)} KB) — the groomer/planner/builder are told to derive every path from it`));
+      // HC-GF-097: over a transport cap the path lists are omitted and the server reads the tree as
+      // v1, so it does NOT check the planner's `## Files` against this repository. That is a guard
+      // switching off; say so, and say which cap did it.
+      if (!Array.isArray(tree.paths)) {
+        const dirCount = allDirs(repoFiles).length;
+        const why = tree.selected_total > MAX_TRANSPORT_PATHS
+          ? `${tree.selected_total} paths, over the ${MAX_TRANSPORT_PATHS}-path cap`
+          : dirCount > MAX_TRANSPORT_DIRS
+            ? `${dirCount} directories, over the ${MAX_TRANSPORT_DIRS}-directory cap`
+            : `the path lists exceed the ${opts.treeByteCap}-byte cap`;
+        notes.push(warn(`  ⚠ repository tree sent WITHOUT its path lists (${why}) — the server will not check the planner's \`## Files\` paths against this repository. Narrow codebase.source_dirs to bring it under the cap.`));
+      }
+    }
+  } catch (e) {
+    notes.push(warn(`  ⚠ repository structure not bundled (non-fatal): ${firstLine(e)}`));
+  }
+
+  // HC-101-followup-2: the adopter's CI gate, so step_5c can branch (github / local / both /
+  // none). Defaults to github + 'make ci' when the config predates the field.
+  try {
+    const ciGate = io.ciGate();
+    config.ci_gate = ciGate.gate;
+    config.ci_local_command = ciGate.local_command;
+    notes.push(info(`  → CI gate mode: ${ciGate.gate}${ciGate.gate !== 'github' ? ` (local_command: ${ciGate.local_command})` : ''}`));
+  } catch (e) {
+    notes.push(warn(`  ⚠ CI gate config read failed (non-fatal, defaulting to gate=github): ${firstLine(e)}`));
+    config.ci_gate = 'github';
+    config.ci_local_command = 'make ci';
+  }
+
+  // HC-COMM-010 B0.5: execution.mode is stamped at CREATION, so a mid-flight
+  // .pipeline-config.yml flip cannot change a running run.
+  let execution;
+  try {
+    execution = io.executionMode();
+    config.execution_mode = execution.mode;
+    if (execution.mode === 'editor') {
+      // §2a: the consent note is shown at the moment editor mode is USED.
+      notes.push(info('  → execution mode: editor (opt-in)'));
+      notes.push(info(`     ${io.consentNote}`));
+    }
+  } catch (e) {
+    notes.push(warn(`  ⚠ execution mode read failed (non-fatal, defaulting to server): ${firstLine(e)}`));
+    config.execution_mode = 'server';
+    // Could-not-check is not checked: an unattended batch must not read this as `server`.
+    execution = { raw: null, mode: 'server', recognized: false, unreadable: firstLine(e) };
+  }
+
+  // HC-COMM-010 C0: composition transports. .hone-local/ is adopter disk the server can never
+  // read, so raw overlay texts travel in the run config, size/count-capped, degrade-to-empty.
+  try {
+    const ov = io.ruleOverlays();
+    if (ov.overlays.length > 0) {
+      config.rule_overlays = ov.overlays;
+      notes.push(info(`  → bundled ${ov.overlays.length} rule overlay(s) for server-side composition`));
+    }
+    for (const skip of ov.skipped) notes.push(warn(`  ⚠ overlay skipped: ${skip}`));
+  } catch (e) {
+    notes.push(warn(`  ⚠ overlay read failed (non-fatal): ${firstLine(e)}`));
+  }
+
+  // HC-019n-followup-28: the E2E spec-generation mode. Per-run flag > config > `auto`. The
+  // "is E2E required?" decision stays server-side; the CLI passes only the MODE.
+  try {
+    let e2eMode, source;
+    if (opts.e2eSpecs) { e2eMode = 'auto'; source = '--e2e-specs'; }
+    else if (opts.skipE2eSpecs) { e2eMode = 'never'; source = '--skip-e2e-specs'; }
+    else { e2eMode = io.e2eSpecMode(); source = 'config/default'; }
+    config.e2e_spec_generation = e2eMode;
+    // The step_3b row is created unless the adopter opted out; the orchestrator still skips it
+    // at runtime for a story that does not require an E2E plan.
+    if (e2eMode !== 'never') config.enableConditional = ['step_3b'];
+    notes.push(info(`  → E2E spec generation (step_3b): ${e2eMode} (source: ${source})`));
+  } catch (e) {
+    notes.push(warn(`  ⚠ e2e spec-mode read failed (non-fatal, defaulting to auto): ${firstLine(e)}`));
+    config.e2e_spec_generation = 'auto';
+  }
+
+  // HC-019n-followup-34: the closed-loop verification gate. HC-COMM-011-followup-6: which verdict
+  // sources may DRIVE the step_4 gate under enforce.
+  try {
+    config.verification_gate = io.verificationGate();
+    config.verification_gate_sources = io.verificationGateSources();
+    if (config.verification_gate !== 'advisory') {
+      notes.push(info(`  → verification gate: ${config.verification_gate} (sources: ${config.verification_gate_sources.join(', ')})`));
+    }
+  } catch (e) {
+    notes.push(warn(`  ⚠ verification-gate read failed (non-fatal, defaulting to advisory): ${firstLine(e)}`));
+    config.verification_gate = 'advisory';
+    config.verification_gate_sources = ['verify-patch'];
+  }
+
+  // HC-019b: EXECUTION_PLAN.yml, read once. Each story's architect flags come from it below.
+  let planText = '';
+  try { planText = io.readPlanText() || ''; } catch (e) {
+    notes.push(warn(`  ⚠ EXECUTION_PLAN.yml read failed (non-fatal, architect flags default to {false, false}): ${firstLine(e)}`));
+  }
+
+  return { config, notes, repoFiles, defaultIncludePaths, planText, execution };
+}
+
+/**
+ * Everything a run's config takes from the STORY: its text, the code it names, its classifier
+ * axes and its architect flags.
+ *
+ * @param {object} io
+ * @param {(n: string) => Promise<{title:string, body?:string, url:string}>|{title:string, body?:string, url:string}} io.fetchIssue
+ *   rejects or throws on failure
+ * @param {(n: string) => Promise<{owner:string, repo:string, remoteUrl:string, issue:object}>} io.fetchIssueProvenance
+ *   HC-GF-270: `gh api repos/<owner>/<repo>/issues/<n>`; rejects with gh's stderr on the error, and
+ *   `where: {owner, repo}` once the remote was parsed
+ * @param {(id: string) => Promise<object>} io.fetchStoryContext  GET /stories/:id/context; throws
+ *   an axios-shaped error (`e.response.status`) on refusal
+ * @param {(rel: string) => boolean} io.exists     repository-scoped; false for anything outside it
+ * @param {(rel: string) => boolean} [io.isDirectory] repository-scoped; HC-GF-288 names a directory as the reason
+ * @param {(rel: string) => string} io.readFile    repository-scoped; throws when unreadable
+ * @param {(touched: string[]) => boolean} io.recentlyModifiedOverlap
+ * @param {object} repoCtx   resolveRepoContext's result
+ * @param {string} storyId   the id as the operator typed it — sent as `storyId`
+ * @param {{ explicitText?: string|null, explicitLabel?: string, explicitSource?: {kind: 'file'|'description', label?: string},
+ *   includePaths?: string[], axes?: string }} [opts]
+ * @returns {Promise<{ storyId: string, resolvedStoryId: string, rawText: string,
+ *   textSource: 'explicit'|'issue'|'roadmap'|null, textFailure: {kind:string, detail?:string}|null,
+ *   config: object, bundle: {files:number, chars:number}, notes: {pre: object[], post: object[]} }>}
+ */
+async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
+  const config = {};
+  const pre = [];
+  const post = [];
+  let rawText = '';
+  let textSource = null;
+  let textFailure = null;
+  let resolvedStoryId = storyId; // canonical id for the architect-config lookup
+
+  // ── Story text: explicit → GitHub issue → Hone roadmap ────────────────────────────────────
+  // HC-GF-010: an EXPLICIT story source short-circuits both lookups, so the operator can never
+  // be told "no roadmap row found" about a story they just handed us.
+  if (opts.explicitText) {
+    config.story_description = opts.explicitText;
+    rawText = opts.explicitText;
+    textSource = 'explicit';
+    // HC-GF-270: the operator wrote this text, or pointed at a file they chose, so it is trusted.
+    // The label is the file's NAME only: it is persisted server-side, and the operator's path is
+    // not the server's business (second review LOW-5).
+    const src = opts.explicitSource || {};
+    config.story_source = src.kind === 'file'
+      ? { kind: 'file', ref: null, label: path.basename(String(src.label || '')) || 'story file' }
+      : { kind: 'description', ref: null, label: '--description' };
+    pre.push(info(`  → story text from ${opts.explicitLabel || '--description'} (${opts.explicitText.length} chars) — roadmap and issue lookups skipped`));
+  } else if (/^\d+$/.test(storyId)) {
+    // HC-019n-followup-11: a bare integer is a GitHub issue number. Degrade gracefully on any
+    // failure; the step_1 hard_pause net catches the resulting placeholder cascade.
+    try {
+      const issue = await io.fetchIssue(storyId);
+      const desc = `# ${issue.title}\n\n${issue.body || '_(issue body is empty)_'}\n\n_Source: ${issue.url}_`;
+      config.story_description = desc;
+      rawText = `${issue.title}\n${issue.body || ''}`;
+      textSource = 'issue';
+      if (!rawText.trim()) textFailure = { kind: 'issue-empty' };
+      pre.push(info(`  → fetched GitHub issue #${storyId} for story context (${desc.length} chars)`));
+      // HC-GF-270: the text is now something an outside party may have written, and the pipeline
+      // turns it into a patch that auto-verify EXECUTES as the operator. Record who wrote it.
+      const prov = await issueStorySource(io, storyId, issue);
+      config.story_source = prov.source;
+      pre.push(...prov.notes);
+      // HC-019b-followup-1 F1: the canonical story id from the issue title, or the architect
+      // lookup keys on '104' and silently misses every EXECUTION_PLAN.yml entry.
+      try {
+        const titleId = extractStoryIdFromBranch(issue.title);
+        if (titleId) {
+          resolvedStoryId = titleId;
+          pre.push(info(`  → resolved issue #${storyId} → canonical story id '${titleId}' for architect-config lookup`));
+        } else {
+          pre.push(warn(`  ⚠ could not extract canonical story id from issue title '${issue.title}' — architect-config lookup will use '${storyId}' (likely silent miss)`));
+        }
+      } catch { /* extractor throws → fall back to the numeric id */ }
+    } catch (e) {
+      textFailure = { kind: 'issue-error', detail: firstLine(e) };
+      // HC-GF-270: stated rather than left absent, so the later pause is readable. Classified, not
+      // raw: this string is persisted in workflow_runs.config for the life of the run.
+      config.story_source = {
+        kind: 'none',
+        ref: null,
+        label: String(storyId),
+        error: /timed? ?out/i.test(firstLine(e)) ? 'the gh issue fetch timed out' : 'the gh issue fetch failed',
+      };
+      pre.push(warn(`  ⚠ could not fetch GitHub issue context: ${firstLine(e)}`));
+      pre.push(warn('  → proceeding without story_description; step_0 may produce placeholder output'));
+      pre.push(warn(`  ⚠ architect-config lookup will use '${storyId}' (likely silent miss)`));
+    }
+  } else {
+    // HC-019n-followup-18: a roadmap-sourced story. Only the SERVER knows what it says; only the
+    // CLI can read the adopter's disk — so ask the server, then read the files it names here.
+    // HC-GF-270: roadmap text is committed repository content, so it is trusted. Stamped BEFORE the
+    // fetch, so a 404 or a network failure still records 'roadmap' rather than no source at all.
+    config.story_source = { kind: 'roadmap', ref: null, label: String(storyId) };
+    try {
+      const data = await io.fetchStoryContext(storyId);
+      if (data && data.description) {
+        // HC-GF-232: siblings fold into story_description and NOT into the path-extraction text —
+        // the server's contract says siblings carry PROSE ONLY.
+        const sibs = Array.isArray(data.referencedStories) ? data.referencedStories : [];
+        config.story_description = composeStoryDescription(data.description, sibs);
+        rawText = data.description;
+        textSource = 'roadmap';
+        const n = Array.isArray(data.referencedPaths) ? data.referencedPaths.length : 0;
+        pre.push(info(
+          `  → resolved story context from roadmap (${data.description.length} chars, ` +
+          `${n} referenced path${n === 1 ? '' : 's'}` +
+          (sibs.length ? `, ${sibs.length} sibling row${sibs.length === 1 ? '' : 's'}` : '') +
+          ')'));
+      } else {
+        // A 200 with no description: nothing to groom from, and it looks like success.
+        textFailure = { kind: 'roadmap-empty' };
+      }
+    } catch (e) {
+      const status = e && e.response && e.response.status;
+      if (status === 404) {
+        textFailure = { kind: 'roadmap-missing' };
+        pre.push(warn(`  ⚠ no roadmap row found for '${storyId}'`));
+      } else {
+        textFailure = { kind: 'roadmap-error', detail: firstLine(e) };
+        pre.push(warn(`  ⚠ could not fetch story context: ${firstLine(e)}`));
+      }
+      pre.push(warn('  → proceeding without story context; the warning below applies'));
+    }
+  }
+
+  // ── Codebase bundle (HC-019n-followup-12) ─────────────────────────────────────────────────
+  // Without it step_1/step_4 have only training-data priors and produce code in the SHAPE of
+  // the adopter's stack but not its architecture (OptionsFlow #104 invented SQLAlchemy for a
+  // JSON-lines repo).
+  const bundle = { files: 0, chars: 0 };
+  const includePaths = opts.includePaths || [];
+  const defaultIncludePaths = repoCtx.defaultIncludePaths || [];
+  if (rawText || parseIncludePaths(includePaths).length > 0 || defaultIncludePaths.length > 0) {
+    try {
+      // HC-GF-188: a `:line` on a FULL path survives, so the windowing below can fire.
+      const candidates = new Set();
+      const pathRefLines = new Map();
+      if (rawText) {
+        for (const r of extractPathRefs(rawText)) {
+          candidates.add(r.path);
+          if (r.line && !pathRefLines.has(r.path)) pathRefLines.set(r.path, r.line);
+        }
+      }
+      // HC-GF-205: an entry may name a REGION — `path:<line>` or `path:<symbol>`.
+      // HC-GF-288: EVERY region per file, in flag order. One slot per file, filled story-first,
+      // is what discarded `cli/hone-cli.js:6180` when the story had already cited
+      // `cli/hone-cli.js:6580`: no message, and the same five regions bundled.
+      const includeAnchors = new Map();
+      let includeTargets = [];
+      if (parseIncludePaths(includePaths).length) {
+        const { resolved, missing } = partitionIncludeTargets(includePaths, io.exists);
+        includeTargets = resolved;
+        for (const t of resolved) {
+          candidates.add(t.path);
+          if (t.line || t.symbol) includeAnchors.set(t.path, [...(includeAnchors.get(t.path) || []), t]);
+        }
+        // A flag that silently does nothing is worse than one that errors.
+        for (const t of missing) pre.push(warn(`  ⚠ --include-paths '${t.raw}' matched no file — not bundled`));
+      }
+      for (const p of defaultIncludePaths) candidates.add(p);
+      const candidateLines = new Map(pathRefLines);
+      // HC-GF-288: the operator's anchors first, then the story's line, alongside rather than
+      // instead (see statedAnchorsFor). This used to return the story's line whenever there was
+      // one, so a symbol for a story-cited file was never even looked up.
+      const resolveAnchors = (candidate, fileContent) => {
+        const { anchors, unresolved } = statedAnchorsFor({
+          path: candidate,
+          content: fileContent,
+          operator: includeAnchors.get(candidate) || [],
+          storyLine: candidateLines.get(candidate) || null,
+        });
+        for (const u of unresolved) pre.push(warn(`  ⚠ --include-paths '${u.raw}' — ${u.reason}; not anchored`));
+        return anchors;
+      };
+      // HC-019n-followup-26: a file named BARE in prose resolves against the repository's own
+      // list — bundled ONLY on a unique basename match, never on a guess.
+      if (rawText) {
+        for (const { name, line } of extractBareRefs(rawText)) {
+          if (alreadyCovered(name, candidates)) continue;
+          const r = resolveBareName(name, repoCtx.repoFiles);
+          if (r.status === 'unique') {
+            candidates.add(r.path);
+            if (line && !candidateLines.has(r.path)) candidateLines.set(r.path, line);
+            pre.push(info(`  → resolved bare ref '${name}${line ? ':' + line : ''}' → ${r.path}`));
+          } else if (r.status === 'ambiguous') {
+            pre.push(warn(`  ⚠ '${name}' is ambiguous (${r.matches.length} files) — not bundling; use --include-paths to disambiguate`));
+          }
+        }
+      }
+      // 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];
+      const codebaseFiles = [];
+      let totalChars = 0;
+      let budgetSpent = false; // HC-GF-288: so a not-bundled warning can say WHY
+      for (const candidate of ordered) {
+        if (codebaseFiles.length >= BUNDLE_MAX_FILES) { budgetSpent = true; break; }
+        if (candidate.startsWith('/') || candidate.startsWith('~') || candidate.includes('..')) continue;
+        if (!io.exists(candidate)) continue;
+        let content;
+        try { content = io.readFile(candidate); } catch { continue; }
+        // HC-GF-188: `path:line` or quoted code anchors the window, and a cut file is ANNOUNCED.
+        const anchors = resolveAnchors(candidate, content);
+        const excerpt = planFileExcerpt({
+          content,
+          cap: BUNDLE_MAX_PER_FILE_CHARS,
+          lines: anchors.map((a) => a.line),
+          storyText: rawText,
+          path: candidate,
+        });
+        content = excerpt.content;
+        if (excerpt.notice) pre.push(warn(excerpt.notice));
+        for (const w of anchorWarnings(anchors, excerpt.unhonoured)) pre.push(warn(w));
+        if (totalChars + content.length > BUNDLE_MAX_TOTAL_CHARS) { budgetSpent = true; break; }
+        totalChars += content.length;
+        codebaseFiles.push({ path: candidate, content });
+      }
+      // HC-GF-288: an operator-named entry whose file never reached the bundle (the budget ran
+      // out first, or it names a directory) vanished as silently as the anchor did. A refused
+      // credential file is already reported by auditLines below.
+      const bundledPaths = new Set(codebaseFiles.map((f) => f.path));
+      for (const t of includeTargets) {
+        if (bundledPaths.has(t.path) || selection.refused.includes(t.path)) continue;
+        const why = (io.isDirectory && io.isDirectory(t.path)) ? 'it is a directory; name the files in it'
+          : budgetSpent ? `the bundle's ${BUNDLE_MAX_FILES}-file / ${BUNDLE_MAX_TOTAL_CHARS}-char budget ran out first`
+            : 'it could not be read as a file inside this repository';
+        pre.push(warn(`  ⚠ --include-paths '${t.raw}' — NOT bundled: ${why}`));
+      }
+      for (const line of auditLines(selection)) pre.push(info(line));
+      if (codebaseFiles.length > 0) {
+        config.codebaseFiles = codebaseFiles;
+        bundle.files = codebaseFiles.length;
+        bundle.chars = totalChars;
+        pre.push(info(`  → bundled ${codebaseFiles.length} codebase file(s) for step_1/step_4 context (${totalChars} chars)`));
+      }
+    } catch (e) {
+      pre.push(warn(`  ⚠ codebase bundling failed (non-fatal): ${firstLine(e)}`));
+    }
+  }
+
+  // HC-019n-followup-17: say so LOUDLY when the code-aware steps will run blind.
+  if (!config.codebaseFiles) {
+    pre.push(warn('  ⚠ no codebase files bundled — step_1 / step_4 / step_5 / step_5d / step_5e'));
+    pre.push(warn('    will run WITHOUT source context and may invent APIs that do not exist.'));
+    if (!/^\d+$/.test(storyId)) {
+      pre.push(warn(`    '${storyId}' is not a GitHub issue number, so file paths cannot be`));
+      pre.push(warn('    auto-detected from an issue body.'));
+    }
+    pre.push(warn('    Fix: hone run-story <id> --include-paths path/one.js,path/two.js'));
+  }
+
+  // ── Classifier axes (HC-COMM-010) ─────────────────────────────────────────────────────────
+  // Explicit --axes wins. Otherwise the DETERMINISTIC axes from the extractors; judgment axes
+  // come from the groomer at step_0 and are harvested server-side. Fail-open.
+  if (opts.axes) {
+    const axes = String(opts.axes).split(',').map(a => a.trim().toLowerCase()).filter(Boolean);
+    if (axes.length > 0) config.classifier_axes = axes;
+  } else {
+    try {
+      const touched = Array.isArray(config.codebaseFiles) ? config.codebaseFiles.map(f => f.path).filter(Boolean) : [];
+      const auto = classifyStory({
+        type: extractType([], rawText, String(storyId)),
+        has_security_implications: extractSecurityImplications([], rawText),
+        cross_repo_dependency: extractCrossRepoDependency(rawText),
+        recently_modified_overlap: io.recentlyModifiedOverlap(touched),
+      });
+      if (auto.architect.engage && auto.architect.axes.length > 0) {
+        config.classifier_axes = auto.architect.axes;
+        pre.push(info(`  → auto-detected classifier axes: ${auto.architect.axes.join(', ')}`));
+      }
+    } catch (e) {
+      pre.push(warn(`  ⚠ axes auto-detection failed (non-fatal): ${firstLine(e)}`));
+    }
+  }
+
+  // ── Architect flags (HC-019b) ─────────────────────────────────────────────────────────────
+  // workflow-dag.js's validateStepPreConditions BLOCKS step_1 when architect_consulted is true
+  // and checklist_b_completed is not; without these flags every architect-engaged story
+  // deadlocks. Keyed on the RESOLVED id (HC-019b-followup-1 F1).
+  const arch = readArchitectConfigFromText(repoCtx.planText || '', resolvedStoryId);
+  config.architect_consulted = arch.architect_consulted;
+  config.checklist_b_completed = arch.checklist_b_completed;
+  if (arch.diagnostic) post.push(warn(`  ⚠ ${arch.diagnostic}`));
+  if (arch.architect_consulted) {
+    post.push(info(`  → architect_consulted: true, checklist_b_completed: ${arch.checklist_b_completed}`));
+  }
+
+  return { storyId, resolvedStoryId, rawText, textSource, textFailure, config, bundle, notes: { pre, post } };
+}
+
+/**
+ * The run config both commands send. The only assembler: run-story and queue-stories agree
+ * because they call this, not because a test compares two hand-built objects.
+ */
+function buildRunConfig(repoCtx, storyCtx) {
+  const config = { ...repoCtx.config, ...storyCtx.config };
+  for (const k of SERVER_OWNED_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(config, k)) {
+      throw new Error(`run config carries the server-owned key '${k}' — the server sets it, a client never does`);
+    }
+  }
+  return config;
+}
+
+/** Whether a story has text to groom from. Judged on the RAW text, never the composed description. */
+function hasStoryText(storyCtx) {
+  return String((storyCtx && storyCtx.rawText) || '').trim().length > 0;
+}
+
+/** One line naming why a story has no text — every cause it could be, where they cannot be told apart. */
+function describeMissingText(storyCtx) {
+  const f = (storyCtx && storyCtx.textFailure) || { kind: 'unknown' };
+  const id = storyCtx && storyCtx.storyId;
+  switch (f.kind) {
+    case 'roadmap-missing':
+      // stories.js answers 404 for both, by design, so neither can be ruled out from here.
+      return `${id} — no roadmap row for this id, or this org is not on the roadmap allowlist (the server answers both with 404)`;
+    case 'roadmap-empty':
+      return `${id} — the roadmap row exists but its description is empty`;
+    case 'roadmap-error':
+      return `${id} — the story context could not be fetched: ${f.detail}`;
+    case 'issue-error':
+      return `${id} — GitHub issue #${id} could not be fetched: ${f.detail}`;
+    case 'issue-empty':
+      return `${id} — GitHub issue #${id} has an empty title and body`;
+    default:
+      return `${id} — no story text was found`;
+  }
+}
+
+/**
+ * Why an OVERNIGHT batch must not start in this repository, or null. Fail closed: an unattended
+ * batch runs with nobody to notice that a mode was mistyped or that every story is waiting.
+ */
+function overnightModeRefusal(execution) {
+  const ex = execution || { raw: null, mode: 'server', recognized: false };
+  if (!ex.recognized) {
+    const what = ex.unreadable
+      ? `could not be read (${ex.unreadable})`
+      : `is '${ex.raw}', which is not a mode Hone knows (server, editor)`;
+    return `✗ --overnight refused: execution.mode in .github/.pipeline-config.yml ${what}. ` +
+      'An unattended batch would run on a guess nobody is awake to check. Fix the mode, then re-run.';
+  }
+  if (ex.mode === 'editor') {
+    return '✗ --overnight refused: execution.mode is editor, so every story would park at step_4 waiting for ' +
+      'your editor AI, with nobody there to build it. Queue without --overnight to park them for the ' +
+      'morning, or set execution.mode to server for an unattended batch.';
+  }
+  return null;
+}
+
+/**
+ * The server's cap on an overnight batch: MUST equal MAX_STORIES_PER_OVERNIGHT_BATCH in
+ * server/src/services/batch-store.js (a cross-package test pins it; the CLI cannot require server
+ * code). Checked BEFORE any story is resolved or uploaded — review of #1100: a 26-50 story overnight
+ * file resolved every story and sent up to ~26 MB only for the server to refuse it.
+ */
+const OVERNIGHT_MAX_STORIES = 25;
+
+/**
+ * How long `hone queue-stories` waits for POST /orchestrate/batch, sized to the body.
+ *
+ * Review of #1100: the API client's 30 s timeout covered the UPLOAD. A 26 MB batch needed about
+ * 7 Mbit/s to finish in time, and one that finished just after the server committed printed
+ * "Failed" for a batch that was queued, so re-running it queued (and paid for) the stories twice.
+ * 30 s plus 4 s per started MB is a 2 Mbit/s floor. `HONE_BATCH_POST_TIMEOUT_BASE_MS` overrides the
+ * 30 s base (tests).
+ *
+ * @param {number} bodyBytes
+ * @returns {number} milliseconds
+ */
+function batchPostTimeoutMs(bodyBytes, baseMs = Number(process.env.HONE_BATCH_POST_TIMEOUT_BASE_MS) || 30_000) {
+  return baseMs + Math.ceil(Math.max(0, bodyBytes) / 1_048_576) * 4_000;
+}
+
+module.exports = {
+  batchPostTimeoutMs,
+  classifyProvenanceFailure,
+  OVERNIGHT_MAX_STORIES,
+  resolveRepoContext,
+  resolveStoryContext,
+  buildRunConfig,
+  hasStoryText,
+  describeMissingText,
+  overnightModeRefusal,
+  SERVER_OWNED_KEYS,
+  BUNDLE_MAX_FILES,
+  BUNDLE_MAX_TOTAL_CHARS,
+  BUNDLE_MAX_PER_FILE_CHARS,
+};