@hone-ai/cli 1.34.0 → 1.35.1

package/lib/run-target.js

@@ -94,4 +94,69 @@ async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
   };
 }
 
-module.exports = { resolveRunTarget, isRunId, LOOKUP_LIMIT };
+/**
+ * HC-GF-270-followup-1 — what a caller-supplied argument must look like before any verb builds a URL
+ * from it. HC-GF-270 checked the step key inline in two verbs; five more verbs took a run id, a step key
+ * or an attempt that nothing checked. Encoding alone is not enough: `encodeURIComponent('..') === '..'`,
+ * and axios resolves the request path with `new URL()`, which collapses dot segments, so
+ * `/orchestrate/../verdict` goes out as `/verdict`.
+ */
+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;
+
+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: '' },
+};
+
+/**
+ * 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
+ *   `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.
+ */
+function runArgsError(checks) {
+  for (const { label, kind, value, optional } of checks) {
+    if (optional && value === undefined) continue;
+    const k = KINDS[kind];
+    if (!k) throw new TypeError(`runArgsError: unknown kind ${JSON.stringify(kind)}`);
+    // JSON.stringify: a crafted value's control characters are escaped, never printed raw to the terminal.
+    if (!k.ok(value)) return `${label} ${k.why} (got ${JSON.stringify(value === undefined ? null : value)})${k.hint}`;
+  }
+  return null;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+function orchestratePath(segments, query) {
+  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+  const parts = segments.map((v, i) => {
+    if (v === null || v === undefined) throw new TypeError(`orchestratePath: segment ${i} is ${v}`);
+    const s = String(v);
+    if (s === '' || s === '.' || s === '..') throw new TypeError(`orchestratePath: segment ${i} is ${JSON.stringify(s)}`);
+    return encodeURIComponent(s);
+  });
+  const base = ['', 'orchestrate', ...parts].join('/');
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v === null || v === undefined || v === false || v === '') continue;
+    qs.append(k, String(v));
+  }
+  const q = qs.toString();
+  return q ? `${base}?${q}` : base;
+}
+
+module.exports = {
+  resolveRunTarget, isRunId, LOOKUP_LIMIT,
+  isStepKey, isAttempt, isBatchId, runArgsError, orchestratePath,
+};

package/lib/sandbox-lifecycle.js

