@skyf0xx/hedgehog 4.1.0 → 4.2.2

package/README.md

@@ -1,6 +1,6 @@
 # Turn AI from a code generator into a reliable software engineer ⭐
 
-[![Total downloads](https://img.shields.io/npm/dt/%40skyf0xx%2Fhedgehog?style=for-the-badge)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
+[![Total downloads](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/badges/npm-downloads.svg)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
 
 AI can write code in seconds.
 
@@ -68,6 +68,19 @@ Every dependency is explicit, so Hedgehog knows which tasks can run in parallel.
 
 Agents fan out to give you great outcomes at **faster speeds**.
 
+## Deterministic Code Generation
+
+Where a piece of code has one correct shape, Hedgehog generates it instead of asking the AI to write it freehand.
+
+![Deterministic code generation](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/deterministic.png)
+
+- **Generators over freehand**: schemas, boilerplate, and scaffolding come from generators that create the code
+- **Faster**: no reasoning required to produce a known shape
+- **More correct**: the same input always produces the same, tested output
+- **Fewer tokens**: nothing spent generating code that a template already covers
+
+The AI is reserved for the parts a generator can't cover.
+
 ## What Hedgehog builds
 
 ### Full-stack applications
@@ -138,6 +151,13 @@ npx @skyf0xx/hedgehog init
 
 Then open your coding agent and describe what you want to build.
 
+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.
+
 ### Coding agents
 
 Hedgehog installs for **Claude Code** by default. Add a host flag to

package/bin/cli.mjs

@@ -504,6 +504,18 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
     // runs the whole workspace (see lefthook.yml), so expect it to take
     // as long as a full typecheck/lint/test — that is the gate working.
     console.log(`  1. ${bold('pnpm install')}`);
+    console.log(
+      dim('     First run can take several minutes — full dependency install plus'),
+    );
+    console.log(dim('     the commit gate running against the whole workspace. This is'));
+    console.log(dim('     expected; let it finish rather than treating a quiet stretch as stuck.'));
+    console.log(
+      dim('     If an agent is running this: tell the user up front that first install'),
+    );
+    console.log(
+      dim('     can take several minutes and why, then check on progress every ~30s'),
+    );
+    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.`);
   } else {
@@ -653,6 +665,20 @@ async function resolveCorePath() {
   return null;
 }
 
+// The active core's `id` (e.g. `full-stack-app`), or null when no core has
+// landed yet or it fails to parse — packet rendering degrades gracefully
+// either way (see next.mjs's layerShapeLines), so a caller only asking for
+// the id doesn't need its own try/catch.
+async function resolveCoreId() {
+  const corePath = await resolveCorePath();
+  if (!corePath) return null;
+  try {
+    return (await loadCore(corePath)).id;
+  } catch {
+    return null;
+  }
+}
+
 // `hedgehog plan --recompile` — the reconciliation path for a core.yaml
 // edited after `plan` already compiled it.
 //
@@ -973,7 +999,7 @@ async function nextCommand() {
     console.error('');
   }
 
-  console.log(formatNext(packet));
+  console.log(formatNext(packet, await resolveCoreId()));
 }
 
 function printStalledTasks(stalled) {
@@ -1043,6 +1069,49 @@ async function missingBinariesForTask(db, taskId, owner) {
   return missing.length === 0 ? null : { layer: layer.id, missing };
 }
 
+// What an out-of-scope path most likely is, and what to do about it.
+// "Outside allowed scope" is true of every offending path and tells the
+// reader nothing about which of three quite different situations they're
+// in: a package shell the layer itself had to create (widen this one
+// task), shared config a source-level fix touched (commit it separately),
+// or a genuine stray. Each wants a different next move, and working out
+// which costs a beat every time.
+//
+// Evidence-only, like core.mjs's lint: an unrecognised path gets no
+// annotation rather than a guessed one.
+const SCOPE_HINTS = [
+  {
+    // A package root's own scaffolding — package.json, tsconfig*.json,
+    // vitest.config.mts, src/index.ts directly under packages/<pkg>/ or
+    // libs/<a>/<b>/. No {module}-bearing scope glob can cover these, so
+    // the first module through a layer that creates its package always
+    // lands here.
+    test: (p) =>
+      /^(packages\/[^/]+|libs\/[^/]+\/[^/]+)\/(package\.json|tsconfig[^/]*\.json|vitest\.config\.[cm]?ts|project\.json|eslint\.config\.[cm]?js|src\/index\.ts)$/.test(
+        p,
+      ),
+    hint: 'package shell — if this layer is the first to create this package, widen just this task with `hedgehog override add` (see hedgehog-loop, "First arrival in a package") and retry',
+  },
+  {
+    test: (p) =>
+      p === 'pnpm-workspace.yaml' ||
+      p === 'pnpm-lock.yaml' ||
+      p === 'tsconfig.json' ||
+      p === 'nx.json' ||
+      p === 'package.json' ||
+      p.startsWith('packages/config/'),
+    hint: 'shared workspace config — no layer owns it; commit it separately as its own `chore(workspace): …` before retrying',
+  },
+  {
+    test: (p) => p.startsWith('.hedgehog/'),
+    hint: 'build-graph state — intents, overrides and friction are committed by the command that writes them, not by a layer',
+  },
+];
+
+function scopeHintFor(path) {
+  return SCOPE_HINTS.find((h) => h.test(path))?.hint ?? null;
+}
+
 async function verifyCommand(args) {
   await ensureDb();
 
@@ -1093,7 +1162,11 @@ async function verifyCommand(args) {
   if (result.outcome === 'scope_violation') {
     console.error(`${red(bold('Scope violation.'))} Task ${bold(taskId)} is now ${bold('blocked')}.\n`);
     console.error('Touched paths outside allowed scope:');
-    for (const path of result.offending) console.error(`  ${red('✗')} ${path}`);
+    for (const path of result.offending) {
+      console.error(`  ${red('✗')} ${path}`);
+      const hint = scopeHintFor(path);
+      if (hint) console.error(`      ${dim(hint)}`);
+    }
     console.error();
     process.exitCode = 1;
     return;
@@ -1145,14 +1218,15 @@ async function verifyCommand(args) {
 // doesn't print the packet here, the STATUS/ALLOWED SCOPE/VERIFICATION an
 // agent is supposed to be dispatched with is no longer reachable from any
 // command. (`hedgehog show <task-id>` reprints it later.)
-function printPackets(tasks) {
+async function printPackets(tasks) {
+  const coreId = await resolveCoreId();
   const db = openDb();
   try {
     for (const task of tasks) {
       const packet = taskPacket(db, task.id);
       if (!packet) continue;
       console.log();
-      console.log(formatPacket(packet, taskStatusLine(packet.task)));
+      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId));
     }
   } finally {
     db.close();
@@ -1239,7 +1313,7 @@ async function claimCommand(args) {
     if (claimed.length > 1) console.log(`  ${bold(task.id)}`);
     console.log(`  ${dim('expires')}  ${task.lease_expires_at}`);
   }
-  printPackets(claimed);
+  await printPackets(claimed);
 }
 
 // The targeted half of `claim`: one named task, or a non-zero exit
@@ -1258,7 +1332,7 @@ async function claimOneCommand(taskId, owner) {
   if (result.claimed) {
     console.log(`${green(bold('Claimed.'))} Task ${bold(taskId)} leased to ${bold(owner)}.`);
     console.log(`  ${dim('expires')}  ${result.task.lease_expires_at}`);
-    printPackets([result.task]);
+    await printPackets([result.task]);
     return;
   }
 
@@ -1382,7 +1456,7 @@ async function showCommand(args) {
     return;
   }
 
-  console.log(formatPacket(packet, taskStatusLine(packet.task)));
+  console.log(formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId()));
 }
 
 // `hedgehog release <task-id> --owner <owner>` — hands a claimed task
@@ -1539,7 +1613,27 @@ async function statusCommand() {
     }
   }
 
-  const overrides = core ? await loadOverrides() : new Map();
+  // Loaded whether or not a core resolved: drift is the only consumer
+  // that needs `core` composed against these, and graphStatus already
+  // gates that on `core` itself. The orphan check reads task ids out of
+  // the database, so it is answerable — and worth answering — on a
+  // project whose core.yaml is missing or unparseable. A missing
+  // overrides directory reads as an empty Map (loadOverrides), so this
+  // costs nothing on a project that has never written one.
+  //
+  // A malformed override file throws, and for the same reason an
+  // unparseable core.yaml doesn't take `status` down, neither may this:
+  // status is the command every session starts with, and the report of
+  // the broken file is more useful than an aborted overview.
+  let overrides = new Map();
+  try {
+    overrides = await loadOverrides();
+  } catch (err) {
+    console.error(
+      `${yellow('Override file unreadable:')} ${err.message}\n${dim('Scope overrides are ignored until it parses.')}\n`,
+    );
+  }
+
   const db = openDb();
   let result;
   try {
@@ -1711,7 +1805,13 @@ function openInBrowser(url) {
 // either fails silently or blocks on a text browser. Printing the URL is
 // the useful behaviour in that case — a person on the other end of a
 // port-forward can still open it.
+//
+// HEDGEHOG_FORCE_HEADLESS bypasses the platform check entirely — the
+// repro suite's only way to exercise the no-display branch on macOS/
+// Windows, where DISPLAY/WAYLAND_DISPLAY are never consulted for real
+// users. Not a documented user-facing flag.
 function hasDisplay() {
+  if (process.env.HEDGEHOG_FORCE_HEADLESS) return false;
   if (process.platform === 'darwin' || process.platform === 'win32') return true;
   return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.1.0",
+  "version": "4.2.2",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {
@@ -44,4 +44,4 @@
     "hedgehog"
   ],
   "license": "MIT"
-}
+}

package/src/agents/backend-eng.md

@@ -36,29 +36,61 @@ project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
 needed.
 
+**Every layer you own starts from its generator in `tools/generators/`** —
+one per layer (`schema`, `contract`, `repository`, `service`,
+`controller`), each landing that layer's package shell, `nx.tags`,
+port-discipline file suffixes, Nest module/controller pair, and barrel
+wiring in one step. The claimed packet's LAYER SHAPE section prints the
+exact command for the layer you're on; `hedgehog-loop`'s "Scaffolding a
+layer" section owns the full flag contract and the workspace wiring a new
+package needs. Generate first, then author this entity's delta — the field
+list and its types, and the business rules below — on top. A hand-copy of
+a sibling module is the drift `hedgehog verify`'s lint step then has to
+catch.
+
 ## Core Responsibilities
 
 - **`schema`**: define the table in `packages/db` (Drizzle). One domain
   module = one table. Cross-module references are FK-by-ID columns
-  only — never a foreign schema import.
+  only — never a foreign schema import. Add one re-export line for the
+  module to `packages/db/src/schema/index.ts` (in scope for this
+  layer) so the table is importable outside `packages/db` — the
+  package's own `src/index.ts` re-exports that barrel and never
+  changes after bootstrap.
 - **`contract`**: derive the Zod schema from Drizzle (`drizzle-zod`) and
-  wire the ts-rest contract in `packages/contracts`.
+  wire the ts-rest contract in `packages/contracts`. A `date`-mode
+  `timestamp` column reflected through `createSelectSchema` is overridden
+  to a union of `z.date()` and an ISO datetime string, never left as the
+  derived `z.date()` alone and never narrowed to a string-only schema —
+  the same field is checked server-side against a real `Date` and
+  client-side against JSON's string, and no `.transform()` can satisfy
+  both.
 - **`repository`**: a port (interface) plus a Drizzle adapter in
   `libs/<module>/repository`. A `findById`-shaped miss returns
   `undefined` — plain absence, not a thrown error; the service decides
-  what absence means.
-- **`service`**: domain logic in `libs/<module>/service`, importing only
-  its own ports (`type:port`, `type:util` — the Nx boundary rule). Throws
-  typed, domain-named errors (`OrderNotFoundError`, not a bare `Error` or
-  an HTTP exception). No logging, no HTTP, no queue mechanics inside a
-  service method. Multi-write operations wrap in one Drizzle transaction,
-  passed through the port.
+  what absence means. The concrete adapter's file name ends in
+  `.adapter.ts` and the lib's entry point exports the port interface and
+  its DI token; `packages/config/eslint-base.js` keys its port-discipline
+  rule on that suffix, so an adapter named anything else silently opts
+  out of the check.
+- **`service`**: domain logic in `libs/<module>/service`, importing its
+  own module's port interface from the repository lib's entry point —
+  never a `*.adapter` file, never `drizzle-orm` or `packages/db`
+  (`no-restricted-imports` in `eslint-base.js` fails lint on either).
+  Throws typed, domain-named errors (`OrderNotFoundError`, not a bare
+  `Error` or an HTTP exception). No logging, no HTTP, no queue mechanics
+  inside a service method. Multi-write operations wrap in one Drizzle
+  transaction, passed through the port.
 - **`controller`**: thin HTTP in `apps/api`, wiring the contract to the
   service. The only layer that maps domain errors to status codes.
   Validation happens once, at this boundary, via the Zod contract — past
-  it, types are trusted. Bundles queue infra (port + BullMQ adapter in
-  `apps/worker`, same shape as the repository) when the Queue add-on is
-  on and this operation needs it.
+  it, types are trusted. `apps/api` is the composition root: the module's
+  `*.module.ts` is the one file that constructs the concrete adapter and
+  binds it to the port's DI token, and the only file in `apps/api`
+  allowed to import a `*.adapter`. A controller takes the service, or the
+  bound token — never the adapter. Bundles queue infra (port + BullMQ
+  adapter in `apps/worker`, same shape as the repository) when the Queue
+  add-on is on and this operation needs it.
 
 ## Workflow
 
@@ -75,15 +107,29 @@ needed.
    `complete` — no need to re-derive that by hand. Cross-module FK
    targets should already have their own schema landed (the packet's
    dependencies guarantee this); check before writing the FK column.
-2. Build exactly one layer, matching the packet's ALLOWED SCOPE. Run
-   typecheck, lint, and test yourself as a sanity check before reporting
-   back — necessary, not sufficient.
+2. Build exactly one layer, matching the packet's ALLOWED SCOPE: run its
+   generator, then author this entity's delta. Run typecheck, lint, and
+   test yourself as a sanity check before reporting back — necessary, not
+   sufficient. If this layer also has to create the package it lands in
+   (the first module through `contract` creates `packages/contracts`), the
+   shell files its generator lands sit outside the packet's ALLOWED SCOPE
+   and `hedgehog verify` will leave them uncommitted — stop and say so
+   before building, so the scope can be widened for this one task
+   (`hedgehog-loop`, "First arrival in a package"). Don't build against a
+   scope you already know won't commit your work. If the layer wires a new
+   or newly-linked package into the workspace, run `pnpm install` and
+   `pnpm nx sync` yourself (`hedgehog-loop`, "Scaffolding a layer") and
+   name the shared files that changed (typically `pnpm-lock.yaml`, root
+   `tsconfig.json`) in your report — the orchestrating session commits
+   them separately, since you report but never commit (next step).
 3. **Report the work as done; do not commit it yourself.** Per the build
    graph's design, an agent reporting success never moves a task — only
    `hedgehog verify <task-id>`'s passing exit code does. It checks your
    changes against the packet's ALLOWED SCOPE, re-runs the real
    verification command, and on a pass writes the commit (the packet's
-   exact Conventional Commit message) itself.
+   exact Conventional Commit message) itself. Any shared workspace files
+   you flagged in step 2 are a separate commit the orchestrating session
+   makes before dispatching `hedgehog verify`, not something you commit.
 4. One layer at a time — never start the next layer before
    `hedgehog verify` reports the current one `complete`.
 5. Once `hedgehog verify` reports the `controller` layer (and any bundled

package/src/agents/front-end-eng.md

@@ -34,6 +34,19 @@ project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
 needed.
 
+**Both layers you own start from their generator in `tools/generators/`** —
+`hook` lands `packages/hooks`'s shell, `nx.tags`, the query hook set, and
+its barrel wiring; `screen` lands the route, the screen component wired to
+that hook, and its test file. The claimed packet's LAYER SHAPE section
+prints the exact command for the layer you're on; `hedgehog-loop`'s
+"Scaffolding a layer" section owns the full flag contract and the
+workspace wiring a new package needs. Generate first, then author this
+entity's delta on top. The `screen` generator is skeleton-only by
+design — placeholders for the list, filter shell, empty state, and form,
+with layout, information hierarchy, and interaction pattern left to
+`ux-planner`'s rationale and your build, so no two modules' screens come
+out identical before anyone decided they should.
+
 If the screen step calls for animation or motion — entrances, sequencing,
 scroll-driven effects, drag, SVG/morph effects — use GSAP, loading the
 relevant skill from `vendor-skills/GSAP/` (`gsap-core`, `gsap-timeline`,
@@ -46,17 +59,26 @@ don't reach for a second one.
 
 - **`hook`**: build the TanStack Query hook in `packages/hooks`, wrapping
   the ts-rest contract client. One hook per contract operation, typed end
-  to end from the Zod contract. The client's base URL comes from a
-  `NEXT_PUBLIC_`-prefixed env var (add to `packages/config/env.schema.ts`
-  if missing) — never a hardcoded `http://localhost:<port>` fallback,
-  which silently drifts out of sync with `apps/api`'s dev port (`3333`,
-  per `hedgehog-bootstrap-full-stack-app-core` — chosen to not collide
-  with `apps/web`'s `next dev` default of `3000`) and produces a 404 that
-  looks like a routing bug, not a config bug.
-- **`screen`**: build the screen/component in `apps/web` and/or
-  `apps/mobile`, consuming the hook and `ux-planner`'s rationale for that
-  module (screen inventory, interaction pattern, information hierarchy).
-  No direct data-fetching in the screen — the hook owns that.
+  to end from the Zod contract. The client's base URL is
+  `process.env.NEXT_PUBLIC_API_BASE_URL`, scaffolded in
+  `apps/web/.env.example` and already carrying `apps/api`'s `/api` global
+  prefix. Read it as-is: don't append or strip a path segment (the prefix
+  is in the value), don't add it to `packages/config/env.schema.ts` (that
+  schema is `apps/api`'s server env, and a `NEXT_PUBLIC_` var is inlined
+  into the browser bundle by Next, never parsed at runtime by `loadEnv()`),
+  and never fall back to a hardcoded `http://localhost:<port>`. A wrong or
+  absent base URL 404s against Next's own dev server — a config bug wearing
+  a routing bug's clothes, and one unit tests never see, because they mock
+  the client.
+- **`screen`**: build the screen/component in `apps/web` (plus
+  `apps/mobile` when the Mobile add-on is on), consuming the hook and
+  `ux-planner`'s rationale for that module (screen inventory, interaction
+  pattern, information hierarchy). No direct data-fetching in the
+  screen — the hook owns that. If this module's screen is the first one
+  built, wire `apps/web/src/app/page.tsx`'s primary CTA (ShadCN's
+  `asChild` + `next/link`, per `button.tsx`'s existing `asChild` prop)
+  to this module's own route — a compiling, lint-clean button with no
+  `href` or `onClick` still ships silent and unclickable.
 - Translate design specs into components. If a design tool is wired into
   this project's MCP config, use it for tokens/spacing/typography;
   otherwise match existing ShadCN/Tailwind patterns in the repo.
