@skyf0xx/hedgehog 6.1.0 → 6.1.2

package/bin/cli.mjs

@@ -424,6 +424,17 @@ async function writePlannedFile(f) {
       const existing = await readFile(f.dest, 'utf8');
       if (!existing.includes('{{PROJECT_NAME}}') && existing.includes('{{CORE_SECTION}}')) {
         out = existing;
+      } else if (!existing.includes('{{PROJECT_NAME}}') && !f.merge.include) {
+        // Brownfield: hand-written content that predates Hedgehog, with
+        // no shell markers at all, on the coreless deferred path (no
+        // `include` — there's no core section yet to fill in). Nothing
+        // to merge in here; the file is untouched until `hedgehog-adopt`
+        // later appends its own core section via appendCoreSection
+        // (src/hosts/claude-md-merge.mjs). Overwriting it with the
+        // greenfield shell, or even just filling {{HOST_DISPATCH}} into
+        // it, would assert a fresh-install shape onto a repo that isn't
+        // new.
+        return;
       }
     }
     if (out === null) out = await readFile(join(PKG_ROOT, f.merge.shell), 'utf8');
@@ -688,11 +699,26 @@ async function init({ force, core, host = DEFAULT_HOST, hostOnly = false, global
   // the project, so rewriting it loses nothing and never counts as a
   // conflict — that's what lets a second host be added to a project the
   // first one already set up.
+  //
+  // A deferred (coreless) install's root-instructions merge is exempted
+  // too, but only when the existing file is a brownfield one: hand-written
+  // content with no {{PROJECT_NAME}} shell marker. That file was never a
+  // Hedgehog shell to overwrite — writePlannedFile leaves it untouched,
+  // for hedgehog-adopt's own merge step to append its delimited core
+  // section into later (src/hosts/claude-md-merge.mjs), once a core is
+  // actually known. A file still carrying {{PROJECT_NAME}} (a previous
+  // deferred init's untouched shell) is not brownfield content and keeps
+  // hitting the ordinary conflict/--force path below.
   const conflicts = [];
   for (const { entry, files } of groups) {
     if (entry.type === 'generated') continue;
     for (const f of files) {
-      if (await exists(f.dest)) conflicts.push(f.dest);
+      if (!(await exists(f.dest))) continue;
+      if (core === null && f.merge) {
+        const existing = await readFile(f.dest, 'utf8');
+        if (!existing.includes('{{PROJECT_NAME}}')) continue;
+      }
+      conflicts.push(f.dest);
     }
   }
 
@@ -719,7 +745,15 @@ async function init({ force, core, host = DEFAULT_HOST, hostOnly = false, global
   for (const { files } of groups) {
     for (const f of files) {
       const already = await exists(f.dest);
+      // Brownfield CLAUDE.md on the coreless path: writePlannedFile
+      // leaves it untouched (see its own comment) rather than overwriting
+      // it, so this write must not be logged or counted as one.
+      const before = already && f.merge ? await readFile(f.dest, 'utf8') : null;
       await writePlannedFile(f);
+      if (before !== null && (await readFile(f.dest, 'utf8')) === before) {
+        console.log(`  ${dim('keep')}  ${relative(DEST_ROOT, f.dest)}`);
+        continue;
+      }
       if (already) overwritten++;
       else written++;
       const label = already ? yellow('overwrite') : green('create');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.1.0",
+  "version": "6.1.2",
   "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

@@ -202,9 +202,11 @@ none of them is a description matching a `when` paragraph:
   enforcement on my changes here"). This is a distinct question from
   everything above: it's not about which core fits new work, because no
   new workspace gets built at all. This project gets the **adopted
-  core**. Route straight to `hedgehog-adopt` — bootstrap and every other
-  Phase 0 outcome are skipped entirely, since there is no workspace to
-  scaffold and no shipped stack to adopt toward. `hedgehog-adopt` runs
+  core**. Run `hedgehog core record-adopted` first — a no-flag `init`
+  never fetched the `adopted` package, so `hedgehog-adopt` is not yet on
+  disk to route to — then route to `hedgehog-adopt`. Bootstrap and every
+  other Phase 0 outcome are skipped entirely, since there is no workspace
+  to scaffold and no shipped stack to adopt toward. `hedgehog-adopt` runs
   its own read-only intake and writes its own `.hedgehog/core.yaml`;
   don't run `hedgehog-planning-intake`'s BMAD shelf first — the drivers
   that skill elicits (persistence, stack, deployment target) are already
@@ -389,18 +391,23 @@ as full-stack-app's Auth/Queue/Mobile trio.
      run.** Continue at step 3.
    - **No intents in the graph, and the request is adoption onto an
      existing repo → brownfield first run.** Skip Phase 0's core
-     selection and every step below through step 9 — go straight to
-     `hedgehog-adopt`. It runs its own intake and Confirm & Lock, writes
-     `.hedgehog/core.yaml` and `.hedgehog/adoption.md`, and adds the
-     first intent(s) itself. Return the summary (step 10) once it's done.
+     selection and every step below through step 9. Run `hedgehog core
+     record-adopted` first — a no-flag `init` never fetched the
+     `adopted` package, so `hedgehog-adopt` is not yet on disk — then go
+     straight to `hedgehog-adopt`. It runs its own intake and Confirm &
+     Lock, writes `.hedgehog/core.yaml` and `.hedgehog/adoption.md`, and
+     adds the first intent(s) itself. Return the summary (step 10) once
+     it's done.
    - **One or more intents, on `.hedgehog/core.yaml` written by
      `hedgehog-adopt` → adoption re-entry.** New change-work on a repo
-     already under adoption. Skip steps 3 through 9 — route straight to
-     `hedgehog-adopt` again instead, same as brownfield first run above.
-     It owns everything the other path's steps 5, 7, 8, and 9 would
-     otherwise do: it sizes the request (a large or ambiguous one gets its
-     own short clarifying pass, a clear small one doesn't), adds the
-     intent(s), runs `hedgehog plan`, and commits its own work as `chore
+     already under adoption. Skip steps 3 through 9. Run `hedgehog core
+     record-adopted` first — safe and idempotent to re-run, and the only
+     guarantee that `hedgehog-adopt` is on disk in this session — then
+     route straight to `hedgehog-adopt` again, same as brownfield first
+     run above. It owns everything the other path's steps 5, 7, 8, and 9
+     would otherwise do: it sizes the request (a large or ambiguous one
+     gets its own short clarifying pass, a clear small one doesn't), adds
+     the intent(s), runs `hedgehog plan`, and commits its own work as `chore
      (planning): adopt change`. Don't run `hedgehog-planning-intake`'s
      Re-entry pass here — there is no BMAD archive to read as context on
      this path, since adoption never runs one. Return the summary (step

package/src/db/core.mjs

@@ -180,9 +180,16 @@ function indentOf(line) {
   return line.length - line.trimStart().length;
 }
 
+// The only values `pattern` may declare — named in every rejection
+// message below, so a typo surfaces the valid set instead of silently
+// degrading to "unset" (which would turn conformance checking off with
+// no signal that anything is wrong).
+const VALID_PATTERNS = ['hexagonal', 'layered', 'vertical-slice', 'none'];
+
 // Parses the narrow subset of YAML a core definition needs:
 //   id: <scalar>
 //   pluralizes: <bool>            # optional, default true
+//   pattern: <scalar>             # optional, one of hexagonal|layered|vertical-slice|none
 //   layers:
 //     - id: <scalar>
 //       depends_on: <scalar>          # optional
@@ -202,7 +209,7 @@ export function parseCoreYaml(text) {
     lines.push({ indent: indentOf(noComment), text: noComment.trim() });
   }
 
-  const core = { id: undefined, pluralizes: true, layers: [] };
+  const core = { id: undefined, pluralizes: true, pattern: null, layers: [] };
   let i = 0;
 
   while (i < lines.length && lines[i].indent === 0) {
@@ -224,6 +231,21 @@ export function parseCoreYaml(text) {
     // advisory stops firing on it for good, rather than every user of
     // that core re-discovering the same false positive.
     if (key === 'pluralizes') core.pluralizes = parseScalar(value) === 'true';
+    // An architecture claim, checked by validateCore below — see that
+    // function's pattern-conformance block for what each value asserts.
+    // Rejected here, at parse time, rather than left to validateCore:
+    // an unrecognized value must never silently resolve to "unset" (the
+    // one value that turns conformance checking off), so a typo has to
+    // surface as a parse error, not a quietly-skipped check.
+    if (key === 'pattern') {
+      const declared = parseScalar(value);
+      if (!VALID_PATTERNS.includes(declared)) {
+        throw new Error(
+          `unknown pattern "${declared}" — must be one of: ${VALID_PATTERNS.join(', ')}`,
+        );
+      }
+      core.pattern = declared;
+    }
     i++;
   }
 
@@ -498,6 +520,132 @@ export function isModuleAxis(core) {
   return core.layers.some((layer) => layer.scope.join('').includes('{module}'));
 }
 
+// `layered`'s and `hexagonal`'s checks both anchor on "the head layer" —
+// the first-declared layer, by the same convention `core.layers[0]`
+// already carries informally everywhere else in this file (e.g. the
+// once-layer checks below walk `core.layers` in declaration order too).
+function headLayer(core) {
+  return core.layers[0];
+}
+
+// `pattern: layered` — a strict linear chain: every layer but the head
+// depends on exactly one other, no two layers share a depends_on parent
+// (that would be branching, not a chain), and every layer is reachable
+// from the head by walking depends_on forward. Throws naming the first
+// layer that breaks the shape, in the order the checks below run.
+function checkLayeredPattern(core) {
+  const head = headLayer(core);
+  const rest = core.layers.filter((layer) => layer.id !== head.id);
+
+  for (const layer of rest) {
+    if (!layer.depends_on) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but layer "${layer.id}" has no depends_on — every layer but the head ("${head.id}") must depend on exactly one other layer`,
+      );
+    }
+  }
+
+  const dependents = new Map(); // parent layer id -> the one layer that depends on it
+  for (const layer of rest) {
+    const prior = dependents.get(layer.depends_on);
+    if (prior) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but both "${prior}" and "${layer.id}" depend on "${layer.depends_on}" — a layered chain is linear, one dependent per layer`,
+      );
+    }
+    dependents.set(layer.depends_on, layer.id);
+  }
+
+  // Walk forward from the head (parent -> its one dependent) and confirm
+  // every layer gets visited. This also catches a chain disconnected from
+  // the head entirely — e.g. two layers depending on each other with
+  // neither reachable from the head — which the checks above don't rule
+  // out on their own: each layer still has exactly one depends_on and no
+  // parent is shared, they just never connect back to "${head.id}".
+  const visited = new Set([head.id]);
+  let current = head;
+  while (dependents.has(current.id)) {
+    current = core.layers.find((layer) => layer.id === dependents.get(current.id));
+    visited.add(current.id);
+  }
+  for (const layer of core.layers) {
+    if (!visited.has(layer.id)) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but layer "${layer.id}" is not reachable from the head layer "${head.id}" by following depends_on`,
+      );
+    }
+  }
+}
+
+// `pattern: hexagonal` — Hedgehog has no adapter marker today, so this
+// checks direction alone rather than an actual domain/adapter boundary:
+// the head layer (the domain, by convention) must have no depends_on, and
+// every other layer's depends_on chain must terminate at the head with no
+// cycle — i.e. dependencies all point one way, inward, and the head is the
+// sink every chain ends at. Weaker than the real hexagonal rule (nothing
+// stops an adapter depending on another adapter instead of the domain
+// directly), and deliberately so — see #314's "Not in this issue" for why
+// a real adapter-boundary marker is a separate design decision.
+function checkHexagonalPattern(core) {
+  const head = headLayer(core);
+  if (head.depends_on) {
+    throw new Error(
+      `core "${core.id}" declares pattern: hexagonal, but its head layer "${head.id}" has a depends_on — the domain layer must be the sink every dependency chain points to, not itself a dependent`,
+    );
+  }
+
+  const byId = new Map(core.layers.map((layer) => [layer.id, layer]));
+  for (const layer of core.layers) {
+    if (layer.id === head.id) continue;
+    if (!layer.depends_on) {
+      throw new Error(
+        `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}" has no depends_on — only the domain layer ("${head.id}") may have none`,
+      );
+    }
+    const seen = new Set([layer.id]);
+    let current = layer;
+    while (current.depends_on) {
+      const next = byId.get(current.depends_on);
+      if (seen.has(next.id)) {
+        throw new Error(
+          `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}"'s depends_on chain cycles back through "${next.id}" instead of terminating at the domain layer "${head.id}"`,
+        );
+      }
+      seen.add(next.id);
+      current = next;
+    }
+    if (current.id !== head.id) {
+      throw new Error(
+        `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}"'s depends_on chain terminates at "${current.id}", not the domain layer "${head.id}" — every layer must point inward toward the domain`,
+      );
+    }
+  }
+}
+
+// Dispatches on `core.pattern` to the check above matching what was
+// declared. `null` (never set) and `'none'` (set, explicitly no enforced
+// direction — the adopted-repo default) both skip checking entirely: an
+// absent pattern must validate exactly as it did before this field
+// existed, and `none` recording "no direction" is a fact, not a finding.
+function checkPatternConformance(core) {
+  if (!core.pattern || core.pattern === 'none') return;
+  if (core.pattern === 'vertical-slice') {
+    if (!isModuleAxis(core)) {
+      throw new Error(
+        `core "${core.id}" declares pattern: vertical-slice, but no layer's scope contains {module} — vertical-slice is a chain instantiated per module, so at least one layer must vary by module`,
+      );
+    }
+    return;
+  }
+  if (core.pattern === 'layered') {
+    checkLayeredPattern(core);
+    return;
+  }
+  if (core.pattern === 'hexagonal') {
+    checkHexagonalPattern(core);
+  }
+}
+
 // Enforces the interview's rule (spec: "Authored cores") — a layer without
 // scope or without a verify command is rejected. Applied uniformly to
 // shipped and authored cores alike; the loader has no shipped-core-only
@@ -575,6 +723,13 @@ export function validateCore(core) {
     }
   }
 
