@hone-ai/cli 1.27.0 → 1.29.0

package/lib/repo-tree.js

@@ -0,0 +1,148 @@
+'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 = {
+    // v3 (HC-019n-followup-45): adds `detected_source_dirs` + `omitted_dirs` so the server can
+    // grade coverage instead of asking a binary question. A ratio alone cannot distinguish a
+    // deliberately narrow scope (server/src only = 6% of this repo, correct) from an accidental
+    // one (server/src+cli = 39%, missing scripts/ and server/scripts/ where real code lives).
+    // The DETECTOR's opinion is the semantic signal: which source-bearing dirs did the config
+    // leave out? Old servers ignore the new fields; old CLIs simply do not send them.
+    version: 3,
+    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;
+  }
+  try {
+    const { detectLayout } = require('./layout-detect');
+    const d = detectLayout({ trackedPaths: allPaths });
+    tree.detected_source_dirs = d.source_dirs;
+    // A detected source dir is "omitted" when no configured dir contains it (or equals it).
+    const cfg = tree.source_dirs.map(_norm).filter(Boolean);
+    tree.omitted_dirs = cfg.length === 0 ? [] : d.source_dirs.filter(
+      dir => !cfg.some(c => dir === c || dir.startsWith(c + '/') || c.startsWith(dir + '/')));
+  } catch { /* detection is best-effort; without it the server falls back to the ratio */ }
+  return tree;
+}
+
+module.exports = { selectPaths, renderTree, buildRepoTree, allDirs, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_BYTES, MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS };

package/lib/run-report.js

