@hone-ai/cli 1.38.1 → 1.40.0

package/lib/required-checks.js

@@ -0,0 +1,354 @@
+'use strict';
+/**
+ * HC-GF-348 — the status checks `hone setup` requires are READ from the repository's own workflows.
+ *
+ * Setup used to require `ai-code-review` on every repository. No workflow Hone serves reports a check
+ * by that name (the served reviewer job is `ai-review`, with no `name:`), and since HC-GF-337g that job
+ * runs only on `--ai-reviewer`. A required check that never reports leaves every PR waiting, and
+ * `enforce_admins: true` stops admins merging around it. So the name is now taken from the installed
+ * workflow, and required only when that workflow will run the job.
+ *
+ * GitHub names an Actions check after the job: its job-level `name:` if it has one, else its key.
+ * The parser below reads exactly that and nothing else. Two near-misses it must reject:
+ *   - the workflow's top-level `name:` (column 0) — that names the workflow, not a check;
+ *   - a step's `- name:` (deeper, behind a dash) — that names a step.
+ * A `name:` built from an expression (`${{ matrix.x }}`) is returned as written. GitHub reports the
+ * evaluated value, and a job with a `strategy:` reports one check per matrix leg (`ai-review (x)`),
+ * never its bare name. Neither can be REQUIRED (it would never report — the failure this module
+ * exists to prevent), so requiredChecksForSetup requires nothing for such a reviewer job. For the
+ * prune they are harmless: such a name never equals the legacy one.
+ *
+ * No YAML library: the CLI bundles none, and reviewer-optin.js reads this same file with a regex.
+ *
+ * Exports
+ *   workflowCheckNames(text)        → string[]  the check names a workflow's jobs report
+ *   reviewerCheckName(text)         → string|null  the name the `ai-review` job reports
+ *   requiredChecksForSetup({...})   → string[]  what setup requires: the reviewer check only when it runs
+ *   reportedChecksInDir(dir)        → string[]|null  every name reported under dir; null = could not tell
+ */
+
+const REVIEWER_JOB_KEY = 'ai-review';
+const SECURITY_SCAN_JOB_KEY = 'security-scan';
+
+function unquote(v) {
+  let s = String(v).replace(/\s+#.*$/, '').trim();
+  if (s.length >= 2 && ((s[0] === '"' && s.endsWith('"')) || (s[0] === "'" && s.endsWith("'")))) {
+    s = s.slice(1, -1);
+  }
+  return s;
+}
+
+/** [{ key, name, matrix }] for each job in the workflow's top-level `jobs:` block; name is null without one. */
+function workflowJobs(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^jobs:\s*(#.*)?$/.test(l));
+  if (start < 0) return [];
+  const jobs = [];
+  let jobIndent = null;   // the column job keys sit at
+  let propIndent = null;  // the column the current job's own properties sit at
+  let current = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;                       // the next top-level key ends `jobs:`
+    if (jobIndent == null) jobIndent = indent;
+    if (indent <= jobIndent) {
+      const m = /^ *([A-Za-z0-9_-]+):\s*(#.*)?$/.exec(line);
+      current = m && indent === jobIndent ? { key: m[1], name: null, matrix: false, reusable: false } : null;
+      if (current) jobs.push(current);
+      propIndent = null;
+      continue;
+    }
+    if (!current) continue;
+    if (propIndent == null) propIndent = indent;
+    // Only the job's own properties count; anything deeper (steps, with:, env:) is not its name.
+    if (indent !== propIndent) continue;
+    if (/^ *strategy:/.test(line)) current.matrix = true;
+    // A job that calls a reusable workflow reports as `caller / callee`, never its own name.
+    if (/^ *uses:/.test(line)) current.reusable = true;
+    const n = current.name == null && /^ *name:\s*(.+)$/.exec(line);
+    if (n) current.name = unquote(n[1]) || null;
+  }
+  return jobs;
+}
+
+function workflowCheckNames(text) {
+  return workflowJobs(text).map((j) => j.name || j.key);
+}
+
+function reviewerCheckName(text) {
+  const job = workflowJobs(text).find((j) => j.key === REVIEWER_JOB_KEY);
+  return job ? (job.name || job.key) : null;
+}
+
+// ── on: — does a workflow run on pull requests to a branch? (HC-GF-354) ────────────────────────────
+
+const PR_EVENTS = new Set(['pull_request', 'pull_request_target']);
+
+/** `[a, b]` or a bare scalar → list of unquoted items; null when it is neither (an anchor, a placeholder). */
+function flowList(v) {
+  const t = String(v).replace(/\s+#.*$/, '').trim();
+  if (!t) return null;
+  if (t.startsWith('[')) {
+    if (!t.endsWith(']')) return null;
+    const inner = t.slice(1, -1).trim();
+    return inner ? inner.split(',').map((x) => unquote(x)).filter(Boolean) : [];
+  }
+  if (/^[&*{|>]/.test(t)) return null;
+  return [unquote(t)];
+}
+
+/**
+ * The pull-request triggers of a workflow: [{ event, branches, branchesIgnore, types, unreadable }], each
+ * filter null when absent and 'unreadable' when present but not a list this parser can read
+ * (`{{BRANCHES}}` before setup substitutes it, an anchor, a nested mapping). `unreadable: true` marks a
+ * trigger with anything else that can skip a PR (`paths`, `paths-ignore`, an inline mapping). Reads
+ * `on: x`, `on: [x, y]` and the block form.
+ */
+function workflowPullRequestTriggers(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^["']?on["']?:/.test(l));
+  if (start < 0) return [];
+  const inline = lines[start].replace(/^["']?on["']?:/, '').replace(/\s+#.*$/, '').trim();
+  if (inline) {
+    const events = flowList(inline) || [];
+    return events.filter((e) => PR_EVENTS.has(e)).map((event) => ({ event, branches: null, branchesIgnore: null, types: null, unreadable: false }));
+  }
+  const out = [];
+  let eventIndent = null;
+  let current = null;   // the PR trigger being read
+  let pending = null;   // { key, indent } of a `branches:` whose list is on the lines below
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;
+    if (eventIndent == null) eventIndent = indent;
+    if (pending && indent >= pending.indent && /^ *- /.test(line)) {
+      const item = unquote(line.replace(/^ *- /, ''));
+      if (current[pending.key] === 'unreadable') continue;
+      if (!item || /^[&*{]/.test(item)) current[pending.key] = 'unreadable';
+      else current[pending.key].push(item);
+      continue;
+    }
+    if (pending && current[pending.key] && current[pending.key].length === 0) current[pending.key] = 'unreadable';
+    pending = null;
+    if (indent === eventIndent) {
+      const m = /^ *([A-Za-z_]+):\s*(.*)$/.exec(line);
+      current = m && PR_EVENTS.has(m[1]) ? { event: m[1], branches: null, branchesIgnore: null, types: null, unreadable: false } : null;
+      if (current) {
+        // `pull_request: { branches: [x] }`, an alias, any inline value: a filter not read here.
+        const v = m[2].replace(/\s+#.*$/, '').trim();
+        if (v && v !== 'null' && v !== '~') current.unreadable = true;
+        out.push(current);
+      }
+      continue;
+    }
+    if (!current) continue;
+    // A path filter skips some pull requests to the branch, so a check from it is not sure to report.
+    if (/^ *(paths|paths-ignore):/.test(line)) { current.unreadable = true; continue; }
+    const f = /^ *(branches|branches-ignore|types):\s*(.*)$/.exec(line);
+    if (!f) continue;
+    const key = { branches: 'branches', 'branches-ignore': 'branchesIgnore', types: 'types' }[f[1]];
+    const rest = f[2].replace(/\s+#.*$/, '').trim();
+    if (!rest) { current[key] = []; pending = { key, indent }; continue; }
+    current[key] = flowList(rest) || 'unreadable';
+  }
+  if (pending && current && current[pending.key] && current[pending.key].length === 0) current[pending.key] = 'unreadable';
+  return out;
+}
+
+/** GitHub's branch glob, as far as it is read here: `**` anything, `*` anything but `/`. 'unreadable' otherwise. */
+function branchMatchesPattern(pattern, branch) {
+  if (typeof pattern !== 'string' || !pattern || /[!?[\]+]/.test(pattern) || pattern.startsWith('/') || pattern.includes('{{')) {
+    return 'unreadable';
+  }
+  const re = pattern.replace(/[.^$()|\\{}]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*');
+  return new RegExp(`^${re}$`).test(branch);
+}
+
+function filterMatches(patterns, branch) {
+  const r = patterns.map((p) => branchMatchesPattern(p, branch));
+  if (r.includes('unreadable')) return 'unreadable';
+  return r.includes(true);
+}
+
+/**
+ * True only when the workflow is SURE to run on a pull request to `branch`. Anything it cannot read
+ * answers false: requiring nothing is safe, requiring a check that never reports holds every PR.
+ */
+function workflowTriggersPullRequestTo(text, branch) {
+  if (typeof branch !== 'string' || !branch) return false;
+  return workflowPullRequestTriggers(text).some((t) => {
+    if (t.unreadable || t.branches === 'unreadable' || t.branchesIgnore === 'unreadable' || t.types === 'unreadable') return false;
+    // Only a trigger that fires when a PR is opened AND when it is pushed to reports on every PR.
+    if (Array.isArray(t.types) && !(t.types.includes('opened') && t.types.includes('synchronize'))) return false;
+    if (t.branches && t.branchesIgnore) return false;   // GitHub rejects a workflow that sets both
+    if (t.branches) return filterMatches(t.branches, branch) === true;
+    if (t.branchesIgnore) return filterMatches(t.branchesIgnore, branch) === false;
+    return true;
+  });
+}
+
+// ── ci.required_checks in .pipeline-config.yml (HC-GF-352) ───────────────────────────────────────
+
+/** The names listed under `ci: required_checks:`, flow or block form; [] when absent. */
+function configuredRequiredChecks(configText) {
+  if (typeof configText !== 'string' || !configText) return [];
+  const lines = configText.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^ci:\s*(#.*)?$/.test(l));
+  if (start < 0) return [];
+  let keyIndent = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;
+    if (keyIndent == null) keyIndent = indent;
+    if (indent !== keyIndent) continue;
+    const m = /^ *required_checks:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const rest = m[1].replace(/\s+#.*$/, '').trim();
+    if (rest) return flowList(rest) || [];
+    const items = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (!l.trim() || /^\s*#/.test(l)) continue;
+      if (!/^ *- /.test(l) || l.match(/^ */)[0].length < keyIndent) break;
+      const v = unquote(l.replace(/^ *- /, ''));
+      if (v) items.push(v);
+    }
+    return items;
+  }
+  return [];
+}
+
+// ── what setup requires ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * [{ key, name }] for the jobs that report under ONE fixed name. Not a matrix job (one check per leg,
+ * `test (18)`), not a reusable-workflow call (`caller / callee`), not a name built from an expression.
+ * Requiring nothing is always safe; requiring a name that never reports holds every PR.
+ */
+function fixedJobs(text) {
+  return workflowJobs(text)
+    .filter((j) => !j.matrix && !j.reusable && !(j.name || j.key).includes('${{'))
+    .map((j) => ({ key: j.key, name: j.name || j.key }));
+}
+
+/** The fixed check name a served job reports, or null. */
+function fixedJobCheck(text, key) {
+  const job = fixedJobs(text).find((j) => j.key === key);
+  return job ? job.name : null;
+}
+
+/**
+ * What `hone setup` requires on the protected branch, and every candidate it left out with the reason.
+ *
+ * Candidates: the served reviewer check (only when the installed workflow runs that job — HC-GF-348),
+ * the served `security-scan` check (always — HC-GF-354), and the names in `ci.required_checks`
+ * (HC-GF-352). Each is required only if a workflow reports it under a fixed name and is sure to run on
+ * pull requests to `branch`. `branch` null (not known yet): no trigger test, nothing dropped for it.
+ *
+ * @returns {{ required: string[], dropped: Array<{ name: string, reason: string }> }}
+ */
+function requiredChecksPlan({
+  reviewerState, reviewerWorkflowText, workflowsDir, configText, branch = null,
+  fsImpl = require('fs'), pathImpl = require('path'),
+} = {}) {
+  const required = [];
+  const dropped = [];
+  const notOnBranch = `its workflow does not run on pull requests to \`${branch}\``;
+  const served = (name) => {
+    if (!name || required.includes(name)) return;
+    if (branch != null && !workflowTriggersPullRequestTo(reviewerWorkflowText, branch)) dropped.push({ name, reason: notOnBranch });
+    else required.push(name);
+  };
+  if (reviewerState === 'on' || reviewerState === 'legacy') served(fixedJobCheck(reviewerWorkflowText, REVIEWER_JOB_KEY));
+  served(fixedJobCheck(reviewerWorkflowText, SECURITY_SCAN_JOB_KEY));
+
+  const configured = configuredRequiredChecks(configText)
+    .filter((n) => !required.includes(n) && !dropped.some((d) => d.name === n));
+  if (configured.length) {
+    const files = reportedChecksByFileInDir(workflowsDir, { fsImpl, pathImpl });
+    for (const name of configured) {
+      if (files == null) { dropped.push({ name, reason: "the repository's workflows could not all be read" }); continue; }
+      const reporting = files.filter((f) => f.names.includes(name));
+      if (!reporting.length) { dropped.push({ name, reason: 'not reported by any workflow' }); continue; }
+      const fixed = reporting.filter((f) => fixedJobs(f.text).some((j) => j.name === name));
+      if (!fixed.length) {
+        dropped.push({ name, reason: 'its job reports per matrix leg or as a reusable-workflow call, never under this name' });
+        continue;
+      }
+      if (branch != null && !fixed.some((f) => workflowTriggersPullRequestTo(f.text, branch))) {
+        dropped.push({ name, reason: notOnBranch });
+        continue;
+      }
+      required.push(name);
+    }
+  }
+  return { required, dropped };
+}
+
+/**
+ * @param {{ reviewerState: 'on'|'off'|'legacy'|'absent', reviewerWorkflowText: string|null }} args
+ *   reviewerState is workflowReviewerState() (cli/lib/reviewer-optin.js) of the installed ai-review.yml.
+ */
+function requiredChecksForSetup(args = {}) {
+  return requiredChecksPlan(args).required;
+}
+
+/**
+ * [{ file, text, names }] for each workflow in `dir`. `[]` when there is no such directory. `null` when a
+ * workflow file exists but could not be read.
+ */
+function reportedChecksByFileInDir(dir, { fsImpl = require('fs'), pathImpl = require('path') } = {}) {
+  if (typeof dir !== 'string' || !dir) return [];
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir);
+  } catch (e) {
+    return e && (e.code === 'ENOENT' || e.code === 'ENOTDIR') ? [] : null;
+  }
+  const out = [];
+  for (const f of entries) {
+    if (!/\.ya?ml$/i.test(f)) continue;
+    let text;
+    try {
+      text = fsImpl.readFileSync(pathImpl.join(dir, f), 'utf8');
+    } catch {
+      return null;
+    }
+    out.push({ file: f, text, names: workflowCheckNames(text) });
+  }
+  return out;
+}
+
+/**
+ * Every check name the workflows in `dir` report. `[]` when there is no such directory (nothing reports
+ * anything). `null` when a workflow file exists but could not be read: the caller cannot tell what is
+ * reported, so it must not remove a required check on the strength of this answer.
+ */
+function reportedChecksInDir(dir, opts = {}) {
+  const files = reportedChecksByFileInDir(dir, opts);
+  if (files == null) return null;
+  return [...new Set(files.flatMap((f) => f.names))];
+}
+
+module.exports = {
+  workflowCheckNames,
+  reviewerCheckName,
+  requiredChecksForSetup,
+  requiredChecksPlan,
+  reportedChecksInDir,
+  reportedChecksByFileInDir,
+  workflowPullRequestTriggers,
+  workflowTriggersPullRequestTo,
+  branchMatchesPattern,
+  configuredRequiredChecks,
+  REVIEWER_JOB_KEY,
+  SECURITY_SCAN_JOB_KEY,
+};

package/lib/reviewer-optin.js

@@ -0,0 +1,115 @@
+'use strict';
+/**
+ * HC-GF-337g — the AI code reviewer is OPT-IN.
+ *
+ * `hone setup` used to install it in every adopter repository, where it runs in the adopter's CI
+ * on the adopter's own ANTHROPIC_API_KEY — so a repository that never chose it, and never set the
+ * key, got a red check on every PR. Now its scripts install only on `--ai-reviewer`, and the
+ * ai-review job runs only then. .github/workflows/ai-review.yml itself installs either way: its other
+ * gates (secret scan, tracker, metrics check, E2E healer) are not the reviewer's to take with it.
+ *
+ * Commander keeps the default `undefined` only because `--ai-reviewer` is declared BEFORE
+ * `--no-ai-reviewer` ("If you define --foo first, adding --no-foo does not change the default
+ * value"). Declared the other way round the default becomes `true`, and the always-install comes
+ * back with nothing in the diff to show it — which is why the decision is `=== true` here, and why
+ * tests/regression/hc-gf-337g-reviewer-optin-default.test.js runs the real CLI with no flag.
+ *
+ * Pure: no I/O, so it is unit-testable without the CLI.
+ */
+
+/** True only for an explicit `--ai-reviewer`. No flag, `--no-ai-reviewer`, or no opts at all: false. */
+function shouldInstallReviewer(opts) {
+  return Boolean(opts) && opts.aiReviewer === true;
+}
+
+/**
+ * What an installed .github/workflows/ai-review.yml says about the reviewer job (HC-GF-337g):
+ * 'on' / 'off' (setup's AI_REVIEWER stamp), 'legacy' (written before the stamp existed — it runs the
+ * reviewer on every PR, red without a key) or 'absent' (no file; pass null).
+ */
+function workflowReviewerState(text) {
+  if (text == null) return 'absent';
+  const m = /AI_REVIEWER: "([^"]*)"/.exec(text);
+  if (!m) return 'legacy';
+  return m[1] === 'true' ? 'on' : 'off';
+}
+
+/**
+ * What the operator is told once the setup script has run.
+ *
+ * @param {boolean} installed        the reviewer script is now in the repository (with dryRun: would be)
+ * @param {{ requested?: boolean, alreadyPresent?: boolean, dryRun?: boolean, workflow?: string }} [ctx]
+ *   requested:      `--ai-reviewer` was passed (so `installed: false` means the download failed)
+ *   alreadyPresent: the repository already has .github/workflows/ai-review.yml from an earlier setup
+ *   dryRun:         `--dry-run` — nothing was written, so nothing may be reported as installed
+ *   workflow:       workflowReviewerState() of the repository's ai-review.yml after the script ran (before,
+ *                   on a dry run). An existing workflow is never regenerated, so an install is claimed only
+ *                   when the workflow actually runs the job.
+ * @returns {string} one or more lines, no trailing newline
+ */
+function reviewerNotice(installed, { requested = false, alreadyPresent = false, dryRun = false, workflow } = {}) {
+  const LEGACY = [
+    '    .github/workflows/ai-review.yml predates the opt-in and was kept: it runs the reviewer on every PR,',
+    '    red without ANTHROPIC_API_KEY. Delete it and re-run `hone setup --ai-reviewer` to get the version that',
+    '    skips without a key.',
+  ];
+  // Unknown workflow state (a caller that did not read it): the reviewer side assumes the job is on.
+  const wf = workflow || 'on';
+  if (installed && dryRun) {
+    if (wf === 'legacy') {
+      return ['  DRY-RUN: would install the AI reviewer scripts, but not the job that skips without a key:', ...LEGACY].join('\n');
+    }
+    return [
+      '  DRY-RUN: would install the AI code reviewer (the ai-review job of .github/workflows/ai-review.yml).',
+      '    It runs in your CI on YOUR OWN key: add ANTHROPIC_API_KEY as a repository secret.',
+    ].join('\n');
+  }
+  if (installed && wf === 'legacy') {
+    return ['  ⚠ AI reviewer scripts installed, but not the job that skips without a key:', ...LEGACY].join('\n');
+  }
+  if (installed && wf !== 'on') {
+    return [
+      `  ⚠ AI reviewer scripts installed, but .github/workflows/ai-review.yml ${wf === 'off' ? 'has the reviewer stamped off' : 'is missing'},`,
+      '    so the ai-review job will not run. Delete .github/workflows/ai-review.yml (if present) and re-run',
+      '    `hone setup --ai-reviewer`.',
+    ].join('\n');
+  }
+  if (installed) {
+    return [
+      '  ✓ AI code reviewer installed (the ai-review job of .github/workflows/ai-review.yml).',
+      '    It runs in your CI on YOUR OWN key: add ANTHROPIC_API_KEY as a repository secret.',
+      '    Without it the job is skipped (grey, never blocks a merge). The H-019 learnings gate runs inside it.',
+    ].join('\n');
+  }
+  const lines = requested
+    ? ['  ⚠ AI code reviewer requested (--ai-reviewer) but NOT installed — its download failed or setup did not write it. Re-run setup to retry.']
+    : ['  ℹ AI code reviewer not installed (opt-in: hone setup --ai-reviewer).'];
+  // What is said about the workflow's OTHER gates is read from the workflow too (re-review step_5): it is
+  // never claimed for a workflow that did not arrive, predates the opt-in, or still has the job on.
+  if (workflow === 'absent') {
+    lines.push(
+      '  ⚠ .github/workflows/ai-review.yml is not installed either (its download failed), so its secret scan,',
+      '    tracker and metrics check are missing too. Re-run setup to retry.',
+    );
+  } else if (workflow === 'legacy') {
+    lines.push('    .github/workflows/ai-review.yml predates the opt-in and was kept: delete it and re-run setup to get the version whose ai-review job runs only when chosen.');
+  } else if (workflow === 'on') {
+    lines.push('    .github/workflows/ai-review.yml was kept with the ai-review job switched on by an earlier setup; setup never switches it off.');
+  } else {
+    lines.push('    .github/workflows/ai-review.yml is installed either way: its secret scan, tracker and metrics check run; its ai-review job is skipped.');
+  }
+  lines.push(
+    '    It needs your own ANTHROPIC_API_KEY repository secret, and it carries the H-019 learnings gate:',
+    '    without the reviewer, the learnings gate is not installed either.',
+  );
+  if (alreadyPresent) {
+    lines.push(
+      '  ⚠ .github/scripts/ai-reviewer.js is still here from an earlier setup and was left in place, and an',
+      '    existing .github/workflows/ai-review.yml is never regenerated. To opt out, delete both files and re-run',
+      '    setup; to keep the reviewer, re-run with --ai-reviewer.',
+    );
+  }
+  return lines.join('\n');
+}
+
+module.exports = { shouldInstallReviewer, reviewerNotice, workflowReviewerState };

package/lib/run-context.js

@@ -438,6 +438,10 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
   // JSON-lines repo).
   const bundle = { files: 0, chars: 0 };
   const includePaths = opts.includePaths || [];
+  // HC-GF-351: what the operator named, recorded on the run so follow-batch can carry it into a re-serve. Never
+  // inferred: the story's own paths and the defaults are re-derived whenever a story is resolved again.
+  const operatorPaths = parseIncludePaths(includePaths);
+  if (operatorPaths.length) config.include_paths = operatorPaths;
   const defaultIncludePaths = repoCtx.defaultIncludePaths || [];
   if (rawText || parseIncludePaths(includePaths).length > 0 || defaultIncludePaths.length > 0) {
     try {
@@ -576,6 +580,23 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
     pre.push(warn('    Fix: hone run-story <id> --include-paths path/one.js,path/two.js'));
   }
 
+  // ── Call sites (HC-GF-217) ────────────────────────────────────────────────────────────────
+  // The planner is told to enumerate every call site of a shared function it changes, and a server-executed
+  // agent has no checkout to search (cwd is a temp dir, deliberately). This CLI has the checkout: it searches for
+  // the compound identifiers the story puts in backticks and sends the result for the server to render. It runs
+  // whatever the classifier axes turn out to be, because the shared-chokepoint axis is harvested from step_0's
+  // output, after this bundle has been sent. Fail-soft: a search that cannot run costs the planner its
+  // enumeration (it then says so and pauses), never the queueing of the story.
+  if (rawText && typeof io.callSites === 'function') {
+    try {
+      const found = await io.callSites(rawText);
+      if (found && found.callSites) config.call_sites = found.callSites;
+      for (const n of (found && found.notes) || []) pre.push(n);
+    } catch (e) {
+      pre.push(warn(`  ⚠ call-site search failed (non-fatal): ${firstLine(e)} — the planner will have no call-site enumeration for this story`));
+    }
+  }
+
   // ── 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.

package/lib/security-scanner.js

@@ -14,13 +14,15 @@
 const SECRET_PATTERNS = [
   {
     id: 'hardcoded-secret-apikey',
-    pattern: /(?:api[_-]?key|apikey|api[_-]?secret)\s*[:=]\s*["']([A-Za-z0-9/+=]{20,})["']/i,
+    // HC-GF-364: `["']?` after the name reads a quoted key — JSON, a dict literal — as the served
+    // workflow's scan does since HC-GF-362.
+    pattern: /(?:api[_-]?key|apikey|api[_-]?secret)["']?\s*[:=]\s*["']([A-Za-z0-9/+=]{20,})["']/i,
     severity: 'HIGH',
     message: 'Hardcoded API key detected. Use environment variables instead.',
   },
   {
     id: 'hardcoded-secret-password',
-    pattern: /(?:password|passwd|pwd|secret|token)\s*[:=]\s*["']([A-Za-z0-9@#$%^&*!]{16,})["']/i,
+    pattern: /(?:password|passwd|pwd|secret|token)["']?\s*[:=]\s*["']([A-Za-z0-9@#$%^&*!]{16,})["']/i,
     severity: 'HIGH',
     message: 'Hardcoded password/secret detected. Use environment variables or a vault.',
   },
@@ -126,8 +128,9 @@ function scanFiles(opts = {}) {
 
       // Skip env var references (not hardcoded)
       if (/process\.env\.|os\.environ|System\.getenv|ENV\[/i.test(line)) continue;
-      // Skip comments
-      if (/^\s*(\/\/|#|--|\/\*|\*)/.test(line)) continue;
+      // Skip comments. `--` is a SQL comment; `-----BEGIN … PRIVATE KEY-----` is not (HC-GF-362: it was
+      // skipped as one, so the private-key rule never fired on a key at the start of a line).
+      if (/^\s*(\/\/|#|--(?!-)|\/\*|\*)/.test(line)) continue;
 
       for (const rule of rules) {
         if (rule.pattern.test(line)) {

package/lib/story-line.js

@@ -2,9 +2,15 @@
 /**
  * story-line.js — one line of a `hone queue-stories --file` list.
  *
- * `STORY-ID` or `STORY-ID depends:DEP1,DEP2`. The `depends:` token is case-sensitive and must come
- * after the storyId; multiple deps are comma-separated and whitespace tolerant. A line with no
- * `depends:` yields no `dependsOn` at all — the server validates absence differently from empty.
+ * `STORY-ID`, optionally followed by `depends:DEP1,DEP2` and/or `paths:a.js,b.js`, in either order. Both
+ * tokens are case-sensitive, must come after the storyId, and may each appear once; their lists are
+ * comma-separated and whitespace tolerant. A line with no `depends:` yields no `dependsOn` at all — the server
+ * validates absence differently from empty — and a line with no `paths:` yields no `paths`.
+ *
+ * `paths:` (HC-GF-351) is `run-story --include-paths` for one story of a batch: the files the bundler must put
+ * in that story's context. A batch cannot carry the flag, and `run-story` runs carry no batch id, so
+ * `follow-batch` cannot follow them. The entries are checked where `--include-paths` entries are, by the
+ * bundler (cli/lib/run-context.js), not here: this module only splits the line.
  *
  * Extracted by HC-GF-140 stage 2. The regex was pinned by its SOURCE TEXT
  * (`assert.match(cliSrc, /\^\(\\S\+\)\\s\+depends:\(\\S\+\)\\s\*\$/)`), which is the worst shape a
@@ -19,22 +25,52 @@ function isStoryLine(line) {
   return Boolean(t) && !t.startsWith('#');
 }
 
+const csv = (s) => s.split(',').map((x) => x.trim()).filter(Boolean);
+const unique = (list) => list.filter((x, i) => list.indexOf(x) === i);
+
 /**
  * @param {string} line
- * @returns {{storyId: string, dependsOn?: string[]}|{error: string}}
+ * @returns {{storyId: string, dependsOn?: string[], paths?: string[]}|{error: string}}
  *   `error` for a line the caller must reject — a storyId followed by anything unrecognised.
- *   Silently treating `STORY-A something` as `STORY-A` loses the operator's intent.
+ *   Silently treating `STORY-A something` as `STORY-A` loses the operator's intent. So does a
+ *   `paths:` that names no path: the operator meant to bundle something.
  */
 function parseStoryLine(line) {
   const t = String(line).trim();
-  const m = t.match(/^(\S+)\s+depends:(\S+)\s*$/);
-  if (m) {
-    return { storyId: m[1], dependsOn: m[2].split(',').map(s => s.trim()).filter(Boolean) };
+  const bad = { error: `Malformed line in --file: "${t}"` };
+  const [storyId, ...tokens] = t.split(/\s+/);
+  const out = { storyId };
+  for (const tok of tokens) {
+    if (tok.startsWith('depends:') && tok.length > 'depends:'.length && !('dependsOn' in out)) {
+      out.dependsOn = csv(tok.slice('depends:'.length));
+    } else if (tok.startsWith('paths:') && !('paths' in out)) {
+      const paths = unique(csv(tok.slice('paths:'.length)));
+      if (paths.length === 0) return bad;
+      out.paths = paths;
+    } else {
+      return bad;
+    }
   }
-  if (/\s/.test(t)) {
-    return { error: `Malformed line in --file: "${t}"` };
+  return out;
+}
+
+/**
+ * The line `parseStoryLine` reads back as the same story — for a caller that writes a stories file
+ * (follow-batch's re-serve). Throws on a value the line cannot carry, rather than writing a line that parses as
+ * something else: whitespace splits a token, and a comma splits a list.
+ * @param {{storyId: string, dependsOn?: string[], paths?: string[]}} story
+ */
+function formatStoryLine({ storyId, dependsOn, paths } = {}) {
+  const carries = (v) => typeof v === 'string' && v !== '' && !/[\s,]/.test(v);
+  if (!carries(storyId)) throw new TypeError(`formatStoryLine: ${JSON.stringify(storyId)} is not a story id a line can carry`);
+  const parts = [storyId];
+  for (const [token, list] of [['depends', dependsOn], ['paths', paths]]) {
+    if (!Array.isArray(list) || list.length === 0) continue;
+    const bad = list.find((v) => !carries(v));
+    if (bad !== undefined) throw new TypeError(`formatStoryLine: ${JSON.stringify(bad)} cannot be written in ${token}:`);
+    parts.push(`${token}:${list.join(',')}`);
   }
-  return { storyId: t };
+  return parts.join(' ');
 }
 
-module.exports = { parseStoryLine, isStoryLine };
+module.exports = { parseStoryLine, isStoryLine, formatStoryLine };