+  // An architecture claim, checked mechanically — an unchecked `pattern`
+  // is a comment, and a comment that can silently disagree with the graph
+  // is worse than no field at all. Depends on depends_on already being
+  // resolved to real layer ids (the loop just above), which every check
+  // below relies on.
+  checkPatternConformance(core);
+
   // A `once: true` layer compiles a single task for the whole build, so
   // there is no module to substitute into its templates. Left unchecked,
   // a stray {module} would survive verbatim into scope_globs — a glob

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

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

package/src/skills/pr-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-writing
-description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English) and the pre-open checklist (CI status, scope, verified claims only).
+description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English), the Why/What shape, folding deep reasoning under `<details>`, and the pre-open checklist (CI status, scope, verified claims only).
 ---
 
 # PR Writing
@@ -47,13 +47,52 @@ as a record of the work session.
 
 ## Shape
 
-- **Title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
+- **PR title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
   chars.
-- **Description**: 1-3 bullets — what changed, why. A test plan section
+- **PR description**: 1-3 bullets — what changed, why. A test plan section
   listing what you actually ran, not what should theoretically pass.
+- **Issue title**: plain English a non-technical reader would say out
+  loud, not a commit-style `<type>(<scope>): <summary>`. Name the
+  outcome, not the mechanism — "Improve how Hedgehog tracks and enforces
+  a project's architecture", not "feat(core): add pattern field".
 - **Comments**: lead with the concrete finding, then (if needed) the fix
   requested. No preamble.
 