@@ -0,0 +1,217 @@
+'use strict';
+/**
+ * run-report.js — HC-GF-016. What happened, and what still needs you.
+ *
+ * WHY: after a run finishes there was no command that said how it went. Judging
+ * one took five separate hand-checks, and the owner's actual complaint is
+ * sharper than that — reading every agent's prose LOSES THE ACTION ITEMS.
+ *
+ * THE LOAD-BEARING CONSTRAINT: every line here is DERIVED from stored data.
+ * Nothing is narrated by an agent. A step that WROTE this summary would
+ * confidently assert things — the same defect HC-GF-026 measured twice, one
+ * layer up — and a digest that lies is worse than no digest, because it is the
+ * thing you read INSTEAD OF the detail.
+ *
+ * Pure: takes the `GET /orchestrate/:runId` projection, returns a structure.
+ * Rendering is separate so both are testable without a server.
+ */
+
+/** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
+const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
+
+function pad(s, n) { return String(s).padEnd(n); }
+
+/**
+ * Wall-clock from start to terminal state. This INCLUDES time parked at a human
+ * gate, which is usually most of it — TICK-001 reads 176m for ~12m of pipeline
+ * work because it waited on an operator. Rendered as "elapsed" rather than bare,
+ * so it is not mistaken for compute time next to a token count.
+ */
+function durationOf(startedAt, endedAt) {
+  const a = Date.parse(startedAt || ''), b = Date.parse(endedAt || '');
+  if (!Number.isFinite(a) || !Number.isFinite(b) || b < a) return null;
+  const secs = Math.round((b - a) / 1000);
+  return secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m${String(secs % 60).padStart(2, '0')}s`;
+}
+
+/**
+ * @param {object} run  the GET /:runId projection
+ * @param {{cost?: {metered:number, notional:number}}} [extra]
+ */
+function buildReport(run, extra = {}) {
+  const cfg = run.config || {};
+  const steps = Array.isArray(run.steps) ? run.steps : [];
+  const verifications = Array.isArray(run.verifications) ? run.verifications : [];
+  const needsYou = [];
+  const worthKnowing = [];
+
+  // ── NEEDS YOU ──────────────────────────────────────────────────────────────
+  // 1. The run itself is not finished.
+  if (run.status === 'paused' && run.currentStep) {
+    needsYou.push({
+      what: `run is paused at ${run.currentStep} — a gate is waiting on your judgment`,
+      how: `hone run-story ${run.runId} --approve ${run.currentStep}`,
+    });
+  }
+  if (run.status === 'failed') {
+    needsYou.push({
+      what: `run FAILED${run.errorMessage ? `: ${String(run.errorMessage).slice(0, 160)}` : ''}`,
+      how: `hone show step ${run.runId} ${run.currentStep || '<stepKey>'}`,
+    });
+  }
+
+  // 2. The last verification is ONE event, so it becomes ONE item with sub-lines.
+  //    Listing "verification failed" and "lint failed" separately gave two entries
+  //    for one problem resolved by one fix — and NEEDS YOU is a list of DISTINCT
+  //    ACTIONS, not of observations. Grouping dedupes structurally rather than by
+  //    string-matching a gate name inside a failure message, which would be a
+  //    heuristic that quietly mis-fires.
+  //
+  //    `fail` and `unavailable` are both actionable and mean different things:
+  //    one found problems, the other never ran. Never collapse them.
+  const lastVerification = verifications[verifications.length - 1] || null;
+  if (lastVerification) {
+    const bad = (lastVerification.gates || []).filter(g => ACTIONABLE_GATE_VERDICTS.includes(g.verdict));
+    const failed = lastVerification.verdict === 'fail' || lastVerification.verdict === 'timeout';
+    if (failed || bad.length) {
+      const stepKey = lastVerification.stepKey || 'step_4';
+      needsYou.push({
+        what: failed
+          ? `verification ${lastVerification.verdict} on ${stepKey}`
+            + `${lastVerification.detail ? ` — ${lastVerification.detail}` : ''}`
+          : `${bad.length} gate(s) not passing on ${stepKey}`,
+        // Sub-lines carry the per-gate verdicts, so one glance separates
+        // "the tests broke" from "the linter never ran".
+        detail: (lastVerification.gates || []).map(
+          g => `${g.name}: ${g.verdict}${g.detail ? ` — ${g.detail}` : ''}`
+             + `${g.command ? `   [${g.command}]` : ''}`),
+        how: `hone verify-patch ${run.runId} ${stepKey} --keep`,
+        howLabel: 'reproduce',
+      });
+    }
+  }
+
+  // ── WORTH KNOWING ──────────────────────────────────────────────────────────
+  // Retries: the step produced something the pipeline rejected at least once.
+  for (const s of steps) {
+    if (Number(s.attempts) > 1) {
+      worthKnowing.push(`${s.stepKey} retried — ${s.attempts} attempts (its first output was rejected)`);
+    }
+  }
+  // The two "blind run" tells, both from HC-GF-006's preflight reasoning.
+  const descChars = typeof cfg.story_description === 'string' ? cfg.story_description.length : 0;
+  if (descChars === 0) {
+    worthKnowing.push('story_description was EMPTY — step_0 groomed a story it never received');
+  }
+  const bundled = Array.isArray(cfg.codebaseFiles) ? cfg.codebaseFiles.length : 0;
+  if (bundled === 0) {
+    worthKnowing.push('no codebase files bundled — step_1/step_4 ran without source context');
+  }
+  // Skipped steps are a decision, not an absence; say which and stay silent on why
+  // (the reason lives in the step output, and inferring it here would be narration).
+  const skipped = steps.filter(s => s.status === 'skipped').map(s => s.stepKey);
+  if (skipped.length) worthKnowing.push(`skipped: ${skipped.join(', ')}`);
+
+  return {
+    runId: run.runId,
+    storyId: run.storyId,
+    status: run.status,
+    mode: cfg.execution_mode || run.mode || null,
+    stepsRun: steps.filter(s => s.status === 'completed').length,
+    stepsTotal: steps.length,
+    totalTokens: Number(run.totalTokens) || 0,
+    // startedAt/completedAt, never createdAt/updatedAt: the latter moves on any
+    // later write (a --report verdict, an approve) and reported 433m for a
+    // 12-minute run. Null when the run has not finished — an absent duration is
+    // honest; a wrong one is not.
+    duration: durationOf(run.startedAt, run.completedAt),
+    cost: extra.cost || null,
+    architectConsulted: cfg.architect_consulted === true,
+    storyDescriptionChars: descChars,
+    bundledFiles: bundled,
+    classifierAxes: Array.isArray(cfg.classifier_axes) ? cfg.classifier_axes : [],
+    needsYou,
+    worthKnowing,
+    steps,
+    verifications,
+  };
+}
+
+/**
+ * Render to terminal text.
+ *
+ * EMPTY-STATE RULE, applied ASYMMETRICALLY and on purpose:
+ *   NEEDS YOU with nothing to report must SAY SO and name what it checked — an
+ *   omitted section is indistinguishable from an unchecked one, which is this
+ *   repo's dominant defect class (HC-GF-005, HC-GF-012, HC-GF-022, HC-GF-030).
+ *   WORTH KNOWING may be omitted silently: nothing actionable is lost.
+ */
+function renderReport(r) {
+  const L = [];
+  const cost = r.cost
+    ? `$${r.cost.metered.toFixed(2)} metered${r.cost.notional != null ? ` ($${r.cost.notional.toFixed(2)} notional)` : ''}`
+    : null;
+  L.push([`${r.storyId || r.runId}`, r.status,
+          r.stepsTotal && r.stepsRun !== r.stepsTotal
+            ? `${r.stepsRun} of ${r.stepsTotal} steps` : `${r.stepsRun} steps`,
+          `${r.totalTokens.toLocaleString()} tokens`, cost,
+          r.duration ? `${r.duration} elapsed` : null]
+         .filter(Boolean).join(' · '));
+  L.push('');
+
+  if (r.needsYou.length) {
+    L.push(`NEEDS YOU (${r.needsYou.length})`);
+    r.needsYou.forEach((n, i) => {
+      L.push(`  ${i + 1}. ${n.what}`);
+      for (const d of n.detail || []) L.push(`       ${d}`);
+      // Label the command when it REPRODUCES rather than resolves — an unlabelled
+      // arrow reads as "run this to fix it", which `ruff check .` does not do.
+      if (n.how) L.push(`     → ${n.howLabel ? `${n.howLabel}: ` : ''}${n.how}`);
+    });
+  } else {
+    // Name what was checked, so "nothing" is a finding rather than a silence.
+    const checked = [];
+    const last = r.verifications[r.verifications.length - 1];
+    if (last) {
+      checked.push('verification');
+      for (const g of last.gates || []) checked.push(g.name);
+    }
+    L.push('NEEDS YOU (0)');
+    L.push(checked.length
+      ? `  nothing — ${checked.join(', ')} all reported and none is failing or unavailable`
+      : '  nothing outstanding, but NO verification was reported for this run — '
+        + 'run `hone verify-patch <runId> step_4 --report` before trusting that');
+  }
+  L.push('');
+
+  if (r.worthKnowing.length) {
+    L.push(`WORTH KNOWING (${r.worthKnowing.length})`);
+    for (const w of r.worthKnowing) L.push(`  · ${w}`);
+    L.push('');
+  }
+
+  L.push('STEPS');
+  for (const s of r.steps) {
+    const mark = s.status === 'completed' ? '✓' : s.status === 'skipped' ? '○' : '·';
+    const retry = Number(s.attempts) > 1 ? `  [${s.attempts} attempts]` : '';
+    L.push(`  ${mark} ${pad(s.stepKey, 8)} ${pad(s.agent || '', 24)} ${s.status}`
+           + `${s.gateResult ? ` (${s.gateResult})` : ''}${retry}`);
+  }
+  L.push('');
+
+  L.push('RUN FACTS');
+  L.push(`  mode ${r.mode || 'unknown'} · story text ${r.storyDescriptionChars} chars · `
+         + `${r.bundledFiles} file(s) bundled · architect_consulted ${r.architectConsulted}`);
+  if (r.classifierAxes.length) L.push(`  axes: ${r.classifierAxes.join(', ')}`);
+  if (r.verifications.length) {
+    for (const v of r.verifications) {
+      const gates = (v.gates || []).map(g => `${g.name}=${g.verdict}`).join(' · ');
+      L.push(`  verify(${v.stepKey || '?'}): ${v.verdict}${gates ? ` · ${gates}` : ''}`);
+    }
+  } else {
+    L.push('  verify: none reported');
+  }
+  return L.join('\n');
+}
+
+module.exports = { buildReport, renderReport, durationOf, ACTIONABLE_GATE_VERDICTS };

package/lib/verify-patch.js

@@ -96,21 +96,174 @@ function verdictFromRun(run) {
   if (run.code === 0) {
     return { verdict: 'pass', exitCode: EXIT.PASS, detail: 'tests passed on the applied diff' };
   }
+  const sum = summarizeFailure(run);
+  // HC-GF-023: lead with HOW MANY. "1 of 8 named" and "the only failure" are
+  // different situations that this line used to render identically.
+  const head = `tests failed (exit ${run.code})`
+    + (sum.count > 1 ? ` — ${sum.count} failure lines` : '');
   return {
     verdict: 'fail',
     exitCode: EXIT.TESTS_FAILED,
-    detail: `tests failed (exit ${run.code})` + (lastMeaningfulLine(run) ? `: ${lastMeaningfulLine(run)}` : ''),
+    detail: head + (sum.first ? `, first: ${sum.first}` : ''),
+    failure: sum,
   };
 }
 
-/** The most useful one-liner from a failed run's output, for the report. */
+/** Lines that look like a runner reporting a failure. Deliberately broad — this
+ *  counts EVIDENCE of failure across pytest/node/jest/go/cargo, not test cases. */
+const FAILURE_LINE_RE = /(^|[\s│|])(FAILED|FAIL|ERROR|ERR!|not ok|✗|✖|×)\b|\w+Error\b|panic:|AssertionError/;
+
+/**
+ * HC-GF-023 — summarise a failed run instead of quoting one line of it.
+ *
+ * The old `lastMeaningfulLine` scanned BACKWARDS for anything matching
+ * /fail|error|…/ and returned it alone. On run 74fc6519 pytest reported EIGHT
+ * failures caused by a single SyntaxError; this returned the LAST line of the
+ * short summary — one unrelated-looking test name, no count, and no cause. It
+ * pointed away from the defect, and diagnosing it took `--keep` plus a manual
+ * re-run. A one-line quote of a multi-failure run is not a summary; it is a
+ * sample presented as a conclusion.
+ *
+ * Pure: returns the count, the FIRST failure (usually nearer the cause than the
+ * last) and a tail excerpt. Writing the full log is IO and stays in the CLI.
+ *
+ * @returns {{ count: number, first: string, excerpt: string[] }}
+ */
+function summarizeFailure({ stdout = '', stderr = '' }, { maxLines = 12 } = {}) {
+  const lines = `${stdout}\n${stderr}`.split('\n').map(l => l.replace(/\s+$/, ''));
+  const nonEmpty = lines.filter(l => l.trim());
+  const failing = nonEmpty.filter(l => FAILURE_LINE_RE.test(l));
+  return {
+    count: failing.length,
+    first: (failing[0] || nonEmpty[nonEmpty.length - 1] || '').trim().slice(0, 200),
+    excerpt: nonEmpty.slice(-maxLines).map(l => l.slice(0, 300)),
+  };
+}
+
+/** The most useful one-liner from a failed run's output. Retained for callers
+ *  that want a single string; verdictFromRun no longer relies on it alone. */
 function lastMeaningfulLine({ stdout = '', stderr = '' }) {
   const combined = `${stdout}\n${stderr}`.split('\n')
     .map(l => l.trim())
     .filter(Boolean);
-  // Prefer a line that names a failure; else the last non-empty line.
   const failLine = combined.reverse().find(l => /fail|error|✗|not ok|assert/i.test(l));
   return (failLine || combined[0] || '').slice(0, 200);
 }
 
-module.exports = { EXIT, resolveCommand, resolveCommandDetailed, DEFAULT_COMMAND, verdictFromRun, lastMeaningfulLine };
+/**
+ * ── HC-GF-026: the gates nobody was running ──────────────────────────────────
+ *
+ * On run 74fc6519 step_4 emitted this, verbatim, in its artifact:
+ *
+ *     $ ruff check flowforge tests
+ *     All checks passed!
+ *     $ mypy flowforge
+ *     Success: no issues found in 3 source files
+ *
+ * It ran neither. step_4 is a server-side LLM call with NO execution surface.
+ * Measured against the emitted branch: six real violations of the repo's own
+ * `pyproject.toml` rules. step_5 then read that artifact and reported
+ * `STANDARDS: Clean — ruff+mypy green`, so a fabrication became a reviewed fact
+ * without one new piece of evidence entering the chain.
+ *
+ * The one TRUE line in that block — `8 passed` — was the only claim the pipeline
+ * independently executes. That is the whole lesson: the cure for a confidently
+ * invented gate result is not prompt wording telling the model to stop, it is
+ * RUNNING the gate so there is a verdict to compare against. Ground truth beats
+ * instruction ([[feedback_placeholder_vs_hallucination_cascades]]).
+ *
+ * These gates are REPORTED, not blocking. A lint failure must not veto a build
+ * that passes its tests — that would change the meaning of verify-patch's exit
+ * code for every existing adopter, and style is not correctness. What it must do
+ * is exist, be measured, and be visible to the operator and the server.
+ */
+
+/** Config key → the gate's name, in the order they run. */
+const AUX_GATES = [
+  { name: 'lint',      configKey: 'lint_command' },
+  { name: 'typecheck', configKey: 'typecheck_command' },
+];
+
+/**
+ * Detection tiers, deliberately conservative: a gate is only inferred when the
+ * repo DECLARES the tool in its own config. We never guess a linter a repo has
+ * not adopted, and every inferred command fails CLOSED to `unavailable` when the
+ * binary is absent (`npx --no-install` rather than `npx`, which would download).
+ */
+const AUX_DETECT = {
+  lint: [
+    { file: 'pyproject.toml', contains: '[tool.ruff]', command: 'ruff check .',                source: 'pyproject [tool.ruff]' },
+    { file: 'package.json',   script: 'lint',          command: 'npm run --silent lint',       source: 'package.json lint script' },
+  ],
+  typecheck: [
+    { file: 'pyproject.toml', contains: '[tool.mypy]', command: 'mypy',                        source: 'pyproject [tool.mypy]' },
+    { file: 'package.json',   script: 'typecheck',     command: 'npm run --silent typecheck',  source: 'package.json typecheck script' },
+    { file: 'tsconfig.json',                           command: 'npx --no-install tsc --noEmit', source: 'tsconfig.json' },
+  ],
+};
+
+/**
+ * Resolve the auxiliary gates for a repo. Pure — filesystem access is injected.
+ * @returns {Array<{ name, command, source }>} only gates that resolved
+ */
+function resolveAuxGates({ configured = {}, cwd = process.cwd(), fsMod = require('node:fs') } = {}) {
+  const path = require('node:path');
+  const read = (f) => { try { return fsMod.readFileSync(path.join(cwd, f), 'utf8'); } catch { return null; } };
+  const out = [];
+  for (const { name, configKey } of AUX_GATES) {
+    const explicit = configured[configKey];
+    if (typeof explicit === 'string' && explicit.trim()) {
+      out.push({ name, command: explicit.trim(), source: `ci.${configKey}` });
+      continue;
+    }
+    for (const tier of AUX_DETECT[name]) {
+      const body = read(tier.file);
+      if (body === null) continue;
+      if (tier.contains && !body.includes(tier.contains)) continue;
+      if (tier.script) {
+        let scripts = null;
+        try { scripts = (JSON.parse(body) || {}).scripts || null; } catch { continue; }
+        if (!scripts || typeof scripts[tier.script] !== 'string') continue;
+      }
+      out.push({ name, command: tier.command, source: tier.source });
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Classify an aux gate run. The three-way split is the point: `unavailable` must
+ * never read as `fail`, or a missing linter looks like a broken patch — the exact
+ * confusion HC-GF-008 exists to prevent one layer up.
+ * @returns {{ verdict: 'pass'|'fail'|'unavailable', detail: string }}
+ */
+function classifyGateRun(run) {
+  const text = `${run.stdout || ''}\n${run.stderr || ''}`;
+  const missing = run.code === 127
+    || (run.error && run.error.code === 'ENOENT')
+    || /command not found|: not found|No such file or directory|is not recognized/i.test(text);
+  if (missing) {
+    return { verdict: 'unavailable', detail: 'command not found — gate NOT run' };
+  }
+  if (run.timedOut) return { verdict: 'unavailable', detail: 'timed out — gate NOT run to completion' };
+  if (run.code === 0) return { verdict: 'pass', detail: 'clean' };
+  const sum = summarizeFailure(run, { maxLines: 6 });
+  // A linter prints its findings from the TOP, so unlike a test runner the most
+  // useful line is the first, not the last. summarizeFailure's fallback is the
+  // last line (right for a runner's summary block), so pick the head here.
+  const firstOut = text.split('\n').map(l => l.trim()).find(Boolean) || '';
+  const lead = sum.count ? sum.first : firstOut;
+  return {
+    verdict: 'fail',
+    detail: (sum.count ? `${sum.count} finding${sum.count === 1 ? '' : 's'}` : `exit ${run.code}`)
+      + (lead ? ` — ${lead.slice(0, 160)}` : ''),
+    excerpt: sum.excerpt,
+  };
+}
+
+module.exports = {
+  EXIT, resolveCommand, resolveCommandDetailed, DEFAULT_COMMAND,
+  AUX_GATES, AUX_DETECT, resolveAuxGates, classifyGateRun,
+  verdictFromRun, lastMeaningfulLine, summarizeFailure, FAILURE_LINE_RE,
+};

package/lib/worktree-provision.js

@@ -20,6 +20,48 @@ const LOCKFILES = [
   ['pnpm-lock.yaml',      'pnpm install --frozen-lockfile'],
   ['yarn.lock',           'yarn install --frozen-lockfile'],
 ];
+
+/**
+ * HC-GF-024: manifests we can RECOGNISE but deliberately do not install.
+ *
+ * Observed on FlowForge (a Python repo with a root `pyproject.toml` declaring
+ * `dependencies = ["pydantic>=2.7"]`): the provisioner printed
+ * `skipped (no dependency manifest detected)` — the manifest was right there.
+ * It happened not to matter because that story's code was stdlib-only, but the
+ * next story with a real import would have failed `ModuleNotFoundError` and been
+ * reported as a FAILING TEST, i.e. as the code-builder's fault.
+ *
+ * We stop short of running these. `npm ci` writes into the worktree's own
+ * `node_modules` and is contained; `pip install -r requirements.txt` with no
+ * active virtualenv writes into the operator's GLOBAL site-packages — a side
+ * effect outside the worktree that "isolated worktree" promises not to have.
+ * Guessing a venv here would also silently diverge from whatever the adopter's
+ * real CI does. So: name the manifest, say we did not provision, and point at
+ * `ci.install_command`, which already wins over every other tier.
+ */
+const RECOGNISED_MANIFESTS = [
+  ['uv.lock',          'python'],
+  ['poetry.lock',      'python'],
+  ['Pipfile.lock',     'python'],
+  ['requirements.txt', 'python'],
+  ['pyproject.toml',   'python'],
+  ['setup.cfg',        'python'],
+  ['go.sum',           'go'],
+  ['go.mod',           'go'],
+  ['Cargo.lock',       'rust'],
+  ['Cargo.toml',       'rust'],
+  ['Gemfile.lock',     'ruby'],
+  ['pom.xml',          'java'],
+  ['build.gradle',     'java'],
+  ['build.gradle.kts', 'java'],
+  ['composer.lock',    'php'],
+];
+
+/** Every filename planProvision looks for, so "not detected" is falsifiable. */
+const ALL_MANIFEST_NAMES = [
+  ...LOCKFILES.map(([f]) => f), 'package.json', ...RECOGNISED_MANIFESTS.map(([f]) => f),
+];
+
 const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
 
 function planProvision({ worktreeDir, parentDir, installCommand = null, fsMod = fs }) {
@@ -40,12 +82,36 @@ function planProvision({ worktreeDir, parentDir, installCommand = null, fsMod =
   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' };
+  // HC-GF-024: a manifest we recognise but cannot safely install. Say so by NAME.
+  for (const [file, ecosystem] of RECOGNISED_MANIFESTS) {
+    if (!ex(path.join(worktreeDir, file))) continue;
+    return {
+      kind: 'unsupported',
+      manifest: file,
+      ecosystem,
+      reason: `${file} detected — ${ecosystem} provisioning is not automated; ` +
+              'set `ci.install_command` in .pipeline-config.yml if the tests need dependencies',
+    };
+  }
+
+  // HC-GF-024: name what was looked for, so "not detected" can be checked rather
+  // than believed. A bare "no dependency manifest detected" is unfalsifiable and
+  // reads identically whether the repo has none or we simply do not know the file.
+  return {
+    kind: 'none',
+    reason: `no dependency manifest detected (looked for: ${ALL_MANIFEST_NAMES.join(', ')})`,
+  };
 }
 
 /** @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'})` };
