@hone-ai/cli 1.28.0 → 1.29.0

package/lib/doctor-source-dirs.js

@@ -0,0 +1,78 @@
+'use strict';
+/**
+ * doctor-source-dirs.js — HC-DF-002.
+ *
+ * The misconfiguration this catches is SILENT: `hone setup` hardcoded `source_dirs: src/` for
+ * every Node repo with no existence check, and since HC-019n-followup-42 that field scopes the
+ * repository tree the whole pipeline is grounded on. An adopter whose code is not at src/ got a
+ * tree of 2 of 1855 paths under a prompt asserting it was the real layout, and `hone derive`
+ * bundled zero files. Nothing surfaced it until a plan came back wrong, several billed steps in.
+ *
+ * States (four, deliberately — a dead entry among live ones is not the same as a total miss):
+ *   ok    — every configured dir exists (or none configured: the tree is the whole repo)
+ *   drift — NOTHING configured exists: the scope selects nothing real. This is the DF-002 bug.
+ *   warn  — some configured dirs are missing, others are live
+ *   info  — configured dirs are live but detection finds a substantial source dir outside them
+ *   skip  — no pipeline config, or not a git repo
+ * Never throws.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+function checkSourceDirs({ repoRoot, trackedPaths = null } = {}) {
+  const name = 'source-dirs';
+  try {
+    if (!repoRoot || !fs.existsSync(repoRoot)) return { name, status: 'skip', reason: 'no repo root' };
+    const { readSourceDirs } = require('./pipeline-config');
+    const raw = readSourceDirs(repoRoot, { repair: false });
+    const cfgExists = ['.pipeline-config.yml', '.github/.pipeline-config.yml'].some(f => fs.existsSync(path.join(repoRoot, f)));
+    if (!cfgExists) return { name, status: 'skip', reason: 'no .pipeline-config.yml — run `hone setup` first' };
+
+    let tracked = trackedPaths;
+    if (!tracked) {
+      try {
+        const { gitEnv } = require('./git-env');
+        tracked = execSync('git ls-files', { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
+      } catch { return { name, status: 'skip', reason: 'not a git repository' }; }
+    }
+
+    // A glob is inert, not broken: selectPaths prefix-matches and there is no glob engine in the
+    // path, so `src/**/__tests__/` never matched anything. Report it, but never as a failure.
+    const isGlob = (d) => String(d).includes('*');
+    const strip = (d) => String(d).replace(/"/g, '').replace(/\/+$/, '');
+    const configured = raw.source_dirs.filter(d => !isGlob(d));
+    const inert = [...raw.source_dirs, ...raw.test_dirs].filter(isGlob);
+    const onDisk = (d) => { try { return fs.statSync(path.join(repoRoot, strip(d))).isDirectory(); } catch { return false; } };
+    const live = configured.filter(onDisk);
+    const dead = configured.filter(d => !onDisk(d));
+
+    const { detectLayout } = require('./layout-detect');
+    const detected = detectLayout({ root: repoRoot, trackedPaths: tracked });
+    const covered = (p) => live.some(d => p === strip(d) || p.startsWith(strip(d) + '/'));
+    const uncovered = detected.source_dirs.filter(d => !covered(d));
+    const fixLine = `run \`hone detect-layout\`, then set codebase.source_dirs in .github/.pipeline-config.yml`;
+
+    if (configured.length === 0) {
+      return { name, status: 'ok', reason: 'no source_dirs configured — the repository tree covers the whole repo', detail: inert.length ? `inert glob patterns ignored: ${inert.join(', ')}` : undefined };
+    }
+    if (live.length === 0) {
+      return {
+        name, status: 'drift',
+        reason: `none of the configured source_dirs exist: ${dead.join(', ')} — the pipeline is grounded on a near-empty repository tree and \`hone derive\` bundles no files`,
+        detail: `real source directories in this repo: ${detected.source_dirs.join(', ') || '(none found)'}. Fix: ${fixLine}`,
+      };
+    }
+    if (dead.length > 0) {
+      return { name, status: 'warn', reason: `some configured source_dirs do not exist: ${dead.join(', ')}`, detail: `live: ${live.join(', ')}. Fix: ${fixLine}` };
+    }
+    if (uncovered.length > 0) {
+      return { name, status: 'info', reason: `source directories outside the configured scope: ${uncovered.join(', ')}`, detail: `they will be invisible to the groomer, planner and builder. Fix: ${fixLine}` };
+    }
+    return { name, status: 'ok', reason: `source_dirs match the repository: ${live.join(', ')}`, detail: inert.length ? `inert glob patterns ignored: ${inert.join(', ')}` : undefined };
+  } catch (e) {
+    return { name, status: 'skip', reason: `check could not run: ${(e && e.message) || e}` };
+  }
+}
+
+module.exports = { checkSourceDirs };