@@ -0,0 +1,357 @@
+'use strict';
+/**
+ * HC-GF-171 — the caller that makes the sandbox fire.
+ *
+ * HC-GF-168 built the fixture, HC-GF-169 built the declaration and the guard, HC-GF-173 built the
+ * trigger, HC-GF-170 built the shapes. Every one shipped, and a run still touches no datastore,
+ * because `assertScratchTarget` — the part 169 calls load-bearing — has ZERO production callers.
+ *
+ * THE HOLE THIS CLOSES. That guard refuses without a live probe of the adopter's database, and
+ * rightly: "could not check" is not "checked". But the `sandbox:` block declares no command that
+ * could produce one, and 169's own premise is that Hone cannot know the adopter's datastore. The
+ * guard demanded proof it gave nobody the means to supply, so it could never pass and the feature
+ * could never fire. `verify.probe` is that means — an adopter-declared command, executed
+ * adopter-side exactly like `create`/`migrate`/`reset`, whose stdout is the evidence.
+ *
+ * REFUSE, DO NOT SKIP. Every path here ends in engage, stand-down or refusal, and the three are
+ * distinguishable. A sandbox that quietly does nothing when it is misconfigured is the failure this
+ * whole chain keeps producing: work that completes, reports success and changes nothing.
+ */
+
+const { isHoneVar } = require('./untrusted-code-env');
+
+/** Why a declared sandbox could not be used. A refusal names the fix; a stand-down is not an error. */
+const SANDBOX_REFUSAL = Object.freeze({
+  NO_PROBE: 'no_probe',
+  NO_RESET: 'no_reset',
+  // HC-GF-192: the sandbox was seeded and nothing could read it.
+  NO_TEST_COMMAND: 'no_test_command',
+  NO_ENV: 'no_env',
+  // HC-GF-269: a published name Hone withholds from every command that runs the patch.
+  RESERVED_ENV: 'reserved_env',
+});
+
+/**
+ * Read the adopter's probe command output into the evidence `assertScratchTarget` demands.
+ *
+ * Accepts `<database>|<rows>` (what `psql -tAc` gives) or a JSON object (what a `jq` pipeline or a
+ * custom script gives). Anything else THROWS. It must never return a partial object: a shape like
+ * `{rows: 0}` with no database, or `{database}` with no count, reads downstream as an empty scratch
+ * database and turns "the probe failed" into "the target is safe to write" — the exact laundering
+ * HC-GF-169's guard exists to refuse.
+ *
+ * @param {string} stdout
+ * @returns {{database: string, rows: number}}
+ * @throws when the output is absent, malformed, or missing either field
+ */
+function parseProbeOutput(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) {
+    throw new Error('sandbox probe produced no output — refusing to treat the target as scratch. '
+      + '"Could not check" is not "checked and found nothing".');
+  }
+  const text = stdout.trim();
+
+  let database = null;
+  let rows = null;
+
+  if (text.startsWith('{')) {
+    let obj;
+    try { obj = JSON.parse(text); } catch {
+      throw new Error(`sandbox probe emitted unparseable JSON: ${text.slice(0, 120)}`);
+    }
+    database = typeof obj.database === 'string' ? obj.database.trim() : null;
+    rows = typeof obj.rows === 'number' && Number.isFinite(obj.rows) ? obj.rows : null;
+  } else {
+    // The LAST non-empty line: psql and friends prepend notices, and the reading is the result.
+    const line = text.split('\n').map(l => l.trim()).filter(Boolean).pop() || '';
+    const parts = line.split('|').map(s => s.trim());
+    if (parts.length === 2) {
+      database = parts[0] || null;
+      // A REAL number. `Number('')` is 0 and `Number('abc')` is NaN; only digits count, because a
+      // probe that printed nothing for the count must not read as an empty table.
+      rows = /^\d+$/.test(parts[1]) ? Number(parts[1]) : null;
+    }
+  }
+
+  if (!database) {
+    throw new Error(`sandbox probe reported no database name (got: ${String(stdout).slice(0, 120)}). `
+      + 'The name must come from the server, e.g. SELECT current_database().');
+  }
+  if (rows === null) {
+    throw new Error(`sandbox probe reported no row count (got: ${String(stdout).slice(0, 120)}). `
+      + 'A name match alone is not proof — a restored copy of production can carry the scratch name.');
+  }
+  return { database, rows };
+}
+
+/**
+ * Decide whether this run touches the adopter's datastore, and with what.
+ *
+ * @param {{sandbox: object|null, axes?: string[], capability?: string|null}} input
+ * @returns {{engage: boolean, refuse: string|null, reason: string,
+ *            commands: string[], reset: string|null, probe: string|null, verify: object|null}}
+ */
+
+/**
+ * A mapping of variable name to string value, or null when it is not one — HC-GF-192.
+ *
+ * `env: DATABASE_URL=postgres://…` is the natural YAML mistake and parses as a STRING. Reading
+ * that leniently would engage the sandbox with nothing published and report success, which is the
+ * exact failure this story closes; so anything that is not a flat string map is refused by the
+ * caller rather than coerced.
+ */
+function plainStringMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof k !== 'string' || !k.trim()) return null;
+    if (typeof v !== 'string' && typeof v !== 'number') return null;
+    out[k] = String(v);
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+function planSandboxRun({ sandbox = null, axes = [], capability = null } = {}) {
+  // HC-GF-183: every path returns the SAME shape, `teardown` included. It was missing here, so a
+  // stand-down or refusal handed back `teardown: undefined` and any caller iterating it would
+  // throw — the CLI only escapes that by checking `engage` first. A plan whose fields depend on
+  // which branch produced it is a trap for the next consumer.
+  // HC-GF-192: `test` and `env` join the shape on EVERY path, for the reason HC-GF-183 gave when
+  // `teardown` did not: a plan whose fields depend on which branch produced it is a trap.
+  const stand = (reason) => ({ engage: false, refuse: null, reason, commands: [], reset: null, teardown: [], probe: null, verify: null, test: null, env: {}, controlEnv: null });
+  const deny = (refuse, reason) => ({ engage: false, refuse, reason, commands: [], reset: null, teardown: [], probe: null, verify: null, test: null, env: {}, controlEnv: null });
+
+  const stateful = Array.isArray(axes) && axes.includes('stateful');
+  if (!stateful) {
+    return stand('the story declares no stored state — the datastore is not touched');
+  }
+  if (!sandbox || typeof sandbox !== 'object') {
+    // HC-GF-173's note already says this at classification time. Repeating it here is deliberate:
+    // this is the moment the capability would have fired, and a silent no-op here is what taught
+    // adopters the feature does not exist.
+    return stand('the story needs stored state but no `sandbox:` block is declared in '
+      + '.pipeline-config.yml — declare one (create/migrate/reset plus a verify block) to have the '
+      + 'pipeline seed a scratch datastore instead of testing against whatever the machine holds');
+  }
+
+  const verify = sandbox.verify && typeof sandbox.verify === 'object' ? sandbox.verify : null;
+  const probe = verify && typeof verify.probe === 'string' && verify.probe.trim()
+    ? verify.probe.trim() : null;
+  if (!probe) {
+    return deny(SANDBOX_REFUSAL.NO_PROBE,
+      'the sandbox declares no `verify.probe` command, so the target can never be PROVEN scratch '
+      + 'and the guard would refuse every run. Add `verify.probe` — a command printing '
+      + '`<database>|<row count>` for the declared table, read from the live connection '
+      + '(e.g. SELECT current_database()), not from the connection string.');
+  }
+
+  const commands = ['create', 'migrate'].map(k => (typeof sandbox[k] === 'string' ? sandbox[k].trim() : ''))
+    .filter(Boolean);
+  const reset = typeof sandbox.reset === 'string' && sandbox.reset.trim() ? sandbox.reset.trim() : null;
+  if (commands.length > 0 && !reset) {
+    // Setting up without a teardown leaves seeded rows in the adopter's datastore after the run.
+    return deny(SANDBOX_REFUSAL.NO_RESET,
+      'the sandbox declares setup commands but no `reset`, so seeded rows would outlive the run. '
+      + 'Declare `reset` — a sandbox that is never cleaned is indistinguishable from a dirty database.');
+  }
+
+  // An EMPTY capabilities list means the sandbox covers everything. Reading it as an empty
+  // allow-list would make the feature inert for exactly the adopters who declared it most simply.
+  const caps = Array.isArray(sandbox.capabilities) ? sandbox.capabilities.filter(Boolean) : [];
+  if (capability && caps.length > 0 && !caps.includes(capability)) {
+    return stand(`the sandbox covers ${caps.join(', ')} and this story's capability is `
+      + `"${capability}" — standing down rather than seeding a datastore nobody said covers it`);
+  }
+
+  // HC-GF-183: the teardown is reset THEN create, not reset alone.
+  //
+  // Found by the first live run: `reset` tore the schema down, the probe reads a table in it, and
+  // the NEXT run refused with "could not prove the target is scratch" — self-inflicted, and
+  // invisible to every test because each drove one lifecycle in isolation. "Reset" already implies
+  // "back to a usable baseline"; it was the pipeline reading it as "destroy" that was wrong.
+  //
+  // `migrate` is deliberately NOT replayed: restoring the shape the probe needs is `create`, and
+  // re-running migrations here would double the slowest part of every teardown.
+  const create = typeof sandbox.create === 'string' && sandbox.create.trim() ? sandbox.create.trim() : null;
+  const teardown = [reset, create].filter(Boolean);
+
+  // HC-GF-192: WHO READS THE SANDBOX.
+  //
+  // Run 4f463e54 seeded `hone_sandbox` correctly and ran `make ci` against
+  // `hone_test_$(CHECKOUT_ID)`. The lifecycle was perfect and observed nothing. The row's proposed
+  // fix — publish the connection as the adopter's own TEST_DATABASE_URL — was refuted by
+  // measurement: `ensure-test-db.js` refuses any name outside `hone_test*`, and the suite
+  // TRUNCATEs, which would wipe the seed. The adopter's whole ci command was never the right
+  // consumer; a suite that manages its own database fights a seeded one, and mature suites do.
+  //
+  // So the sandbox declares the command that reads it and the environment that suite expects.
+  // Hone publishes one into the other, which is what makes the result PROVABLE instead of merely
+  // configured: the connection is one Hone set, not one an adopter promises is wired up.
+  const test = typeof sandbox.test === 'string' && sandbox.test.trim() ? sandbox.test.trim() : null;
+  const env = plainStringMap(sandbox.env);
+
+  if (!test) {
+    return deny(SANDBOX_REFUSAL.NO_TEST_COMMAND,
+      'the sandbox declares setup commands but no `test` command, so it would be created, seeded '
+      + 'and torn down with nothing reading it — which reports a clean verification for stored-state '
+      + 'behaviour that was never exercised. Add `test:` (the command that runs the story\'s '
+      + 'sandbox suite) plus `env:` (the variables that suite reads).');
+  }
+  if (!env) {
+    return deny(SANDBOX_REFUSAL.NO_ENV,
+      'the sandbox declares a `test` command but no usable `env` map of variable to value, so that '
+      + 'suite would run against whatever the machine happens to hold rather than the scratch '
+      + 'datastore just seeded — the condition the sandbox exists to remove. Add `env:` as a '
+      + 'mapping, e.g. `env: {DATABASE_URL: postgres://…}`.');
+  }
+  // HC-GF-269: `HONE_*` is withheld from every command that runs the patch, so a published name in
+  // it would be announced and then never arrive — the real run and the control identical, and the
+  // verdict blaming the patch or the glob for a variable Hone removed. Refuse it by name instead.
+  const reserved = Object.keys(env).filter(isHoneVar);
+  if (reserved.length) {
+    return deny(SANDBOX_REFUSAL.RESERVED_ENV,
+      `the sandbox publishes ${reserved.join(', ')}, but \`HONE_*\` is Hone's own namespace and is `
+      + 'withheld from every command that runs the patch, so the sandbox suite would never see it. '
+      + 'Rename the variable, and read the new name in the suite.');
+  }
+
+  return {
+    engage: true,
+    refuse: null,
+    reason: `seeding the declared sandbox (${verify.database}) before the tests run`,
+    // `reset` stays exposed so nothing reading the field HC-GF-171 shipped changes meaning.
+    commands, reset, teardown, probe, verify, test, env, controlEnv: controlEnvFor(env),
+  };
+}
+
+
+/**
+ * What the guard PROVED, in one line — HC-GF-190.
+ *
+ * `assertScratchTarget` throws on refusal and returns nothing on success, so a passing guard was
+ * silent. Run 6be117b3's output showed the seed, the suite and the teardown, and HC-GF-185's
+ * acceptance — "a real run's output shows the probe, the guard verdict and the teardown" — stayed
+ * open on a run where all three HAD happened. That they ran was an inference from the seed loop
+ * being unreachable otherwise, and an inference is not evidence.
+ *
+ * READS THE PROBE, NOT THE DECLARATION. Echoing `verify.database` would print the same line
+ * whether the guard checked anything or not, which is the false-verified this chain exists to
+ * refuse (HC-GF-169). The name here is the one the SERVER returned.
+ *
+ * @param {{database: string, table: string, max_rows: number}} verify what the adopter declared
+ * @param {{database: string, rows: number}} probe what the live connection reported
+ * @returns {string}
+ */
+function describeProbeResult(verify, probe) {
+  const db = probe && probe.database ? String(probe.database) : '(no database reported)';
+  const rows = probe && Number.isFinite(probe.rows) ? probe.rows : '?';
+  const table = verify && verify.table ? verify.table : 'the verify table';
+  const cap = verify && Number.isFinite(Number(verify.max_rows)) ? Number(verify.max_rows) : '?';
+  return `guard ok — the live connection reports ${db}, holding ${rows} of at most ${cap} `
+    + `row(s) in ${table}`;
+}
+
+/**
+ * The fourth outcome: the sandbox was never asked — HC-GF-190.
+ *
+ * The contract at the top of this file promises engage, stand-down or refusal, "and the three are
+ * distinguishable". That holds inside the planner. It does not hold for a RUN: `verify-patch`
+ * exits on `no_diff` before `planSandboxRun` is ever called, so a stateful story with a declared
+ * sandbox can produce none of the three and say nothing about it. Run 2a9b2af5 did exactly that,
+ * and its verdict is indistinguishable from an ordinary empty build.
+ *
+ * Returns null when there is nothing to report — a plan that was never going to engage has not
+ * been skipped, and a line printed on every run is one nobody reads. A REFUSAL returns null too:
+ * it has already said more, and naming it again as merely "not reached" reads as a second, vaguer
+ * problem.
+ *
+ * @param {{engage: boolean, refuse: string|null, verify: object|null}} plan
+ * @returns {string|null}
+ */
+function describeNotReached(plan) {
+  // `engage` alone is the condition. An earlier draft also tested `plan.refuse`, which reads like
+  // a second case and is unreachable: a refusal always carries `engage: false`, so the clause
+  // could never change the outcome. Mutation found it — removing it left the suite green, which
+  // is the definition of a guard that does nothing.
+  if (!plan || !plan.engage) return null;
+  const db = plan.verify && plan.verify.database ? plan.verify.database : 'the declared sandbox';
+  return `sandbox NOT reached — ${db} would have been seeded for this story, and the run ended `
+    + 'before it was asked. Nothing was written to it, and nothing about stored-state behaviour '
+    + 'was verified.';
+}
+
+
+/**
+ * A value that cannot resolve to anything real — HC-GF-193.
+ *
+ * Deliberately not a URL, not a host, and not a path: the control must fail for every variable it
+ * replaces, and a value that accidentally WORKS proves the opposite of what the control claims.
+ */
+const CONTROL_VALUE = 'hone-sandbox-control-this-must-not-resolve';
+
+/**
+ * The published environment, broken on purpose — HC-GF-193.
+ *
+ * Run 6be117b3's first attempt declared `node --test tests/sandbox/*.test.js`, the worktree was
+ * built from HEAD, `tests/sandbox/` was not yet committed, and the glob matched nothing. That
+ * exits 0 — `tests 0 / pass 0 / fail 0` — so the sandbox was created, seeded, declared verified
+ * and torn down having observed nothing at all.
+ *
+ * The row's first idea was to establish that the command "had files to execute". Hone cannot know
+ * that: the command is an arbitrary shell string and `npm run test:sandbox` names no paths. What
+ * Hone DOES control is the environment it published, so the check is a negative control — run the
+ * suite again with every published value replaced, and require it to FAIL. A suite that still
+ * passes is not reading what we published, whether because it ran no tests, because its tests
+ * never touch the datastore, or because it is pointed somewhere else.
+ *
+ * EVERY variable is replaced, not a guessed subset: Hone cannot know which one carries the
+ * connection. And each is replaced rather than UNSET, because an absent variable lets a suite fall
+ * back to a default that may well work — which would pass the control while observing nothing,
+ * reintroducing the defect through the check meant to catch it.
+ *
+ * @param {object|null} env the published map
+ * @returns {object|null} the same keys with unusable values, or null when nothing was published
+ */
+function controlEnvFor(env) {
+  if (!env || typeof env !== 'object') return null;
+  const keys = Object.keys(env);
+  if (keys.length === 0) return null;
+  const out = {};
+  for (const k of keys) out[k] = CONTROL_VALUE;
+  return out;
+}
+
+/**
+ * What the two runs of the sandbox suite mean together — HC-GF-193.
+ *
+ * Kept separate from the CLI so the decision is testable and mutable, and so the two failure kinds
+ * stay distinguishable: a RED suite sends the operator to the code, a suite that observes nothing
+ * sends them to the suite or its wiring. Collapsing them sends them to the wrong place.
+ *
+ * The control is only consulted when the real run PASSED. A red suite is already a failure, and
+ * re-running it with a broken environment spends the timeout to learn nothing.
+ *
+ * @param {{realStatus: number, controlStatus: number}} input
+ * @returns {{ok: boolean, kind: string|null, detail: string|null}}
+ */
+function sandboxSuiteVerdict({ realStatus, controlStatus } = {}) {
+  if (realStatus !== 0) {
+    return { ok: false, kind: 'sandbox_tests_failed', detail: 'the sandbox suite failed' };
+  }
+  if (controlStatus === 0) {
+    return {
+      ok: false,
+      kind: 'sandbox_tests_not_observing',
+      detail: 'the sandbox suite PASSED with every published variable replaced by an unusable '
+        + 'value, so it is not reading the sandbox at all. The usual cause is that it ran ZERO '
+        + 'tests — a glob that matched nothing, a renamed directory, or files that exist locally '
+        + 'but are not in the commit this worktree was built from. It can also mean the tests run '
+        + 'but never touch the datastore. Either way nothing about stored-state behaviour was '
+        + 'verified, whatever the exit status said.',
+    };
+  }
+  return { ok: true, kind: null, detail: null };
+}
+
+module.exports = { parseProbeOutput, planSandboxRun, SANDBOX_REFUSAL,
+  describeProbeResult, describeNotReached, controlEnvFor, sandboxSuiteVerdict, CONTROL_VALUE };