@@ -82,12 +104,24 @@ don't reach for a second one.
    no such confirmation, stop — you're being asked to build Phase B
    early.
 2. Build the hook against the contract client, matching the packet's
-   ALLOWED SCOPE. Run typecheck, lint, and test yourself as a sanity
-   check before reporting back — necessary, not sufficient.
+   ALLOWED SCOPE: run its generator, then author this entity's delta. Run
+   typecheck, lint, and test yourself as a sanity check before reporting
+   back — necessary, not sufficient. On the first module through this
+   layer, the hook also creates `packages/hooks`, and that package's shell
+   sits outside the packet's ALLOWED SCOPE — `hedgehog verify` would leave
+   it uncommitted. Stop and say so before building, so the scope can be
+   widened for this one task (`hedgehog-loop`, "First arrival in a
+   package"); run `pnpm install` and `pnpm nx sync` yourself
+   (`hedgehog-loop`, "Scaffolding a layer") to wire the new package into
+   the workspace, and name the shared files that changed (typically
+   `pnpm-lock.yaml`, root `tsconfig.json`) in your report — the
+   orchestrating session commits them separately (next step).
 3. **Report the work as done; do not commit it yourself.** Only
    `hedgehog verify <task-id>`'s passing exit code moves the task to
    `complete` and writes the commit (the packet's exact Conventional
-   Commit message).
+   Commit message). Any shared workspace files you flagged in step 2 are a
+   separate commit the orchestrating session makes before dispatching
+   `hedgehog verify`, not something you commit.
 4. Build the screen consuming the hook the same way — packet, build,
    report, `hedgehog verify`.
 5. One layer at a time — `hook` fully `complete` before the `screen`

