@hone-ai/cli 1.26.0 → 1.28.0

package/hone-cli.js

@@ -5755,7 +5755,11 @@ program
     //     escape the repo)
     //   - .md / .txt / .yml docs (rarely needed for code-builder; would
     //     blow context with prose)
-    if (issueBodyForFiles || opts.includePaths) {
+    // HC-DF-001: config-level default include paths (codebase.default_include_paths)
+    // are merged with story-text auto-detection and --include-paths.
+    const { readCodebaseDefaults } = require('./lib/pipeline-config');
+    const defaultIncludePaths = readCodebaseDefaults(process.cwd()).include_paths;
+    if (issueBodyForFiles || opts.includePaths || defaultIncludePaths.length > 0) {
       try {
         // HC-019n-followup-13c: word-boundary `\b` at end of extension
         // group so `.jsonl` doesn't match as `.js` and `.tsx` doesn't
@@ -5776,6 +5780,7 @@ program
             candidates.add(p);
           }
         }
+        for (const p of defaultIncludePaths) candidates.add(p); // HC-DF-001 config defaults
         // HC-019n-followup-26: FILE_PATH_RE above requires a directory segment,
         // so a story that names a file BARE (`derive-worker.js:787` in prose)
         // extracts 0 paths and step_4 runs blind — and, blind, hallucinates a
@@ -5928,6 +5933,27 @@ program
       }
     }
 