+  // HC-GF-024: recognised-but-unautomated. ok:true keeps the fail-open contract (the
+  // test command still runs), but the summary names the manifest so a later
+  // ModuleNotFoundError reads as "unprovisioned", not as a broken patch.
+  if (plan.kind === 'unsupported') {
+    return { ok: true, did: 'none', summary: `NOT provisioned — ${plan.reason}` };
+  }
   if (plan.kind === 'link') {
     try {
       const dest = path.join(worktreeDir, 'node_modules');
@@ -61,4 +127,7 @@ function provisionWorktree(plan, { worktreeDir, exec, fsMod = fs }) {
   } 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 };
+module.exports = {
+  planProvision, provisionWorktree,
+  LOCKFILES, RECOGNISED_MANIFESTS, ALL_MANIFEST_NAMES, INSTALL_TIMEOUT_MS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {
@@ -8,6 +8,7 @@
     "hone-mcp": "./bin/hone-mcp.js"
   },
   "files": [
+    "README.md",
     "bin/",
     "hone-cli.js",
     "lib/",
@@ -20,7 +21,7 @@
     "link": "npm link",
     "sync-server-cli-version": "node scripts/sync-server-cli-version.js",
     "prepublishOnly": "node scripts/sync-server-cli-version.js",
-    "postinstall": "echo '\\n  Hone AI CLI installed successfully.\\n  Next: run `hone init --token <YOUR_TOKEN>` to configure.\\n  Docs: https://github.com/subbareddyvani/hone-server\\n'"
+    "postinstall": "echo '\\n  Hone AI CLI installed successfully.\\n  Next: run `hone init --token <YOUR_TOKEN>` to configure.\\n  Docs: https://www.npmjs.com/package/@hone-ai/cli\\n'"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
@@ -44,5 +45,6 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "homepage": "https://www.npmjs.com/package/@hone-ai/cli"
 }