@skyf0xx/hedgehog 4.3.4 → 4.4.0

package/bin/cli.mjs

@@ -50,6 +50,7 @@ import { rebuildDb } from '../src/db/rebuild.mjs';
 import { loadOverrides, addOverride, orphanedOverrides, OVERRIDES_DIR } from '../src/db/overrides.mjs';
 import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
 import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
+import { recordVersion, checkForUpdate, installedVersion } from '../src/hosts/version.mjs';
 
 const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 
@@ -65,6 +66,12 @@ const DEST_ROOT = process.cwd();
 const CORES_ROOT = join(PKG_ROOT, 'src/golden-cores');
 const DEFAULT_CORE = 'full-stack-app';
 
+// The version of the payload this CLI carries — what `init` and
+// `update` stamp into the project they write to.
+const PKG_VERSION = JSON.parse(
+  await readFile(join(PKG_ROOT, 'package.json'), 'utf8'),
+).version;
+
 // One install flag per core, named for what a user is asking to build
 // rather than the internal src/golden-cores/<name> directory — the two
 // diverge deliberately so the CLI's public surface can stay stable
@@ -384,6 +391,7 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --all-hosts          install for every supported coding agent
   npx @skyf0xx/hedgehog init --force              overwrite existing files
   npx @skyf0xx/hedgehog update                    refresh the installed agents + skills
+  npx @skyf0xx/hedgehog update --check            report whether a newer release is published
   npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
   npx @skyf0xx/hedgehog db rebuild                re-derive the build graph from committed intents + git history
   npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies
@@ -449,6 +457,15 @@ those directories. The instructions file, the build graph, the core
 workspace, and vendor-skills/BMAD and vendor-skills/GSAP stay as they
 are — those are project-specific or updated deliberately, not by this
 command.
+
+Both ${bold('init')} and ${bold('update')} stamp the version they wrote into
+.hedgehog/version.json. ${bold('update --check')} compares that stamp against
+the newest published release and exits 1 when a newer one exists, without
+writing anything. The same comparison rides on ${bold('status')} and
+${bold('next')} as a one-line notice, from a once-a-day cached lookup, so a
+stale project surfaces itself; set HEDGEHOG_NO_UPDATE_CHECK=1 to silence it.
+Run ${bold('npx @skyf0xx/hedgehog@latest update')} to pull a newer release —
+the @latest tag matters, since a bare npx may reuse a cached older CLI.
 `);
 }
 
@@ -500,6 +517,7 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
   // Recorded before anything is written: the routing doc is generated
   // from this list, so it has to already name the host being installed.
   await recordHosts(DEST_ROOT, [host]);
+  await recordVersion(DEST_ROOT, PKG_VERSION);
 
   let written = 0;
   let overwritten = 0;
@@ -548,31 +566,22 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
     );
     console.log(dim('     instead of polling tightly or narrating the wait.'));
     console.log(`  2. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
