@hone-ai/cli 1.38.1 → 1.39.0

package/lib/classify-spec.js

@@ -0,0 +1,68 @@
+'use strict';
+/**
+ * classify-spec.js — how `hone tests organize` sorts an existing spec file: its type (browser, API,
+ * hybrid), its module, where it moves to, and whether it is a smoke candidate.
+ *
+ * HC-CI-019-followup-3: moved verbatim out of cli/hone-cli.js, which cannot be required (it parses
+ * argv on load), so a test can call it. Before the move no suite asserted any of its fields.
+ */
+const fs = require('fs');
+
+function classifySpec(file, repoRoot) {
+  let content = '';
+  try { content = fs.readFileSync(file.fullPath, 'utf8'); } catch { }
+
+  const hasPage = /page\.(goto|click|locator|fill|waitFor|getBy)/.test(content);
+  const hasRequest = /request\.(get|post|put|delete|patch)\(/.test(content);
+  const hasExpectResponse = /response\.(status|json|ok|body)/.test(content) ||
+                            /expect\(resp/.test(content);
+
+  // Detect type
+  let type = 'UNKNOWN';
+  if (hasPage && (hasRequest || hasExpectResponse)) type = 'HYBRID';
+  else if (hasPage) type = 'BROWSER';
+  else if (hasRequest || hasExpectResponse) type = 'API';
+  else if (/import.*playwright|from.*@playwright/.test(content)) type = 'BROWSER';
+  else if (/import.*supertest|from.*supertest/.test(content)) type = 'API';
+
+  // Detect module from filename or content
+  // Detect module — filename takes priority over content, most specific first
+  let module = 'general';
+  const name = file.name.toLowerCase();
+  const contentLower = content.toLowerCase();
+
+  // Pass 1: check filename (strongest signal)
+  if (/auth|login|signup|oauth|session/.test(name)) module = 'auth';
+  else if (/trade|order|execution/.test(name)) module = 'trading';
+  else if (/position|portfolio|pnl|p&l/.test(name)) module = 'portfolio';
+  else if (/alert|notification/.test(name)) module = 'alerts';
+  else if (/dashboard|widget|overview/.test(name)) module = 'dashboard';
+  else if (/scanner|scan|market/.test(name)) module = 'market';
+  else if (/setting|config|preference/.test(name)) module = 'settings';
+
+  // Pass 2: fallback to content (if filename didn't match)
+  if (module === 'general') {
+    if (/login|authenticate|sign.?in/.test(contentLower)) module = 'auth';
+    else if (/trading|order|execute/.test(contentLower)) module = 'trading';
+    else if (/portfolio/.test(contentLower)) module = 'portfolio';
+    else if (/alert|notification/.test(contentLower)) module = 'alerts';
+    else if (/dashboard/.test(contentLower)) module = 'dashboard';
+    else if (/market|scanner/.test(contentLower)) module = 'market';
+  }
+
+  // Determine destination
+  let destination;
+  if (type === 'API') {
+    destination = `e2e/api/${file.name}`;
+  } else {
+    destination = `e2e/regression/${module}/${file.name}`;
+  }
+
+  // Smoke candidate: login, auth, critical navigation, app loads
+  const smoke = /login|auth|app.load|critical|smoke|health/.test(name) ||
+                /login|authenticate/.test(contentLower);
+
+  return { ...file, type, module, destination, smoke };
+}
+
+module.exports = { classifySpec };

package/lib/context-reserve.js

@@ -0,0 +1,270 @@
+'use strict';
+/**
+ * context-reserve.js — HC-GF-351: serve the files a hard-paused run asked for, once, without a person.
+ *
+ * A step that cannot proceed for want of a file says so (HC-GF-263 records the paths it named), and a batch had
+ * nothing to serve them with. `follow-batch` now kills that run and queues its story again with those paths
+ * added to the story's line. This module is the part that decides WHETHER a request may be served and WHAT the
+ * line says. Pure: data in, data out. The loop's I/O is injected (cli/lib/batch-follow.js).
+ *
+ * THE TRUST BOUNDARY. The paths came out of an LLM artifact and the bundler reads each one and sends its contents
+ * to a model. An agent can be steered by the bundled source and the story text, so a request is a claim to check,
+ * not an instruction. A request is served only when EVERY path in it:
+ *   - passes hard-pause-remedy's token allowlist (the characters a shell could misread are refused outright),
+ *   - is a plain relative path: no `..`, nothing absolute, home-relative or option-like, no empty segment,
+ *   - is not a credential file or a hidden file or directory (`.env`, `*.pem`, `id_rsa*`, `.ssh/`, `.git/`),
+ *   - is a REGULAR FILE that git tracks in this checkout. A tracked symlink is refused: the bundler follows it,
+ *     so `notes.txt -> ~/.ssh/id_rsa` would be a tracked path that leaves the checkout.
+ *   - resolves, on the disk as it is NOW, to a path inside this checkout that passes the same rules. The index
+ *     says what git recorded; a file or a directory replaced by a symlink since is invisible to it, and the
+ *     bundler reads through the link (`realPath`, repoRealPath).
+ * The paths the story's own line carried (config.include_paths) are held to the same rules: any client of the org
+ * can write a run's config, so they are no more trusted than an agent's.
+ * One path that fails refuses the whole request, and so does a request the server cut off (`truncated`). A partly served request is a run that pauses again for what was
+ * left out, and the loop does not serve twice.
+ *
+ * Why not just "exists in the working tree": that includes untracked and ignored files, which is exactly where an
+ * `.env`, a local key or a scratch file with a pasted token lives. Tracked means a reviewer already sees it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { remedyFor, partitionSafePaths, tokenOf, isSafeToken } = require('./hard-pause-remedy');
+const { parseIncludeTarget } = require('./include-paths');
+const { isSecretPath } = require('./bundle-context');
+const { isBatchId } = require('./run-target');
+
+/** The start of the reason a re-served run is killed with. The loop reads it back to find the new batch. */
+const RESERVED_PREFIX = 're-served as batch ';
+
+/** What the kill reason says; `reservedBatchOf` reads it back. */
+function reserveReason(batchId, stepKey) {
+  return `${RESERVED_PREFIX}${batchId}: ${stepKey} named files it was not given`;
+}
+
+/**
+ * The batch a killed run was re-served as, or null. The kill is how the loop remembers, so a restart follows the
+ * new batch and does not serve the same story a second time.
+ * @param {object} run  a row of `GET /orchestrate/batch/:id` runs (untrusted shape)
+ */
+function reservedBatchOf(run) {
+  if (!run || run.status !== 'killed' || typeof run.errorMessage !== 'string') return null;
+  const m = run.errorMessage.match(/^re-served as batch (\S+?)(?::|\s|$)/);
+  return m && isBatchId(m[1]) ? m[1] : null;
+}
+
+/**
+ * The request a run is hard-paused on, or null. Scoped by hard-pause-remedy's reader to the run's CURRENT step,
+ * and the step the pause message names must be that step, so a request recorded on an earlier step that the run
+ * has since moved past is never served as if the current pause had asked for it.
+ * @param {object} run  a `GET /orchestrate/:runId` payload
+ * @returns {{stepKey: string, paths: object[], truncated: boolean}|null}
+ */
+function hardPauseRequest(run) {
+  if (!run || run.status !== 'paused' || typeof run.errorMessage !== 'string') return null;
+  const at = run.errorMessage.match(/^hard_pause at (\S+?)(?::|\s|$)/);
+  const remedy = at ? remedyFor(run) : null;
+  return remedy && remedy.stepKey === at[1] ? remedy : null;
+}
+
+// Credential-looking names the bundler's own refusal (isSecretPath) does not cover: a public half of a key pair,
+// key containers, anything the author named a secret or a credential.
+const SECRET_LOOKING = [/(^|[._-])id_(rsa|dsa|ecdsa|ed25519)/i, /\.(key|pfx|jks|keystore|p8)$/i, /(secret|credential)/i];
+
+/** Why a path is not a plain relative path, or null. `file` has no `:line` or `:symbol` suffix. */
+function structuralRefusal(file) {
+  if (typeof file !== 'string' || file === '') return 'empty';
+  if (/^[-/~]/.test(file)) return 'absolute, home-relative or option-like';
+  if (/[\\\0]/.test(file)) return 'not a plain relative path';
+  if (file.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'not a plain relative path';
+  return null;
+}
+
+/**
+ * Why the CONTENT of a path (a plain file path, no `:line`) must not be sent to a model, or null: the three
+ * rules that need no file list. HC-GF-217 reads this directly for the lines of a search result, so a search
+ * and a re-serve cannot disagree about what is withheld (they used to be one inline sequence in requestRefusal).
+ * @param {string} file
+ */
+function contentRefusal(file) {
+  const plain = structuralRefusal(file);
+  if (plain) return plain;
+  if (isSecretPath(file) || SECRET_LOOKING.some((re) => re.test(path.posix.basename(file)))) return 'looks like a credential file';
+  if (file.split('/').some((s) => s.startsWith('.'))) return 'a hidden file or directory';
+  return null;
+}
+
+/**
+ * Why a requested path (`file`, `file:line` or `file:symbol`) must not be served, or null.
+ * @param {string} token
+ * @param {Set<string>|null} tracked  the regular files git tracks here; null when they could not be listed
+ */
+function requestRefusal(token, tracked) {
+  const file = parseIncludeTarget(token).path;
+  const why = contentRefusal(file);
+  if (why) return why;
+  if (!(tracked instanceof Set)) return 'this checkout\'s tracked files could not be listed';
+  if (!tracked.has(file)) return 'not a regular file git tracks in this checkout';
+  return null;
+}
+
+/**
+ * May this request be served? All of it, or none of it.
+ * @param {{paths: object[], truncated?: boolean}} request  from hardPauseRequest
+ * @param {{tracked?: Set<string>|null, realPath?: ((file: string) => string|null)|null, original?: string[]}} [ctx]
+ *   `realPath`: where `file` resolves on the disk now, relative to the checkout, or null if outside it or unreadable;
+ *   without it nothing is served (a request is not checked on a disk nobody looked at). `original`: the entries of
+ *   the story's own line, judged by the same rules and written before what the step asked for.
+ * @returns {{ok: true, tokens: string[]}|{ok: false, reason: string}}
+ */
+function judgeRequest(request, { tracked = null, realPath = null, original = [] } = {}) {
+  if (request && request.truncated === true) {
+    return { ok: false, reason: 'the step asked for more paths than were recorded, and a part of a request pauses again; nothing was served' };
+  }
+  const { safe, dropped } = partitionSafePaths(request && request.paths);
+  const candidates = [...original.map((token) => ({ token, own: true })), ...safe.map((p) => ({ token: tokenOf(p) }))];
+  const tokens = [];
+  const refused = [];
+  for (const { token, own } of candidates) {
+    const why = requestRefusal(token, tracked) || resolutionRefusal(token, tracked, realPath);
+    if (why) refused.push(`${token} (${why}${own ? ', on the story\'s own line' : ''})`);
+    else if (!tokens.includes(token)) tokens.push(token);
+  }
+  if (refused.length === 0 && dropped.length === 0) return { ok: true, tokens };
+  // A path the allowlist dropped is never printed: it holds characters a terminal or a shell could misread.
+  const parts = [];
+  if (refused.length) parts.push(`refused ${refused.slice(0, 5).join(', ')}${refused.length > 5 ? `, and ${refused.length - 5} more` : ''}`);
+  if (dropped.length) parts.push(`${dropped.length} requested path(s) hold characters a shell could misread`);
+  return { ok: false, reason: `${parts.join('; ')}; nothing was served` };
+}
+
+/**
+ * Where a path that passed requestRefusal really points. Null when it is fine, else why not. The path the bundler
+ * will read is the one the disk resolves, so THAT path has to pass the rules: a tracked `notes.txt` that is a link to
+ * the checkout's own `.env` is a credential read, and one that is a link out of the checkout is a read of anything.
+ */
+function resolutionRefusal(token, tracked, realPath) {
+  if (typeof realPath !== 'function') return 'where it resolves on the disk was not checked';
+  const file = parseIncludeTarget(token).path;
+  const real = realPath(file);
+  if (real === null || real === undefined) return 'it does not resolve to a readable path inside this checkout';
+  if (real === file) return null;
+  const why = requestRefusal(real, tracked);
+  return why ? `it resolves to ${real}, which is refused: ${why}` : null;
+}
+
+/**
+ * `rel` resolved through every symlink on the disk, relative to the checkout (POSIX separators), or null when it
+ * does not exist or ends outside the checkout. The one place this module touches the file system.
+ */
+function repoRealPath(cwd, rel) {
+  try {
+    const root = fs.realpathSync(cwd);
+    const inside = path.relative(root, fs.realpathSync(path.resolve(root, rel)));
+    if (inside === '' || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) return null;
+    return inside.split(path.sep).join('/');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The paths the story's own line carried, recorded on its run config as `include_paths` (cli/lib/run-context.js).
+ * An entry that is not a safe token is counted, never passed on; the rest are judged by judgeRequest with the
+ * request, because the config can be written by any client of the org.
+ * @param {object} run  a `GET /orchestrate/:runId` payload
+ * @returns {{paths: string[], dropped: number}}
+ */
+function originalPathsOf(run) {
+  const list = run && run.config && Array.isArray(run.config.include_paths) ? run.config.include_paths : [];
+  const paths = [];
+  let dropped = 0;
+  for (const entry of list) {
+    if (!isSafeToken(entry)) dropped += 1;
+    else if (!paths.includes(entry)) paths.push(entry);
+  }
+  return { paths, dropped };
+}
+
+/**
+ * The batch id `hone queue-stories --format json` printed. The command prints its per-story lines first and the
+ * response document last, and the document starts at a line that is exactly `{`.
+ * @returns {string|null} a batch id, or null when no document with one is there
+ */
+function batchIdFromQueueOutput(stdout) {
+  const text = String(stdout || '');
+  const starts = [...text.matchAll(/^\{$/gm)].map((m) => m.index).reverse();
+  for (const at of starts) {
+    try {
+      const doc = JSON.parse(text.slice(at));
+      if (doc && isBatchId(doc.batchId)) return doc.batchId;
+    } catch { /* not the document; try the next opening brace back */ }
+  }
+  return null;
+}
+
+/**
+ * Has this story already been served? From `GET /orchestrate?storyId=&repoName=` rows (id, story_id, repo_name,
+ * status, created_at, error_message), newest first.
+ *  - `later`: a run of the story in this repository, created AFTER the paused one and not killed. A re-serve that
+ *    queued but whose kill failed, or that died between the two, leaves exactly this and no marker.
+ *  - `earlier`: a run of the story killed with `re-served as batch <id>` BEFORE this one, so this run is that
+ *    re-serve (the loop was started on the new batch alone) and a second pause here is the second.
+ *  - `unknown`: the paused run's creation time is not a date, so neither can be told.
+ * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string}|null}
+ */
+function serveHistory(rows, { runId, storyId, repoName, since }) {
+  const t0 = Date.parse(since);
+  if (!Number.isFinite(t0)) return { kind: 'unknown' };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!row || row.id === runId || row.story_id !== storyId || row.repo_name !== repoName) continue;
+    const t = Date.parse(row.created_at);
+    if (!Number.isFinite(t)) continue;
+    if (t > t0 && row.status !== 'killed') return { kind: 'later', runId: row.id };
+    const batchId = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
+    if (batchId) return { kind: 'earlier', runId: row.id, batchId };
+  }
+  return null;
+}
+
+/**
+ * serveHistory over the server, and, for a `later` run, the batch it is in (found among the batches created since the
+ * paused run, newest first, at most 10; a lookup that fails only costs the batch id).
+ * @param {{listRuns: (storyId: string, repoName: string) => Promise<object[]>, listBatches: () => Promise<object[]>,
+ *          fetchBatch: (id: string) => Promise<object>}} io
+ * @param {{runId: string, storyId: string, repoName: string|null, since: string|null}} action
+ */
+async function findServe(io, action) {
+  const hit = serveHistory(await io.listRuns(action.storyId, action.repoName), action);
+  if (!hit || hit.kind !== 'later') return hit;
+  try {
+    const since = Date.parse(action.since) - 60_000;
+    const recent = (await io.listBatches()).filter((b) => b && isBatchId(b.batchId) && !(Date.parse(b.createdAt) < since)).slice(0, 10);
+    for (const b of recent) {
+      const batch = await io.fetchBatch(b.batchId);
+      if ((Array.isArray(batch && batch.runs) ? batch.runs : []).some((r) => r && r.runId === hit.runId)) return { ...hit, batchId: b.batchId };
+    }
+  } catch { /* the batch is only worth following if it can be found */ }
+  return hit;
+}
+
+/**
+ * The regular files in `git ls-files -z -s` output. A symlink (120000) and a submodule (160000) are tracked but
+ * are not files this checkout holds, and a symlink can point anywhere; a conflicted path (stage above 0) has no
+ * single content.
+ * @param {string} output
+ * @returns {Set<string>}
+ */
+function trackedRegularFiles(output) {
+  const files = new Set();
+  for (const entry of String(output || '').split('\0')) {
+    const m = entry.match(/^(\d{6}) [0-9a-f]+ (\d)\t(.+)$/s);
+    if (m && m[2] === '0' && (m[1] === '100644' || m[1] === '100755')) files.add(m[3]);
+  }
+  return files;
+}
+
+module.exports = {
+  RESERVED_PREFIX, reserveReason, reservedBatchOf, hardPauseRequest, requestRefusal, contentRefusal, judgeRequest, repoRealPath,
+  originalPathsOf, serveHistory, findServe, batchIdFromQueueOutput, trackedRegularFiles,
+};

package/lib/detect-test-framework.js

@@ -0,0 +1,54 @@
+'use strict';
+/**
+ * detect-test-framework.js — what `hone setup` finds already installed in an adopter repo: the stack,
+ * test framework, package manager, Playwright, configs and test script, read from package.json, the
+ * lockfiles and the config files on disk.
+ *
+ * HC-CI-019-followup-3: moved verbatim out of cli/hone-cli.js, which cannot be required (it parses
+ * argv on load), so a test can call it. Before the move no suite asserted any of its fields:
+ * deleting each one left every suite the continuity gate selects green. The I/O stays here rather
+ * than behind injected callbacks, so the move changes no behaviour.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function detectExistingTestFramework(repoRoot) {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { stack: 'unknown', testFw: null, pkgMgr: null };
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  // Detect stack
+  let stack = 'node';
+  if (allDeps['react']) stack = allDeps['vite'] ? 'react-vite' : 'react';
+  if (allDeps['next']) stack = 'nextjs';
+  if (allDeps['@nestjs/core']) stack = 'nestjs';
+
+  // Detect existing test framework
+  let testFw = null;
+  if (allDeps['vitest']) testFw = 'vitest';
+  else if (allDeps['jest']) testFw = 'jest';
+  else if (allDeps['mocha']) testFw = 'mocha';
+
+  // Detect Playwright
+  const hasPlaywright = !!allDeps['@playwright/test'];
+
+  // Detect package manager
+  let pkgMgr = 'npm';
+  if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) pkgMgr = 'yarn';
+  if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) pkgMgr = 'pnpm';
+
+  // Detect existing configs
+  const hasTestConfig = ['vitest.config.js', 'vitest.config.ts', 'jest.config.js', 'jest.config.ts', 'jest.config.cjs']
+    .some(f => fs.existsSync(path.join(repoRoot, f)));
+  const hasPlaywrightConfig = fs.existsSync(path.join(repoRoot, 'playwright.config.js'))
+    || fs.existsSync(path.join(repoRoot, 'playwright.config.ts'));
+
+  // Detect existing test script
+  const hasTestScript = !!pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1';
+
+  return { stack, testFw, hasPlaywright, pkgMgr, hasTestConfig, hasPlaywrightConfig, hasTestScript, pkg };
+}
+
+module.exports = { detectExistingTestFramework };

package/lib/hard-pause-remedy.js

@@ -98,4 +98,4 @@ function renderIncludePathsCommand(storyId, paths) {
   return `hone run-story ${id} ${safe.map((p) => `--include-paths ${tokenOf(p)}`).join(' ')}`;
 }
 
-module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths };
+module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths, tokenOf, isSafeToken };

package/lib/learnings-sync.js

@@ -67,7 +67,8 @@ function updateTopLevelStatus(yamlText, newStatus) {
     return { text: yamlText, updated: false };
   }
   return {
-    text: yamlText.replace(re, `status: ${newStatus}`),
+    // A function, so a `$&` or `$'` in the status is written as itself, not expanded as a replacement pattern.
+    text: yamlText.replace(re, () => `status: ${newStatus}`),
     updated: true,
   };
 }

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/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 };

package/package.json

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