@skyf0xx/hedgehog 5.4.2 → 6.0.2

package/src/db/status.mjs

@@ -11,9 +11,10 @@
 // every task meeting that condition, not just the one `hedgehog next`
 // would pick.
 
+import { radiusGaps } from './code-intelligence.mjs';
 import { listDebt } from './debt.mjs';
 import { detectDrift, formatDrift } from './drift.mjs';
-import { listFriction } from './friction.mjs';
+import { frictionByModule, listFriction } from './friction.mjs';
 import { orphanedOverrides } from './overrides.mjs';
 import { formatMissingRequirements } from './requires.mjs';
 import { readyTasks, heldBackReason } from './ready.mjs';
@@ -102,6 +103,33 @@ function loadDebtByTask(db) {
     .sort((a, b) => a.taskId.localeCompare(b.taskId));
 }
 
+// Advisory radius suggestions: for every task whose context was resolved
+// against a code-intelligence index (context_files non-NULL), the files
+// its computed blast radius reaches that no verify_radius/scope_globs
+// glob covers (code-intelligence.mjs#radiusGaps). Skips every task with
+// no resolved context outright, which is what a task planned without a
+// working index leaves behind — the same NULL a broken or removed CGC
+// install produces, not a state `status` distinguishes from an
+// intentionally unindexed run.
+//
+// Wrapped the way countFriction is: `status` reads through a read-only
+// handle, which never migrates, so on a graph predating the context
+// columns this SELECT throws on a column that isn't there yet. An
+// unmigrated graph reads as no suggestions, not as a failed `status`.
+function loadRadiusSuggestions(db) {
+  try {
+    const tasks = db.prepare('SELECT * FROM tasks WHERE context_files IS NOT NULL').all();
+    const suggestions = [];
+    for (const task of tasks) {
+      const gaps = radiusGaps(task);
+      if (gaps.length > 0) suggestions.push({ taskId: task.id, files: gaps });
+    }
+    return suggestions;
+  } catch {
+    return [];
+  }
+}
+
 // The friction row count, or 0. `listFriction` reads the table
 // unguarded, so a build graph predating it throws here where `listDebt`
 // would return [] — caught rather than propagated for the same reason
@@ -117,11 +145,13 @@ function countFriction(db) {
 }
 
 // Returns { counts, ready, heldBack, inFlight, attention, drift,
-// orphanedOverrides, debt, frictionCount, total } — counts keyed by
-// every status in the tasks CHECK constraint (present even at zero),
-// ready the full list of currently-pickable tasks, heldBack the subset
-// of those that `hedgehog claim` would skip over right now because they
-// conflict with in-flight work or another ready task ahead of them
+// orphanedOverrides, debt, frictionCount, frictionHotspots,
+// radiusSuggestions, total } —
+// counts keyed by every status in the tasks CHECK constraint (present
+// even at zero), ready the full list of currently-pickable tasks,
+// heldBack the subset of those that `hedgehog claim` would skip over
+// right now because they conflict with in-flight work or another ready
+// task ahead of them
 // (ready.mjs's own simulation, reused rather than reimplemented —
 // without this a task can sit in READY indefinitely with no visible
 // reason, the same invisible-stall shape blocked tasks had before
@@ -159,6 +189,20 @@ function countFriction(db) {
 // only the existence signal: `debt list` needs a task id the operator
 // has no way to guess, and `friction list` needs the operator to
 // already suspect there is something to read.
+//
+// `frictionHotspots` (friction.mjs#frictionByModule) is the one reading
+// of friction that isn't a count: the files the friction-carrying tasks
+// reach, ranked. It rides along here because it is a read of `friction`
+// joined to `tasks` and needs nothing else passed in. On a project whose
+// tasks carry no resolved context it is an empty hotspot list and a full
+// `uncorrelated` count, which is the same signal `frictionCount` alone
+// already gave.
+//
+// `radiusSuggestions` (code-intelligence.mjs#radiusGaps) is advisory,
+// never enforcement: files a task's computed blast radius reaches that
+// its declared verify_radius/scope_globs doesn't cover. Computed only
+// for tasks with a resolved context_files, same gate as the hotspots
+// read — a project with no index attached contributes nothing here.
 export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const counts = countTasksByStatus(db);
   const ready = loadReadyTasks(db);
@@ -169,6 +213,8 @@ export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const orphaned = orphanedOverrides(db, overrides);
   const debt = loadDebtByTask(db);
   const frictionCount = countFriction(db);
+  const frictionHotspots = frictionByModule(db);
+  const radiusSuggestions = loadRadiusSuggestions(db);
   const total = Object.values(counts).reduce((a, b) => a + b, 0);
   return {
     counts,
@@ -180,6 +226,8 @@ export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
     orphanedOverrides: orphaned,
     debt,
     frictionCount,
+    frictionHotspots,
+    radiusSuggestions,
     total,
   };
 }