-    console.log(
-      `  3. Start a ${bold('new')} ${HOSTS[host].label} session and describe what you want to build.`,
-    );
+    console.log(`  3. Describe what you want to build.`);
   } else {
     console.log(`  1. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
-    console.log(
-      `  2. Start a ${bold('new')} ${HOSTS[host].label} session and describe what you want to build.`,
-    );
-  }
-  console.log(
-    dim(
-      `     The ${bold('planner')} agent runs planning intake, then hands off to bootstrap.`,
-    ),
-  );
-  // A host enumerates its agents once, at session start. This install just
-  // wrote them mid-session, so in THIS session they are not dispatchable —
-  // and the failure is worse than a plain error: names like `planner` and
-  // `reviewer` often resolve to the user's own unrelated global agents,
-  // silently running a different discipline instead of erroring.
+    console.log(`  2. Describe what you want to build.`);
+  }
+  // Hand off by path, not by name. Reading the file works on every host in
+  // the session that ran this install — no restart, no dependence on whether
+  // the harness re-scans its agent directory, and no chance of a bare
+  // `planner` resolving to an unrelated global agent of the same name.
+  const agents = HOSTS[host].agentsDir;
+  const skills = HOSTS[host].skillsDir;
   console.log(
     dim(
-      `     A new session matters: ${HOSTS[host].label} lists its agents at startup, so the\n` +
-        '     ones just installed are not dispatchable in the session that ran this.\n' +
-        '     If a handoff must happen here anyway, read the agent file and follow it\n' +
-        '     inline rather than dispatching to a name that may resolve elsewhere.',
+      `     Read ${bold(`${agents}/planner.md`)} and follow it — it runs planning\n` +
+        `     intake (${skills}/hedgehog-planning-intake/SKILL.md), then hands\n` +
+        `     off to ${agents}/bootstrap.md.`,
     ),
   );
   console.log();
@@ -597,6 +606,42 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
   }
 }
 
+// `update --check` answers the question without acting on it: what's
+// installed, what's published, and whether they differ. Exit code 0 when
+// current or unknown, 1 when an update is available, so a script or a
+// host's own tooling can branch on it without parsing the output.
+async function updateCheck() {
+  const { installed, latest, stale } = await checkForUpdate(DEST_ROOT, {
+    force: true,
+  });
+
+  if (!installed) {
+    console.log(
+      `${yellow('Installed version unknown.')} ${dim(
+        'This project predates version stamping — run `hedgehog update` to refresh and stamp it.',
+      )}\n`,
+    );
+    return;
+  }
+  if (!latest) {
+    console.log(
+      `Installed: ${bold(installed)}\n${dim(
+        "Couldn't reach the npm registry — no update check performed.",
+      )}\n`,
+    );
+    return;
+  }
+  if (stale) {
+    console.log(
+      `${yellow(bold('Update available.'))} installed ${bold(installed)} → latest ${bold(latest)}\n\n` +
+        `  Run ${bold('npx @skyf0xx/hedgehog@latest update')} to refresh this project's agents and skills.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`${green('Up to date.')} ${dim(`installed ${installed}, latest ${latest}`)}\n`);
+}
+
 async function update({ hosts }) {
   const targets = hosts?.length ? hosts : await installedHosts(DEST_ROOT);
 
@@ -623,10 +668,19 @@ async function update({ hosts }) {
     }
   }
 
+  // Stamped after the writes land, so the recorded version always
+  // describes the payload actually on disk.
+  const previous = await installedVersion(DEST_ROOT);
+  await recordVersion(DEST_ROOT, PKG_VERSION);
+
   const label = targets.map((h) => HOSTS[h].label).join(', ');
+  const versionNote =
+    previous && previous !== PKG_VERSION
+      ? `${previous} → ${PKG_VERSION}`
+      : PKG_VERSION;
   console.log(
     `\n${green(bold('Hedgehog agents/skills updated.'))} ${dim(
-      `${written} files written for ${label}`,
+      `${versionNote} — ${written} files written for ${label}`,
     )}\n`,
   );
   console.log('Next steps:');
@@ -1113,6 +1167,34 @@ function warnSingularModuleIdsAtPlan(core, db) {
   );
 }
 