package/src/agents/reviewer.md

@@ -32,10 +32,15 @@ Everything lefthook already enforces (typecheck, lint, unit test
 pass/fail) is out of scope — don't re-report a green gate. Check what the
 gate structurally cannot:
 
-- **Port discipline**: does the service import only `type:port` /
-  `type:util`, per the Nx boundary rule — read the actual imports, don't
-  just trust `nx lint` ran. A boundary violation tagged wrong slips past
-  the rule. Use `nx show project <name> --json` (per nrwl's
+- **Port discipline**: a module's port interface and its Drizzle adapter
+  share one lib, so the tag graph has to allow `type:service →
+  type:adapter` and the real check is at the import level: does the
+  service import the port from the repository lib's entry point, or the
+  concrete `*.adapter`? Does anything in `apps/api` outside a
+  `*.module.ts` construct an adapter? `eslint-base.js`'s
+  `no-restricted-imports` rules catch the named cases — read the actual
+  imports anyway, since an adapter file not named `*.adapter.ts` opts
+  itself out of the rule. Use `nx show project <name> --json` (per nrwl's
   [nx-workspace](https://github.com/nrwl/nx-ai-agents-config/tree/main/skills/nx-workspace) skill) to check a project's resolved tags and
   dependencies rather than reading `project.json` directly — it only
   holds partial configuration, not tags inferred by plugins.

package/src/agents/ux-planner.md

@@ -127,8 +127,8 @@ conclusion.
 8. Hand off to `front-end-eng` for the screen step. The file isn't a step in
    the Domain Module Pattern and isn't committed on its own — it lands in
    the same commit as the screen step it informs
-   (`feat(<module>): screen-web` / `screen-mobile`), same as any other
-   file `front-end-eng` touches while building that step.
+   (`feat(<module>): screen-web`), same as any other file
+   `front-end-eng` touches while building that step.
 
 ## Constraints
 

package/src/db/next.mjs

@@ -234,6 +234,85 @@ export function taskStatusLine(task) {
   return task.status.toUpperCase();
 }
 
+// full-stack-app's own layer → Nx tag shape, mirroring the tag reference
+// table `src/golden-cores/full-stack-app/packages/config/eslint-base.js`
+// ships as a comment. A layer's `depConstraints` failure is a mechanical
+// consequence of this table crossed with `core.yaml`'s `depends_on` chain
+// — printing it in the packet turns that failure into a pre-flight fact
+// instead of something `nx lint` teaches the agent after the fact. Keyed
+// by layer id, not module, since the shape is the same for every module.
+//
+// `scaffold` is the same kind of fact one step earlier: the generator in
+// `tools/generators/` every layer starts from (hedgehog-loop, "Scaffolding
+// a layer", which owns the flag contract these lines instantiate). It sits
+// here rather than in RELEVANT RULES because that section is per-intent —
+// identical across every layer of an intent, by plan.mjs's requirement
+// linkage — while the command differs per layer, which is exactly what
+// LAYER SHAPE already keys on.
+const FULL_STACK_APP_LAYER_TAGS = {
+  schema: {
+    tags: ['scope:db', 'type:adapter'],
+    dependsOnTags: [],
+    scaffold: "nx g ./tools/generators:schema --module={module} --fields='<name:type,...>'",
+  },
+  contract: {
+    tags: ['scope:contracts', 'type:contract'],
+    dependsOnTags: ['type:adapter', 'type:util'],
+    scaffold: "nx g ./tools/generators:contract --module={module} --fields='<the schema layer's list>'",
+  },
+  repository: {
+    tags: ['scope:{module}', 'type:adapter'],
+    dependsOnTags: ['type:adapter', 'type:contract', 'type:util'],
+    scaffold: 'nx g ./tools/generators:repository --module={module}',
+  },
+  service: {
+    tags: ['scope:{module}', 'type:service'],
+    dependsOnTags: ['type:adapter', 'type:contract', 'type:util'],
+    scaffold: 'nx g ./tools/generators:service --module={module}',
+  },
+  controller: {
+    tags: ['scope:api'],
+    dependsOnTags: ['type:adapter', 'type:service', 'type:contract', 'type:util'],
+    scaffold: "nx g ./tools/generators:controller --module={module} --fields='<the schema layer's list>'",
+  },
+  hook: {
+    tags: ['scope:hooks', 'type:hook'],
+    dependsOnTags: ['type:contract', 'type:util'],
+    scaffold: 'nx g ./tools/generators:hook --module={module} [--toggleField=<boolField>]',
+  },
+  screen: {
+    tags: ['scope:web'],
+    dependsOnTags: ['scope:contracts', 'scope:hooks', 'scope:shared', 'type:util'],
+    scaffold: 'nx g ./tools/generators:screen --module={module}   (skeleton only — UX is yours)',
+  },
+};
+
+// A LAYER SHAPE section for full-stack-app tasks only (`coreId ===
+// 'full-stack-app'`) — an authored core has no equivalent tag scheme
+// (layer-eng.md already points that agent at reading .hedgehog/core.yaml
+// directly instead), and `join` has no fixed tag shape of its own to
+// state, so both fall through to null and print nothing.
+function layerShapeLines(task, coreId) {
+  if (coreId !== 'full-stack-app') return null;
+  const shape = FULL_STACK_APP_LAYER_TAGS[task.layer];
+  if (!shape) return null;
+  const tags = shape.tags.map((t) => t.replace('{module}', task.module));
+  const lines = ['LAYER SHAPE', `  this layer's tags:      ${tags.join(', ')}`];
+  if (shape.dependsOnTags.length === 0) {
+    lines.push('  may depend on tags:     (nothing in-workspace — floor layer)');
+  } else {
+    lines.push(`  may depend on tags:     ${shape.dependsOnTags.join(', ')}`);
+  }
+  lines.push(`  scaffold from:          ${shape.scaffold.replace('{module}', task.module)}`);
+  lines.push(
+    "  Confirm against packages/config/eslint-base.js's depConstraints before",
+    "  writing an import — a mismatch here is a pre-flight fact, not a lint",
+    '  failure to discover later. Start from the generator and author only',
+    "  this entity's delta on top of what it lands.",
+  );
+  return lines;
+}
+
 // The standing honesty requirement, appended to every packet.
 //
 // Every other section is task-specific — this one is constant, which is
@@ -264,8 +343,8 @@ const HONESTY = [
 ];
 
 // Renders a packet into the STATUS / INTENT / RELEVANT RULES /
-// INHERITED DEBT / WHY NOW / BLOCKED DOWNSTREAM / ALLOWED SCOPE /
-// VERIFICATION / HONESTY format. The spec
+// INHERITED DEBT / WHY NOW / BLOCKED DOWNSTREAM / ALLOWED SCOPE / LAYER
+// SHAPE / VERIFICATION / HONESTY format. The spec
 // splits this across two examples — the `hedgehog next` display and "The
 // task packet" (which carries the intent and its rules) — but an agent
 // receives one thing, so the packet is one thing: everything the worker
@@ -273,12 +352,15 @@ const HONESTY = [
 //
 // `statusLine` is what goes on the STATUS row. `next` passes READY
 // literally, as it always has; `show` passes taskStatusLine(task), which
-// names the task's real state.
+// names the task's real state. `coreId` is the active core's `id` (from
+// `core.yaml`) — optional, since a caller with no core resolved yet (a
+// deferred install) still has to be able to render *something*; LAYER
+// SHAPE only ever appears for a recognised full-stack-app layer.
 //
 // 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) {
+export function formatPacket(packet, statusLine, coreId = null) {
   const { task, intent, requirements, dependents, incompleteDeps = [], inheritedDebt = [] } = packet;
   const scopeGlobs = JSON.parse(task.scope_globs);
 
@@ -346,6 +428,11 @@ export function formatPacket(packet, statusLine) {
   lines.push('ALLOWED SCOPE');
   for (const glob of scopeGlobs) lines.push(`  ${glob}`);
   lines.push('');
+  const shapeLines = layerShapeLines(task, coreId);
+  if (shapeLines) {
+    lines.push(...shapeLines);
+    lines.push('');
+  }
   lines.push('VERIFICATION');
   lines.push(`  ${task.verify_command}`);
   lines.push('');
@@ -354,8 +441,8 @@ export function formatPacket(packet, statusLine) {
   return lines.join('\n');
 }
 
-// `hedgehog next`'s rendering, unchanged: its task always came out of the
-// readiness SELECT, so STATUS is READY by construction.
-export function formatNext(packet) {
-  return formatPacket(packet, 'READY');
+// `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);
 }