@hone-ai/cli 1.30.0 → 1.31.0

package/hone-cli.js

@@ -5604,6 +5604,7 @@ program
   .option('--kill', 'Kill the latest workflow run for this story')
   .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). Exit codes: 2 = paused at a human gate, 3 = parked for your editor (execution.mode: editor)')
+  .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')
   .option('--story-file <path>', 'HC-GF-010: read the story text from a local file. Skips the GitHub-issue and Hone-roadmap lookups entirely, so a repo with neither can still run the pipeline.')
@@ -5915,21 +5916,24 @@ program
         // bundler can WINDOW a too-big file around its edit site instead of
         // head-truncating past it (the demo's line 787 sits at char 37K).
         const candidateLines = new Map();
+        // HC-GF-073: hoisted out of the bare-ref branch below, because the sibling tier
+        // needs the same list on stories that contain no bare refs at all — which is most
+        // of them.
+        const { gitEnv } = require('./lib/git-env');
+        let repoFiles = null;
+        const listRepoFiles = () => {
+          if (repoFiles) return repoFiles;
+          try {
+            repoFiles = execSync('git ls-files', {
+              cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+            }).split('\n').filter(Boolean);
+          } catch { repoFiles = []; }
+          return repoFiles;
+        };
         if (issueBodyForFiles) {
           const { extractBareRefs, resolveBareName, alreadyCovered } = require('./lib/bundle-paths');
-          const { gitEnv } = require('./lib/git-env');
           const bareRefs = extractBareRefs(issueBodyForFiles);
           if (bareRefs.length > 0) {
-            let repoFiles = null;
-            const listRepoFiles = () => {
-              if (repoFiles) return repoFiles;
-              try {
-                repoFiles = execSync('git ls-files', {
-                  cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
-                }).split('\n').filter(Boolean);
-              } catch { repoFiles = []; }
-              return repoFiles;
-            };
             for (const { name, line } of bareRefs) {
               if (alreadyCovered(name, candidates)) continue;
               const r = resolveBareName(name, listRepoFiles());
@@ -5954,9 +5958,32 @@ program
         const MAX_FILES = 30;
         const MAX_TOTAL_CHARS = 150_000;
         const MAX_PER_FILE_CHARS = 25_000;
+        // HC-GF-073: `candidates` is only what the STORY named, and a story names the
+        // files it will CREATE — so on a greenfield repo every one of them fails the
+        // existsSync below and the bundle is EMPTY. Measured across FlowForge's 33 real
+        // stories: 29 extracted zero existing files. The dogfood runs looked fine only
+        // because an operator had typed --include-paths once; 12 of 12 runs then bundled
+        // the same three files across five different stories.
+        //
+        // selectBundle() splits them into what exists, what is pending, and adds two
+        // tiers the story can never name: repo-level signal files (whose ABSENCE is what
+        // a security reviewer must be able to check — HC-GF-063) and existing neighbours
+        // of the pending paths (the conventions a new module has to match). Order is
+        // priority order, because the char cap below truncates from the end.
+        const { selectBundle, auditLines } = require('./lib/bundle-context');
+        const selection = selectBundle({
+          named: [...candidates],
+          repoFiles: listRepoFiles(),
+          exists: (rel) => {
+            if (rel.startsWith('/') || rel.startsWith('~') || rel.includes('..')) return false;
+            const abs = path.resolve(process.cwd(), rel);
+            return abs.startsWith(process.cwd() + path.sep) && fs.existsSync(abs);
+          },
+        });
+        const ordered = [...selection.present, ...selection.signal, ...selection.siblings];
         const codebaseFiles = [];
         let totalChars = 0;
-        for (const candidate of candidates) {
+        for (const candidate of ordered) {
           if (codebaseFiles.length >= MAX_FILES) break;
           if (candidate.startsWith('/') || candidate.startsWith('~') || candidate.includes('..')) continue;
           const abs = path.resolve(process.cwd(), candidate);
@@ -5989,6 +6016,11 @@ program
           totalChars += content.length;
           codebaseFiles.push({ path: candidate, content });
         }
+        // HC-GF-073: the old line printed a COUNT, and a count cannot distinguish three
+        // files the story named from three it did not. That is why 12 consecutive runs
+        // bundled an unrelated module and nothing said so — the "running blind" warning
+        // below fires on an EMPTY bundle, and these were not empty.
+        for (const line of auditLines(selection)) console.log(line);
         if (codebaseFiles.length > 0) {
           orchestrateConfig.codebaseFiles = codebaseFiles;
           console.log(`  → bundled ${codebaseFiles.length} codebase file(s) for step_1/step_4 context (${totalChars} chars)`);
@@ -6233,6 +6265,10 @@ program
 
       // Poll loop
       const interval = parseInt(opts.pollInterval, 10) * 1000;
+      // HC-GF-064: at most ONE verification per attempt per process. Without this the
+      // advisory path re-verifies on every poll tick, because advisory never advances
+      // the run and the pause it re-observes is the same pause.
+      const _verifiedAttempts = new Set();
       while (true) {
         await new Promise(r => setTimeout(r, interval));
 
@@ -6265,6 +6301,50 @@ program
           }
           console.log(`⏳ Step ${status.currentStep} (${step?.agent || 'unknown'}) — awaiting approval`);
 
+          // HC-GF-064: verify BEFORE asking anyone to approve.
+          //
+          // The gate this feeds has existed since HC-019n-followup-34/35 and had never
+          // fired — 22 of 22 runs advisory, 5 of 22 with any verdict at all — because
+          // nothing ever ran the executing step. The only prompt was a run-report line,
+          // and 5-of-22 is what that nag was worth.
+          //
+          // Consent is DERIVED: `ci.local_command` being explicitly set is the adopter's
+          // own statement of how to test this repo (see cli/lib/auto-verify.js and
+          // docs/architecture/adr-verification-invocation.md). Never throws — a failure
+          // here must leave the operator exactly where they were, which is being asked
+          // to approve.
+          try {
+            const { decideAutoVerify, announce, shouldRepoll, alreadyVerified } = require('./lib/auto-verify');
+            const attemptKey = `${status.currentStep}#${step?.attempt ?? 1}`;
+            const decision = decideAutoVerify({
+              stepKey: status.currentStep,
+              repoRoot: process.cwd(),
+              noVerifyFlag: opts.verify === false,
+            });
+            if (decision.run && !alreadyVerified(attemptKey, _verifiedAttempts)) {
+              _verifiedAttempts.add(attemptKey);
+              console.log(announce(decision, data.runId));
+              const { spawnSync } = require('child_process');
+              const r = spawnSync(process.execPath,
+                [process.argv[1], 'verify-patch', data.runId, '--report'],
+                { stdio: 'inherit', env: process.env });
+              // A green verdict under `enforce` AUTO-APPROVES this gate, so the run may
+              // already have moved on. Re-poll rather than prompting for an approval that
+              // is no longer wanted — asking a human to approve something already approved
+              // is how an operator learns to distrust the output.
+              if (shouldRepoll({ gate: decision.gate, verdictOk: r.status === 0,
+                                 attemptKey, verifiedAttempts: null })) {
+                console.log('  → verified; enforce may have advanced the run. Re-checking...');
+                continue;
+              }
+              console.log(r.status === 0
+                ? `  → verified and recorded (gate: ${decision.gate}). The gate still needs you.`
+                : '  → verification did not pass; the gate still needs you.');
+            }
+          } catch (e) {
+            console.log(`  (auto-verify skipped: ${e.message})`);
+          }
+
           // Interactive prompt
           if (process.stdin.isTTY) {
             const readline = require('readline');
@@ -7344,11 +7424,15 @@ showCmd
   .command('step <workflowId> <stepKey>')
   .description('Print the actual LLM output of an orchestrator step (latest attempt by default)')
   .option('--attempt <n>', 'Specific attempt number (default: latest)')
+  .option('--prompt', 'Also print the exact prompt this step sent to the model (HC-GF-055)')
   .action(async (workflowId, stepKey, opts) => {
     const config = getConfig();
     const client = api(config);
     try {
-      const url = `/orchestrate/${workflowId}/step/${stepKey}${opts.attempt ? `?attempt=${opts.attempt}` : ''}`;
+      const q = [];
+      if (opts.attempt) q.push(`attempt=${opts.attempt}`);
+      if (opts.prompt) q.push('prompt=1');
+      const url = `/orchestrate/${workflowId}/step/${stepKey}${q.length ? `?${q.join('&')}` : ''}`;
       const r = await client.get(url);
       const s = r.data;
       console.log(`── step output ──────────────────────────────────────────`);
@@ -7366,6 +7450,21 @@ showCmd
         console.log(`── error_context (retry feedback) ──────────────────────`);
         console.log(s.errorContext);
       }
+      // HC-GF-055: say whether the prompt was recorded, ALWAYS. The rule this repo keeps
+      // relearning is that a stored field nobody surfaces is the same as no field at all —
+      // `input_artifact` sat in the schema with zero writers for months and nobody noticed
+      // because nothing ever mentioned it.
+      console.log(``);
+      if (s.promptChars == null) {
+        console.log(`── prompt ─────────────────────────────────────────────`);
+        console.log(`  (not recorded for this attempt — pre-HC-GF-055 runs have none)`);
+      } else if (s.prompt != null) {
+        console.log(`── prompt SENT to the model (${s.promptChars} chars) ────────`);
+        console.log(s.prompt);
+      } else {
+        console.log(`── prompt ─────────────────────────────────────────────`);
+        console.log(`  ${s.promptChars} chars recorded — re-run with --prompt to print it`);
+      }
       console.log(``);
       console.log(`── output (the LLM's actual response) ──────────────────`);
       console.log(s.output || '(no output recorded — step may not have completed)');

package/lib/auto-verify.js

@@ -0,0 +1,149 @@
+'use strict';
+/**
+ * auto-verify.js — HC-GF-064: decide whether the CLI should run `verify-patch` itself
+ * when a run pauses at the step_4 gate.
+ *
+ * WHY THIS EXISTS. The closed-loop gate has been shipped and integration-tested since
+ * HC-019n-followup-34/35, and had never fired: 22 of 22 runs `advisory`, 5 of 22 with any
+ * verdict recorded at all, and zero automatic invocations. The only prompt was a line
+ * `run-report` prints — "NO verification was reported for this run" — and 5-of-22 is what
+ * that nag is worth. A gate that never receives a verdict is indistinguishable from a gate
+ * that does not exist.
+ *
+ * The value is measured, not assumed. On run 77ed4f1b `verify-patch` found three ruff
+ * errors that BOTH the code-reviewer and the security agent had passed — neither could
+ * have caught them, because no reviewing step executes anything. And on run 6964b87e a
+ * green verdict auto-approved step_4 with no human approval, which is the first time
+ * enforce mode has been demonstrated end to end.
+ *
+ * CONSENT IS DERIVED, NOT REQUESTED. Running an adopter's test suite unasked is a real
+ * intrusion — it provisions dependencies, writes to disk, and costs wall clock. But
+ * `ci.local_command` and `ci.install_command` are ALREADY in their `.pipeline-config.yml`:
+ * an adopter who filled those in has declared, in their own words, how to build and test
+ * this repo locally. Running exactly those commands, in an isolated worktree, at the
+ * moment their pipeline pauses for their approval, is inside what they have sanctioned.
+ * An adopter who has not configured them gets today's behaviour, unchanged.
+ *
+ * So this defaults ON where consent already exists and OFF where it does not — neither a
+ * blanket opt-in (which recreates the 5-of-22 failure this work exists to fix) nor a
+ * blanket opt-out.
+ *
+ * THIS DOES NOT VIOLATE HC-026c's "ships advisory by default" discipline, though it looks
+ * like it might. That rule is about not letting a detector CHANGE FLOW before it has
+ * earned trust. This changes no flow: it produces a verdict. Whether the verdict gates
+ * anything remains `verification.gate`, which stays `advisory` by default and is untouched
+ * here. Running the tests is safe-by-default; ACTING on them stays opt-in.
+ *
+ * Design: docs/architecture/adr-verification-invocation.md
+ */
+
+const { readCIConfigDetails, readVerificationGateConfig } = require('./pipeline-config');
+
+/** The only gate a `verify-patch` verdict can inform (gate_sources default). */
+const VERIFIABLE_STEP = 'step_4';
+
+/**
+ * @returns {{ run: boolean, reason: string, command: string|null, gate: string }}
+ *
+ * `reason` is always populated, including when `run` is true, because the caller ANNOUNCES
+ * it. An adopter discovering their test suite mid-run should be told why it is running and
+ * how to stop it — the surprise is the real cost of this feature, and an unexplained
+ * surprise is the version that gets it reverted.
+ */
+function decideAutoVerify({ stepKey, repoRoot, noVerifyFlag = false, env = process.env } = {}) {
+  const gate = safeGate(repoRoot);
+  const off = (reason) => ({ run: false, reason, command: null, gate });
+
+  if (noVerifyFlag) return off('--no-verify was passed');
+  if (String(env.HONE_NO_AUTO_VERIFY || '') === '1') return off('HONE_NO_AUTO_VERIFY=1');
+
+  // Only step_4. A verdict for any other step has no gate to inform, so running an
+  // adopter's suite there would spend their time for nothing.
+  if (stepKey !== VERIFIABLE_STEP) {
+    return off(`only ${VERIFIABLE_STEP} has a verification gate (paused at ${stepKey})`);
+  }
+
+  const auto = readVerificationAuto(repoRoot);
+  if (auto === false) return off('verification.auto is false in .pipeline-config.yml');
+
+  const ci = safeCi(repoRoot);
+  if (!ci.local_command_explicit) {
+    // The consent gate. NOT an error and NOT a nag — an adopter who has not told us how
+    // to test their repo has not consented to us guessing, and `make ci` is a guess.
+    return off('ci.local_command is not set in .pipeline-config.yml — no consent to run tests');
+  }
+
+  return { run: true, reason: `ci.local_command is configured (${ci.local_command})`, command: ci.local_command, gate };
+}
+
+/** `verification.auto` — true unless explicitly false. Unset means "use the consent rule". */
+function readVerificationAuto(repoRoot) {
+  const block = readYamlBlock(repoRoot, 'verification');
+  if (!block || typeof block !== 'object') return null;
+  if (block.auto === false || String(block.auto).toLowerCase() === 'false') return false;
+  if (block.auto === true || String(block.auto).toLowerCase() === 'true') return true;
+  return null;
+}
+
+function readYamlBlock(repoRoot, key) {
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+  const fs = require('fs'); const path = require('path');
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'), path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8'));
+      if (parsed && typeof parsed === 'object' && parsed[key] !== undefined) return parsed[key];
+    } catch { /* a malformed config must not break the run — fall through to null */ }
+  }
+  return null;
+}
+
+function safeCi(repoRoot) {
+  try { return readCIConfigDetails(repoRoot); }
+  catch { return { local_command: null, local_command_explicit: false, install_command: null }; }
+}
+function safeGate(repoRoot) {
+  try { return readVerificationGateConfig(repoRoot) || 'advisory'; }
+  catch { return 'advisory'; }
+}
+
+/** What the operator sees before their test suite starts. */
+function announce(decision, runId) {
+  if (!decision.run) return null;
+  return [
+    `  → verifying step_4 before you approve it: ${decision.command}`,
+    `    (in an isolated worktree; gate mode: ${decision.gate}. Skip with --no-verify.)`,
+  ].join('\n');
+}
+
+
+/**
+ * After a verdict is posted, should the caller RE-POLL (the run may have moved) or fall
+ * through to the normal approve prompt?
+ *
+ * HC-GF-064-followup: the first version always re-polled on a green verdict, which is an
+ * UNBOUNDED LOOP under the default `advisory` mode — advisory only RECORDS the verdict, so
+ * the run stays paused, the caller re-polls, sees the same pause, and runs the adopter's
+ * test suite again, provisioning a worktree every time, once per poll interval, forever.
+ * It was invisible during development because the repo it was built against is set to
+ * `enforce`, where a green verdict really does advance the run. Every adopter on the
+ * DEFAULT config would have hit it.
+ *
+ * Two independent guards, because either alone is thin:
+ *   - only `enforce` can advance a run, so only `enforce` justifies re-polling;
+ *   - an attempt is verified AT MOST ONCE per process regardless of mode, so a
+ *     misconfiguration or a future third mode cannot resurrect the loop.
+ */
+function shouldRepoll({ gate, verdictOk, attemptKey, verifiedAttempts }) {
+  if (!verdictOk) return false;
+  if (gate !== 'enforce') return false;
+  if (verifiedAttempts && verifiedAttempts.has(attemptKey)) return false;
+  return true;
+}
+
+/** Has this exact attempt already been verified by this process? */
+function alreadyVerified(attemptKey, verifiedAttempts) {
+  return Boolean(verifiedAttempts && verifiedAttempts.has(attemptKey));
+}
+
+module.exports = { decideAutoVerify, announce, readVerificationAuto, shouldRepoll, alreadyVerified, VERIFIABLE_STEP };

package/lib/bundle-context.js

@@ -0,0 +1,182 @@
+'use strict';
+/**
+ * bundle-context.js — HC-GF-073: decide what source the pipeline actually gets to read.
+ *
+ * WHY THIS EXISTS. The bundler drops every path that fails `existsSync`, which on a
+ * greenfield story is all of them: a story names what it will CREATE. Measured across the
+ * 33 real FlowForge stories, 29 extracted ZERO existing files. The dogfood runs looked
+ * healthy only because an operator had typed `--include-paths` once — 12 of 12 runs then
+ * bundled the same three files across five different stories, none of which named them.
+ *
+ * Three recorded failures trace back here, and none of them looked like a bundling bug:
+ *   HC-GF-063  a HIGH security finding on `.gitignore` "being unverified" — it was never
+ *              bundled; `.gitignore:2` already contained `.env`.
+ *   HC-GF-069  step_5 aborted: "two ACs are blocked on files that have never been bundled".
+ *   HC-GF-072  the builder invented `FLOWFORGE_MODE` while `.env.example`, unbundled,
+ *              already read `MODE=paper`.
+ *
+ * THREE TIERS, in priority order, because the CLI's char budget truncates from the end:
+ *   present  — paths the STORY named that exist. The best context there is.
+ *   signal   — small repo-level files no story ever names but every reviewer needs:
+ *              ignore files, manifests, env TEMPLATES. Their ABSENCE is the finding.
+ *   siblings — existing neighbours of the paths the story will create, taken from the
+ *              nearest ancestor directory that has files. This is the greenfield answer:
+ *              you cannot show the builder a file that does not exist, but you can show
+ *              it how this package writes the ones that do.
+ *
+ * SECRETS ARE REFUSED AT EVERY TIER, including when the story names one outright. `named`
+ * is untrusted input — story prose, or an `--include-paths` flag. `.env.example` is a
+ * template and safe; `.env` holds live broker credentials, and `git ls-files` is no guard
+ * because a misconfigured repo can track one. A refusal is REPORTED, never silent.
+ *
+ * The reporting half is not decoration. Today's "running blind" warning fires on an EMPTY
+ * bundle, so a bundle of three irrelevant files is indistinguishable from a good one and
+ * the operator is told nothing — a check that cannot fail, at the input stage.
+ */
+
+const path = require('path');
+
+/**
+ * Repo-level files worth bundling regardless of what the story says. Deliberately
+ * cross-stack: a list that only knows `pyproject.toml` hands every Node adopter the old
+ * behaviour. Kept to files that are small and that answer "does this repo already handle
+ * X" — the question a reviewer cannot otherwise settle.
+ */
+const SIGNAL_FILES = Object.freeze([
+  '.gitignore', '.dockerignore', '.npmignore',
+  '.env.example', '.env.sample', '.env.template',
+  'package.json', 'pyproject.toml', 'setup.cfg', 'go.mod', 'Cargo.toml',
+  'Gemfile', 'pom.xml', 'build.gradle', 'composer.json',
+]);
+
+/**
+ * A path that must never reach an agent prompt. Matched on the BASENAME so a nested
+ * `config/.env` is caught too. The `.example`/`.sample`/`.template` suffixes are the
+ * documented exception and are handled by testing them first.
+ */
+const SECRET_BASENAMES = [/^\.env($|\.)/i, /^secrets?\./i, /\.pem$/i, /\.p12$/i, /(^|[._-])id_(rsa|dsa|ecdsa|ed25519)$/i];
+const SECRET_EXEMPT = /\.(example|sample|template|dist)$/i;
+
+/** Is this path a credential file? `.env.example` is not; `.env.production` is. */
+function isSecretPath(p) {
+  const base = path.posix.basename(String(p || '').replace(/\\/g, '/'));
+  if (SECRET_EXEMPT.test(base)) return false;
+  return SECRET_BASENAMES.some((re) => re.test(base));
+}
+
+/** Directory of a repo-relative path, '' at the root. */
+const dirOf = (p) => {
+  const d = path.posix.dirname(String(p).replace(/\\/g, '/'));
+  return d === '.' ? '' : d;
+};
+
+/**
+ * Existing files that are DIRECT children of `dir` (not of its subdirectories — a
+ * recursive walk would drag a whole tree in and blow the char budget on the first story
+ * that touches a package root).
+ */
+function directChildren(dir, repoFiles) {
+  return repoFiles.filter((f) => dirOf(f) === dir);
+}
+
+/**
+ * Walk from a pending path's own directory toward the root, stopping at the FIRST
+ * directory that has files. `flowforge/config/settings.py` in a repo with no
+ * `flowforge/config/` yields `flowforge/`'s children; it does not climb to the root and
+ * return the entire repo.
+ */
+function nearestPopulatedAncestor(pendingPath, repoFiles) {
+  let dir = dirOf(pendingPath);
+  for (;;) {
+    const kids = directChildren(dir, repoFiles);
+    if (kids.length > 0) return { dir, kids };
+    if (dir === '') return { dir: '', kids: [] };
+    dir = dirOf(dir);
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string[]} o.named      paths the story named (or --include-paths supplied)
+ * @param {string[]} o.repoFiles  tracked files, `git ls-files`
+ * @param {(p:string)=>boolean} o.exists  the CLI passes an fs check, so an untracked-but-
+ *                                        present file is not miscounted as pending
+ * @param {number} [o.maxSiblings=6]
+ * @returns {{present:string[], pending:string[], signal:string[], siblings:string[], refused:string[]}}
+ */
+function selectBundle({ named = [], repoFiles = [], exists = () => false, maxSiblings = 6 } = {}) {
+  const present = [], pending = [], refused = [];
+  for (const p of named) {
+    if (isSecretPath(p)) { refused.push(p); continue; }
+    (exists(p) ? present : pending).push(p);
+  }
+
+  const taken = new Set(present);
+  // No isSecretPath() filter here: SIGNAL_FILES is a frozen literal, so the guarantee
+  // belongs to the LIST and is asserted against it directly. A filter here could never
+  // fire, and a guard that cannot fire is indistinguishable from one that is missing.
+  const signal = SIGNAL_FILES.filter((f) => !taken.has(f) && exists(f));
+  signal.forEach((f) => taken.add(f));
+
+  // Prefer a sibling sharing the pending file's extension — the convention a new .py must
+  // match lives in another .py, not in the package's README.
+  const siblings = [];
+  for (const p of pending) {
+    if (siblings.length >= maxSiblings) break;
+    const ext = path.posix.extname(p);
+    const { kids } = nearestPopulatedAncestor(p, repoFiles);
+    const ranked = [...kids].sort((a, b) =>
+      (path.posix.extname(b) === ext) - (path.posix.extname(a) === ext));
+    for (const k of ranked) {
+      if (siblings.length >= maxSiblings) break;
+      if (taken.has(k) || isSecretPath(k)) continue;
+      taken.add(k); siblings.push(k);
+    }
+  }
+
+  return { present, pending, signal, siblings, refused };
+}
+
+/**
+ * What the operator reads before the run starts.
+ *
+ * The load-bearing line is the ratio: `0 of 2 paths this story names`. It is what makes a
+ * bundle that matched nothing distinguishable from one that matched everything — the
+ * distinction the current empty-bundle warning cannot draw. The reason is always given
+ * alongside it, because a create-only story is NORMAL and a warning that reads as a defect
+ * on every greenfield story gets tuned out within a day, taking the real one with it.
+ */
+function auditLines(sel) {
+  const { present = [], pending = [], signal = [], siblings = [], refused = [] } = sel || {};
+  const named = present.length + pending.length;
+  const out = [];
+
+  if (named > 0) {
+    out.push(`  → bundle: ${present.length} of ${named} path${named === 1 ? '' : 's'} this story names`);
+    if (pending.length > 0) {
+      out.push(`    ${pending.length} do not yet exist (to be created): ${pending.join(', ')}`);
+    }
+  } else {
+    // The regression this fix nearly introduced, caught reviewing it before merge. A
+    // story yielding zero paths used to produce an EMPTY bundle, which tripped the
+    // caller's "running blind" warning. The signal tier means the bundle is never empty
+    // again — a .gitignore and a manifest are always there — so that warning would be
+    // silently suppressed on the one condition it exists for. Bundling two config files
+    // is not source context, and saying nothing about it would be this change committing
+    // the defect it was written to fix.
+    out.push('  ⚠ the story named no source paths — step_1 / step_4 will run WITHOUT source context');
+  }
+  if (siblings.length > 0) {
+    out.push(`    + ${siblings.length} existing neighbour(s) for convention: ${siblings.join(', ')}`);
+  }
+  if (signal.length > 0) out.push(`    + ${signal.length} repo-level file(s): ${signal.join(', ')}`);
+  if (refused.length > 0) {
+    out.push(`  ⚠ refused ${refused.length} credential file(s), never bundled: ${refused.join(', ')}`);
+  }
+  if (present.length === 0 && siblings.length === 0 && signal.length === 0) {
+    out.push('  ⚠ nothing to bundle — the code steps will run WITHOUT source context');
+  }
+  return out;
+}
+
+module.exports = { selectBundle, auditLines, isSecretPath, SIGNAL_FILES };

package/package.json

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