@skyf0xx/hedgehog-core-full-stack-app 1.1.0 → 1.3.0

package/CLAUDE.core.md

@@ -22,46 +22,25 @@ steps from memory:
   `hedgehog verify`, which commits it on a pass. Also holds the Correction
   Protocol for fixing a wrong upstream step. Invoke it at the start of any
   build session and for "what's next".
+<!-- hedgehog:bootstrap-only start -->
 - **`hedgehog-bootstrap`** — run **once**, at project start, to scaffold
   the core stack, the enforcement config, and whichever add-ons (Auth,
   Queue, Mobile) planning intake turned on. Skip if `nx.json` already
   exists.
+<!-- hedgehog:bootstrap-only end -->
 - **`conventional-commits`** — when a change spans several steps in one
   working-tree pass and needs splitting back into per-step commits (mainly
   Correction Protocol cleanups).
 
 ### The agents — delegate the judgment calls
 
-- **`planner`** — planning intake (which core applies, then
-  `hedgehog-planning-intake`'s BMAD-METHOD brainstorming/brief/PRD/UX-spec
-  shelf, mined into intent records, the Add-ons decision, and domain
-  vocabulary) at project start. Writes intents via `hedgehog intent add`,
-  `.hedgehog/addons.yaml`, and `.hedgehog/BMAD/`. On first run, hands off
-  to the `bootstrap` agent once Confirm & Lock holds. Runs again whenever
-  new scope enters play — including after the build is complete — taking
-  `hedgehog-planning-intake`'s **Re-entry pass**: the BMAD shelf and
-  `bootstrap` are both skipped, new modules are mined into additional
-  intents, and `hedgehog plan` appends their tasks without touching
-  anything already built.
-- **`bootstrap`** — runs `hedgehog-bootstrap`'s core steps (always) plus
-  whichever add-on steps planning intake turned on. Triggered
-  automatically by `planner` after its first run; skip if `nx.json`
-  already exists.
-- **`backend-eng`** — builds each module's Phase A layers (schema →
-  contract → repository → service → controller → queue?), one
-  `hedgehog claim`ed packet at a time, gated by `hedgehog verify`.
-- **`ux-planner`** — once per module in Phase B, after the hook exists and
-  before the screen: writes `docs/design/<module>.md`, reading
-  `.hedgehog/BMAD/05-ux-spec/` directly (or
-  `docs/design/<module>-notes.md` if a prior run already filed one). Where
-  the archive holds no UX spec, it asks for visual input rather than
-  inferring a direction.
-- **`front-end-eng`** — builds each module's Phase B layers (hook, screen)
-  from the ux-planner rationale, one `hedgehog claim`ed packet at a time,
-  gated by `hedgehog verify`.
-- **`reviewer`** — phase-transition and Correction Protocol checks the
-  mechanical gate can't make (port discipline, FK-by-ID discipline,
-  contract shape).
+`backend-eng` builds each module's Phase A layers (schema → contract →
+repository → service → controller → queue?), one `hedgehog claim`ed
+packet at a time, gated by `hedgehog verify`. `front-end-eng` builds
+each module's Phase B layers (hook, screen) from `ux-planner`'s
+rationale, the same way. See `hedgehog-loop` for exactly which agent
+owns which layer and the claim/verify sequencing — that skill is the
+source, not restated here.
 
 ## The constants (do not deviate)
 
@@ -121,9 +100,6 @@ docs/
   design     <module>.md (ux-planner, reading .hedgehog/BMAD/05-ux-spec/ directly)
 ```
 
-Check `.hedgehog/addons.yaml` before assuming any "only if" line above is
-actually present in this codebase.
-
 ### Core rules
 
 - **One table = one domain module.** Each carries the full step sequence.

package/agents/backend-eng.md

@@ -51,12 +51,12 @@ 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. 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.
+  module per table, cross-module references FK-by-ID only (root
+  CLAUDE.md's Core rules) — 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`. A `date`-mode
   `timestamp` column reflected through `createSelectSchema` is overridden
@@ -101,8 +101,7 @@ catch.
    the packet's scope and rules don't account for; your own tests prove
    internal consistency, never coverage of what was asked. INHERITED DEBT
    is what the layers you depend on declared they left for you; declare