+    // HC-019n-followup-42: repository-structure grounding. Bundling FILES is not
+    // grounding — with no tree in the prompt the groomer invents a layout and the
+    // planner inherits it (dogfood run f276fe00). Stamp a compact, capped tree of
+    // tracked paths (scoped to source_dirs/test_dirs when configured) into the run
+    // config; the server renders it for the steps that name paths. Fail-open.
+    try {
+      const { execSync } = require('child_process');
+      const { buildRepoTree } = require('./lib/repo-tree');
+      const { readSourceDirs } = require('./lib/pipeline-config');
+      const tracked = execSync('git ls-files', { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
+      const dirs = readSourceDirs(process.cwd());
+      const tree = buildRepoTree(tracked, { sourceDirs: dirs.source_dirs, testDirs: dirs.test_dirs });
+      if (tree.selected_total > 0) {
+        orchestrateConfig.repo_tree = tree;
+        const scope = dirs.source_dirs.length ? dirs.source_dirs.join(', ') : 'all tracked';
+        console.log(`  → repository structure: ${tree.shown} of ${tree.selected_total} paths under ${scope} (${(Buffer.byteLength(tree.text, 'utf8') / 1024).toFixed(1)} KB) — the groomer/planner/builder are told to derive every path from it`);
+      }
+    } catch (e) {
+      console.warn(`  ⚠ repository structure not bundled (non-fatal): ${(e && e.message || String(e)).split('\n')[0]}`);
+    }
+
     // HC-101-followup-2: pass the adopter's CI gate config to the
     // orchestrator so step_5c can branch (github / local / both / none).
     // Defaults to gate=github + local_command='make ci' when the config
@@ -7353,6 +7379,7 @@ program
   .option('--command <cmd>', 'Test command (default: ci.local_command from config, else `make ci`)')
   .option('--timeout <sec>', 'Seconds before the test command is killed', '600')
   .option('--keep', 'Leave the worktree in place for debugging')
+  .option('--no-provision', 'Do not install/link dependencies into the isolated worktree (HC-COMM-010-followup-6)')
   .option('--report', 'HC-019n-followup-34: report the verdict back to the server (closed loop, advisory)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
@@ -7418,7 +7445,7 @@ program
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-verify-'));
     const diffFile = path.join(os.tmpdir(), `hone-verify-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command);
+    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
     let cleanupDone = false;
     const cleanup = () => {
       if (cleanupDone || opts.keep) return;
@@ -7458,6 +7485,16 @@ program
         reportVerdict = 'does_not_apply'; reportDetail = applyDetail;
       } else {
         // 5. Run the adopter's test command in the worktree.
+        // HC-COMM-010-followup-6: a bare worktree has no dependencies — provision it
+        // (link the repo's node_modules when the lockfile is unchanged, else run the
+        // lockfile's install, or ci.install_command). Fail-open; --no-provision opts out.
+        if (opts.provision !== false) {
+          const { planProvision, provisionWorktree } = require('./lib/worktree-provision');
+          const { readCIConfigDetails } = require('./lib/pipeline-config');
+          const plan = planProvision({ worktreeDir: wt, parentDir: process.cwd(), installCommand: readCIConfigDetails(process.cwd()).install_command });
+          const prov = provisionWorktree(plan, { worktreeDir: wt, exec: spawnSync });
+          if (opts.format !== 'json') console.log(`  provisioning: ${prov.summary}`);
+        }
         if (opts.format !== 'json') console.log(`  running: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
         const run = spawnSync(command, {
           cwd: wt, shell: true, encoding: 'utf8',
@@ -7523,6 +7560,7 @@ program
   .option('--command <cmd>', 'Test command for --verify (default: ci.local_command, else `make ci`)')
   .option('--timeout <sec>', 'Seconds before the verify test command is killed', '600')
   .option('--keep', 'Leave the worktree in place for debugging')
+  .option('--no-provision', 'Do not install/link dependencies into the isolated worktree (HC-COMM-010-followup-6)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
     const { execFileSync, spawnSync } = require('child_process');
@@ -7634,7 +7672,7 @@ program
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-emit-'));
     const diffFile = path.join(os.tmpdir(), `hone-emit-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command);
+    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
     // `worktree add -b` creates the branch ref BEFORE apply/verify. If we bail
     // before a successful commit (apply fails, verify fails), that empty branch
     // (pointing at HEAD) must be torn down too — else "a failing diff never
@@ -7679,6 +7717,16 @@ program
         // 4b. Re-verify inline (default) — a failing diff never reaches a branch.
         let verifyOk = true;
         if (doVerify) {
+          // HC-COMM-010-followup-6: a bare worktree has no dependencies — provision it
+          // (link the repo's node_modules when the lockfile is unchanged, else run the
+          // lockfile's install, or ci.install_command). Fail-open; --no-provision opts out.
+          if (opts.provision !== false) {
+            const { planProvision, provisionWorktree } = require('./lib/worktree-provision');
+            const { readCIConfigDetails } = require('./lib/pipeline-config');
+            const plan = planProvision({ worktreeDir: wt, parentDir: process.cwd(), installCommand: readCIConfigDetails(process.cwd()).install_command });
+            const prov = provisionWorktree(plan, { worktreeDir: wt, exec: spawnSync });
+            if (opts.format !== 'json') console.log(`  provisioning: ${prov.summary}`);
+          }
           if (opts.format !== 'json') console.log(`  verifying: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
           const run = spawnSync(command, {
             cwd: wt, shell: true, encoding: 'utf8',

package/lib/pipeline-config.js

@@ -33,7 +33,7 @@ const path = require('node:path');
 const KNOWN_THRESHOLD_KEYS = ['estimate_full_sdlc', 'recently_modified_window_days'];
 
 const CI_GATE_MODES = ['github', 'local', 'both', 'none'];
-const KNOWN_CI_GATE_KEYS = ['gate', 'local_command'];
+const KNOWN_CI_GATE_KEYS = ['gate', 'local_command', 'install_command']; // install_command: HC-COMM-010-followup-6
 const DEFAULT_CI_LOCAL_COMMAND = 'make ci';
 
 /**
@@ -111,6 +111,69 @@ function normalizeCIGate(raw) {
  * @param {string} repoRoot
  * @returns {{ gate: 'github'|'local'|'both'|'none', local_command: string }}
  */
+/**
+ * HC-COMM-010-followup-6/-7: the ci: block details readCIGateConfig deliberately
+ * does not expose (its return shape is pinned): whether local_command was set
+ * EXPLICITLY in the file (vs the `make ci` default), and an optional
+ * install_command used to provision the verification worktree.
+ * @returns {{ local_command: string|null, local_command_explicit: boolean, install_command: string|null }}
+ */
+function readCIConfigDetails(repoRoot) {
+  const none = { local_command: null, local_command_explicit: false, install_command: null };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'), path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    const block = parsed && typeof parsed === 'object' ? parsed.ci : null;
+    if (!block || typeof block !== 'object') continue;
+    const lc = typeof block.local_command === 'string' && block.local_command.trim() ? block.local_command.trim() : null;
+    const ic = typeof block.install_command === 'string' && block.install_command.trim() ? block.install_command.trim() : null;
+    return { local_command: lc, local_command_explicit: lc !== null, install_command: ic };
+  }
+  return none;
+}
+
+/**
+ * HC-DF-001: `codebase.default_include_paths` — repo-relative files bundled into
+ * every run-story from this repo, merged with story-text auto-detection and
+ * --include-paths. Opt-in, empty by default. Malformed → [] (fail-open).
+ * @returns {{ include_paths: string[] }}
+ */
+function readCodebaseDefaults(repoRoot) {
+  const none = { include_paths: [] };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'), path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    const block = parsed && typeof parsed === 'object' ? parsed.codebase : null;
+    if (!block || typeof block !== 'object') continue;
+    const list = Array.isArray(block.default_include_paths) ? block.default_include_paths : [];
+    return { include_paths: list.filter(x => typeof x === 'string' && x.trim()).map(x => x.trim()) };
+  }
+  return none;
+}
+
+/**
+ * HC-019n-followup-42: `source_dirs` / `test_dirs` from the pipeline config (setup
+ * writes them) — used to scope the repository-structure signal. Absent ⇒ [].
+ * @returns {{ source_dirs: string[], test_dirs: string[] }}
+ */
+function readSourceDirs(repoRoot) {
+  const none = { source_dirs: [], test_dirs: [] };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'), path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const list = (v) => (Array.isArray(v) ? v : []).filter(x => typeof x === 'string' && x.trim()).map(x => x.trim());
+    return { source_dirs: list(parsed.source_dirs), test_dirs: list(parsed.test_dirs) };
+  }
+  return none;
+}
+
 function readCIGateConfig(repoRoot) {
   const defaults = { gate: 'github', local_command: DEFAULT_CI_LOCAL_COMMAND };
   if (!repoRoot || typeof repoRoot !== 'string') return defaults;
@@ -417,6 +480,9 @@ function readAgentEvalConfig(repoRoot) {
 }
 
 module.exports = {
+  readSourceDirs,
+  readCodebaseDefaults,
+  readCIConfigDetails,
   EXECUTION_MODES,
   DEFAULT_EXECUTION_MODE,
   EDITOR_MODE_CONSENT_NOTE,

package/lib/repo-tree.js

@@ -0,0 +1,133 @@
+'use strict';
+/**
+ * repo-tree.js — HC-019n-followup-42: repository-structure grounding.
+ *
+ * Why: bundling FILES is not grounding. With two real files bundled, the groomer
+ * still invented a TypeScript monorepo (`packages/hone-cli/src/commands/story.ts`)
+ * because no repository STRUCTURE ever reached a prompt, and the planner carried
+ * the assumption forward (dogfood run f276fe00, 2026-09-06). This module turns
+ * `git ls-files` into a compact, capped, LLM-readable tree that the CLI stamps
+ * into the run config and the server renders for the steps that name paths.
+ *
+ * Pure: takes a path list; the CLI does the git I/O. Deterministic (sorted).
+ */
+const DEFAULT_MAX_ENTRIES = 300;
+const DEFAULT_MAX_BYTES = 16 * 1024;
+const ALWAYS_EXCLUDE = /(^|\/)(node_modules|dist|build|coverage|\.git|\.next|vendor|__pycache__|target)(\/|$)/;
+
+function _norm(d) { return String(d || '').replace(/^\.\//, '').replace(/\/+$/, ''); }
+
+/**
+ * Select the tracked paths worth showing: under source/test dirs when configured,
+ * otherwise everything tracked minus generated/dependency dirs.
+ */
+function selectPaths(allPaths, { sourceDirs = [], testDirs = [] } = {}) {
+  const dirs = [...sourceDirs, ...testDirs].map(_norm).filter(Boolean);
+  const paths = (Array.isArray(allPaths) ? allPaths : []).map(p => String(p).trim()).filter(p => p && !ALWAYS_EXCLUDE.test(p));
+  if (dirs.length === 0) return paths.sort();
+  const inScope = paths.filter(p => dirs.some(d => p === d || p.startsWith(d + '/')));
+  // Keep repo-root manifests so the model sees the package layout even when only dirs are configured.
+  const roots = paths.filter(p => !p.includes('/') && /^(package\.json|pyproject\.toml|go\.mod|Cargo\.toml|Makefile|pom\.xml|build\.gradle|Gemfile)$/.test(p));
+  return [...new Set([...roots, ...inScope])].sort();
+}
+
+/** Build a nested {name -> node} structure from paths. */
+function _nest(paths) {
+  const root = { dirs: new Map(), files: [] };
+  for (const p of paths) {
+    const segs = p.split('/'); let node = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+      if (!node.dirs.has(segs[i])) node.dirs.set(segs[i], { dirs: new Map(), files: [] });
+      node = node.dirs.get(segs[i]);
+    }
+    node.files.push(segs[segs.length - 1]);
+  }
+  return root;
+}
+function _count(node) { let n = node.files.length; for (const d of node.dirs.values()) n += _count(d); return n; }
+
+/**
+ * Render an indented tree. Over the entry cap, the deepest/largest directories are
+ * collapsed to `name/ (N files)` so the SHAPE survives even when the listing cannot.
+ * @returns {{ text: string, shown: number, total: number, collapsed: number }}
+ */
+function renderTree(paths, { maxEntries = DEFAULT_MAX_ENTRIES, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  const sorted = [...new Set(paths)].sort(); const total = sorted.length;
+  const root = _nest(sorted);
+  let budget = Math.max(1, maxEntries); let collapsed = 0; let shown = 0;
+  const lines = [];
+  // Convention: FILES first, then subdirectories (a reader sees what lives at a
+  // level before descending; shallow files keep priority under the entry cap).
+  // Budget applies to FILE lines; directories always appear (the shape must survive the cap):
+  // once the budget is spent, remaining files at a level become `… (N more files)` and remaining
+  // subdirectories become `name/ (N files)`. Deep, large directories are collapsed regardless.
+  function walk(node, indent, depth) {
+    const dirNames = [...node.dirs.keys()].sort();
+    const files = [...node.files].sort();
+    let skipped = 0;
+    for (const f of files) {
+      if (budget <= 0) { skipped += 1; continue; }
+      lines.push(`${indent}${f}`); budget -= 1; shown += 1;
+    }
+    if (skipped > 0) { lines.push(`${indent}… (${skipped} more files)`); collapsed += skipped; }
+    for (const d of dirNames) {
+      const child = node.dirs.get(d); const n = _count(child);
+      if (budget <= 0 || (depth >= 4 && n > 8)) { lines.push(`${indent}${d}/ (${n} files)`); collapsed += n; continue; }
+      lines.push(`${indent}${d}/`); walk(child, indent + '  ', depth + 1);
+    }
+  }
+  walk(root, '', 0);
+  let text = lines.join('\n');
+  if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+    // Hard byte cap: trim whole lines from the end and say so.
+    while (lines.length && Buffer.byteLength(lines.join('\n'), 'utf8') > maxBytes - 40) { lines.pop(); }
+    text = lines.join('\n') + '\n… (listing truncated to fit the size cap)';
+  }
+  return { text, shown, total, collapsed: Math.max(0, total - shown) };
+}
+
+const MAX_TRANSPORT_PATHS = 5000;
+const MAX_TRANSPORT_DIRS = 3000;
+
+/**
+ * HC-019n-followup-43: every tracked directory repo-wide (minus generated/dependency dirs),
+ * all ancestor levels included. Directories are few (hundreds) and answer "does this
+ * directory exist?" even OUTSIDE the tree's source/test scope — the validator's question.
+ */
+function allDirs(allPaths) {
+  const out = new Set();
+  for (const raw of (Array.isArray(allPaths) ? allPaths : [])) {
+    const p = String(raw).trim(); if (!p || ALWAYS_EXCLUDE.test(p)) continue;
+    const segs = p.split('/');
+    for (let i = 1; i < segs.length; i++) out.add(segs.slice(0, i).join('/'));
+  }
+  return [...out].sort();
+}
+
+/**
+ * The transport object stamped into run.config.repo_tree.
+ * v2 (followup-43) adds `paths` (the selected files) and `dirs` (all tracked directories) so
+ * the server can validate the planner's `## Files` without token cost; `text` is unchanged
+ * from v1 (prompt bytes stable). Both lists are capped; over the cap they are omitted and
+ * the server treats the tree as v1 (guard skipped, never a false rejection).
+ */
+function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, maxBytes } = {}) {
+  const selected = selectPaths(allPaths, { sourceDirs, testDirs });
+  const r = renderTree(selected, { maxEntries, maxBytes });
+  const dirs = allDirs(allPaths);
+  const tree = {
+    version: 2,
+    source_dirs: sourceDirs.map(_norm).filter(Boolean),
+    test_dirs: testDirs.map(_norm).filter(Boolean),
+    tracked_total: Array.isArray(allPaths) ? allPaths.length : 0,
+    selected_total: selected.length,
+    shown: r.shown,
+    text: r.text,
+  };
+  if (selected.length <= MAX_TRANSPORT_PATHS && dirs.length <= MAX_TRANSPORT_DIRS) {
+    tree.paths = selected; tree.dirs = dirs;
+  }
+  return tree;
+}
+
+module.exports = { selectPaths, renderTree, buildRepoTree, allDirs, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_BYTES, MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS };

package/lib/verify-patch.js

@@ -38,12 +38,50 @@ const EXIT = {
  * @param {string|undefined} configured ci_local_command from run config
  * @returns {string}
  */
-function resolveCommand(explicit, configured) {
-  const pick = (explicit && explicit.trim())
-    || (configured && configured.trim())
-    || 'make ci';
-  return pick;
+const DEFAULT_COMMAND = 'make ci';
+function _hasMakeCiTarget(cwd) {
+  try { const f = require('node:fs'); const p = require('node:path').join(cwd, 'Makefile'); return f.existsSync(p) && /^ci\s*:/m.test(f.readFileSync(p, 'utf8')); } catch { return false; }
 }
+function _npmTestScript(cwd) {
+  try {
+    const f = require('node:fs'); const p = require('node:path').join(cwd, 'package.json');
+    if (!f.existsSync(p)) return null;
+    const t = JSON.parse(f.readFileSync(p, 'utf8'))?.scripts?.test;
+    return (typeof t === 'string' && t.trim() && !/no test specified/i.test(t)) ? 'npm test' : null;
+  } catch { return null; }
+}
+/**
+ * HC-COMM-010-followup-7: tiered resolution. Without `opts.cwd` this is the
+ * original pure function (explicit → configured → `make ci`). With `opts.cwd`:
+ *   1. --command (explicit)
+ *   2. ci.local_command set EXPLICITLY in the file NOW (re-read at verify/emit
+ *      time — the run config captured it at creation and may be stale)
+ *   3. the run config's ci_local_command, unless it is just the stamped default
+ *   4. `make ci` if the Makefile has a ci target
+ *   5. `npm test` if package.json has a real test script
+ *   6. `make ci` (documented default; fails loudly)
+ * @returns {{command:string, source:string}}
+ */
+function resolveCommandDetailed(explicit, configured, opts = {}) {
+  const e = (typeof explicit === 'string' ? explicit : '').trim();
+  if (e) return { command: e, source: '--command' };
+  const cwd = opts && opts.cwd;
+  if (cwd) {
+    try {
+      const { readCIConfigDetails } = require('./pipeline-config');
+      const d = readCIConfigDetails(cwd);
+      if (d.local_command_explicit) return { command: d.local_command, source: 'ci.local_command (config file)' };
+    } catch { /* fall through */ }
+  }
+  const c = (typeof configured === 'string' ? configured : '').trim();
+  if (c && c !== DEFAULT_COMMAND) return { command: c, source: 'run config' };
+  if (cwd) {
+    if (_hasMakeCiTarget(cwd)) return { command: DEFAULT_COMMAND, source: 'Makefile ci target' };
+    const npm = _npmTestScript(cwd); if (npm) return { command: npm, source: 'package.json test script' };
+  }
+  return { command: DEFAULT_COMMAND, source: 'default' };
+}
+function resolveCommand(explicit, configured, opts) { return resolveCommandDetailed(explicit, configured, opts).command; }
 
 /**
  * Interpret a completed command run into a condition-6 verdict.
@@ -75,4 +113,4 @@ function lastMeaningfulLine({ stdout = '', stderr = '' }) {
   return (failLine || combined[0] || '').slice(0, 200);
 }
 
-module.exports = { EXIT, resolveCommand, verdictFromRun, lastMeaningfulLine };
+module.exports = { EXIT, resolveCommand, resolveCommandDetailed, DEFAULT_COMMAND, verdictFromRun, lastMeaningfulLine };

package/lib/worktree-provision.js

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * worktree-provision.js — HC-COMM-010-followup-6: "verify in an isolated
+ * worktree" implies "provision the worktree". A bare `git worktree add` has no
+ * node_modules, so a Node adopter's test command failed with "Cannot find
+ * package 'vitest'" before any test ran (found 2026-09-05, run 4ab3a962).
+ *
+ * Plan (pure) → execute (injected exec). Fast path: when the worktree's
+ * lockfile is byte-identical to the repo's and the repo already has
+ * node_modules, LINK it (seconds, no network). Otherwise run the lockfile's
+ * install. Explicit `ci.install_command` wins. Fail-open: a provisioning
+ * failure is reported and the test command still runs (it will fail clearly).
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCKFILES = [
+  ['package-lock.json',   'npm ci --no-audit --no-fund'],
+  ['npm-shrinkwrap.json', 'npm ci --no-audit --no-fund'],
+  ['pnpm-lock.yaml',      'pnpm install --frozen-lockfile'],
+  ['yarn.lock',           'yarn install --frozen-lockfile'],
+];
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+function planProvision({ worktreeDir, parentDir, installCommand = null, fsMod = fs }) {
+  const ex = (p) => { try { return fsMod.existsSync(p); } catch { return false; } };
+  const rd = (p) => { try { return fsMod.readFileSync(p, 'utf8'); } catch { return null; } };
+  if (installCommand && String(installCommand).trim()) {
+    return { kind: 'install', command: String(installCommand).trim(), reason: 'ci.install_command' };
+  }
+  for (const [lock, cmd] of LOCKFILES) {
+    const wl = path.join(worktreeDir, lock);
+    if (!ex(wl)) continue;
+    const pl = path.join(parentDir, lock); const pnm = path.join(parentDir, 'node_modules');
+    if (ex(pnm) && ex(pl) && rd(wl) !== null && rd(wl) === rd(pl)) {
+      return { kind: 'link', target: pnm, reason: `${lock} unchanged — linking the repo's node_modules` };
+    }
+    return { kind: 'install', command: cmd, reason: `${lock} present${ex(pnm) ? ' but changed' : ''}` };
+  }
+  if (ex(path.join(worktreeDir, 'package.json'))) {
+    return { kind: 'install', command: 'npm install --no-audit --no-fund', reason: 'package.json without a lockfile' };
+  }
+  return { kind: 'none', reason: 'no dependency manifest detected' };
+}
+
+/** @returns {{ok:boolean, did:'none'|'link'|'install', summary:string, command?:string}} */
+function provisionWorktree(plan, { worktreeDir, exec, fsMod = fs }) {
+  if (!plan || plan.kind === 'none') return { ok: true, did: 'none', summary: `skipped (${plan ? plan.reason : 'no plan'})` };
+  if (plan.kind === 'link') {
+    try {
+      const dest = path.join(worktreeDir, 'node_modules');
+      if (!fsMod.existsSync(dest)) fsMod.symlinkSync(plan.target, dest, 'dir');
+      return { ok: true, did: 'link', summary: `linked node_modules (${plan.reason})` };
+    } catch (e) { return { ok: false, did: 'link', summary: `link failed (${e.message}) — tests run unprovisioned` }; }
+  }
+  try {
+    const run = exec(plan.command, { cwd: worktreeDir, shell: true, encoding: 'utf8', timeout: INSTALL_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] });
+    const ok = run && run.status === 0;
+    const tail = ok ? '' : ` — ${String((run && (run.stderr || run.stdout)) || '').trim().split('\n').filter(Boolean).pop() || 'install failed'}`;
+    return { ok, did: 'install', command: plan.command, summary: `${ok ? 'ran' : 'FAILED'} \`${plan.command}\` (${plan.reason})${tail}` };
+  } catch (e) { return { ok: false, did: 'install', command: plan.command, summary: `install threw (${e.message}) — tests run unprovisioned` }; }
+}
+
+module.exports = { planProvision, provisionWorktree, LOCKFILES, INSTALL_TIMEOUT_MS };

package/package.json

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