@skyf0xx/hedgehog 6.0.2 → 6.0.3

package/README.md

@@ -202,9 +202,7 @@ Where possible, Hedgehog uses a battle-tested blueprint in [`hedgehog-core-autho
 
 ### Existing codebases
 
-Hedgehog also adopts onto existing repos.
-
-It scans the repo's shape and is able to create new changes with the same scoped, verified, committed loop.
+Hedgehog also adopts onto a repo it didn't build. It reads the repo and proposes a layer chain that verifies with the repo's own test/lint/build commands.
 
 ## Why Hedgehog Works
 
@@ -223,7 +221,7 @@ Mention `Hedgehog` whenever you want to build something with it.
 2. Check Python >=3.10 is installed — it runs [CodeGraphContext](https://github.com/CodeGraphContext/CodeGraphContext), the code index every project uses.
 3. Check CodeGraphContext is installed and configured.
 4. If anything is missing, offer to set it up with the `hedgehog-code-intelligence-setup` skill — `init` stops without it.
-5. Run the install commands above.
+5. Run the install commands below.
 
 </details>
 

package/bin/cli.mjs

@@ -80,6 +80,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 { wrapSection } from '../src/hosts/claude-md-merge.mjs';
 import {
   recordVersion,
   checkForUpdate,
@@ -88,7 +89,7 @@ import {
 } from '../src/hosts/version.mjs';
 import { loadRegistry, resolveCore } from '../src/registry/index.mjs';
 import { fetchCore, cachedCore, cachedVersions, cachedEngine } from '../src/registry/fetch.mjs';
-import { recordCore, installedCore } from '../src/registry/installed.mjs';
+import { recordCore, installedCore, ADOPTED_CORE_NAME } from '../src/registry/installed.mjs';
 
 const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 const CODE_INTELLIGENCE_CONFIG_PATH = '.hedgehog/code-intelligence.json';
@@ -472,7 +473,13 @@ async function writePlannedFile(f) {
         join(f.merge.includeRoot ?? PKG_ROOT, f.merge.include),
         'utf8',
       );
-      out = out.replaceAll('{{CORE_SECTION}}', section.trimEnd());
+      // Wrapped in the same markers appendCoreSection uses on a
+      // brownfield CLAUDE.md with no {{CORE_SECTION}} placeholder to
+      // substitute into — see src/hosts/claude-md-merge.mjs. Keeping
+      // both paths' output mutually recognizable is what lets
+      // hasCoreSection/appendCoreSection treat a template-filled file
+      // and an appended one the same way on a later re-run.
+      out = out.replaceAll('{{CORE_SECTION}}', wrapSection(section));
     }
     const dispatch = await readFile(join(PKG_ROOT, f.merge.dispatch), 'utf8');
     await writeFile(f.dest, out.replaceAll('{{HOST_DISPATCH}}', dispatch.trimEnd()));
@@ -544,6 +551,9 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --pwa-app            scaffold the pwa-app core now
   npx @skyf0xx/hedgehog init --landing-page       scaffold the landing-page core now
   npx @skyf0xx/hedgehog cores list                every core this release can install
+  npx @skyf0xx/hedgehog core record-adopted       land the authored core's agents/skills and record
+                                                   this project as adopted (hedgehog-adopt calls this
+                                                   after writing .hedgehog/core.yaml; not for other cores)
   npx @skyf0xx/hedgehog init --cursor             install for Cursor (default: Claude Code)
   npx @skyf0xx/hedgehog init --host=claude,gemini install for several coding agents at once
   npx @skyf0xx/hedgehog init --all-hosts          install for every supported coding agent
@@ -1173,6 +1183,84 @@ async function resolveInstalledCore() {
   }
 }
 
+// `hedgehog core record-adopted` — the record path for `hedgehog-adopt`
+// (shipped in @skyf0xx/hedgehog-core-authored), which brings the
+// discipline to an existing repo by writing `.hedgehog/core.yaml` and
+// `.hedgehog/adoption.md` directly. That path has no `init` step and so
+// never fetches the `authored` package or calls `recordCore` — a no-flag
+// `init` (what the offer skill actually runs before adoption) installs
+// only the shared engine payload, never a core's own agents/skills, and
+// `bootstrap` (the only other place a core package gets fetched) is
+// explicitly skipped for adoption. Left alone, `hedgehog-authored-loop`
+// and `layer-eng` — the skill and agent adoption hands off to — would
+// never land on disk, and even if they did by some other means, `update`
+// would have nothing telling it they're there: `resolveInstalledCore`
+// falls through to `detectUnrecordedCore`, which only looks for a root
+// `core.yaml` (the shipped-core workspace marker) and finds nothing for
+// an adopted repo's `.hedgehog/core.yaml`, so it would read as "no core
+// yet" and update would silently rewrite `.claude/agents`/`.claude/skills`
+// down to just the shared payload, deleting the authored package's files
+// with nothing put back.
+//
+// This command is both fixes at once: it fetches the `authored` package
+// and lands its agents/skills for every host this project already has
+// installed (never its workspace, template, or vendor_skills — adoption
+// already wrote its own CLAUDE.md section and root workspace is the one
+// thing adoption must never touch), then records the core with
+// `adopted: true` so `update` refreshes it correctly from here on.
+// Idempotent and safe to re-run — e.g. from a later `hedgehog-adopt` pass
+// adding new change-work — since it always overwrites from the current
+// package rather than merging.
+async function recordAdoptedCommand() {
+  const entry = await resolveCore(ADOPTED_CORE_NAME);
+  if (!entry) {
+    console.error(
+      `${red('authored core not in this release.')} This Hedgehog release's registry has no\n` +
+        `entry named "authored" — nothing to install. Update Hedgehog and retry.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let core;
+  try {
+    core = await fetchCore(entry);
+  } catch (err) {
+    console.error(`\n${red(bold('Core unavailable.'))} ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const targets = await installedHosts(DEST_ROOT);
+  let written = 0;
+  for (const host of targets) {
+    const h = HOSTS[host];
+    for (const payloadEntry of corePayload(core, h, { hostOnly: true })) {
+      for (const f of await plannedFiles(payloadEntry)) {
+        await writePlannedFile(f);
+        written++;
+        console.log(`  ${green('install')}  ${relative(DEST_ROOT, f.dest)}`);
+      }
+    }
+  }
+
+  await recordCore(DEST_ROOT, { name: core.manifest.name, version: core.version, adopted: true });
+
+  console.log(
+    `\n${green(bold('Adopted core recorded.'))} ${dim(
+      `${written} file(s) written for ${targets.map((h) => HOSTS[h].label).join(', ')}`,
+    )}\n`,
+  );
+  console.log(
+    dim(
+      'hedgehog-authored-loop and layer-eng are now on disk and this project is\n' +
+        'recorded as adopted — `hedgehog update` will keep them current alongside\n' +
+        "the shared engine payload, and will never treat this project's core as a\n" +
+        'name it gets to change.\n',
+    ),
+  );
+}
+
 async function dbRebuildCommand() {
   const corePath = await resolveCorePath();
   if (!corePath) {
@@ -3569,6 +3657,21 @@ function engineNote(engine) {
   return `${engine} ${dim(`— CLI is ${PKG_VERSION}`)}`;
 }
 
+// `hedgehog core record-adopted` — see recordAdoptedCommand for why this
+// exists. `cores` (plural) lists the registry; `core` (singular) acts on
+// this project's own core, so the two don't collide despite the name.
+async function coreCommand(args) {
+  const sub = args[0];
+  if (sub !== 'record-adopted') {
+    console.error(
+      `${red('Unknown core subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog core record-adopted\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  await recordAdoptedCommand();
+}
+
 // Wraps prose to `width`, indenting every line after the first so it sits
 // under the column its label opened.
 function wrapProse(text, width, indent) {
@@ -3675,6 +3778,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'core') {
+    await coreCommand(args.slice(1));
+    return;
+  }
+
   if (cmd === 'update') {
     if (args.includes('--check')) {
       await updateCheck();

package/package.json

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

package/src/db/plan.mjs

@@ -5,10 +5,11 @@
 //
 // full-stack-app and pwa-app: one task per layer per intent (an intent is
 // a domain module — see the core definition's `{module}` placeholder).
-// landing-page: one task per phase, no module axis. All three are the
-// same operation — walk a core definition's layer chain once per intent
-// — because a linear chain is the degenerate case of the layer graph
-// (spec: MVP scope item 5).
+// landing-page, deepseek-harness, and authored (whether designed from
+// scratch or adopted onto an existing repo): one task per phase/layer, no
+// module axis. All are the same operation — walk a core definition's layer
+// chain once per intent — because a linear chain is the degenerate case of
+// the layer graph (spec: MVP scope item 5).
 //
 // Layer cardinality: a layer marked `once: true` in the core definition
 // opts out of that per-intent multiplication and compiles a single task

package/src/hosts/claude-md-merge.mjs

@@ -0,0 +1,69 @@
+// Merges a core's CLAUDE.md section into a project's root instructions
+// file, for the one path where that file is not a Hedgehog shell: a
+// repo adopted onto existing, hand-written content that has no
+// {{CORE_SECTION}} placeholder at all.
+//
+// `writePlannedFile` in bin/cli.mjs (the `merge` entry kind) fills
+// {{CORE_SECTION}} by substring replacement, which requires the shell's
+// placeholder to already be present — true for every project `init`
+// ever wrote, since it always starts from src/templates/CLAUDE.md. An
+// adopted repo's CLAUDE.md predates Hedgehog entirely and carries no
+// such marker, so that replacement has nothing to replace. This module
+// is the one place that gap is closed: appending a delimited section
+// instead of substituting into one.
+//
+// Referenced by name (not substance) from hedgehog-adopt's own SKILL.md
+// in the @skyf0xx/hedgehog-core-authored package — that skill invokes
+// `appendCoreSection` the same way it already invokes `loadCore` from
+// src/db/core.mjs, via `node -e "import('<path-to-hedgehog-install>/
+// src/hosts/claude-md-merge.mjs')..."`.
+
+const MARKER_START = '<!-- hedgehog:core-section start -->';
+const MARKER_END = '<!-- hedgehog:core-section end -->';
+
+// True when `content` already carries a Hedgehog-managed section — from
+// either mechanism: the shell's own {{CORE_SECTION}} placeholder (still
+// unfilled, or already filled by writePlannedFile's substring
+// replacement — filled content stays wrapped in the same markers, so
+// this check still finds it) or this module's own appended, delimited
+// block.
+export function hasCoreSection(content) {
+  return content.includes('{{CORE_SECTION}}') || content.includes(MARKER_START);
+}
+
+// Wraps `section` (a core's CLAUDE.core.*.md content, verbatim) in the
+// stable markers that make both the substring-replace path
+// (writePlannedFile, bin/cli.mjs) and this append path idempotent and
+// mutually recognizable. Exported so writePlannedFile's {{CORE_SECTION}}
+// substitution wraps its own output the same way, rather than each path
+// hand-rolling the marker text.
+export function wrapSection(section) {
+  return `${MARKER_START}\n\n${section.trimEnd()}\n\n${MARKER_END}`;
+}
+
+// Appends `section` to `existingContent` as a clearly delimited block,
+// never touching a byte of what's already there. Idempotent: if a
+// marked section is already present, its content is replaced in place
+// (so a later `hedgehog-adopt` re-run, or a core switch, updates the
+// section without duplicating it) rather than appending a second copy.
+//
+// This is the merge path for a CLAUDE.md hedgehog-adopt's Step 5 finds
+// with no {{CORE_SECTION}} placeholder — the file predates Hedgehog and
+// was never written from src/templates/CLAUDE.md. Every file that shell
+// ever produced already has the placeholder, so that case always goes
+// through writePlannedFile's ordinary substitution instead; this
+// function is never called on that path.
+export function appendCoreSection(existingContent, section) {
+  const block = wrapSection(section);
+  const markerRe = new RegExp(
+    `${escapeRe(MARKER_START)}[\\s\\S]*?${escapeRe(MARKER_END)}`,
+  );
+  if (markerRe.test(existingContent)) {
+    return existingContent.replace(markerRe, block);
+  }
+  return `${existingContent.trimEnd()}\n\n${block}\n`;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

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

package/src/registry/cores.json

@@ -4,7 +4,7 @@
       "name": "full-stack-app",
       "flag": "--ts-full-stack-app",
       "package": "@skyf0xx/hedgehog-core-full-stack-app",
-      "version": "^1.0.0",
+      "version": "^1.0.6",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-full-stack-app",
       "selects_when": "The description names server-side logic across most of the app: authorization more expressive than per-object row-level security, background jobs, scheduled work or webhook receivers as the app's primary function, server-rendered or SEO-critical pages beyond an app shell, or a data model whose working set doesn't sensibly fit on a device. Persistent domain data alone is not the signal — a tracker, journal, notebook, or planner whose data fits on the user's device is pwa-app, even with sharing, accounts, or multi-device sync in scope, and even with one or two entities that must be server-authoritative. If the project has both a marketing page and a real app behind it, this is still full-stack-app: the page becomes routes inside apps/web, not a separate project."
@@ -13,7 +13,7 @@
       "name": "pwa-app",
       "flag": "--pwa-app",
       "package": "@skyf0xx/hedgehog-core-pwa-app",
-      "version": "^1.0.0",
+      "version": "^1.0.4",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-pwa-app",
       "selects_when": "The description names an app whose data model fits on the user's device and whose reads and writes are the user's own — a tracker, journal, notebook, planner, offline reference, or utility. Offline capability or installability named explicitly is a strong signal. Sharing, collaboration, accounts, and multi-device sync do NOT disqualify a project: Dexie Cloud provides sync, authentication, and server-enforced per-object access control, so a shared list, a family calendar, or a small team's board is still this core. A small number of entities that must be server-authoritative — a points balance, a reward ledger, anything a client must not write to directly — do NOT disqualify a project either: those entities are declared --remote and backed by Supabase (Postgres + RLS + Edge Functions) behind the same repository interface, while the rest of the app stays local-first. What routes a project to full-stack-app is server-side logic across most of the app, not the presence of one or two such entities: authorization beyond row-level policies, background jobs or webhooks as the app's primary function, server-rendered pages, or a working set too large for a device."
@@ -22,7 +22,7 @@
       "name": "landing-page",
       "flag": "--landing-page",
       "package": "@skyf0xx/hedgehog-core-landing-page",
-      "version": "^1.0.0",
+      "version": "^1.0.2",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-landing-page",
       "selects_when": "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 into a third-party form service, or has no state at all, qualifies. The bar is \"no domain module\" — a landing page with a dozen sections is still landing-page, not promoted to full-stack-app for being long."
@@ -31,7 +31,7 @@
       "name": "deepseek-harness",
       "flag": "--deepseek-harness",
       "package": "@skyf0xx/hedgehog-core-deepseek-harness",
-      "version": ">=0.1.0 <1.0.0",
+      "version": ">=0.2.3 <1.0.0",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-deepseek-harness",
       "selects_when": "The description names building a plugin, tool, hook, or extension for DeepSeek Harness (DSH) — a Cordis-based agent framework — or otherwise extending an existing DSH installation with new capabilities via its plugin/bundle system. Concrete signals: DSH, DeepSeek Harness, Cordis, `defineTool`, `ctx.tools.register`, a `cordis.patch.yml` manifest, or a request to add a tool that a DSH agent can call. This is the core most often confused with authored: authored fits when no shipped core matches and the planner must design a system shape from scratch, but a DSH plugin already has a fixed, battle-tested shape (the six-layer scaffold → logic → wiring → smoke → bundle → join sequence, one plugin per intent) that authored's from-scratch design would only reinvent worse. Route here whenever the target of the work is a DSH plugin, not a general \"no other core fits\" fallback."
@@ -39,7 +39,7 @@
     {
       "name": "authored",
       "package": "@skyf0xx/hedgehog-core-authored",
-      "version": "^1.0.0",
+      "version": "^1.0.2",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-authored",
       "selects_when": "Neither shipped core fits, but the description names a real artifact a Builder step would produce — just not in either shipped core's shape. This core is designed by the planner rather than chosen from a fixed set: hedgehog-planning-intake's Phase 0 elicits the drivers first, then hedgehog-core-design names the system shape, picks the stack, derives the layers, and writes .hedgehog/core.yaml. It carries the same enforcement as a shipped core — ordered layers, scoped file access, verification before completion — but the sequence is designed for this project rather than battle-tested across many."

package/src/registry/index.mjs

@@ -1,14 +1,16 @@
 // Core package registry. One entry per Hedgehog core — full-stack-app,
-// pwa-app, landing-page, authored — naming the npm package that ships its
-// agents, skills, and (for the three shipped cores) scaffold, plus the CLI
-// flag `hedgehog init` accepts for it and the prose `planner` reads aloud
-// in Phase 0 to choose one. A fixed table, one entry per core, discovered
-// by name or flag rather than convention.
+// pwa-app, landing-page, deepseek-harness, and authored — naming the npm
+// package that ships its agents, skills, and (for the first four) scaffold,
+// plus the CLI flag `hedgehog init` accepts for it and the prose `planner`
+// reads aloud in Phase 0 to choose one. A fixed table, one entry per core,
+// discovered by name or flag rather than convention.
 //
 // `authored` carries no flag — it is never selected off a fixed list at
-// install time. hedgehog-core-design chooses it during planning, from the
-// drivers hedgehog-planning-intake's Phase 0 elicits, not from a value a
-// user passes to `init`.
+// install time. hedgehog-core-design chooses it during planning (from-scratch
+// design path), or hedgehog-adopt brings it to an existing repo (brownfield
+// adoption path), from the drivers hedgehog-planning-intake's Phase 0 elicits
+// or the repo characteristics adoption discovers, not from a value a user
+// passes to `init`.
 
 import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';

package/src/registry/installed.mjs

@@ -6,34 +6,62 @@
 // install time has nothing recorded until its bootstrap-core skill lands
 // the core — `installedCore` returns null until then, and `update` limits
 // itself to the shared payload.
+//
+// `authored` has a second entry point with no `init` step at all:
+// `hedgehog-adopt` brings the discipline to a repo that already exists by
+// writing `.hedgehog/core.yaml` itself, directly, and never calls
+// `recordCore` (see that skill, shipped in
+// @skyf0xx/hedgehog-core-authored — adoption has no npm package of its
+// own to fetch, just a core.yaml and adoption.md derived from the
+// existing repo). `hedgehog core record-adopted` (bin/cli.mjs) is the
+// record path for that case instead: it lands the authored package's
+// agents/skills — otherwise never installed, since adoption's `init` runs
+// with no `--core` flag and `bootstrap` is skipped entirely for adoption
+// — and calls `recordCore` with `adopted: true`. That flag is the one
+// thing distinguishing an adopted record from a normal one: `update`'s
+// resolveInstalledCore refreshes an adopted project's payload the same as
+// any other (same package, same agents/skills, kept current) but must
+// never treat `record.name` changing upstream, or the record going
+// missing, as license to fetch and install a *different* core the way it
+// would for a project that chose one at `init` — adoption's core is a
+// fixed fact of the repo (its `.hedgehog/core.yaml`), not a choice
+// `update` gets to revisit.
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
+export const ADOPTED_CORE_NAME = 'authored';
+
 const CORE_PATH = '.hedgehog/core.json';
 
 /**
  * Record the core a project installed and the exact version resolved for
  * it. Written after the core's files land, so the record describes what
- * is on disk.
+ * is on disk. `adopted: true` marks a record written by `hedgehog core
+ * record-adopted` rather than by `init` — see the module comment above.
  */
-export async function recordCore(root, { name, version }) {
+export async function recordCore(root, { name, version, adopted = false }) {
   const path = join(root, CORE_PATH);
   await mkdir(dirname(path), { recursive: true });
   await writeFile(
     path,
-    `${JSON.stringify({ core: name, version, installedAt: new Date().toISOString() }, null, 2)}\n`,
+    `${JSON.stringify(
+      { core: name, version, installedAt: new Date().toISOString(), ...(adopted ? { adopted: true } : {}) },
+      null,
+      2,
+    )}\n`,
   );
 }
 
 /**
- * The core `update` should refresh — `{ name, version }` — or null when
- * this project has no core installed yet.
+ * The core `update` should refresh — `{ name, version, adopted }` — or
+ * null when this project has no core installed yet. `adopted` is always a
+ * boolean, `false` for every record `init` writes.
  */
 export async function installedCore(root) {
   try {
-    const { core, version } = JSON.parse(await readFile(join(root, CORE_PATH), 'utf8'));
-    return core ? { name: core, version } : null;
+    const { core, version, adopted } = JSON.parse(await readFile(join(root, CORE_PATH), 'utf8'));
+    return core ? { name: core, version, adopted: adopted === true } : null;
   } catch {
     return null;
   }