-   your own with `hedgehog debt add <task-id> "<note>"` rather than a
-   code comment nothing reads. Its WHY NOW section
+   your own with `hedgehog debt add <task-id> "<note>"`. Its WHY NOW section
    already confirms the module is in scope and every dependency is
    `complete` — no need to re-derive that by hand. Cross-module FK
    targets should already have their own schema landed (the packet's
@@ -122,14 +121,10 @@ catch.
    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. 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.
+3. **Report the work as done; do not commit it yourself.** 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
@@ -154,7 +149,7 @@ catch.
   reported rather than chosen here. `verify` cannot check any of this,
   which is exactly why it's on you.
 - Never import another module's repository, service, or schema directly
-  — cross-module references are FK-by-ID, resolved at the
+  — FK-by-ID only (root CLAUDE.md's Core rules), resolved at the
   contract/controller layer (parallel calls) or via a same-repository
   Drizzle join against the other module's *schema*, never its adapter.
 - Never write queue infra when the Queue add-on is off (per

package/agents/front-end-eng.md

@@ -96,8 +96,7 @@ don't reach for a second one.
    and rules don't account for; your own tests prove internal
    consistency, never coverage of what was asked. INHERITED DEBT is what
    the layers you depend on declared they left for you; declare your own
-   with `hedgehog debt add <task-id> "<note>"` rather than a code comment
-   nothing reads. Its WHY NOW section already
+   with `hedgehog debt add <task-id> "<note>"`. Its WHY NOW section already
    confirms Phase A is closed for this module (the `hook`/`screen`
    layer's dependencies wouldn't be `complete` otherwise) — no need to
    re-derive that by hand. If you're handed a step outside a packet with
@@ -116,12 +115,10 @@ don't reach for a second one.
    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). 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.
+3. **Report the work as done; do not commit it yourself.** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog-core-full-stack-app",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Hedgehog's full-stack-app core: an Nx/pnpm/NestJS/Next.js workspace, backend-first domain module build discipline, and the agents and skills that drive it.",
   "type": "module",
   "scripts": {

package/skills/hedgehog-loop/SKILL.md

@@ -9,9 +9,10 @@ The operating loop for a bootstrapped Hedgehog project: `hedgehog claim`
 reserves the packet(s) for ready layers, build them, `hedgehog verify`
 gates and commits each. The build graph (`.hedgehog/hedgehog.db`) is the
 live list — query it via `hedgehog status`/`hedgehog ready`, never
-re-derive state from prose. The step tables below mirror this core's
+re-derive state from prose. The step table in the [scaffolding
+reference](references/scaffolding.md) mirrors this core's
 `workspace/core.yaml`, the design source of truth
-for layer order, scope, and verify command per layer — read the tables
+for layer order, scope, and verify command per layer — read the table
 for the human-readable shape, and the YAML when they seem to disagree.
 
 The packet, though, is what actually runs. `hedgehog plan` copies each
@@ -44,14 +45,14 @@ Phase A.
 
 ## The Domain Module Pattern
 
-A **domain module = one table.** `users`, `orders`, `order_items` are each
-their own module, carrying the full step sequence below. The schema is the
-source of truth for module boundaries.
+Root CLAUDE.md's Core rules own "one table = one domain module" and
+"FK-by-ID only" — this section is their mechanics. `users`, `orders`,
+`order_items` are each their own module, carrying the full step sequence
+below. The schema is the source of truth for module boundaries.
 
-**Cross-module references are FK-by-ID only.** If `orders.user_id`
-references `users`, the `orders` schema holds a plain FK column. The
-`orders` repository and service depend only on their own ports — a service
-knows related entities only as an ID.
+If `orders.user_id` references `users`, the `orders` schema holds a plain
+FK column. The `orders` repository and service depend only on their own
+ports — a service knows related entities only as an ID.
 
 - Need the related row? Resolve it at the contract/controller layer
   (parallel calls to each module's own endpoint), or join against the
@@ -96,49 +97,30 @@ What's authored on top is the entity-specific delta: the field list and
 its types, the module's business rules, and the UX intent behind its
 screen.
 
-## Domain Module — Backend Steps (Phase A, every module in scope)
-
-A horizontal pass across the whole backend — every module goes through
-these before any module gets a hook or screen. Each row is one compiled
-layer in `full-stack-app/core.yaml`; delegate each module's Phase A
-layers to the `backend-eng` agent, one claimed packet per dispatch — it
-builds the layer, `hedgehog verify` gates and commits it.
-
-| # | Layer | Lives in | Commit |
-|---|---|---|---|
-| 1 | `schema` | `packages/db` (Drizzle) | `feat(<module>): schema` |
-| 2 | `contract` | `packages/contracts` (Zod via `drizzle-zod` + ts-rest) | `feat(<module>): contract` |
-| 3 | `repository` | `libs/<module>/repository` (port + Drizzle adapter) | `feat(<module>): repository` |
-| 4 | `service` | `libs/<module>/service` (domain logic — imports only ports) | `feat(<module>): service` |
-| 5 | `controller` | `apps/api` (thin HTTP, wires contract → service; bundles Queue infra, see above, if that add-on is on and this module needs it) | `feat(<module>): api` |
-
-Repeat 1–5 per module in scope, via `hedgehog claim`/`hedgehog verify`.
-The API is complete, typed, and callable (Postman/curl/contract tests)
-before frontend work starts.
-
-## Domain Module — Frontend Steps (Phase B, after Phase A closes for the module)
-
-| # | Layer | Lives in | Commit |
-|---|---|---|---|
-| 6 | `hook` | `packages/hooks` (TanStack Query) | `feat(<module>): hooks` |
-| 6a | UX rationale | `docs/design/<module>.md`, `ux-planner` agent | bundled into layer 7's commit |
-| 7 | `screen` | `apps/web`, plus `apps/mobile` when the Mobile add-on is on | `feat(<module>): screen-web`, or `feat(<module>): screen` when the Mobile add-on is on |
-
-Phase B starts once Phase A is done for the scope. The frontend is a pure
-consumer of an already-finished API. Delegate each module's Phase B
-layers to the `front-end-eng` agent, same reasoning as `backend-eng` for
-Phase A — one claimed packet per dispatch, in its own context. Step
-6a is where "how it should feel" gets decided — once per module, after
-the `hook` layer's task is `complete` and before `front-end-eng` starts
-the `screen` layer — via `ux-planner`, starting from whatever `planner`
-filed in `docs/design/<module>-notes.md` at planning intake, or the raw
-UX spec directly if that file is absent, or — where the archive holds
-neither — from the contract and hook plus whatever the user supplies when
-it asks. Its first run for a module also
-signals to the user that Phase B has started, and is the point a mockup,
-screenshot, or export (Google Stitch, Figma) can be handed over. It
-writes `docs/design/<module>.md`, not its own compiled layer — the
-`screen` layer's `hedgehog verify` is what gates and commits it.
+## Domain Module — Backend and Frontend Steps
+
+Each module goes through `schema` → `contract` → `repository` → `service`
+→ `controller` in Phase A, then `hook` → `screen` in Phase B — the same
+sequence "The Domain Module Pattern" above states. Read the [scaffolding
+reference](references/scaffolding.md) for the full step table (layer,
+where it lives, its commit message) and the generator command each layer
+starts from. Delegate each module's Phase A layers to `backend-eng` and
+Phase B layers to `front-end-eng`, one claimed packet per dispatch — it
+builds the layer, `hedgehog verify` gates and commits it. The API is
+complete, typed, and callable (Postman/curl/contract tests) before
+frontend work starts.
+
+Between the `hook` layer's task going `complete` and `front-end-eng`
+starting the `screen` layer, `ux-planner` runs once per module to decide
+"how it should feel" — starting from whatever `planner` filed in
+`docs/design/<module>-notes.md` at planning intake, or the raw UX spec
+directly if that file is absent, or — where the archive holds neither —
+from the contract and hook plus whatever the user supplies when it asks.
+Its first run for a module also signals to the user that Phase B has
+started, and is the point a mockup, screenshot, or export (Google Stitch,
+Figma) can be handed over. It writes `docs/design/<module>.md`, not its
+own compiled layer — the `screen` layer's `hedgehog verify` is what gates
+and commits it.
 
 ## The Loop (every unit of work)
 
@@ -193,12 +175,8 @@ writes `docs/design/<module>.md`, not its own compiled layer — the
    `hedgehog verify <task-id> --owner <owner>` (the same owner that
    claimed it; verify requires the lease owner). Building happens in
    parallel; verifying does not — verify writes a commit, and commits go
-   through one at a time. It checks the touched files against the
-   packet's ALLOWED SCOPE, runs the layer's VERIFICATION command, and on
-   a pass writes the commit (the exact Conventional Commit message from
-   the tables above, plus the updated build graph) and unlocks the next
-   layer. On a scope violation or a failing check, the task moves to
-   `blocked` with a `blocked_reason` of `scope_violation` or
+   through one at a time. On a scope violation or a failing check, the
+   task moves to `blocked` with a `blocked_reason` of `scope_violation` or
    `verification_failed`, and nothing downstream unlocks. Fix the work,
    then run `hedgehog retry <task-id>` to return the task to `planned`,
    claim it again (by task id — see below), and verify again —
@@ -238,7 +216,7 @@ the built work against it there, because nothing else in the build does.
 A layer that hits a limitation the next layer must compensate for
 declares it with `hedgehog debt add <task-id> "<note>"`; the note lands
 in the **INHERITED DEBT** section of every packet that depends on that
-task. A comment in a source file is not a mechanism — nothing reads it.
+task.
 
 Each `hedgehog verify` call commits exactly one layer, built right for
 what's known now; a wrong layer is fixed forward later via the
@@ -249,183 +227,21 @@ or `lease_expired`).
 
 ## Scaffolding a layer
 
-`tools/generators/` holds one Nx generator per layer, and every layer
-starts from its own:
-
-```bash
-nx g ./tools/generators:schema     --module=<module> --fields='<name:type,...>'
-nx g ./tools/generators:contract   --module=<module> --fields='<name:type,...>' [--toggleField=<boolField>]
-nx g ./tools/generators:repository --module=<module>
-nx g ./tools/generators:service    --module=<module> [--toggleField=<boolField>]
-nx g ./tools/generators:controller --module=<module> --fields='<name:type,...>' [--toggleField=<boolField>]
-nx g ./tools/generators:hook       --module=<module> [--toggleField=<boolField>]
-nx g ./tools/generators:screen     --module=<module>
-```
-
-`--module` is the domain module's plural kebab-case name (`tasks`,
-`order-items`). `--fields` is a comma-separated list of `name:type` pairs
-over `string`, `text`, `boolean`, `integer`, and `timestamp`, with a
-trailing `?` marking the column nullable
-(`--fields='title:string,done:boolean,dueDate:timestamp?'`); `contract`
-and `controller` take the same list the module's `schema` was generated
-with. A `string` field takes an optional length in parentheses
-(`title:string(500)`), threaded to both the Drizzle `varchar` and the Zod
-`.max()` so the two cannot disagree; omitted, it is 255. Check every
-length against the intent's own rules in the packet's **RELEVANT RULES** —
-a rule like "at most 500 characters" is the field list's business, not
-the authored delta's, and a Zod bound that outruns its column surfaces as
-a driver error at the database rather than a 400 at the boundary.
-
-`--toggleField` names a boolean field from the schema to expose as a
-toggle, and is passed to `contract`, `service`, `controller`, and `hook`
-alike — one flag, four layers, so the route, the domain method, the
-handler, and the mutation are generated from one source. The toggle is
-server-side by construction: `POST /<module>/:id/toggle` carries no body,
-and the service reads the current value and flips it inside the same
-transaction its `update` uses. The client sends only the id, so a stale
-cached row cannot overwrite a newer state — which is exactly what
-computing the new value on the client would do, losing one of any two
-flips that raced. Note that `@ts-rest/core` generates no `body` parameter
-for a `c.noBody()` route: the call is `client.toggle({ params: { id } })`,
-and passing `body: undefined` is a compile error.
-
-Each generator lands the whole conventional shape of its layer in one
-deterministic step — the package shell (`package.json`, `tsconfig*.json`,
-`vitest.config.mts`, `src/index.ts`) where the layer creates one, the
-`nx.tags` pair `packages/config/eslint-base.js`'s `depConstraints` keys
-on, the port-discipline file suffixes lint checks for, the Nest module
-and controller pair with `@Controller()` left bare (the ts-rest contract
-already encodes full route paths), and every barrel export the new files
-need. Hand-copying a sibling module's files invites exactly the drift
-`hedgehog verify`'s lint step then has to catch: missing tags, missing
-project references, a doubled route prefix.
-
-What the generator lands is the layer's skeleton, not the layer. Author
-the entity-specific delta on top: the module's business rules in
-`service`, its domain-error mapping in `controller`, and — for `screen`,
-which is skeleton-only by design — the layout, information hierarchy, and
-interaction pattern from `ux-planner`'s rationale, over the placeholders
-the generator leaves for the list, filter shell, empty state, and form.
-
-Registration inside `apps/api` is automatic and stays that way:
-`apps/api/src/app/feature-modules.ts` globs
-`apps/api/src/app/*/*.module.ts` and is regenerated by the
-`generate-feature-modules` Nx target that `build`/`typecheck`/`test`
-depend on. Never register a module by editing `app.module.ts` — a shared
-file no module-scoped task can safely touch. Validation is ts-rest + Zod,
-so this core has no Nest DTOs and no class-validator.
-
-The root page is the same: `apps/web/src/app/page.tsx` renders whatever
-`module-routes.ts` holds, and that file is regenerated by the
-`generate-module-routes` Nx target from every
-`apps/web/src/app/*/page.tsx` on disk. A screen layer creates its own
-`page.tsx` in its own directory and the root page picks it up — never
-edit either the root page or the generated file to add a link.
-
-**A new package needs wiring into the workspace before `hedgehog verify`
-runs on it.** A package that exists on disk isn't yet part of the
-workspace:
-
-```bash
-pnpm install          # link the new workspace:* deps
-pnpm nx sync          # regenerate TypeScript project references
-```
-
-`pnpm-workspace.yaml` already globs `packages/*`, `apps/*` and `libs/*/*`,
-so a package under any of those needs no edit there. This is the common
-case, not an edge case: any layer that is the first arrival in a package
-(`contract`, `hook`, each module's `repository` and `service`) or that
-wires a new package into an existing one (`controller`, adding the
-module's `contracts`/`repository`/`service` packages to `apps/api`) needs
-it — on a module's first pass through Phase A/B that is most of the
-layers, not an occasional one.
-
-The building agent runs `pnpm install` / `pnpm nx sync` and reports back
-which shared files changed (typically `pnpm-lock.yaml`, root
-`tsconfig.json`, and — on a `controller` layer — `apps/api/package.json`,
-`apps/api/tsconfig.app.json`), because it has the shell access to run
-them, but it never commits: no agent reporting success moves a task or
-touches git, only `hedgehog verify`'s passing exit code does (see the
-building agents' own Workflow step on this). Committing those shared
-files is the orchestrating session's job, done between dispatch and
-`hedgehog verify` on every layer where the agent flagged a change: expect
-it, don't wait to be reminded.
-
-```bash
-git add pnpm-lock.yaml tsconfig.json   # plus apps/*/package.json,
-                                        # apps/*/tsconfig.app.json on a
-                                        # controller layer
-git commit -m "chore(workspace): sync project references"
-```
-
-These files are mechanically derived by `pnpm install` and `pnpm nx
-sync`, not authored content, and sit outside every module-scoped layer's
-scope — they belong to no layer, and no override covers them. Committing
-them separately, before `hedgehog verify` runs, keeps the layer's own
-commit exactly the layer.
-
-This is the orchestrating session's step rather than a verify post-step
-on purpose: `hedgehog verify` gates the tree it's handed, and a gate that
-mutates that tree would manufacture the scope violation it then reports.
+Every layer starts from its own generator in `tools/generators/`, which
+lands the layer's package shell, tags, and conventional shape in one
+deterministic step, and a new package needs `pnpm install`/`pnpm nx sync`
+wired in before `hedgehog verify` can run on it. Read the [scaffolding
+reference](references/scaffolding.md) for the generator commands, flag
+contract, and workspace-wiring steps.
 
 ## First arrival in a package
 
-Every layer scope names a directory *inside* a package
-(`packages/contracts/src/{module}/**`, `libs/{module}/repository/**`), and
-on the first module through that layer the package itself doesn't exist
-yet. Its shell — `package.json`, `tsconfig*.json`, `vitest.config.mts`,
-`src/index.ts` — necessarily lands outside the layer's scope glob, because
-no `{module}`-bearing glob can cover a package root. Left alone those files
-sit on disk uncommitted until the `join` layer's `**` scope sweeps them in,
-so `git log -- packages/contracts/` shows source with no buildable package
-behind it for the whole middle of the build.
-
-A generator can also drop shared, package-wide source at the `src/` root
-alongside the module's own files on that same first pass — the `contract`
-generator's `timestamp.ts` is one (a shared Zod util every module in the
-package imports, written once, sibling to `src/index.ts`). That file needs
-the same widening as the shell itself.
-
-The packet says so: when the package a scope points into has no
-`package.json` on disk yet, `hedgehog next`/`show` prints a **FIRST
-ARRIVAL** section under ALLOWED SCOPE carrying the exact command for that
-task. Run it before building — the widening is only available while the
-task is still `ready`, and a verify that rejects the shell paths blocks
-the task and turns this into a five-command recovery.
-
-```bash
-hedgehog override add TASKS-CONTRACT \
-  --scope 'packages/contracts/*' \
-  --scope 'packages/contracts/src/*' \
-  --reason 'first module through the contract layer also creates the package shell'
-```
-
-`packages/contracts/src/*` is non-recursive, so it covers `src/index.ts`
-and `src/timestamp.ts` without also granting the module subdirectory the
-layer's own `packages/contracts/src/{module}/**` scope already covers.
-
-`.hedgehog/overrides/*.json` is additive, per-task, committed, and replayed
-by `plan`, `--recompile` and `db rebuild` alike, so the exception survives a
-rebuild and stays reviewable in the diff — unlike a hand-edited task row,
-which the next rebuild silently drops. It widens exactly the one task that
-creates the package, not the layer, so module two's task keeps the narrow
-scope.
-
-Which tasks need it: the first module through `contract`
-(`packages/contracts`) and through `hook` (`packages/hooks`), and every
-module's `repository` and `service`, since `libs/{module}/repository` and
-`libs/{module}/service` are new libs per module — there, the layer's own
-`libs/{module}/repository/**` glob already covers the package root, so no
-override is needed. `packages/db` and `packages/config` ship with core, so
-`schema` never needs one. `controller` never needs one either — `apps/api`
-ships with core, and its `apps/api/src/app/{module}/**` scope already
-covers the module's generated directory.
-
-Never widen a scope to route around a violation the Correction Protocol
-should handle — this is for a package shell the layer genuinely creates,
-nothing else. The shell itself comes from the layer's generator
-("Scaffolding a layer" above), which is also where the workspace wiring a
-new package needs lives.
+The first module through a layer whose scope names a directory inside a
+package that doesn't exist yet on disk needs its scope widened for that
+one task, since the package shell lands outside the layer's own
+`{module}`-bearing glob. Read the [first arrival
+reference](references/first-arrival.md) for which layers this applies to
+and the `hedgehog override add` command it calls for.
 
 ## Intra-step conventions
 
@@ -615,8 +431,8 @@ the graph doesn't have a task for.
   committed.
 - The screen step doesn't start blank — `ux-planner` runs once per module,
   after the hook is committed, before `front-end-eng` starts the screen.
-- `packages/config` is the single source for shared config; a per-app
-  override request signals to fix the base config at the source.
+- `packages/config` is the single source for shared config (root
+  CLAUDE.md's Core rules).
 
 ## Stop Condition
 

package/skills/hedgehog-loop/references/first-arrival.md

@@ -0,0 +1,60 @@
+# First arrival in a package
+
+Every layer scope names a directory *inside* a package
+(`packages/contracts/src/{module}/**`, `libs/{module}/repository/**`), and
+on the first module through that layer the package itself doesn't exist
+yet. Its shell — `package.json`, `tsconfig*.json`, `vitest.config.mts`,
+`src/index.ts` — necessarily lands outside the layer's scope glob, because
+no `{module}`-bearing glob can cover a package root. Left alone those files
+sit on disk uncommitted until the `join` layer's `**` scope sweeps them in,
+so `git log -- packages/contracts/` shows source with no buildable package
+behind it for the whole middle of the build.
+
+A generator can also drop shared, package-wide source at the `src/` root
+alongside the module's own files on that same first pass — the `contract`
+generator's `timestamp.ts` is one (a shared Zod util every module in the
+package imports, written once, sibling to `src/index.ts`). That file needs
+the same widening as the shell itself. See [scaffolding a
+layer](scaffolding.md) for what a layer's generator lands and the
+`pnpm install` / `pnpm nx sync` workspace wiring a new package needs.
+
+The packet says so: when the package a scope points into has no
+`package.json` on disk yet, `hedgehog next`/`show` prints a **FIRST
+ARRIVAL** section under ALLOWED SCOPE carrying the exact command for that
+task. Run it before building — the widening is only available while the
+task is still `ready`, and a verify that rejects the shell paths blocks
+the task and turns this into a five-command recovery.
+
+```bash
+hedgehog override add TASKS-CONTRACT \
+  --scope 'packages/contracts/*' \
+  --scope 'packages/contracts/src/*' \
+  --reason 'first module through the contract layer also creates the package shell'
+```
+
+`packages/contracts/src/*` is non-recursive, so it covers `src/index.ts`
+and `src/timestamp.ts` without also granting the module subdirectory the
+layer's own `packages/contracts/src/{module}/**` scope already covers.
+
+`.hedgehog/overrides/*.json` is additive, per-task, committed, and replayed
+by `plan`, `--recompile` and `db rebuild` alike, so the exception survives a
+rebuild and stays reviewable in the diff — unlike a hand-edited task row,
+which the next rebuild silently drops. It widens exactly the one task that
+creates the package, not the layer, so module two's task keeps the narrow
+scope.
+
+Which tasks need it: the first module through `contract`
+(`packages/contracts`) and through `hook` (`packages/hooks`), and every
+module's `repository` and `service`, since `libs/{module}/repository` and
+`libs/{module}/service` are new libs per module — there, the layer's own
+`libs/{module}/repository/**` glob already covers the package root, so no
+override is needed. `packages/db` and `packages/config` ship with core, so
+`schema` never needs one. `controller` never needs one either — `apps/api`
+ships with core, and its `apps/api/src/app/{module}/**` scope already
+covers the module's generated directory.
+
+Never widen a scope to route around a violation the Correction Protocol
+should handle — this is for a package shell the layer genuinely creates,
+nothing else. The shell itself comes from the layer's generator, which is
+also where the workspace wiring a new package needs lives (see
+[scaffolding a layer](scaffolding.md)).

package/skills/hedgehog-loop/references/scaffolding.md

@@ -0,0 +1,151 @@
+# Scaffolding a layer
+
+Every module in this core goes through the same layer sequence, in order:
+
+```
+schema      (Drizzle)              — types before data
+contract    (Zod / ts-rest)        — the boundary
+repository  (port + Drizzle adapter)
+service     (domain logic)         — imports only ports
+controller  (thin HTTP)
+hook        (TanStack Query)       — Phase B only
+screen      (Next.js / Expo)       — Phase B only
+```
+
+`workspace/core.yaml` declares this as `pattern: vertical-slice` — every
+layer's scope carries `{module}`, so the chain runs once per module,
+independently, joined only at the exclusive `join` layer. Each row below
+is one compiled layer; `backend-eng` builds the Phase A rows (`schema`
+through `controller`), `front-end-eng` builds the Phase B rows (`hook`,
+`screen`), one claimed packet per dispatch — it builds the layer,
+`hedgehog verify` gates and commits it.
+
+| # | Layer | Lives in | Commit |
+|---|---|---|---|
+| 1 | `schema` | `packages/db` (Drizzle) | `feat(<module>): schema` |
+| 2 | `contract` | `packages/contracts` (Zod via `drizzle-zod` + ts-rest) | `feat(<module>): contract` |
+| 3 | `repository` | `libs/<module>/repository` (port + Drizzle adapter) | `feat(<module>): repository` |
+| 4 | `service` | `libs/<module>/service` (domain logic — imports only ports) | `feat(<module>): service` |
+| 5 | `controller` | `apps/api` (thin HTTP, wires contract → service; bundles Queue infra if that add-on is on and this module needs it) | `feat(<module>): api` |
+| 6 | `hook` | `packages/hooks` (TanStack Query) | `feat(<module>): hooks` |
+| 7 | `screen` | `apps/web`, plus `apps/mobile` when the Mobile add-on is on | `feat(<module>): screen-web`, or `feat(<module>): screen` when the Mobile add-on is on |
+
+`tools/generators/` holds one Nx generator per layer, and every layer
+starts from its own:
+
+```bash
+nx g ./tools/generators:schema     --module=<module> --fields='<name:type,...>'
+nx g ./tools/generators:contract   --module=<module> --fields='<name:type,...>' [--toggleField=<boolField>]
+nx g ./tools/generators:repository --module=<module>
+nx g ./tools/generators:service    --module=<module> [--toggleField=<boolField>]
+nx g ./tools/generators:controller --module=<module> --fields='<name:type,...>' [--toggleField=<boolField>]
+nx g ./tools/generators:hook       --module=<module> [--toggleField=<boolField>]
+nx g ./tools/generators:screen     --module=<module>
+```
+
+`--module` is the domain module's plural kebab-case name (`tasks`,
+`order-items`). `--fields` is a comma-separated list of `name:type` pairs
+over `string`, `text`, `boolean`, `integer`, and `timestamp`, with a
+trailing `?` marking the column nullable
+(`--fields='title:string,done:boolean,dueDate:timestamp?'`); `contract`
+and `controller` take the same list the module's `schema` was generated
+with. A `string` field takes an optional length in parentheses
+(`title:string(500)`), threaded to both the Drizzle `varchar` and the Zod
+`.max()` so the two cannot disagree; omitted, it is 255. Check every
+length against the intent's own rules in the packet's **RELEVANT RULES** —
+a rule like "at most 500 characters" is the field list's business, not
+the authored delta's, and a Zod bound that outruns its column surfaces as
+a driver error at the database rather than a 400 at the boundary.
+
+`--toggleField` names a boolean field from the schema to expose as a
+toggle, and is passed to `contract`, `service`, `controller`, and `hook`
+alike — one flag, four layers, so the route, the domain method, the
+handler, and the mutation are generated from one source. The toggle is
+server-side by construction: `POST /<module>/:id/toggle` carries no body,
+and the service reads the current value and flips it inside the same
+transaction its `update` uses. The client sends only the id, so a stale
+cached row cannot overwrite a newer state — which is exactly what
+computing the new value on the client would do, losing one of any two
+flips that raced. Note that `@ts-rest/core` generates no `body` parameter
+for a `c.noBody()` route: the call is `client.toggle({ params: { id } })`,
+and passing `body: undefined` is a compile error.
+
+Each generator lands the whole conventional shape of its layer in one
+deterministic step — the package shell (`package.json`, `tsconfig*.json`,
+`vitest.config.mts`, `src/index.ts`) where the layer creates one, the
+`nx.tags` pair `packages/config/eslint-base.js`'s `depConstraints` keys
+on, the port-discipline file suffixes lint checks for, the Nest module
+and controller pair with `@Controller()` left bare (the ts-rest contract
+already encodes full route paths), and every barrel export the new files
+need. Hand-copying a sibling module's files invites exactly the drift
+`hedgehog verify`'s lint step then has to catch: missing tags, missing
+project references, a doubled route prefix.
+
+What the generator lands is the layer's skeleton, not the layer. Author
+the entity-specific delta on top: the module's business rules in
+`service`, its domain-error mapping in `controller`, and — for `screen`,
+which is skeleton-only by design — the layout, information hierarchy, and
+interaction pattern from `ux-planner`'s rationale, over the placeholders
+the generator leaves for the list, filter shell, empty state, and form.
+
+Registration inside `apps/api` is automatic and stays that way:
+`apps/api/src/app/feature-modules.ts` globs
+`apps/api/src/app/*/*.module.ts` and is regenerated by the
+`generate-feature-modules` Nx target that `build`/`typecheck`/`test`
+depend on. Never register a module by editing `app.module.ts` — a shared
+file no module-scoped task can safely touch. Validation is ts-rest + Zod,
+so this core has no Nest DTOs and no class-validator.
+
+The root page is the same: `apps/web/src/app/page.tsx` renders whatever
+`module-routes.ts` holds, and that file is regenerated by the
+`generate-module-routes` Nx target from every
+`apps/web/src/app/*/page.tsx` on disk. A screen layer creates its own
+`page.tsx` in its own directory and the root page picks it up — never
+edit either the root page or the generated file to add a link.
+
+**A new package needs wiring into the workspace before `hedgehog verify`
+runs on it.** A package that exists on disk isn't yet part of the
+workspace:
+
+```bash
+pnpm install          # link the new workspace:* deps
+pnpm nx sync          # regenerate TypeScript project references
+```
+
+`pnpm-workspace.yaml` already globs `packages/*`, `apps/*` and `libs/*/*`,
+so a package under any of those needs no edit there. This is the common
+case, not an edge case: any layer that is the first arrival in a package
+(`contract`, `hook`, each module's `repository` and `service`) or that
+wires a new package into an existing one (`controller`, adding the
+module's `contracts`/`repository`/`service` packages to `apps/api`) needs
+it — on a module's first pass through Phase A/B that is most of the
+layers, not an occasional one. See [first arrival in a
+package](first-arrival.md) for the scope-widening override this same
+situation needs.
+
+The building agent runs `pnpm install` / `pnpm nx sync` and reports back
+which shared files changed (typically `pnpm-lock.yaml`, root
+`tsconfig.json`, and — on a `controller` layer — `apps/api/package.json`,
+`apps/api/tsconfig.app.json`), because it has the shell access to run
+them, but it never commits: no agent reporting success moves a task or
+touches git, only `hedgehog verify`'s passing exit code does. Committing
+those shared files is the orchestrating session's job, done between
+dispatch and `hedgehog verify` on every layer where the agent flagged a
+change: expect it, don't wait to be reminded.
+
+```bash
+git add pnpm-lock.yaml tsconfig.json   # plus apps/*/package.json,
+                                        # apps/*/tsconfig.app.json on a
+                                        # controller layer
+git commit -m "chore(workspace): sync project references"
+```
+
+These files are mechanically derived by `pnpm install` and `pnpm nx
+sync`, not authored content, and sit outside every module-scoped layer's
+scope — they belong to no layer, and no override covers them. Committing
+them separately, before `hedgehog verify` runs, keeps the layer's own
+commit exactly the layer.
+
+This is the orchestrating session's step rather than a verify post-step
+on purpose: `hedgehog verify` gates the tree it's handed, and a gate that
+mutates that tree would manufacture the scope violation it then reports.