package/lib/schedule-cron.js

@@ -6,7 +6,7 @@
  * UTC) almost always want Night Shift mode (--overnight) because a
  * 2 AM run is by definition an overnight batch. Pre-HC-054f the CLI
  * never passed --overnight to queue-stories so the scheduled workflow
- * silently ran without auto-approve / longer timeouts / 25-story cap.
+ * silently ran without the longer timeouts and the 25-story cap.
  *
  * **Timezone — load-bearing**: GitHub Actions cron runs in **UTC** by
  * default. This helper analyzes the cron's hour field AS UTC. It does

package/lib/skill-assertions.js

@@ -5,7 +5,7 @@
  *
  * Story 1 ships the ENGINE only. Story 2 (CLI command + Code Reviewer
  * agent prompt) is gated on ≥2 real skills authoring `## Assertions`
- * blocks OR OptionsFlow E29-G design landing.
+ * blocks OR OptionsFlow E29-G design landing. (Story 2 shipped as SA-002.)
  *
  * Why ship the engine first (LC-001-L1 pattern): the assertion shape
  * needs to soak against real skill-author intent before the runtime
@@ -20,15 +20,23 @@
  *   version: 1
  *   assertions:
  *     - id: ERR-001
- *       severity: BLOCKER          # advisory; no escalation logic in v1
+ *       severity: BLOCKER          # fails `hone step-5b` (HC-GF-227); WARN/INFO do not
  *       description: "console.log forbidden in src/"
  *       applies_to: "^src/"        # regex matched against file paths
  *       forbid_added: "console\\.log"  # regex matched against added lines
  *   ```
  *   ```
  *
