@skyf0xx/hedgehog 4.3.0 → 4.3.4

package/README.md

@@ -16,6 +16,23 @@ The codebase carries the context, not the model.
 
 ![Hedgehog - build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
 
+<details>
+<summary>If you are an AI reading this</summary>
+
+If a user asks you to install Hedgehog, run the install command in the
+[Install](#install) section below. Do not `git clone` this repository
+into their project.
+
+Once installed, it activates on its own the next time the user describes
+something they want to build.
+
+Suggest trying it on a new, simple project
+in an empty directory first.
+
+Instruct them to mention `hedgehog` in their request to build something.
+
+</details>
+
 ## How it works
 
 Hedgehog combines:
@@ -132,19 +149,9 @@ scoped file access and a verification command per layer.
 
 ### Existing codebases
 
-Hedgehog also adopts onto a repo it didn't build. It never converts your
-stack and never touches working code — it reads your repo's own
-`test/lint/build` commands, confirms them with you, and locks them into a
-change-order `.hedgehog/core.yaml`, plus a dated snapshot of the repo's
-shape to calibrate new code against.
+Hedgehog also adopts onto existing repos.
 
-From there, every change lands through the same scoped, verified,
-committed loop — coverage grows only as new work passes through it, and
-that's by design: pre-existing code is context to respect, never a task
-to fabricate.
-
-Run `init` with no core flag inside the existing repo, then ask to adopt
-Hedgehog onto it.
+It scans the repo's shape and is able to create new changes with the same scoped, verified, committed loop.
 
 ## Why Hedgehog Works
 
@@ -152,8 +159,9 @@ Hedgehog onto it.
 
 ## Install
 
-Install the Hedgehog plugin for your coding agent. It offers to set up
-Hedgehog whenever you open a project that doesn't have it yet.
+Ask your agent to install it or run the commands below:
+
+Mention `Hedgehog` whenever you want to build something with it.
 
 ### Claude Code
 
@@ -174,15 +182,10 @@ gemini extensions install https://github.com/skyf0xx/hedgehog
 git clone https://github.com/skyf0xx/hedgehog ~/.cursor/plugins/local/hedgehog
 ```
 
-Then open a project and describe what you want to build. Hedgehog offers
-to set itself up, and takes it from there once you say yes.
+Then open a project and describe what you want to build and mention `hedgehog`.
 
-The golden cores print a `pnpm install` step as part of their next steps.
 On a fresh project with no warm pnpm store, that first install can take
-several minutes — it's pulling a full monorepo toolchain (Nx, webpack,
-sass-embedded, Playwright, etc.) and, on first commit, running the commit
-gate against the whole workspace. A quiet stretch of output during that
-step is expected, not a hang.
+several minutes.
 
 To update:
 
@@ -190,11 +193,7 @@ To update:
 npx @skyf0xx/hedgehog update
 ```
 
-This refreshes the installed agents and skills — for every coding agent
-the project was set up for — along with the `AGENTS.md` index derived
-from them. It never touches the instructions file, the build graph, the
-core workspace, or `vendor-skills/BMAD`, since those carry project-specific or
-write-once content.
+This refreshes the installed agents and skills in a specific repo (note, not vendor skills)
 
 ## Why Hedgehog
 

package/bin/cli.mjs

@@ -13,13 +13,13 @@
 //   npx @skyf0xx/hedgehog --help
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
-import { constants } from 'node:fs';
+import { constants, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { dbInit, DB_PATH, dbAbsPath, openDb } from '../src/db/init.mjs';
-import { loadCore, lintCore } from '../src/db/core.mjs';
-import { planTasks } from '../src/db/plan.mjs';
+import { loadCore, lintCore, isModuleAxis } from '../src/db/core.mjs';
+import { planTasks, CORE_INTENT_ID } from '../src/db/plan.mjs';
 import { addIntent, INTENTS_DIR } from '../src/db/intent.mjs';
 import {
   nextTask,
@@ -89,6 +89,14 @@ const dim = (s) => paint('2', s);
 // this name in the package, renamed back on copy.
 const DOTFILE_RENAMES = { 'gitignore.template': '.gitignore' };
 
+// Build artifacts that must never be copied into a consuming project,
+// even if a future publish accidentally includes them: the full-stack-app
+// golden core documents that `node_modules` is regenerated by `pnpm
+// install` in step 4, not shipped, and a platform-specific `node_modules`
+// snapshot from the publisher's machine can be stale or broken for
+// everyone else (e.g. a dangling optional-dependency symlink).
+const SKIP_DIR_NAMES = new Set(['node_modules', '.nx', 'dist', '.next', 'out-tsc']);
+
 // Every subdirectory of src/golden-cores/ is a valid --core value —
 // discovered from disk so a new core added under golden-cores/ doesn't
 // need this list touched separately.
@@ -273,6 +281,26 @@ function warnRebuildDrift({ drift }, corePath) {
   );
 }
 
+// Debt and friction notes are operator-recorded and have no committed
+// source, so a rebuild carries them across by task id. A note whose task
+// is no longer in the recompiled graph — its intent file was renamed,
+// deleted, or its layer sequence changed — has nowhere to re-attach.
+// Friction notes survive unattached (their task_id is nullable); debt
+// notes are lost, so both are printed with their text rather than
+// disappearing into a count.
+function warnOrphanedNotes({ orphanedNotes }) {
+  if (!orphanedNotes || orphanedNotes.length === 0) return;
+  console.log(
+    `${yellow(bold('Notes without a task after rebuild.'))} ${orphanedNotes.length} note(s) referenced a\n` +
+      'task the recompiled graph no longer holds. Friction notes were kept unattached;\n' +
+      'debt notes could not be, so they are reproduced here:\n',
+  );
+  for (const note of orphanedNotes) {
+    console.log(`  ${dim(note.kind)}  ${bold(note.taskId)}  ${note.note}`);
+  }
+  console.log('');
+}
+
 // Writes one planned file to disk — a straight copy, or for a `merge`
 // entry, the shell template with {{CORE_SECTION}} replaced by the
 // chosen core's include.
@@ -324,7 +352,10 @@ async function plannedFiles(entry) {
     const abs = join(src, rel);
     const st = await stat(abs);
     if (st.isDirectory()) {
-      for (const name of await readdir(abs)) await walk(join(rel, name));
+      for (const name of await readdir(abs)) {
+        if (SKIP_DIR_NAMES.has(name)) continue;
+        await walk(join(rel, name));
+      }
     } else {
       const renamed = DOTFILE_RENAMES[rel] ?? rel;
       out.push({ src: abs, dest: join(DEST_ROOT, entry.to, renamed), emit: entry.emit });
@@ -517,16 +548,33 @@ 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. Open ${HOSTS[host].label} and describe what you want to build.`);
+    console.log(
+      `  3. Start a ${bold('new')} ${HOSTS[host].label} session and describe what you want to build.`,
+    );
   } else {
     console.log(`  1. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
-    console.log(`  2. Open ${HOSTS[host].label} and describe what you want to build.`);
+    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(
+    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.',
+    ),
+  );
   console.log();
   if (explicitCore) {
     console.log(dim(`Core: ${bold(core)}.`));
@@ -625,6 +673,7 @@ async function dbRebuildCommand() {
   console.log(
     `${green('rebuilt')}  ${dim(`${result.intentsReplayed} intent(s) replayed, ${result.tasksMarkedComplete} task(s) marked complete`)}\n`,
   );
+  warnOrphanedNotes(result);
   warnRebuildDrift(result, corePath);
 }
 
@@ -656,6 +705,13 @@ async function dbCommand(args) {
 // along with the rest of src/golden-cores/<core>). Neither exists yet on
 // a deferred install (plain `init`, no explicit core flag) until
 // `bootstrap` runs — this returns null until then.
+// Synchronous on purpose: formatPacket renders in one pass and takes this
+// as a predicate, so the FIRST ARRIVAL check cannot be an await. Paths are
+// repo-relative, the same way scope globs are.
+function packetExists(path) {
+  return existsSync(join(DEST_ROOT, path));
+}
+
 async function resolveCorePath() {
   if (await exists(join(DEST_ROOT, AUTHORED_CORE_PATH))) {
     return join(DEST_ROOT, AUTHORED_CORE_PATH);
@@ -810,6 +866,7 @@ async function planCommand(args = []) {
   const driftDb = openDb({ readOnly: true });
   let drifted;
   try {
+    warnSingularModuleIdsAtPlan(core, driftDb);
     drifted = detectDrift(driftDb, core, { overrides });
   } finally {
     driftDb.close();
@@ -946,6 +1003,114 @@ async function intentCommand(args) {
 
   console.log(`  ${green('added')}  ${intent.id}`);
   console.log(`  ${dim(`${intent.requirements.length} requirement(s), ${intent.depends_on.length} dependency(ies)`)}`);
+  await warnSingularModuleId(intent);
+}
+
+// On a module-axis core the intent id becomes {module} in every layer's
+// scope glob and verify command, and the generators the packet points at
+// take the module name plural. A singular id compiles a whole graph
+// scoped to a directory the generator will never write, and nothing
+// downstream catches it: plan compiles it, claim hands out a packet whose
+// own scaffold command contradicts its ALLOWED SCOPE.
+//
+// A warning rather than a refusal: plenty of real modules are singular
+// (`billing`, `search`), so the convention cannot be enforced without
+// rejecting correct ids. Raised here because this is the last moment the
+// fix is one file rename — three layers later it is a Correction Protocol
+// case across every compiled task.
+//
+// The convention is a heuristic, not a checkable property of the graph:
+// `tasks` and `task` are both structurally valid, and nothing downstream
+// knows which one the generator wants. So this only ever reports.
+function looksSingular(id) {
+  return !/(s|ae|ia|people|children)$/i.test(id);
+}
+
+// `intent add` is one route to the compiler among several — `--file`, a
+// hand-written intents/*.json, and `db rebuild` all reach it without
+// passing through here — so `plan` re-raises the same check where every
+// route converges. See planCommand.
+async function warnSingularModuleId(intent) {
+  const corePath = await resolveCorePath();
+  if (!corePath) return;
+
+  let core;
+  try {
+    core = await loadCore(corePath);
+  } catch {
+    // A core that will not load is `plan`'s error to report, not this
+    // advisory's.
+    return;
+  }
+  if (!isModuleAxis(core)) return;
+  if (!looksSingular(intent.id)) return;
+
+  console.log(
+    `\n${yellow(bold('Module id looks singular.'))} On this core the intent id is ${bold('{module}')} in\n` +
+      `every layer's scope, and the generators take it plural — so ${bold(intent.id)} compiles\n` +
+      `scope for ${bold(`${intent.id}/`)} while the scaffold command writes ${bold(`${intent.id}s/`)}.\n` +
+      `If ${bold(`${intent.id}s`)} is the name you meant, fix it now, before ${bold('hedgehog plan')}:\n` +
+      `  ${dim(`git mv ${INTENTS_DIR}/${intent.id}.json ${INTENTS_DIR}/${intent.id}s.json`)}\n` +
+      `  ${dim(`# edit "id" and every ${intent.id.toUpperCase()}-* requirement id, then:`)}\n` +
+      `  ${dim('hedgehog db rebuild')}\n`,
+  );
+}
+
+// The same advisory at `plan`, where `--file`, a hand-written intent
+// file, and `db rebuild` all converge — none of them passes through
+// `intent add`, so on those routes this is the first and last cheap
+// warning before a whole graph is compiled against the id. It reports
+// while every one of an intent's tasks is still unstarted; once work has
+// landed the fix is a Correction Protocol case rather than a rename, and
+// repeating the `git mv` advice would point at the wrong recovery.
+//
+// One block for however many ids trip it, rather than repeating the
+// per-intent explanation: the reasoning is identical every time, and
+// stacking it once per intent buries the list of names under it. The
+// recovery is still per-id, so those lines are listed one per name.
+function warnSingularModuleIdsAtPlan(core, db) {
+  if (!isModuleAxis(core)) return;
+
+  // Every intent whose tasks have all yet to start, not just the ones
+  // this run compiled. `db rebuild` replays the committed intent files
+  // *and* compiles their tasks, so a `plan` after it compiles nothing —
+  // and that is precisely the route where nothing else has ever looked at
+  // the id. The cheap-fix window is "no work has landed yet", which
+  // outlasts any single `plan` invocation.
+  const singular = db
+    .prepare(
+      `SELECT i.id FROM intents i
+        WHERE i.id <> ?
+          AND NOT EXISTS (
+            SELECT 1 FROM tasks t
+             WHERE t.intent_id = i.id
+               AND t.status NOT IN ('proposed','planned','ready')
+          )
+        ORDER BY i.id`,
+    )
+    .all(CORE_INTENT_ID)
+    .map((row) => row.id)
+    .filter(looksSingular);
+  if (singular.length === 0) return;
+
+  const many = singular.length > 1;
+  console.log(
+    `${yellow(bold(many ? `${singular.length} module ids look singular.` : 'Module id looks singular.'))} ` +
+      `On this core an intent id is ${bold('{module}')} in\n` +
+      `every layer's scope, and the generators take it plural — so ${many ? 'each of these compiles' : 'this compiles'}\n` +
+      `scope for a directory the scaffold command will never write:\n` +
+      singular.map((id) => `  ${bold(id)} ${dim(`— scope ${id}/, scaffold writes ${id}s/`)}`).join('\n') +
+      `\n\nThis is a naming convention, not a rule — ${bold('billing')} and ${bold('search')} are ` +
+      `legitimately\nsingular. If the plural is what you meant, it is still cheap to fix:\n` +
+      singular
+        .map(
+          (id) =>
+            `  ${dim(`git mv ${INTENTS_DIR}/${id}.json ${INTENTS_DIR}/${id}s.json`)}\n` +
+            `  ${dim(`# edit "id" and every ${id.toUpperCase()}-* requirement id`)}`,
+        )
+        .join('\n') +
+      `\n  ${dim('hedgehog db rebuild')}\n`,
+  );
 }
 
 async function nextCommand() {
@@ -999,7 +1164,7 @@ async function nextCommand() {
     console.error('');
   }
 
-  console.log(formatNext(packet, await resolveCoreId()));
+  console.log(formatNext(packet, await resolveCoreId(), packetExists));
 }
 
 function printStalledTasks(stalled) {
@@ -1226,7 +1391,7 @@ async function printPackets(tasks) {
       const packet = taskPacket(db, task.id);
       if (!packet) continue;
       console.log();
-      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId));
+      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId, packetExists));
     }
   } finally {
     db.close();
@@ -1456,7 +1621,9 @@ async function showCommand(args) {
     return;
   }
 
-  console.log(formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId()));
+  console.log(
+    formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId(), packetExists),
+  );
 }
 
 // `hedgehog release <task-id> --owner <owner>` — hands a claimed task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.3.0",
+  "version": "4.3.4",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {
@@ -27,7 +27,15 @@
     "src/templates",
     "src/golden-cores",
     "vendor-skills/BMAD",
-    "vendor-skills/GSAP"
+    "vendor-skills/GSAP",
+    "!src/golden-cores/full-stack-app/node_modules/**",
+    "!src/golden-cores/full-stack-app/.nx/**",
+    "!src/golden-cores/full-stack-app/apps/*/node_modules/**",
+    "!src/golden-cores/full-stack-app/apps/*/dist/**",
+    "!src/golden-cores/full-stack-app/apps/*/.next/**",
+    "!src/golden-cores/full-stack-app/apps/*/out-tsc/**",
+    "!src/golden-cores/full-stack-app/packages/*/node_modules/**",
+    "!src/golden-cores/full-stack-app/packages/*/dist/**"
   ],
   "engines": {
     "node": ">=22.5.0"

package/src/agents/planner.md

@@ -50,6 +50,28 @@ follows delegates normally. Re-entry stays a subagent dispatch: its
 questions are short, scoped, and answer-shaped, not a facilitated
 session.
 
+A hard rule stated in this file or `hedgehog-planning-intake` (this one
+included) is not one option to weigh against a user's earlier
+instruction — it's a constraint to work within. If a user instruction
+genuinely conflicts with one (e.g. "don't ask clarifying questions"
+against Phase 0's live elicitation requirement), say plainly that the
+two conflict and ask the user how to proceed. Never resolve the conflict
+by defaulting to a recommendation that bypasses the rule, and never
+present bypassing it as an equally-weighted option alongside following
+it — that smuggles the bypass in as the path of least resistance instead
+of surfacing the actual conflict.
+
+"Don't ask clarifying questions" is the common case, and on full-stack-app
+or an authored core it has a defined destination once the user has chosen
+it: **compressed intake** (`hedgehog-planning-intake`'s Phase 0). Surface
+the conflict first, exactly as above — compressed intake is what the
+user's answer can select, never what you recommend to avoid the
+conversation. Say what it costs when you name it: one batched round of
+questions instead of the shelf, a thinner archive, and an architecture
+(on an authored core) designed from a brief rather than elicited drivers.
+Landing-page has no such destination — see that skill for why — so there
+the conflict is surfaced and resolved with the user, not routed.
+
 ## Phase 0 — which core applies
 
 Before invoking any planning-intake skill, on a first run only (Workflow
@@ -189,6 +211,11 @@ anything here a background job, or is it all instant reads and writes?",
 default an add-on on or off without either a concrete trigger in the PRD
 or a direct answer.
 
+This gate holds identically on compressed intake — it is the reason that
+mode has a batched round of questions at all. Whatever the brief doesn't
+concretely trigger goes into that round; nothing here is inferred from
+silence because the user asked not to be asked.
+
 Write the decision to `.hedgehog/addons.yaml`, one entry per add-on with
 its on/off state and the one-line reason it landed there:
 
@@ -219,7 +246,9 @@ accounts get added where there were none).
 - Decide which core applies before running any planning-intake skill —
   Phase 0 above.
 - **full-stack-app**: owns `.hedgehog/BMAD/` (archival, written once,
-  never edited after) and `.hedgehog/addons.yaml` as artifacts; the
+  never edited after — including its `00-manifest.md`, which records
+  which intake mode produced it) and `.hedgehog/addons.yaml` as
+  artifacts; the
   intent records Phase 1 writes via `hedgehog intent add` live in the
   build graph, not a file this agent owns.
 - **landing-page**: owns `.hedgehog/BMAD/` and
@@ -277,11 +306,14 @@ accounts get added where there were none).
    that turns out to be wrong is a Correction Protocol case, not a quiet
    rewrite here.
 5. **Run planning intake**, in the shape this path calls for:
-   - **First run, full-stack-app**: run the vendored BMAD shelf, then
-     mine `04-prd.md` only into intent records per the PRD→graph-row
-     table (spec: "Mapping BMAD output to intents") and the Add-ons
-     decision (see above) — asking the user directly only for whatever
-     the PRD leaves unresolved.
+   - **First run, full-stack-app**: run the vendored BMAD shelf — or, if
+     the user has explicitly chosen it after the conflict was surfaced,
+     compressed intake's batched round — then mine `04-prd.md` only into
+     intent records per the PRD→graph-row table (spec: "Mapping BMAD
+     output to intents") and the Add-ons decision (see above) — asking
+     the user directly only for whatever the PRD leaves unresolved. The
+     mining step is the same either way; only how the archive was
+     produced differs.
    - **First run, landing-page**: run the same vendored BMAD shelf in
      full, then mine `.hedgehog/BMAD/` into a draft subject statement
      (subject, audience, single page job) — asking the user directly only

package/src/agents/ux-planner.md

@@ -35,15 +35,26 @@ material `planner` files per module at planning intake, for you to act on here.
 If it's thin, or a specific detail you need (information architecture, a
 named flow, visual identity) isn't in it, read the full source directly:
 `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md`, the un-mined
-UX spec `planner`'s notes were drawn from. Read the notes file if present,
-then say so plainly and ask for anything further
-before producing the rationale: "Phase A is closed for `<module>` — this
-is the UX planning step before the screen gets built. [If notes exist:
-"I've got what was noted at planning intake for this module — here's a quick
-recap: (one-line summary)."] If you have a mockup, screenshot, an export
-from a tool like Google Stitch or Figma, or an existing screen you want
-this to resemble, hand it over now; otherwise I'll propose the layout
-from the contract, hook, and any notes on file." Treat whatever's
+UX spec `planner`'s notes were drawn from. Read whichever of the two the
+archive holds — a project planned through compressed intake
+(`hedgehog-planning-intake`'s Phase 0) has `EXPERIENCE.md` only, and one
+whose brief stated no flows may have neither. **An absent file is your
+cue to ask, not to invent.** Visual identity is the first thing a
+compressed brief omits, so where the archive is silent, say so and
+propose from the contract and hook rather than inferring a direction the
+user never gave — that inference is the improvisation this step exists to
+replace.
+
+Read the notes file if present, then say so plainly and ask for anything
+further before producing the rationale: "Phase A is closed for
+`<module>` — this is the UX planning step before the screen gets built.
+[If notes exist: "I've got what was noted at planning intake for this
+module — here's a quick recap: (one-line summary)."] [If the archive
+holds no UX spec: "This project was planned through compressed intake, so
+there's no visual direction on file."] If you have a mockup, screenshot,
+an export from a tool like Google Stitch or Figma, or an existing screen
+you want this to resemble, hand it over now; otherwise I'll propose the
+layout from the contract, hook, and any notes on file." Treat whatever's
 supplied or on file the same way — a source of screen inventory and
 hierarchy, not something to transcribe pixel-for-pixel. No visual tool or
 prior note is required; the rationale stands on its own when nothing is
@@ -70,7 +81,10 @@ mockup, not a design system, not code:
    was (a screenshot, a Stitch/Figma export, a named reference app,
    planning-intake notes from `docs/design/<module>-notes.md`, or the
    raw UX spec at `.hedgehog/BMAD/05-ux-spec/`) and what was drawn from
-   it versus decided independently.
+   it versus decided independently. Where there was none — a compressed
+   archive with no UX spec and nothing supplied — say that plainly here,
+   so `front-end-eng` and `reviewer` read the rationale as reasoned from
+   the contract and hook rather than from a direction on file.
 
 Keep it short — a few bullets per screen, not a document. This is a
 rationale `front-end-eng` reads once before starting, and `reviewer` can
@@ -110,9 +124,11 @@ conclusion.
 1. Confirm the module's hook step is committed (`feat(<module>): hooks`)
    — if not, stop, this is being asked for too early.
 2. Check for `docs/design/<module>-notes.md` and read it if present. If
-   it's thin or missing a detail you need, read
-   `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md` directly for
-   the full material it was drawn from.
+   it's thin or missing a detail you need, read whichever of
+   `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md` the archive
+   holds, for the full material it was drawn from. Where neither the
+   notes nor the spec covers what you need, that gap goes into step 3's
+   ask — it is not something to fill in yourself.
 3. Announce the Phase B transition and ask for visual input, per "When
    you run," above.
 4. Read the contract (`packages/contracts`) for the module: what

package/src/db/core.mjs

@@ -480,6 +480,14 @@ function tokenInsideGlob(token, glob) {
   return false;
 }
 
+// True when the core compiles one task per domain module rather than one
+// per layer — i.e. some layer's scope varies by {module}. The single
+// owner of that question: validateCore, lintCore, and `intent add`'s
+// plural-id check all read it from here.
+export function isModuleAxis(core) {
+  return core.layers.some((layer) => layer.scope.join('').includes('{module}'));
+}
+
 // 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
@@ -600,10 +608,7 @@ export function validateCore(core) {
   // is nothing for a {module} in its scope to isolate — and requiring one
   // would reject exactly the cross-cutting layers `once` exists to
   // express.
-  const isModuleAxis = core.layers.some((layer) =>
-    layer.scope.join('').includes('{module}'),
-  );
-  if (isModuleAxis) {
+  if (isModuleAxis(core)) {
     for (const layer of core.layers) {
       if (layer.exclusive || layer.once) continue;
       if (!layer.scope.join('').includes('{module}')) {
@@ -662,10 +667,7 @@ export function validateCore(core) {
 // hedgehog-core-design carries the question as an authoring rule too.
 export function lintCore(core) {
   const warnings = [];
-  const isModuleAxis = core.layers.some((layer) =>
-    layer.scope.join('').includes('{module}'),
-  );
-  if (isModuleAxis) {
+  if (isModuleAxis(core)) {
     for (const layer of core.layers) {
       if (layer.exclusive || layer.once) continue;
       if (!layer.scope.join('').includes('{module}')) continue; // validateCore already rejects this

package/src/db/next.mjs

@@ -360,9 +360,74 @@ const HONESTY = [
 // HONESTY is last deliberately: it's the one section that qualifies the
 // gate above it, so it reads as the answer to "and what if I can't clear
 // VERIFICATION honestly" rather than as preamble.
-export function formatPacket(packet, statusLine, coreId = null) {
+// The package root a scope glob lives inside: the literal path above the
+// glob's first wildcard, truncated at `src/` when one appears — a package
+// root is where `package.json` sits, which is always above the `src/` a
+// module directory hangs off.
+//
+// `{module}` is substituted first rather than treated as a wildcard,
+// because on this core it is a real directory name in the compiled task
+// and the package root can sit *below* it: `packages/contracts/src/tasks/**`
+// has its root two segments up, while `libs/tasks/repository/**` has its
+// root at the full literal path. Only `*` genuinely ends the literal part.
+export function scopePackageRoot(glob, module) {
+  const segments = glob.replace('{module}', module).split('/');
+  const wildcard = segments.findIndex((s) => s.includes('*'));
+  const literal = wildcard === -1 ? segments.slice(0, -1) : segments.slice(0, wildcard);
+  const src = literal.indexOf('src');
+  const root = src === -1 ? literal : literal.slice(0, src);
+  // A package root is at least `<area>/<name>`; anything shallower is the
+  // repo itself, which is never a first arrival.
+  return root.length >= 2 ? root.join('/') : null;
+}
+
+// A task is the first arrival in its package when the package the scope
+// points into has no package.json on disk yet: the generator that
+// scaffolds this layer will create the package shell (package.json,
+// tsconfig*.json, vitest.config.mts, src/index.ts) alongside the module's
+// own files, and every one of those lands outside a {module}-bearing
+// glob. Detected here rather than left to be discovered from a failed
+// verify, which is where the override stops being available and the
+// recovery becomes a five-command round trip.
+//
+// `exists` is injected so this module keeps no filesystem dependency of
+// its own; the CLI passes a real one and the packet degrades to no
+// section when a caller supplies none.
+export function firstArrivalPackages(task, exists) {
+  if (!exists) return [];
+  const roots = new Set();
+  for (const glob of JSON.parse(task.scope_globs)) {
+    const root = scopePackageRoot(glob, task.module);
+    if (root && !exists(`${root}/package.json`)) roots.add(root);
+  }
+  return [...roots].sort();
+}
+
+function firstArrivalLines(task, roots) {
+  const scopes = roots.flatMap((root) => [`${root}/*`, `${root}/src/*`]);
+  return [
+    'FIRST ARRIVAL',
+    `  ${roots.join(', ')} ${roots.length > 1 ? 'do' : 'does'} not exist yet, so this task's`,
+    "  generator also creates the package shell (package.json, tsconfig*.json,",
+    '  vitest.config.mts, src/index.ts) plus any package-wide source it writes',
+    '  at the src/ root. All of that lands OUTSIDE the scope above. Widen this',
+    '  one task before building it, or verify will reject those paths and',
+    '  block the task:',
+    '',
+    `  hedgehog override add ${task.id} \\`,
+    ...scopes.map((s) => `    --scope '${s}' \\`),
+    `    --reason 'first module through ${task.layer} also creates the package shell'`,
+    '',
+    '  src/* is non-recursive on purpose: it covers src/index.ts and any',
+    "  shared util beside it without re-granting the module directory the",
+    '  scope above already covers.',
+  ];
+}
+
+export function formatPacket(packet, statusLine, coreId = null, exists = null) {
   const { task, intent, requirements, dependents, incompleteDeps = [], inheritedDebt = [] } = packet;
   const scopeGlobs = JSON.parse(task.scope_globs);
+  const firstArrival = firstArrivalPackages(task, exists);
 
   const lines = [];
   lines.push(`TASK  ${task.id}`);
@@ -428,6 +493,10 @@ export function formatPacket(packet, statusLine, coreId = null) {
   lines.push('ALLOWED SCOPE');
   for (const glob of scopeGlobs) lines.push(`  ${glob}`);
   lines.push('');
+  if (firstArrival.length > 0) {
+    lines.push(...firstArrivalLines(task, firstArrival));
+    lines.push('');
+  }
   const shapeLines = layerShapeLines(task, coreId);
   if (shapeLines) {
     lines.push(...shapeLines);
@@ -443,6 +512,6 @@ export function formatPacket(packet, statusLine, coreId = null) {
 
 // `hedgehog next`'s rendering: its task always came out of the readiness
 // SELECT, so STATUS is READY by construction.
-export function formatNext(packet, coreId = null) {
-  return formatPacket(packet, 'READY', coreId);
+export function formatNext(packet, coreId = null, exists = null) {
+  return formatPacket(packet, 'READY', coreId, exists);
 }