package/lib/layout-detect.js

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * layout-detect.js — HC-DF-002 (absorbing HC-DF-003): find where the code ACTUALLY lives.
+ *
+ * Why: `setup-ai-pipeline.sh` detected the stack by reading ONLY the root manifest and then
+ * HARDCODED the layout (`DETECTED_SOURCE_DIRS="src/"` for every Node repo, no existence check).
+ * That was a config annoyance until HC-019n-followup-42/-43 made `source_dirs` the load-bearing
+ * input to the repository tree: on hone-server the `src/` default yields a tree of 2 of 1855
+ * tracked paths (`Makefile`, `package.json`) under a prompt asserting it is the real layout.
+ * It also guts `hone derive`, which bundles files from `source_dirs` and skips absent ones.
+ *
+ * Pure and deterministic: takes the tracked path list (the caller does the git I/O), returns
+ * sorted results. Mirrors cli/lib/repo-tree.js so the two agree on what a source path is.
+ */
+
+// Directories that are never source, whatever the stack. Kept in sync with repo-tree.js's
+// ALWAYS_EXCLUDE, plus agent worktrees (gitignored, but an on-disk fallback walk can see them).
+const EXCLUDE = /(^|\/)(node_modules|dist|build|coverage|\.git|\.next|vendor|__pycache__|target|\.venv|venv|\.claude|out|bin|obj)(\/|$)/;
+
+const SOURCE_EXT = /\.(js|mjs|cjs|jsx|ts|tsx|py|java|kt|rb|go|rs|php|cs|scala|swift|cls|trigger|apex)$/i;
+const TEST_HINT = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$/i;
+
+// Directories whose NAME means "this is where the code is". A repo that puts code directly at the
+// root of a package still gets that package dir, via the manifest-dir fallback below.
+const SOURCE_DIR_NAMES = /^(src|lib|app|source|server|client|api|packages|apps|core)$/i;
+// A directory named `tests/` qualifies as a test root on its name alone — a repo with a single
+// integration test still has a test root, and it must be visible to the pipeline.
+const TEST_DIR_NAMES = /^(tests?|spec|specs|e2e|__tests__)$/i;
+
+function _norm(d) { return String(d || '').replace(/^\.\//, '').replace(/\/+$/, ''); }
+function _dir(p) { const i = p.lastIndexOf('/'); return i < 0 ? '' : p.slice(0, i); }
+
+/** Every manifest in the repo (not just the root one) — the HC-DF-003 half of the bug. */
+function detectManifests(trackedPaths) {
+  const MANIFEST = /(^|\/)(package\.json|pyproject\.toml|requirements\.txt|pom\.xml|build\.gradle(\.kts)?|Cargo\.toml|go\.mod|Gemfile|composer\.json|[^/]+\.csproj|sfdx-project\.json)$/;
+  return (Array.isArray(trackedPaths) ? trackedPaths : [])
+    .filter(p => !EXCLUDE.test(p) && MANIFEST.test(p))
+    .sort();
+}
+
+/**
+ * Source and test directories, derived from where source files actually sit.
+ *
+ * Rule (deliberately conservative — an over-broad scope is as wrong as a narrow one):
+ *  1. Bucket every tracked source file under its TOP-LEVEL directory (or `.` for root files).
+ *  2. Keep a top-level dir when it is a recognized source-dir name OR holds a manifest OR holds
+ *     at least MIN_FILES source files. This is what stops `docs/` and `.github/` qualifying.
+ *  3. Descend one level when the top-level dir is a container (packages/, apps/) or when the
+ *     child is a conventional source root (server/src), so the scope is tight but real.
+ *  4. Test dirs are the same computation over test-shaped paths. PREFIX directories only —
+ *     `selectPaths` prefix-matches and there is no glob engine anywhere in the path, so a
+ *     pattern like `src/**​/__tests__/` would silently match nothing.
+ */
+function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
+  void root; // reserved: an on-disk fallback walk when git is unavailable
+  const paths = (Array.isArray(trackedPaths) ? trackedPaths : [])
+    .map(p => _norm(p)).filter(p => p && !EXCLUDE.test(p));
+  const manifests = detectManifests(paths);
+  const manifestDirs = new Set(manifests.map(m => _dir(m)));
+
+  const srcFiles = paths.filter(p => SOURCE_EXT.test(p) && !TEST_HINT.test(p));
+  const testFiles = paths.filter(p => SOURCE_EXT.test(p) && TEST_HINT.test(p));
+
+  function roll(files, nameRe = SOURCE_DIR_NAMES) {
+    const byTop = new Map();
+    for (const f of files) {
+      const top = f.includes('/') ? f.split('/')[0] : '.';
+      if (!byTop.has(top)) byTop.set(top, []);
+      byTop.get(top).push(f);
+    }
+    const out = [];
+    for (const [top, list] of byTop) {
+      if (top === '.') continue; // root-level scripts are not a source ROOT
+      const qualifies = nameRe.test(top) || manifestDirs.has(top) || list.length >= minFiles;
+      if (!qualifies) continue;
+      // Descend one level when this is a container of packages, or when a conventional source
+      // root sits directly under it (server/src) — keeps the scope tight without inventing depth.
+      const kids = new Map();
+      for (const f of list) {
+        const seg = f.split('/');
+        if (seg.length > 2) { const k = seg[0] + '/' + seg[1]; kids.set(k, (kids.get(k) || 0) + 1); }
+      }
+      // Files sitting DIRECTLY in this dir (cli/hone-cli.js). If any exist, the dir itself is
+      // the source root — descending would silently drop them, which is how an early cut of this
+      // rule emitted `cli/lib` and lost cli/hone-cli.js (5.8k lines, the whole CLI surface).
+      // Descend ONLY into a package container (packages/, apps/). Anywhere else, prefer the
+      // PARENT: a wider scope is the safe error for grounding, a narrower one hides real files.
+      // An earlier rule descended into conventional children and emitted `server/src`, which
+      // dropped `server/scripts/` — the exact residual the followup-42 dogfood run hit, where the
+      // planner could not see the agent prompts and proposed inventing them elsewhere.
+      const direct = list.filter(f => f.split('/').length === 2).length;
+      const container = /^(packages|apps|services|modules)$/i.test(top);
+      if (container && kids.size > 0 && direct === 0) { out.push(...[...kids.keys()]); continue; }
+      out.push(top);
+    }
+    return [...new Set(out)].sort();
+  }
+
+  return {
+    version: 1,
+    source_dirs: roll(srcFiles),
+    test_dirs: roll(testFiles, TEST_DIR_NAMES),
+    manifests,
+    ...detectFrameworks(paths, manifests),
+  };
+}
+
+/**
+ * HC-DF-003: framework + test framework from the UNION of manifests, not just the root one.
+ * hone-server's root package.json has ZERO dependencies — express and `node --test` live in
+ * server/package.json — so root-only detection wrote `framework: none, test_framework: none`.
+ * `readManifest` is injected so this stays pure and testable.
+ */
+const FRAMEWORKS = [
+  ['express', /"express"\s*:/], ['nestjs', /"@nestjs\/core"\s*:/], ['fastify', /"fastify"\s*:/],
+  ['nextjs', /"next"\s*:/], ['koa', /"koa"\s*:/], ['hapi', /"@hapi\/hapi"\s*:/],
+  ['django', /^\s*django\b/im], ['flask', /^\s*flask\b/im], ['fastapi', /^\s*fastapi\b/im],
+  ['spring-boot', /spring-boot/],
+];
+const TEST_FRAMEWORKS = [
+  ['jest', /"jest"\s*:/], ['vitest', /"vitest"\s*:/], ['mocha', /"mocha"\s*:/],
+  // node:test ships with Node and appears only as a SCRIPT, never as a dependency — which is
+  // why the old dependency-only chain missed it entirely (grep count in the setup script: 0).
+  ['node:test', /node\s+--test|["']node:test["']|require\(['"]node:test['"]\)/],
+  ['pytest', /^\s*pytest\b/im], ['junit', /junit/i],
+];
+function detectFrameworks(paths, manifests, readManifest = null) {
+  const blobs = [];
+  if (typeof readManifest === 'function') {
+    for (const m of manifests) { const t = readManifest(m); if (t) blobs.push(t); }
+  }
+  const hay = blobs.join('\n');
+  const pick = (table) => { for (const [name, re] of table) if (re.test(hay)) return name; return ''; };
+  return { framework: pick(FRAMEWORKS), test_framework: pick(TEST_FRAMEWORKS), _manifestCount: manifests.length };
+}
+
+/** Which configured dirs are real? The DIRECT signal — no ratio guesswork. */
+function classifyConfiguredDirs(configuredDirs, knownDirs) {
+  const known = new Set((knownDirs || []).map(_norm));
+  const live = []; const dead = [];
+  for (const d of (configuredDirs || []).map(_norm).filter(Boolean)) (known.has(d) ? live : dead).push(d);
+  return { live, dead };
+}
+
+module.exports = { detectLayout, detectManifests, detectFrameworks, classifyConfiguredDirs, EXCLUDE, SOURCE_EXT };