- * E29-G may later define a richer DSL; v1 stays parseable so existing
- * skill assertions keep working until adopters explicitly migrate.
+ * HC-GF-310 adds a second rule kind, still `version: 1` (additive — every v1 block still parses):
+ *   ```yaml
+ *     - id: REPLAY-DECLARED
+ *       severity: BLOCKER
+ *       applies_to: "^src/parsers/"            # a changed file here triggers the rule
+ *       require_commit_line: "^REPLAY: \\S"   # some line of the branch's commit messages must match
+ *   ```
+ * `forbid_added` judges the DIFF; `require_commit_line` judges what the change SAYS about itself,
+ * which no diff line can carry. An assertion has exactly one of the two. When the caller cannot
+ * supply the commit messages, the rule is reported as a warning, never as a pass or a finding.
  *
  * Pure helper — no fs / child_process imports. Caller injects:
  *   - parseAssertions(skillMarkdown) → { version, assertions, warnings }
@@ -41,7 +49,7 @@ const yaml = require('js-yaml');
 const ASSERTION_VERSION = 1;
 const ASSERTIONS_HEADING_RE = /^##\s+Assertions\s*$/m;
 
-/** Severity labels. v1 carries them through findings; no escalation logic. */
+/** Severity labels. The engine only carries them; `hone step-5b` fails on BLOCKER (HC-GF-227). */
 const SEVERITY = Object.freeze({
   BLOCKER: 'BLOCKER',
   WARN:    'WARN',
@@ -113,13 +121,23 @@ function parseAssertions(skillMarkdown) {
     const severity = (typeof raw.severity === 'string' && VALID_SEVERITIES.has(raw.severity)) ? raw.severity : SEVERITY.WARN;
     const appliesToSrc = typeof raw.applies_to === 'string' ? raw.applies_to : null;
     const forbidAddedSrc = typeof raw.forbid_added === 'string' ? raw.forbid_added : null;
+    const requireCommitLineSrc = typeof raw.require_commit_line === 'string' ? raw.require_commit_line : null;
 
     if (!id) {
       out.warnings.push({ kind: 'assertion_missing_id', message: `assertions[${i}] missing required field 'id'` });
       continue;
     }
-    if (!forbidAddedSrc) {
-      out.warnings.push({ kind: 'assertion_missing_pattern', message: `assertion ${id} missing required field 'forbid_added'` });
+    if (!forbidAddedSrc && !requireCommitLineSrc) {
+      out.warnings.push({ kind: 'assertion_missing_pattern', message: `assertion ${id} missing required field 'forbid_added' or 'require_commit_line'` });
+      continue;
+    }
+    if (forbidAddedSrc && requireCommitLineSrc) {
+      out.warnings.push({ kind: 'assertion_two_patterns', message: `assertion ${id} sets both 'forbid_added' and 'require_commit_line'; use one rule per assertion` });
+      continue;
+    }
+    if (requireCommitLineSrc && !appliesToSrc) {
+      // Without a path scope the rule would demand the line of every change in the repository.
+      out.warnings.push({ kind: 'assertion_missing_scope', message: `assertion ${id}: 'require_commit_line' needs 'applies_to'` });
       continue;
     }
 
@@ -132,6 +150,18 @@ function parseAssertions(skillMarkdown) {
       }
     }
 
+    if (requireCommitLineSrc) {
+      let requireCommitLine;
+      // `m`: the pattern is judged per line, so `^` and `$` mean a line of a commit message.
+      try { requireCommitLine = new RegExp(requireCommitLineSrc, 'm'); }
+      catch (e) {
+        out.warnings.push({ kind: 'invalid_require_commit_line', message: `assertion ${id}: invalid require_commit_line regex — ${e.message}` });
+        continue;
+      }
+      out.assertions.push({ id, severity, description, appliesTo, appliesToSrc, requireCommitLine, requireCommitLineSrc });
+      continue;
+    }
+
     let forbidAdded;
     try { forbidAdded = new RegExp(forbidAddedSrc); }
     catch (e) {
@@ -159,6 +189,8 @@ function parseAssertions(skillMarkdown) {
  * @param {string} opts.diff - unified diff text (output of `git diff origin/develop...HEAD`)
  * @param {Array<{id: string, content: string}>} opts.skills - skill objects with markdown content
  * @param {string[]} [opts.referencedSkills] - if provided, only these skills are evaluated
+ * @param {string} [opts.commitMessages] - the branch's commit messages, for `require_commit_line`.
+ *        Absent means "could not read them": those rules then warn instead of judging.
  * @returns {{ findings: Finding[], scannedSkills: string[], skipped: Skip[], warnings: Warning[] }}
  */
 function runAssertions(opts = {}) {
@@ -194,6 +226,28 @@ function runAssertions(opts = {}) {
     scannedSkills.push(skillId);
 
     for (const a of parsed.assertions) {
+      if (a.requireCommitLine) {
+        const triggered = [...filesAddedLines.keys()].filter((f) => a.appliesTo.test(f));
+        if (triggered.length === 0) continue;
+        if (typeof opts.commitMessages !== 'string') {
+          warnings.push({ skillId, kind: 'commit_messages_unavailable',
+            message: `assertion ${a.id}: ${triggered.length} file(s) in scope changed but the commit messages were not supplied — not judged` });
+          continue;
+        }
+        if (a.requireCommitLine.test(opts.commitMessages)) continue;
+        findings.push({
+          skillId,
+          assertionId: a.id,
+          severity: a.severity,
+          description: a.description,
+          matchedFile: triggered[0],
+          matchedLine: null,
+          matchedText: `${triggered.length} file(s) in scope changed; no commit message line matches /${a.requireCommitLineSrc}/`,
+          requireCommitLineSrc: a.requireCommitLineSrc,
+          appliesToSrc: a.appliesToSrc,
+        });
+        continue;
+      }
       for (const [filePath, addedLines] of filesAddedLines) {
         if (a.appliesTo && !a.appliesTo.test(filePath)) continue;
         for (const { lineNumber, text } of addedLines) {

package/lib/skill-audit-render.js

@@ -55,7 +55,7 @@ function renderStep5bArtifact(opts = {}) {
   lines.push(`> Branch: \`${branchName}\` vs \`${baseBranch}\``);
   lines.push(`> Generated: ${generatedAt}`);
   lines.push(`> Engine: \`cli/lib/skill-assertions.js\` (SA-001 v1)`);
-  lines.push(`> Gating: **informational only** — exit-code-0 by contract; severity-to-gate mapping deferred to OptionsFlow E29-G.`);
+  lines.push(`> Gating: a BLOCKER finding fails \`hone step-5b\` (exit 2) and \`hone verify-pr\` (exit 5); WARN and INFO are informational (HC-GF-227).`);
   lines.push('');
 
   // ─── Marker 1: ^## Skill audit (canonical heading) ───

package/lib/story-classifier-extract.js

@@ -11,18 +11,23 @@
  *
  * Pure-helper-with-injected-IO style:
  *   - Extractors take parsed inputs (labels array, body string, etc.)
- *   - The git-log query is the one extractor that needs the repo path,
- *     and shells out to git via execSync — same pattern as
- *     cli/lib/git-helpers.js.
+ *   - The git-log query is the one extractor that needs the repo path.
+ *     It runs git with an argument array, never a shell string — same
+ *     pattern as cli/lib/git-helpers.js (HC-GF-097-followup-2).
  *
  * Issue: user-request 2026-05-05 SC-002. Builds on SC-001's classifyStory().
  */
 
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const { gitEnv } = require('./git-env');
 const fs = require('node:fs');
 const path = require('node:path');
 
+// HC-GF-097-followup-2: `hone queue-stories` reaches this for up to 50 stories per batch, so
+// one git that never returns must not hang the batch. A timeout throws, which reads as "no
+// overlap" like any other git failure below.
+const GIT_LOG_TIMEOUT_MS = 10_000;
+
 // ── Label-to-type canonical mapping ──
 // First-match-wins per label-array order.
 const LABEL_TO_TYPE = Object.freeze({
@@ -180,13 +185,16 @@ function extractRecentlyModifiedOverlap(repoRoot, touchedFiles, windowDays) {
     const abs = path.join(repoRoot, rel);
     if (!fs.existsSync(abs)) continue;
     try {
-      const out = execSync(
-        `git log --since="${w} days ago" --format=%H -- ${JSON.stringify(rel)}`,
-        { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+      // HC-GF-097-followup-2: argv, not a shell string. `rel` is a tracked file's name, and
+      // double quotes do not stop `$(...)` or backticks: a file named `a$(touch x).js` ran
+      // `touch x` on the operator's machine, and in the nightly queue job, beside HONE_TOKEN.
+      const out = execFileSync(
+        'git', ['log', `--since=${w} days ago`, '--format=%H', '--', rel],
+        { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_LOG_TIMEOUT_MS }
       ).trim();
       if (out) return true;
     } catch {
-      // Git unavailable / not a repo — silently continue
+      // Git unavailable / not a repo / timed out — silently continue
     }
   }
   return false;