+## Why/What for issues
+
+An issue proposing a change — a feature, a fix worth explaining, a
+`ROADMAP.md` item being picked up — states **Why** before **What**:
+
+- **Why**: the problem, as a short list of plain-language facts. Each
+  bullet is one observation a reader can verify or disagree with, not a
+  justification wrapped in caveats. State the problem first, then (if
+  the fix isn't obvious from the problem) a short "to fix this" list of
+  intended outcomes.
+- **What**: the change itself — the concrete steps, fields, or sub-issues.
+  Numbered if sequenced, bulleted if not.
+
+Skip the Why section only when the title already states the problem in
+full (a one-line bug report needs no restatement). Never skip What.
+
+## Fold deep reasoning under `<details>`
+
+An issue or PR body written for a human reader stays short. Extended
+reasoning — architecture rationale, alternatives considered, prior
+decisions, anything aimed at an AI agent picking up the work or a reader
+who wants the full trail — goes under a collapsed section, not inline:
+
+```markdown
+<details>
+<summary>Full reasoning (for AI agents and anyone who wants the detail)</summary>
+
+...
+</details>
+```
+
+Ask first whether that detail needs to exist in the issue at all — a
+link to an existing doc or prior discussion is often enough. Only fold
+in content that has no better home.
+
 ## When NOT to apply
 
 - Internal scratch notes, planning docs, or anything not read by another