package/lib/learnings-parse.js

@@ -33,6 +33,7 @@ const yaml = require('js-yaml');
 const SCHEMA_A = 'A';
 const SCHEMA_B = 'B';
 const SCHEMA_C = 'C';
+const SCHEMA_D = 'D';
 const SCHEMA_UNKNOWN = 'unknown';
 
 // LC-001 / #58 G2 partial: optional categorization. Per architect plan for
@@ -72,6 +73,15 @@ function detectSchema(parsed) {
   // Schema C wins on collision (both arrays present); caller emits warning.
   if (Array.isArray(parsed.learnings)) return SCHEMA_C;
   if (Array.isArray(parsed.enterprise_candidates)) return SCHEMA_B;
+  // H-029-followup-4: Schema D — a FLAT single-learning dict. Not a new format invented here:
+  // it is what 120 of 226 files already use, written consistently across four months
+  // (2026-05..2026-09) by every agent that produced a learning. All 120 carry
+  // id/story_id/title/category/severity/captured_at/observation; 119 add proposed_fix + impact.
+  // They were parsing to `unknown` and returning zero eligible learnings, so `hone promote`,
+  // `hone audit-learnings` and step_5b never saw them. Recognizing the de facto shape beats
+  // migrating 120 files, because a migration leaves the next agent writing the same thing.
+  // Checked LAST so it can never shadow A/B/C.
+  if (typeof parsed.observation === 'string' && (parsed.id || parsed.story_id)) return SCHEMA_D;
   return SCHEMA_UNKNOWN;
 }
 
