@skyf0xx/hedgehog 4.1.0 → 4.2.0

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.
 

package/bin/cli.mjs

@@ -653,6 +653,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 +987,7 @@ async function nextCommand() {
     console.error('');
   }
 
-  console.log(formatNext(packet));
+  console.log(formatNext(packet, await resolveCoreId()));
 }
 
 function printStalledTasks(stalled) {
@@ -1043,6 +1057,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 +1150,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 +1206,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 +1301,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 +1320,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 +1444,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 +1601,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 +1793,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.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/backend-eng.md

@@ -34,31 +34,54 @@ build exactly what its ALLOWED SCOPE names, one layer at a time, gated by
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
 project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+needed. A layer's first-arrival package shell (`contract`, `repository`,
+`service`) is a generator call, not a hand-copy of a sibling package —
+`hedgehog-loop`'s "First arrival in a package" section names the exact
+command and tags for each.
 
 ## 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
 
@@ -77,7 +100,16 @@ needed.
    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.
+   back — necessary, not sufficient. If this layer also has to create the
+   package it lands in (the first module through `contract` creates
+   `packages/contracts`), its shell files 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. That section also owns
+   the workspace wiring a new package needs (`pnpm install`, `pnpm nx
+   sync`, and its own `chore(workspace):` commit) — follow it rather than
+   leaving the package unlinked for a later layer to trip over.
 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

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

@@ -32,7 +32,9 @@ before the next starts.
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
 project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+needed. The `hook` layer's first-arrival package shell is a generator
+call, not a hand-copy of a sibling package — `hedgehog-loop`'s "First
+arrival in a package" section names the exact command and tags.
 
 If the screen step calls for animation or motion — entrances, sequencing,
 scroll-driven effects, drag, SVG/morph effects — use GSAP, loading the
@@ -46,17 +48,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.
@@ -83,7 +94,13 @@ don't reach for a second one.
    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.
+   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") — that section also
+   owns the workspace wiring the new package needs.
 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

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,47 @@ 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.
+const FULL_STACK_APP_LAYER_TAGS = {
+  schema: { tags: ['scope:db', 'type:adapter'], dependsOnTags: [] },
+  contract: { tags: ['scope:contracts', 'type:contract'], dependsOnTags: ['type:adapter', 'type:util'] },
+  repository: { tags: ['scope:{module}', 'type:adapter'], dependsOnTags: ['type:adapter', 'type:contract', 'type:util'] },
+  service: { tags: ['scope:{module}', 'type:service'], dependsOnTags: ['type:adapter', 'type:contract', 'type:util'] },
+  controller: { tags: ['scope:api'], dependsOnTags: ['type:adapter', 'type:service', 'type:contract', 'type:util'] },
+  hook: { tags: ['scope:hooks', 'type:hook'], dependsOnTags: ['type:contract', 'type:util'] },
+  screen: { tags: ['scope:web'], dependsOnTags: ['scope:contracts', 'scope:hooks', 'scope:shared', 'type:util'] },
+};
+
+// 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(
+    "  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.',
+  );
+  return lines;
+}
+
 // The standing honesty requirement, appended to every packet.
 //
 // Every other section is task-specific — this one is constant, which is
@@ -264,8 +305,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 +314,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 +390,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 +403,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);
 }