+// The passive half of update detection. Printed to stderr, after a
+// command's real output, on the commands every host's loop runs anyway —
+// so a stale project surfaces itself without anyone thinking to ask.
+//
+// This lives in the CLI rather than in any one host's hook because every
+// host drives the same binary: Claude Code, Cursor, and Gemini CLI all
+// reach it through `hedgehog next`, and one implementation here covers
+// all of them.
+//
+// Never throws and never blocks: the answer comes from a day-long cache,
+// a missing or unreachable registry reads as "no news", and the notice is
+// skipped entirely when output isn't a terminal so it can't corrupt
+// anything parsing stdout.
+async function noteAvailableUpdate() {
+  if (process.env.HEDGEHOG_NO_UPDATE_CHECK) return;
+  try {
+    const { installed, latest, stale } = await checkForUpdate(DEST_ROOT);
+    if (!stale) return;
+    console.error(
+      `\n${yellow(bold('Hedgehog update available.'))} ${dim(
+        `${installed} → ${latest}. Run \`npx @skyf0xx/hedgehog@latest update\` to refresh this project's agents and skills.`,
+      )}`,
+    );
+  } catch {
+    // Advisory only — a failed check is never worth failing a command over.
+  }
+}
+
 async function nextCommand() {
   await ensureDb();
 
@@ -1149,6 +1231,7 @@ async function nextCommand() {
       return;
     }
     console.log(`${dim('No ready task.')} Nothing is planned with all dependencies complete.\n`);
+    await noteAvailableUpdate();
     return;
   }
 
@@ -1165,6 +1248,7 @@ async function nextCommand() {
   }
 
   console.log(formatNext(packet, await resolveCoreId(), packetExists));
+  await noteAvailableUpdate();
 }
 
 function printStalledTasks(stalled) {
@@ -1834,6 +1918,8 @@ async function statusCommand() {
 
   const warningLines = await coreWarningLines();
   if (warningLines.length > 0) console.log(warningLines.join('\n'));
+
+  await noteAvailableUpdate();
 }
 
 // `hedgehog ready` — read-only preview of what a `hedgehog claim` call
@@ -2450,6 +2536,10 @@ async function main() {
   }
 
   if (cmd === 'update') {
+    if (args.includes('--check')) {
+      await updateCheck();
+      return;
+    }
     await update({ hosts });
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.3.4",
+  "version": "4.4.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/planner.md

@@ -87,7 +87,12 @@ and the scaffolded workspace.
   real app beyond a single page. If in doubt between this and
   landing-page because the project has *both* a marketing page and a
   real app behind it, this is `full-stack-app` — the page becomes routes
-  inside `apps/web`, not a separate project.
+  inside `apps/web`, not a separate project. Data that gets stored is
+  this core, at any size: a todo list, a notes app, a tracker of any
+  kind. Never talk the user down to browser-local storage, an in-memory
+  array, or a single-file page because the app sounds small, and never
+  offer that as a quicker start — the core ships a real database, and
+  reaching for less is the drift this discipline exists to prevent.
 - **`landing-page`** — the description is a marketing/announcement/
   waitlist/portfolio page (or a small handful of such pages) with no
   persistent domain data of its own. A page that only collects an email

package/src/hosts/version.mjs

@@ -0,0 +1,154 @@
+// What version of the payload a project has, and whether a newer one exists.
+//
+// `init` and `update` stamp the version they wrote into
+// `.hedgehog/version.json`. Without that stamp a project's installed
+// agents and skills are indistinguishable from any other release's, so
+// staleness can only be discovered by reading the files themselves.
+//
+// The registry lookup is cached and best-effort: a project that can't
+// reach npm, or is offline entirely, gets no answer rather than an error.
+// Nothing here is on the path of any command that has real work to do.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+const VERSION_PATH = '.hedgehog/version.json';
+const REGISTRY_URL = 'https://registry.npmjs.org/@skyf0xx/hedgehog/latest';
+
+// How long a registry answer stays good. The payload ships daily, so a
+// once-a-day question matches how often the answer can actually change,
+// and keeps a session that runs many commands to a single network call.
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+// The check is advisory — it must never delay a command that has real
+// work to do, so a registry that hangs is treated the same as one that
+// says nothing.
+const FETCH_TIMEOUT_MS = 1500;
+
+/**
+ * Record the payload version now installed in `root`. Called by both
+ * `init` and `update`, so the stamp tracks the payload on disk rather
+ * than whichever release first landed.
+ */
+export async function recordVersion(root, version) {
+  const path = join(root, VERSION_PATH);
+  const prior = await readVersionFile(root);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(
+    path,
+    `${JSON.stringify({ ...prior, version, installedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+  return version;
+}
+
+async function readVersionFile(root) {
+  try {
+    return JSON.parse(await readFile(join(root, VERSION_PATH), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The payload version installed in `root`, or null for a project
+ * installed before the stamp existed.
+ */
+export async function installedVersion(root) {
+  const { version } = await readVersionFile(root);
+  return typeof version === 'string' ? version : null;
+}
+
+/**
+ * Compare two semver strings. Returns true when `a` is strictly newer
+ * than `b`. Prerelease tags sort before their release, matching semver;
+ * anything unparseable compares as equal so a malformed version can
+ * never fabricate an update prompt.
+ */
+export function isNewer(a, b) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v ?? '').trim());
+    return m
+      ? { nums: [+m[1], +m[2], +m[3]], pre: m[4] ?? null }
+      : null;
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i];
+  }
+  // Equal release numbers: a release outranks its own prereleases.
+  if (pa.pre === pb.pre) return false;
+  if (pa.pre === null) return true;
+  if (pb.pre === null) return false;
+  return pa.pre > pb.pre;
+}
+
+/**
+ * The newest published version, from cache when it's fresh and from the
+ * registry otherwise. Returns null on any failure — offline, timeout,
+ * rate limit, malformed response. A null answer means "don't know", and
+ * every caller treats that as "say nothing".
+ */
+export async function latestVersion(root, { force = false } = {}) {
+  const cached = await readVersionFile(root);
+  if (!force && cached.checkedAt && cached.latest) {
+    const age = Date.now() - Date.parse(cached.checkedAt);
+    if (age >= 0 && age < CACHE_TTL_MS) return cached.latest;
+  }
+
+  const latest = await fetchLatest();
+  if (!latest) return null;
+
+  // Cache alongside the install stamp rather than in a separate file, so
+  // one read answers both halves of the question.
+  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
+    // answer we fetched is still good for this call.
+  }
+  return latest;
+}
+
+async function fetchLatest() {
+  try {
+    // No `accept` header. The abbreviated-metadata type
+    // (application/vnd.npm.install-v1+json) is only valid on the
+    // packument root — sending it to /latest returns 406, which this
+    // function would swallow as "no answer" and the check would
+    // silently never fire. Plain /latest returns just the one version
+    // object, which is also far smaller than the full packument.
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const { version } = await res.json();
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The full staleness picture for a project: what's installed, what's
+ * published, and whether the gap is worth telling anyone about.
+ *
+ * `stale` is true only when both versions are known and the published
+ * one is newer — an unknown on either side reads as "no", so a project
+ * installed before stamping and an offline machine both stay quiet.
+ */
+export async function checkForUpdate(root, { force = false } = {}) {
+  const installed = await installedVersion(root);
+  const latest = await latestVersion(root, { force });
+  return {
+    installed,
+    latest,
+    stale: Boolean(installed && latest && isNewer(latest, installed)),
+  };
+}

package/src/templates/CLAUDE.md

@@ -38,20 +38,19 @@ Lock and the `bootstrap` handoff. This same rule holds at every later
 handoff to a newly-installed agent or skill in this session: read its
 file, don't assume its content.
 
-Dispatch is the part that can't be worked around by reading. A host lists
-its agents once, at session start, and this install wrote them after
-that — so in this session `bootstrap` and the rest may not be
-dispatchable at all. Two symptoms, and neither means a broken install:
-an error naming the available agents without Hedgehog's in it, or —
-worse, because it has no symptom — a name like `planner` or `reviewer`
-silently resolving to the user's own unrelated global agent and running a
-different discipline. If either happens, read the agent's file from
-`.claude/agents/` and follow it inline here; each one is self-contained.
-Everything delegates normally from the next session on, which is why the
-installer's next step is to start a fresh one. Don't re-explain the discipline or summarize this
-file; the greeting is one line, not a tour. Skip this entirely once the
-placeholder is filled in — every later session starts with `hedgehog
-status`, not a greeting.
+The build continues in this session — nothing here needs a restart. Hosts
+differ in whether they pick up agents written mid-session, so prefer
+reading an agent's file from `.claude/agents/` and following it inline;
+each one is self-contained, and that path works everywhere. Reading also
+avoids the quiet failure of dispatch by name, where `planner` or
+`reviewer` resolves to the user's own unrelated global agent and runs a
+different discipline with no symptom. If a dispatch does error with a
+list of available agents that omits Hedgehog's, that is the same case —
+read the file and carry on.
+
+Don't re-explain the discipline or summarize this file; the greeting is
+one line, not a tour. Skip this entirely once the placeholder is filled
+in — every later session starts with `hedgehog status`, not a greeting.
 
 ## How to work here
 
@@ -86,6 +85,16 @@ loop) is what a generic skill pack has no notion of, and running one
 alongside Hedgehog's own skills produces work that bypasses the very
 discipline this file describes.
 
+**Build through the loop, including when the work looks too small to need
+it.** A task that seems like a quick edit is not a reason to skip the
+graph, the step sequence, or the gate — scope grows, and the shortcut is
+what turns a small change into debt the next step has to work around.
+Don't propose going around the discipline to save a step, and don't treat
+a user's impatience as license to: say what the loop's next step is and
+take it. Where a rule genuinely conflicts with what the user is asking
+for, name the conflict and let them decide — never resolve it by quietly
+taking the faster path.
+
 {{CORE_SECTION}}
 
 ## Consuming the graph