@@ -115,6 +125,7 @@ function parseLearningsFile(content, opts = {}) {
     if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted), warning };
     if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted), warning };
     if (schema === SCHEMA_C) return { schema, eligible: parseSchemaC(parsed, includePromoted), warning };
+    if (schema === SCHEMA_D) return { schema, eligible: parseSchemaD(parsed, includePromoted), warning };
   } catch (e) {
     return { schema, eligible: [], warning, parseError: e };
   }
@@ -206,6 +217,40 @@ function parseSchemaC(doc, includePromoted = false) {
     }));
 }
 
+/**
+ * H-029-followup-4: Schema D — one flat dict IS one learning.
+ *
+ * The flat shape has no `enterprise_candidate` flag and no `enterprise_summary`, so the C-style
+ * filters would drop every file. The mapping instead: the learning is an enterprise candidate
+ * when the file says `share_enterprise: true` OR carries a `proposed_fix` (the field that makes a
+ * lesson actionable elsewhere), and the summary is the proposed fix, falling back to the title.
+ * Deliberately permissive on the way IN — a learning that reaches a human to triage is worth far
+ * more than one silently dropped, which is the failure this story exists to fix.
+ */
+function parseSchemaD(doc, includePromoted = false) {
+  const status = doc.status || 'pending';
+  if (!includePromoted && status !== 'pending' && status !== 'captured') return [];
+  const summary = [doc.proposed_fix, doc.recommendation, doc.title]
+    .map(v => (typeof v === 'string' ? v.trim() : '')).find(v => v.length > 0);
+  if (!summary) return [];
+  const candidate = doc.share_enterprise === true
+    || (doc.share_enterprise === undefined && typeof doc.proposed_fix === 'string' && doc.proposed_fix.trim().length > 0);
+  if (!candidate) return [];
+  return [{
+    id: doc.id || doc.story_id,
+    story: doc.story_id || doc.id,
+    enterprise_summary: summary,
+    skill_update: null,
+    status: 'pending',
+    enterprise_candidate: true,
+    _schema: SCHEMA_D,
+    category: validateCategory(doc.category),
+    referenced_skill: doc.referenced_skill || null,
+    referenced_section: doc.referenced_section || null,
+    evidence: Array.isArray(doc.evidence) ? doc.evidence : (doc.evidence ? [doc.evidence] : null),
+  }];
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // writeBackPromoted — schema-aware idempotent regex rewrite
 //
@@ -215,6 +260,7 @@ function parseSchemaC(doc, includePromoted = false) {
 // ─────────────────────────────────────────────────────────────────────
 function writeBackPromoted(content, schema, idsPromoted) {
   if (!idsPromoted || idsPromoted.length === 0) return content;
+  if (schema === SCHEMA_D) return writeBackD(content, idsPromoted);
   if (schema === SCHEMA_A) return writeBackA(content, idsPromoted);
   if (schema === SCHEMA_B) return writeBackB(content, idsPromoted);
   if (schema === SCHEMA_C) return writeBackC(content, idsPromoted);
@@ -269,6 +315,21 @@ function writeBackB(content, idsPromoted) {
 // line. Idempotent: skip if any `status:` already exists in the item's
 // block. Top-level `status:` MUST NOT be touched — it's the story-level
 // status, separate from per-learning status.
+/**
+ * H-029-followup-4: a flat dict is one learning with ONE top-level status, so promotion is a
+ * top-level `status:` rewrite (insert if absent). `hone retract` reads the same field.
+ */
+function writeBackD(content, ids) {
+  if (!ids || ids.length === 0) return content;
+  if (/^status:\s*\S+/m.test(content)) return content.replace(/^status:\s*\S+.*$/m, 'status: promoted');
+  const lines = content.split('\n');
+  let at = lines.findIndex(l => /^captured_at:/.test(l));
+  if (at < 0) at = lines.findIndex(l => /^severity:/.test(l));
+  if (at < 0) at = 0;
+  lines.splice(at + 1, 0, 'status: promoted');
+  return lines.join('\n');
+}
+
 function writeBackC(content, ids) {
   const idSet = new Set(ids.map(String));
   if (idSet.size === 0) return content;
@@ -309,6 +370,9 @@ function rewriteWithStatusInsertion(content, matcher) {
 }
 
 module.exports = {
+  SCHEMA_D,
+  parseSchemaD,
+  writeBackD,
   SCHEMA_A,
   SCHEMA_B,
   SCHEMA_C,

package/lib/materialize-diff.js

@@ -24,8 +24,30 @@ const path = require('node:path');
 /**
  * A ```file:<path> fenced block, capturing the path and the verbatim body.
  * Info-string tolerant: ```file:foo, ``` file: foo, ```FILE:foo all match.
+ *
+ * HC-GF-022: the closing fence is anchored to its OWN LINE (`^...$` under /m).
+ * The previous form spelled the terminator `\r?\n``` `, which REQUIRED a newline
+ * between the opener and the closer and so could not match an EMPTY block. On a
+ * legitimately empty file (`flowforge/core/__init__.py` — every Python package
+ * has one) the body then swallowed its own closing fence, matched the NEXT
+ * block's opening fence as its terminator, and consumed it: the empty file was
+ * written containing a literal ``` `, and the following file — 2,888 bytes of
+ * pipeline logic — vanished from the diff entirely. `check-patch` reported
+ * "applies cleanly", because the diff git built from the surviving blocks was
+ * perfectly valid. Line-anchoring is also strictly better for a body that
+ * contains an indented or info-tagged fence of its own.
  */
-const FILE_BLOCK_RE = /```[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)\r?\n```/gi;
+const FILE_BLOCK_RE = /^[ \t]*```[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*\r?$/gim;
+
+/**
+ * The line-anchored closer necessarily absorbs the newline that terminates the
+ * last content line. Strip exactly one so `contents` keeps the meaning it has
+ * always had (the body WITHOUT its terminating newline) — and so an empty block
+ * stays the empty string rather than becoming "\n".
+ */
+function blockBody(raw) {
+  return String(raw == null ? '' : raw).replace(/\r?\n$/, '');
+}
 
 /**
  * A ```edit:<path> fenced block — HC-019n-followup-27. For a file too big to
@@ -97,7 +119,7 @@ function extractFileBlocks(output) {
     if (!rel) continue;            // rejected (traversal/absolute) — see below
     if (seen.has(rel)) continue;   // first block wins on a dup path
     seen.add(rel);
-    files.push({ path: rel, contents: m[2] });
+    files.push({ path: rel, contents: blockBody(m[2]) });
   }
 
   // HC-019n-followup-27: region edits for files too big to bundle whole.
@@ -287,8 +309,29 @@ function buildFileDiff({ repoPath, isNew, runGitDiff }) {
   return { diff: ensureTrailingNewline(rewriteDiffPaths(stdout, repoPath, isNew)), changed: true };
 }
 
+/**
+ * HC-GF-029 — APPEND ONLY. This must never remove anything.
+ *
+ * It used to be `s.replace(/\s*$/, '') + '\n'`, and `\s*$` matches the whole
+ * trailing whitespace RUN — which swallows a final blank CONTEXT LINE. A hunk
+ * ending on a blank source line (a blank line before the next def, i.e. ordinary
+ * Python and JS spacing) therefore lost one line while its `@@` header still
+ * declared the original count, and `git apply` rejected the result as
+ * `corrupt patch at line N`. Measured on run 74fc6519: `flowforge/app.py`
+ * header said `-12/+7`, body carried `-11/+6`.
+ *
+ * It stayed invisible because a NEW file's diff is pure additions with no
+ * trailing context to lose. It fires the first time a story MODIFIES an existing
+ * file — that is, every story after the first one on any repository.
+ *
+ * This function sits at the end of the one path whose entire premise is that
+ * git's arithmetic is authoritative ("a diff git produces is one `git apply`
+ * accepts by construction", top of this file). Rewriting git's output after the
+ * fact is what broke that premise, so the only safe normalisation here is to add
+ * a terminator when one is missing.
+ */
 function ensureTrailingNewline(s) {
-  return s.replace(/\s*$/, '') + '\n';
+  return s.endsWith('\n') ? s : `${s}\n`;
 }
 
 /**

package/lib/pipeline-config.js

@@ -33,7 +33,8 @@ 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', 'install_command']; // install_command: HC-COMM-010-followup-6
+const KNOWN_CI_GATE_KEYS = ['gate', 'local_command', 'install_command',
+  'lint_command', 'typecheck_command']; // install_command: HC-COMM-010-followup-6; lint/typecheck: HC-GF-026
 const DEFAULT_CI_LOCAL_COMMAND = 'make ci';
 
 /**
@@ -119,7 +120,14 @@ function normalizeCIGate(raw) {
  * @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 };
+  // HC-GF-026: lint_command / typecheck_command. step_4 emitted a shell transcript
+  // claiming `ruff check → All checks passed!` for a command it never ran (it has no
+  // execution surface), and step_5 repeated it as `STANDARDS: Clean`. Measured against
+  // the emitted branch: 6 real violations of the repo's OWN pyproject rules. The cure
+  // is not prompt wording — it is running the command and having a verdict to compare
+  // against, which is what these two keys make possible.
+  const none = { local_command: null, local_command_explicit: false, install_command: null,
+                 lint_command: null, typecheck_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;
@@ -129,7 +137,11 @@ function readCIConfigDetails(repoRoot) {
     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 };
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    return {
+      local_command: lc, local_command_explicit: lc !== null, install_command: ic,
+      lint_command: str(block.lint_command), typecheck_command: str(block.typecheck_command),
+    };
   }
   return none;
 }
@@ -158,20 +170,71 @@ function readCodebaseDefaults(repoRoot) {
 /**
  * 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[] }}
+ *
+ * HC-DF-002: this is now THE chokepoint, and it SELF-HEALS. `hone setup` wrote a hardcoded
+ * `src/` for every Node repo with no existence check, which silently broke three consumers that
+ * each read this field: run-story's repository tree (2 of 1855 paths on this repo), `hone derive`
+ * (bundled 0 files, so the derived skills came from nothing) and `hone check-refresh` (counted 0,
+ * so staleness never fired). Fixing only the setup script would leave every already-installed
+ * adopter broken, because generate_config() returns early when the config exists. So the READ
+ * repairs itself: configured directories that do not exist on disk are dropped, and if that
+ * leaves nothing, the layout is detected from the repo. Config still wins whenever it is real.
+ *
+ * @param {string} repoRoot
+ * @param {{trackedPaths?: string[], repair?: boolean}} [opts] repair=false returns the raw config
+ * @returns {{source_dirs: string[], test_dirs: string[], repaired: boolean, dropped: string[], detected: boolean}}
  */
-function readSourceDirs(repoRoot) {
-  const none = { source_dirs: [], test_dirs: [] };
+function readSourceDirs(repoRoot, opts = {}) {
+  const none = { source_dirs: [], test_dirs: [], repaired: false, dropped: [], inert: [], detected: false };
   if (!repoRoot || typeof repoRoot !== 'string') return none;
+  let raw = null;
   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) };
+    raw = { source_dirs: list(parsed.source_dirs), test_dirs: list(parsed.test_dirs) };
+    break;
   }
-  return none;
+  if (!raw) return none;
+  if (opts.repair === false) return { ...raw, repaired: false, dropped: [], inert: [], detected: false };
+
+  // A glob is INERT, not broken: `selectPaths` prefix-matches and there is no glob engine
+  // anywhere in the path, so `src/**/__tests__/` never matched anything even before this story.
+  // Dropping it is correct, but it is not a repair and must not raise an operator warning.
+  const isGlob = (d) => String(d).includes('*');
+  const exists = (d) => {
+    const clean = String(d).replace(/"/g, '').replace(/\/+$/, '');
+    if (!clean || isGlob(clean)) return false;
+    try { return fs.existsSync(path.join(repoRoot, clean)) && fs.statSync(path.join(repoRoot, clean)).isDirectory(); }
+    catch { return false; }
+  };
+  const liveSrc = raw.source_dirs.filter(exists);
+  const liveTest = raw.test_dirs.filter(exists);
+  // Only a real directory that is ABSENT counts as a repair.
+  const dropped = [...raw.source_dirs, ...raw.test_dirs].filter(d => !isGlob(d) && !exists(d));
+  const inert = [...raw.source_dirs, ...raw.test_dirs].filter(isGlob);
+
+  // An EMPTY configured list is a legitimate, healthy state — it means "the whole repo".
+  // Only a list that was non-empty and is now empty signals a broken config worth detecting for.
+  if (liveSrc.length > 0 || raw.source_dirs.length === 0) {
+    return { source_dirs: liveSrc, test_dirs: liveTest, repaired: dropped.length > 0, dropped, inert, detected: false };
+  }
+  try {
+    const { detectLayout } = require('./layout-detect');
+    let tracked = Array.isArray(opts.trackedPaths) ? opts.trackedPaths : null;
+    if (!tracked) {
+      const { execSync } = require('child_process');
+      const { gitEnv } = require('./git-env');
+      tracked = execSync('git ls-files', { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
+    }
+    const d = detectLayout({ root: repoRoot, trackedPaths: tracked });
+    if (d.source_dirs.length > 0) {
+      return { source_dirs: d.source_dirs, test_dirs: d.test_dirs, repaired: true, dropped, inert, detected: true };
+    }
+  } catch { /* detection is best-effort: a broken scope beats a crashed command */ }
+  return { source_dirs: liveSrc, test_dirs: liveTest, repaired: dropped.length > 0, dropped, inert, detected: false };
 }
 
 function readCIGateConfig(repoRoot) {

package/lib/repo-tree.js

@@ -116,7 +116,13 @@ function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, m
   const r = renderTree(selected, { maxEntries, maxBytes });
   const dirs = allDirs(allPaths);
   const tree = {
-    version: 2,
+    // 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,
@@ -127,6 +133,15 @@ function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, m
   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;
 }