@@ -213,8 +261,15 @@ export function formatStatus({
   orphanedOverrides = [],
   debt = [],
   frictionCount = 0,
+  frictionHotspots = { hotspots: [], uncorrelated: 0 },
+  radiusSuggestions = [],
   total,
   missingRequirements,
+  // Rendered lines from formatIndexStaleness, or [] when the index is
+  // fresh or absent. Passed in rather than computed: this module reads
+  // the graph, and index provenance lives on disk and in git, which is
+  // the CLI's side of the line.
+  indexStaleness = [],
 }) {
   const lines = [];
   lines.push(`TASKS  ${total}`);
@@ -266,9 +321,9 @@ export function formatStatus({
     lines.push('  Fix the work, then: hedgehog retry <task-id> && hedgehog claim <task-id> --owner <owner>');
   }
 
-  // Last two, because both are conditions of the graph as a whole rather
-  // than of any one task, and because an operator reading top-down should
-  // reach them after knowing what's ready and what's stuck.
+  // These three, because each is a condition of the graph as a whole
+  // rather than of any one task, and because an operator reading top-down
+  // should reach them after knowing what's ready and what's stuck.
   if (drift && drift.length > 0) {
     lines.push('');
     lines.push(formatDrift(drift));
@@ -290,6 +345,35 @@ export function formatStatus({
     lines.push('  Each widens nothing until the id matches a real task. See: hedgehog override list');
   }
 
+  // Advisory, never a defect count: verify_radius/scope_globs is what
+  // actually gates `hedgehog verify`, and stays the sole authority on
+  // that whether or not this prints. This only names what a
+  // code-intelligence index thinks a task's blast radius reaches beyond
+  // its declared radius — a widening the operator may or may not want.
+  if (radiusSuggestions.length > 0) {
+    lines.push('');
+    lines.push('RADIUS SUGGESTIONS');
+    for (const { taskId, files } of radiusSuggestions) {
+      lines.push(`  ${taskId}   verify_radius may be missing:`);
+      for (const file of files) lines.push(`    ${file}`);
+    }
+    lines.push('');
+    lines.push(
+      indexStaleness.length > 0
+        ? '  Sourced from a code-intelligence index that is out of date (below). Widen with: hedgehog plan --recompile'
+        : '  Sourced from a code-intelligence index. Widen with: hedgehog plan --recompile',
+    );
+  }
+
+  // Below the suggestions it qualifies, and printed whether or not any
+  // were raised: an index that has drifted from HEAD also under-reports,
+  // so an empty RADIUS SUGGESTIONS section is exactly when a reader most
+  // needs to know the index is stale rather than the code clean.
+  if (indexStaleness.length > 0) {
+    lines.push('');
+    lines.push(...indexStaleness);
+  }
+
   // Bottom, below every condition above, and two sections rather than
   // one. Everything above is something wrong — work stalled, a graph
   // that disagrees with its core, an override doing nothing. These two
@@ -320,6 +404,21 @@ export function formatStatus({
   if (frictionCount > 0) {
     lines.push('');
     lines.push(`FRICTION LOGGED  ${frictionCount}`);
+    // The top three only: this is a lead for tweaker's grouping pass, not
+    // a listing, and a ranked tail nobody acts on costs the whole block
+    // its readability. The uncorrelated count prints whenever it's
+    // non-zero — including with no hotspots at all, which is how a
+    // project whose tasks carry no resolved context reads.
+    const { hotspots = [], uncorrelated = 0 } = frictionHotspots ?? {};
+    if (hotspots.length > 0 || uncorrelated > 0) {
+      lines.push('');
+      for (const { path, frictionCount: n } of hotspots.slice(0, 3)) {
+        lines.push(`  ${path}   ${n} note${n === 1 ? '' : 's'}`);
+      }
+      if (uncorrelated > 0) {
+        lines.push(`  ${uncorrelated} note${uncorrelated === 1 ? '' : 's'} not correlated to any file`);
+      }
+    }
     lines.push('');
     lines.push('  Reviewed as a batch at the end of a build. See: hedgehog friction list');
   }

package/src/hosts/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hedgehog",
-  "version": "5.4.2",
+  "version": "6.0.2",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

package/src/hosts/version.mjs

@@ -101,16 +101,19 @@ export async function latestVersion(root, { force = false } = {}) {
   if (!latest) return null;
 
   // Cache alongside the install stamp rather than in a separate file, so
-  // one read answers both halves of the question.
+  // one read answers both halves of the question. Written only into a
+  // `.hedgehog/` that already exists — a version lookup is a read, and
+  // creating the directory here would leave one behind in a project that
+  // never completed `init`, which `init`'s own preconditions rely on
+  // being absent when they abort.
   const path = join(root, VERSION_PATH);
   try {
-    await mkdir(dirname(path), { recursive: true });
     await writeFile(
       path,
       `${JSON.stringify({ ...cached, latest, checkedAt: new Date().toISOString() }, null, 2)}\n`,
     );
   } catch {
-    // A read-only or missing .hedgehog just means no caching; the
+    // A read-only or absent .hedgehog just means no caching; the
     // answer we fetched is still good for this call.
   }
   return latest;

package/src/registry/fetch.mjs

@@ -61,9 +61,10 @@ function packSpec(entry) {
  * Resolve, extract, and read one core package.
  *
  * @param {object} entry - a cores.json entry (`name`, `package`, `version`)
- * @returns {Promise<{manifest: object, root: string, version: string}>}
- *   the parsed hedgehog-core.yaml, the directory the package extracted to,
- *   and the exact version resolved.
+ * @returns {Promise<{manifest: object, root: string, version: string,
+ *   engineAdvisory: string|null}>} the parsed hedgehog-core.yaml, the
+ *   directory the package extracted to, the exact version resolved, and a
+ *   line to print when the CLI is ahead of the core's engine line.
  */
 export async function fetchCore(entry) {
   const staged = await packAndExtract(entry);
@@ -74,9 +75,9 @@ export async function fetchCore(entry) {
   // `cores list` reports as reusable and what an offline `update` reads
   // back, so only a core this engine can actually install belongs in it —
   // a manifest that fails here throws before anything is cached.
-  let manifest;
+  let read;
   try {
-    manifest = await readManifest(staged.root, entry);
+    read = await readManifest(staged.root, entry);
   } catch (err) {
     await rm(staged.tmp, { recursive: true, force: true });
     throw err;
@@ -86,13 +87,13 @@ export async function fetchCore(entry) {
   // and now; its copy is as good as this one, so keep it and drop ours.
   if (await exists(cached)) {
     await rm(staged.tmp, { recursive: true, force: true });
-    return { manifest, root: cached, version };
+    return { ...read, root: cached, version };
   }
 
   await mkdir(join(CORE_CACHE_ROOT, entry.name), { recursive: true });
   await rename(staged.root, cached);
   await rm(staged.tmp, { recursive: true, force: true });
-  return { manifest, root: cached, version };
+  return { ...read, root: cached, version };
 }
 
 /**
@@ -104,7 +105,7 @@ export async function fetchCore(entry) {
 export async function cachedCore(entry, version) {
   const root = join(CORE_CACHE_ROOT, entry.name, version);
   if (!(await exists(join(root, MANIFEST_NAME)))) return null;
-  return { manifest: await readManifest(root, entry), root, version };
+  return { ...(await readManifest(root, entry)), root, version };
 }
 
 async function packAndExtract(entry) {
@@ -159,8 +160,12 @@ async function readManifest(root, entry) {
         `The package and the registry entry have to agree on the core's name.`,
     );
   }
-  assertEngineSatisfies(manifest, ENGINE_VERSION, `${entry.package}/${MANIFEST_NAME}`);
-  return manifest;
+  const engineAdvisory = assertEngineSatisfies(
+    manifest,
+    ENGINE_VERSION,
+    `${entry.package}/${MANIFEST_NAME}`,
+  );
+  return { manifest, engineAdvisory };
 }
 
 // npm's own failure text is a wall of registry detail; what a user can act
@@ -178,6 +183,34 @@ function unresolvableMessage(entry, spec, err) {
   );
 }
 
+/**
+ * The engine line the newest cached extraction of a core declares, or
+ * null when that core has never been fetched. `cores list` reports it so
+ * the engine line each core is written against is visible at the point a
+ * core is chosen, rather than only once an install has run.
+ */
+export async function cachedEngine(name, versions) {
+  const newest = [...versions].sort(compareVersions).pop();
+  if (!newest) return null;
+  try {
+    const text = await readFile(join(CORE_CACHE_ROOT, name, newest, MANIFEST_NAME), 'utf8');
+    return parseCoreManifest(text, `${name}/${MANIFEST_NAME}`).engine ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Orders `1.0.5` after `1.0.0` rather than before it, which a plain
+// string sort would not.
+function compareVersions(a, b) {
+  const parts = (v) => String(v).split('.').map(Number);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i += 1) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  }
+  return 0;
+}
+
 /**
  * List which versions of a core are already extracted in the cache.
  * Reported by `hedgehog cores list` so a user can see what an install

package/src/registry/manifest.mjs

@@ -137,17 +137,22 @@ export function parseCoreManifest(text, source = 'hedgehog-core.yaml') {
 /**
  * Check a core's declared `engine` range against the CLI installing it.
  *
- * A core states which engine line it installs against; an engine older
+ * A core states which engine line it installs against. An engine *older*
  * than that line writes a payload the core's own skills expect features
- * from, so the install stops here rather than part-way through.
+ * from, so the install stops here rather than part-way through. An engine
+ * *newer* than that line is a different situation: the CLI carries every
+ * feature the core asks for, plus more, so the install proceeds and the
+ * skew is reported back to the caller as an advisory instead.
  *
  * @param {object} manifest - a parsed manifest, carrying `engine`
  * @param {string} engineVersion - the CLI's own package.json `version`
  * @param {string} source - what to name in the error
+ * @returns {string|null} an advisory line when the CLI is ahead of the
+ *   core's line, `null` when the two agree
  */
 export function assertEngineSatisfies(manifest, engineVersion, source = 'hedgehog-core.yaml') {
   const required = manifest.engine;
-  if (required == null) return;
+  if (required == null) return null;
 
   const range = ENGINE_RANGE.exec(String(required).trim());
   if (!range) {
@@ -166,12 +171,12 @@ export function assertEngineSatisfies(manifest, engineVersion, source = 'hedgeho
   const [, wantMajor, wantMinor, wantPatch] = range.map(Number);
   const [, haveMajor, haveMinor, havePatch] = installed.map(Number);
 
-  // Caret semantics: the same major line, at or above the stated version.
-  const satisfied =
-    haveMajor === wantMajor &&
-    (haveMinor > wantMinor || (haveMinor === wantMinor && havePatch >= wantPatch));
+  const behind =
+    haveMajor < wantMajor ||
+    (haveMajor === wantMajor &&
+      (haveMinor < wantMinor || (haveMinor === wantMinor && havePatch < wantPatch)));
 
-  if (!satisfied) {
+  if (behind) {
     throw new Error(
       `This core needs Hedgehog ${required}, and the CLI running is ${engineVersion}.\n\n` +
         `The core's agents and skills are written against that engine line, so installing\n` +
@@ -180,4 +185,14 @@ export function assertEngineSatisfies(manifest, engineVersion, source = 'hedgeho
         `  npx @skyf0xx/hedgehog@latest init\n`,
     );
   }
+
+  if (haveMajor > wantMajor) {
+    return (
+      `This core is written against Hedgehog ${required}, and the CLI running is ${engineVersion}.\n` +
+      `Installing it anyway: a newer engine carries everything the core asks for. If the\n` +
+      `core's own skills behave oddly, that skew is the first thing to suspect.`
+    );
+  }
+
+  return null;
 }