@skyf0xx/hedgehog 0.1.2 → 0.1.7

package/README.md

@@ -124,6 +124,7 @@ Hedgehog is a package of agents and skills. An opinionated stack is used so the
 | Backend | NestJS | Modules naturally mirror Hedgehog's build progression. |
 | ORM | Drizzle + drizzle-zod | Database schema is the single source of truth. |
 | Database | PostgreSQL | Simple, relational, predictable. |
+| Local infra | Docker Compose | Postgres/Redis run identically on every machine. |
 | Platform | Railway | Infrastructure is available from the first commit. |
 | API contract | ts-rest | Contracts are code, not documentation. |
 | Validation | Zod | One schema for runtime and compile time. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.2",
+  "version": "0.1.7",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -13,6 +13,9 @@
   "bin": {
     "hedgehog": "bin/cli.mjs"
   },
+  "scripts": {
+    "release": "npm version patch -m \"chore: bump version to %s\""
+  },
   "files": [
     "bin",
     "src/agents",

package/src/agents/planner.md

@@ -56,8 +56,13 @@ Revising a draft is a normal edit — the Correction Protocol
 
 1. **Scope boundary** — what's in, what's explicitly out.
 2. **Domain vocabulary** — the nouns and verbs of the problem.
-3. **Screen/flow notes**, when offered — captured verbatim by module, for
-   `ux-planner` to act on at that module's Phase B (see below).
+3. **`docs/context.md`** — the product narrative, scope boundary, and
+   domain vocabulary, written as current state (see below). Mandatory,
+   every project gets one.
+4. **Screen/flow notes** — captured by module in
+   `docs/design/<module>-notes.md`, for `ux-planner` to act on at that
+   module's Phase B (see below). Mandatory per module in scope, even when
+   nothing was offered for that module.
 
 ### Screens, flows, and other visual input
 
@@ -68,11 +73,70 @@ here, and doubles as raw material for Phase B later.
 
 Layout, styling, and interaction described — "the dashboard should show X
 and Y together," "this should feel like Stripe's checkout" — are
-captured under the relevant module in `docs/design/<module>-notes.md`
-(create it if needed). `ux-planner` turns this into a screen rationale
-once that module's contract and hook exist, in Phase A build order. Name
-this in the moment: "noted for `<module>`'s screen — that gets built
-after its API is working."
+captured under the relevant module in `docs/design/<module>-notes.md`.
+`ux-planner` turns this into a screen rationale once that module's
+contract and hook exist, in Phase A build order. Name this in the moment:
+"noted for `<module>`'s screen — that gets built after its API is
+working."
+
+Every module in scope gets this file, whether or not anything was
+offered for it — a module with no screen input yet still gets a
+`docs/design/<module>-notes.md` stating that plainly, not a missing
+file.
+
+### Interview formatting
+
+The interview is the whole UI — there's no screen to lean on, so
+structure carries the weight a layout normally would. Keep a light,
+consistent set of markers so the person can tell at a glance what kind of
+turn they're reading, without turning the transcript noisy:
+
+- A bold section title on entering a new stage (`**Scope**`,
+  `**Domain vocabulary**`, `**Confirm & lock**`) — once per stage, not
+  once per message.
+- 🧭 for the opening brain-dump prompt, ❓ for a single follow-up
+  question, 🔍 for reading supplied material (a screenshot, a
+  spreadsheet), 📋 for a synthesis recap, 🔒 for the final confirmation
+  gate. One icon per turn, at most — this marks the kind of turn, it
+  isn't decoration.
+- Tables for anything tabular (scope boundary, vocabulary) — never
+  prose pretending to be a table.
+- Short paragraphs, one question per turn (already required below) —
+  never stack multiple asks in one block just because both fit.
+
+This applies to every Intake turn from here on, not just the ones
+below.
+
+### Confidence tracking
+
+Track a running confidence estimate for "I know what this person
+actually wants" — not "I have enough to start guessing." Confidence
+rises only when an answer resolves genuine ambiguity; a detail that
+just restates something already clear doesn't move it.
+
+State it out loud periodically as elicitation progresses — after
+synthesis produces a draft, and any time confidence is low enough that
+continuing to guess would be worse than asking:
+
+> Confidence: ~70% — clear on the core flow and the actors, still open
+> on what "cancel" means once payment's been taken, and whether
+> `status` is a single lifecycle or independent tags.
+
+Keep asking until confidence reaches **95%**: every module has a
+resolved "owned by," at least one out-of-scope item has surfaced, and
+no term is doing double duty for two different lifecycles (see "When
+to ask instead of guess," below). 95% is a floor on understanding
+what's real, not a ceiling on how much detail to gather — don't pad the
+interview past the point where more questions stop resolving
+ambiguity. If the person answers "I don't know, just pick something,"
+that's a resolved answer (their call, recorded as such) — it moves
+confidence up, not down.
+
+Never silently settle for "what I think they should want." If a
+guess would fill a gap, surface it as a candidate to confirm or
+correct instead of writing it into the draft unchallenged — this is
+the same move as "offering a candidate boundary... to confirm or
+correct" below, applied to every gap, not just scope.
 
 ### Elicitation — what to ask
 
@@ -141,10 +205,50 @@ on — read which one this is early and let it set the pace.
    to.
 5. **Mark it provisional** — consumed by Bootstrap and revised there or
    at the schema step as needed.
-6. **File any screen/flow notes** under their module in
-   `docs/design/<module>-notes.md`, verbatim or lightly organized — raw
-   material for `ux-planner`, not a rationale, so don't polish or
-   structure beyond attributing it to the right module.
+6. **Run Confirm & lock** (below) before writing anything. Only after
+   the person confirms does synthesis proceed to steps 7–8.
+7. **Write `docs/context.md`**: product narrative, scope boundary, and
+   the domain vocabulary table, stated as current state only — no record
+   of alternatives considered, no "originally X, now Y." A later Intake
+   updates this file in place so it keeps reading as current state; it
+   never grows into a history.
+8. **File screen/flow notes** under their module in
+   `docs/design/<module>-notes.md`, one file per module in scope, even
+   when nothing was offered for that module (say so plainly instead of
+   omitting the file) — verbatim or lightly organized, raw material for
+   `ux-planner`, not a rationale, so don't polish or structure beyond
+   attributing it to the right module.
+
+### Confirm & lock
+
+Everything above this point is provisional and cheap to change — nothing
+has been written yet. This stage is the last point before that stops
+being true, so it's a hard stop, not a recap in passing.
+
+🔒 **Confirm & lock**. Show, in full, not condensed:
+
+- The scope boundary table (in / out).
+- The domain vocabulary table (entity, definition, attributes, owned
+  by).
+- The module list in build order, with any cross-module FK dependencies
+  flagged.
+- The confidence estimate, and what it's based on (e.g. "95% — every
+  module has a resolved owner, one out-of-scope item confirmed, no
+  double-duty terms remaining").
+
+Then state plainly what happens on confirmation, before it happens:
+
+> This locks in `docs/context.md` and the per-module design notes, and
+> starts Phase A build (schema first) on the first module. Anything
+> wrong or missing — say so now; it's a normal edit before this point,
+> and a Correction Protocol entry after. Confirm to proceed, or tell me
+> what to change.
+
+Wait for an explicit go-ahead. A revision here is just another
+elicitation turn — update the draft, re-run this stage, don't write
+anything until the confirmation holds. Don't lower the bar because the
+person seems eager to start; the cost of a wrong schema is exactly why
+this gate exists.
 
 ### Worked example
 
@@ -199,15 +303,20 @@ ask now than fix forward later.
   schema.
 - Update `TODO.md` to reflect the checklist for what's in scope, mirroring
   the phase/step structure from `hedgehog-loop`.
+- Write and maintain `docs/context.md` — the product narrative, scope
+  boundary, and domain vocabulary, stated as current state only.
+  Mandatory on every project; not conditional on domain complexity.
 - Screens or flows described during Intake are captured under the
-  relevant module (`docs/design/<module>-notes.md`); Phase B, after the
-  backend exists for that module, is when they get acted on.
+  relevant module (`docs/design/<module>-notes.md`, one per module in
+  scope, always present); Phase B, after the backend exists for that
+  module, is when they get acted on.
 
 ## Workflow
 
 1. **Read the requirement** fully before doing anything.
-2. **Check `TODO.md` and the commit log** for what's already built —
-   `feat(<module>): api` commits mark modules with a closed Phase A.
+2. **Check `TODO.md`, `docs/context.md`, and the commit log** for what's
+   already built — `feat(<module>): api` commits mark modules with a
+   closed Phase A.
 3. **Run Intake** if this is project start: extract scope boundary and
    domain vocabulary per the procedure above. If input is insufficient,
    ask — don't guess at scope.
@@ -217,19 +326,35 @@ ask now than fix forward later.
    referenced by another's FK doesn't need to exist first — FK-by-ID
    means no compile-time coupling — but flag it if joined reads are
    expected from day one, since that shapes contract design).
-6. **Write/update `TODO.md`**: a checklist mirroring the Phase A and
+6. **Run Confirm & lock** (Intake procedure, above) before writing
+   anything below. On a project's first Intake this is mandatory; on a
+   later Intake adding new scope, re-run it scoped to what's new.
+7. **Write/update `TODO.md`**: a checklist mirroring the Phase A and
    Phase B steps per module in scope. Checked or unchecked is its only
    state. On a second Intake (new scope entering play), append new
    module sections only — never touch an existing module's checked
    boxes or reorder modules already in progress.
-7. **File any screen/flow notes** captured during Intake under
-   `docs/design/<module>-notes.md`, per module.
-8. **Return a summary**: scope boundary, module list, any open questions.
+8. **Write/update `docs/context.md`**: product narrative, scope boundary,
+   domain vocabulary — current state only. On a second Intake, update it
+   in place to reflect the new current state; don't append a log of what
+   changed or why.
+9. **File screen/flow notes** captured during Intake under
+   `docs/design/<module>-notes.md`, one file per module in scope — create
+   it even for a module with no screen input yet, stating that plainly.
+10. **Return a summary**: scope boundary, module list, any open
+    questions.
 
 ## Constraints
 
 - Never write or modify application code. Read-only against the
-  codebase; you may write `TODO.md` and `docs/design/<module>-notes.md`.
+  codebase; you may write `TODO.md`, `docs/context.md`, and
+  `docs/design/<module>-notes.md`.
+- `docs/context.md` and `docs/design/<module>-notes.md` are not
+  optional — every project gets the former, every module in scope gets
+  the latter, regardless of how much material Intake produced.
+- State current state only in `docs/context.md` — no negation of
+  alternatives, no changelog-style narration, no "we used to say X." If
+  Intake revises something, edit the file to say what's true now.
 - Never invent scope. Ambiguous scope means stop and ask.
 - Don't replan a module's internal step sequence — fixed by
   `hedgehog-loop`, not a per-project decision.

package/src/skills/hedgehog-bootstrap/SKILL.md

@@ -29,6 +29,7 @@ One opinionated stack, applied the same way on every project:
 | Backend framework | NestJS |
 | ORM | Drizzle (+ `drizzle-zod`) |
 | Database | PostgreSQL |
+| Local infra | Docker Compose (Postgres + Redis) |
 | Platform | Railway |
 | API contract | ts-rest |
 | Validation | Zod |
@@ -99,6 +100,20 @@ Confirm this hasn't already run: check for an existing Nx workspace
 existing workspace is a Correction Protocol case (patch the specific
 config step at its source, per `hedgehog-loop`), not a re-scaffold.
 
+If a fresh `pnpm install` in the generated workspace fails on a binary
+package's postinstall script with a version-mismatch error (e.g.
+"Expected X but got Y" for a native binary like `esbuild`), don't assume
+project misconfiguration or a corrupted pnpm store — check **Known issue:
+esbuild postinstall version mismatch** below first; this is a known,
+deterministic collision, not something to misdiagnose from scratch.
+
+Confirm Docker is available (`docker --version`) before step 1. Local
+Postgres/Redis run through Docker Compose on every host OS — see **Local
+infra: Docker, always** below. No Docker installed: stop and point the
+user to installing Docker Desktop (macOS/Windows) or Docker
+Engine (Linux) rather than falling back to a natively-installed
+Postgres/Redis.
+
 ## Steps (run in sequence, one commit per step)
 
 ### 1. Nx workspace + `packages/config`
@@ -119,6 +134,26 @@ pnpm add -D @nx/js
 one it falls into standalone (`.nx` wrapper) mode instead of a proper
 pnpm workspace.
 
+`nx init` does not reliably respect an existing `packageManager: pnpm@...`
+field — it can run its own install via npm regardless, leaving a
+`package-lock.json` next to the intended `pnpm-lock.yaml`. Immediately
+after `nx init` completes, check for `package-lock.json` at the repo
+root; if present, delete it and run `pnpm install` to regenerate
+`pnpm-lock.yaml` before continuing to step 2. Don't assume `nx init`
+respects the locked package manager — verify.
+
+`nx init` also does not create `pnpm-workspace.yaml`. Without it, pnpm
+doesn't recognize `packages/*` or `apps/*` as workspace members —
+`pnpm add -w` fails with `ERR_PNPM_ADDING_TO_ROOT`-adjacent errors, and
+cross-package `pnpm add` for a lib silently installs to the wrong place.
+Create it manually right after `nx init`, before the first `pnpm add`:
+
+```yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+```
+
 Then generate the first lib. The **first** `@nx/js:lib` call materializes
 the whole workspace shape (`tsconfig.base.json`, root `eslint.config.mjs`,
 `.prettierrc`, `vitest.workspace.ts`, the `packages/` layout, and the
@@ -135,7 +170,16 @@ files:
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib. Include `@nx/enforce-module-boundaries` and `depConstraints`
   from Enforcement wiring below, verbatim.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — **don't** add `prettier-plugin-tailwindcss`
+  here. The plugin parses every file prettier touches (not just files with
+  Tailwind classes) and throws (`TypeError: e.charAt is not a function` /
+  `a.startsWith is not a function`) on any file when no Tailwind config is
+  resolvable yet — which is every project from step 1 through step 5, since
+  Tailwind doesn't arrive until `apps/web` in step 6. Loading it globally
+  here breaks `nx format:write` and any bare `prettier --check` for the
+  first five steps of every project. Add the plugin to `apps/web`'s own
+  prettier setup (extending this base config) once Tailwind exists, not to
+  the shared base.
 - `packages/config/env.schema.ts` — the Zod env schema from Enforcement
   wiring below (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `REDIS_URL`,
   `NODE_ENV`; extend per project as new infra is added later).
@@ -143,6 +187,65 @@ files:
   declares the project tags table below (`scope:*`, `type:*`) as comments
   or a lookup, so every later generator step tags its project correctly.
 
+Root `eslint.config.mjs` is itself ESM (`.mjs`), which surfaces a Node
+warning ("Module type of file... is not specified") unless the root
+`package.json` declares `"type": "module"`. Setting that is correct and
+worth doing — but it changes how Node resolves *every* plain `.js` file
+in the repo from CommonJS to ESM by default. Several files later steps
+generate are CommonJS (`require`/`module.exports`) and will break with
+`ReferenceError: require is not defined` or `module is not defined` the
+moment `"type": "module"` is set: `apps/*/webpack.config.js`,
+`commitlint.config.js`, and any hand-written CommonJS tool script (e.g.
+`tools/phase-gate.js`). Rename each to `.cjs` as it's created (or convert
+its content to ESM, as `next.config.js` supports natively via
+`export default`) rather than discovering the break later when `nx
+graph` or a generator that depends on the project graph fails
+opaquely — Nx surfaces this as "Failed to process project graph" pointing
+at the offending file, not as a module-system explanation.
+
+Add a root `docker-compose.yml` provisioning Postgres and Redis for local
+dev, regardless of host OS (macOS, Windows, Linux) — see **Local infra:
+Docker, always** below for why this isn't optional. `DATABASE_URL` and
+`REDIS_URL` in `.env` point at the compose services from the first
+commit, matching the env schema below.
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis-data:/data
+
+volumes:
+  postgres-data:
+  redis-data:
+```
+
+Add an `esbuild` override to root `package.json` in this step, before step
+2 installs `drizzle-kit` — see **Known issue: esbuild postinstall version
+mismatch** below for why.
+
+```json
+{
+  "pnpm": {
+    "overrides": { "esbuild": "0.25.12" }
+  }
+}
+```
+
 Commit: `feat(config): workspace + shared config`
 
 ### 2. `packages/db` — Drizzle client + connection
@@ -182,6 +285,20 @@ structured logging. Call `loadEnv()` at the top of `apps/api/src/main.ts`.
 Tag: `scope:api`. No controllers beyond a health check — domain
 controllers arrive per module in Phase A.
 
+`@nx/nest:app` also scaffolds a companion `apps/api-e2e` project wired to
+Jest (`jest.config.cts`), not Vitest — inconsistent with the locked stack.
+Convert it: delete the Jest config, add a `vitest.config.mts` (mirroring
+`packages/db`'s), and give `apps/api-e2e`'s `tsconfig.spec.json` the same
+`composite`/`declaration` treatment as above. Rename its target from the
+plugin-inferred `test` to an explicit `e2e` — an HTTP e2e suite needs a
+live server (`dependsOn: ["api:build", "api:serve"]`), and if it keeps the
+default `test` name, `nx affected -t test` (what lefthook's pre-commit
+hook runs on every commit, per the Commit gate below) will try to boot a
+server on every commit. Exclude `apps/api-e2e` from the `@nx/vitest`
+plugin's auto-inference in `nx.json` (`"exclude": ["apps/api-e2e/**"]` on
+that plugin entry) so it stops registering a `test` target for this
+project at all, keeping only the manually-defined `e2e` target.
+
 Commit: `feat(api): nest shell + global guard + pino`
 
 ### 5. `apps/worker` — BullMQ seam (Redis, no consumers yet)
@@ -203,17 +320,73 @@ Commit: `feat(worker): bullmq seam, no consumers`
 ```bash
 npx nx g @nx/next:app apps/web
 pnpm add @tanstack/react-query
-pnpm dlx shadcn@latest init
 ```
 
-Wire the TanStack Query provider at the root layout. `shadcn init` writes
-`apps/web`'s base theme (CSS variables for color, radius, light/dark
-mode) — set the actual palette here, once, rather than leaving ShadCN's
-placeholder values for `ui-builder` to inherit unnoticed on the first
-screen. Light/dark mode toggle wiring belongs here too, not as a
-per-screen decision later. No screens or hooks yet — Phase B doesn't
+**Do not run `pnpm dlx shadcn@latest init` (or `shadcn add`) against
+`apps/web` directly.** The shadcn CLI hard-requires a `package.json` in
+its target directory to detect the project; an Nx-generated app under
+this stack has no per-app `package.json` (dependencies live at the
+workspace root). Finding none, the CLI's default behavior is to offer —
+and on `--yes`, silently proceed — to scaffold a *brand-new*
+`create-next-app` project **inside** `apps/web`, complete with its own
+nested `.git`, its own lockfile, and its own `package.json`. This doesn't
+error; it succeeds and leaves a corrupted nested project (e.g.
+`apps/web/web/`) that has to be manually detected and deleted. There is
+currently no supported non-interactive flag that makes shadcn's CLI
+target an existing package-json-less directory in place.
+
+Build the base theme by hand instead: write `apps/web/components.json`
+directly (style, aliases, `tailwind.css` path — the `css` field), add
+`class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, and
+`@radix-ui/react-slot` as dependencies, write `apps/web/src/lib/utils.ts`
+(the standard `cn()` helper), and hand-write the CSS variable theme block
+(light/dark, using shadcn's published default token values) into
+`apps/web`'s global stylesheet. Individual components (e.g. `button.tsx`)
+can then be hand-written from shadcn's published source for that
+component — small, stable, well-known files — rather than fetched via the
+CLI. Set the actual palette here, once, rather than leaving placeholder
+values for `ui-builder` to inherit unnoticed on the first screen. Light/
+dark mode toggle wiring belongs here too, not as a per-screen decision
+later.
+
+Wire the TanStack Query provider at the root layout (App Router: a
+`'use client'` `Providers` wrapper component, since the root layout
+itself is a server component). No screens or hooks yet — Phase B doesn't
 start until Phase A closes for at least one module. Tag: `scope:web`.
 
+**Set `NODE_ENV` explicitly on the `build` target, or the production
+build silently runs in dev mode under Nx.** Nx's task runner sets
+`NODE_ENV=development` by default for every task unless a target
+overrides it — including a plain `nx:run-commands` target running `next
+build`. Next.js's production build pipeline assumes `NODE_ENV=production`;
+running it under `development` produces a build that compiles and
+appears to succeed on individual pages but crashes prerendering the
+auto-generated `/_global-error` route with `TypeError: Cannot read
+properties of null (reading 'useContext')` — a React-internals mismatch
+from the dev/prod build split, not an app bug. This only reproduces
+through `nx run web:build`; the identical `next build --webpack` run
+directly from `apps/web` succeeds, because a bare shell has no `NODE_ENV`
+set and Next defaults it correctly itself — which makes the symptom look
+Nx-specific and environment-related rather than what it is (a task-runner
+default silently overriding a value the build assumes). Set it on the
+`build` target only, in `apps/web/project.json`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "options": {
+        "command": "next build --webpack",
+        "env": { "NODE_ENV": "production" }
+      }
+    }
+  }
+}
+```
+
+Leave `dev` alone — it correctly wants `NODE_ENV=development`, which is
+also what Nx already defaults it to.
+
 Commit: `feat(web): next shell + query provider + base theme`
 
 ### 7. `apps/mobile` — Expo shell (only if mobile is in scope)
@@ -288,6 +461,51 @@ e.g. `libs/orders/port`, `libs/orders/repository`, `libs/orders/service`.
 Building out of order (a controller before a service exists, a hook
 reaching into `apps/api` directly) fails `nx lint`.
 
+The rule list above is illustrative, not exhaustive — `@nx/enforce-
+module-boundaries` denies by default for any project whose tag isn't
+named as a `sourceTag` in some `depConstraints` entry ("A project without
+tags matching at least one constraint cannot depend on any libraries").
+`packages/db` (`scope:db`, `type:adapter`) and `apps/api` (`scope:api`)
+both hit this the moment they're generated and tagged in steps 2 and 4,
+because neither `type:adapter` nor `scope:api` has an entry above. Add
+constraints for every tag combination as it's introduced, not only the
+ones in the illustrative list — at minimum `type:adapter` (needs
+`type:util`, for `packages/config`) and `scope:api` (needs `type:port`,
+`type:service`, `type:util` — never `scope:db` directly; `apps/api`
+reaches storage through a module's repository/service, not by importing
+`packages/db` itself).
+
+### Typecheck target (required before the commit gate can work)
+
+`lefthook.yml`'s pre-commit below runs `nx affected -t typecheck`, but
+`@nx/js:lib` and `@nx/nest:app` don't register a `typecheck` target on
+their own — it only exists once the `@nx/js/typescript` plugin is
+registered in `nx.json`, added in step 1 alongside the eslint and
+vitest plugins:
+
+```json
+{
+  "plugin": "@nx/js/typescript",
+  "options": { "typecheck": { "targetName": "typecheck" } }
+}
+```
+
+Registering the plugin isn't sufficient on its own, either: `tsc
+--build`'s composite-project mode (what the inferred `typecheck` target
+actually runs) requires every `tsconfig.lib.json` and `tsconfig.spec.json`
+it touches to set `"composite": true` and `"declaration": true`. The
+generators don't set these — every `@nx/js:lib` and `@nx/nest:app`
+project needs both added by hand to `tsconfig.lib.json` /
+`tsconfig.app.json` and `tsconfig.spec.json` right after generation, or
+`nx run <proj>:typecheck` fails immediately with `TS5069: Option
+'emitDeclarationOnly' cannot be specified without specifying option
+'declaration' or option 'composite'`. If a project's spec file imports
+from its own lib source (the common case), `tsconfig.spec.json` also
+needs an explicit `references` entry pointing at `tsconfig.lib.json`, or
+`tsc` reports `TS6307: File '...' is not listed within the file list of
+project`. Do this for `packages/config` in step 1 so the pattern is
+established before every later step repeats it.
+
 ### Commit gate (lefthook + commitlint)
 
 Enforces one coherent change, tested, conventionally committed. Runs on
@@ -301,13 +519,13 @@ pre-commit:
   commands:
     typecheck:
       glob: "*.{ts,tsx}"
-      run: npx nx affected -t typecheck --files={staged_files}
+      run: npx nx affected -t typecheck --base=HEAD
     lint:
       glob: "*.{ts,tsx}"
-      run: npx nx affected -t lint --files={staged_files}
+      run: npx nx affected -t lint --base=HEAD
     test:
       glob: "*.{ts,tsx}"
-      run: npx nx affected -t test --files={staged_files}
+      run: npx nx affected -t test --base=HEAD
 
 commit-msg:
   commands:
@@ -315,6 +533,14 @@ commit-msg:
       run: npx commitlint --edit {1}
 ```
 
+Don't pass `--files={staged_files}` to `nx affected` — `nx affected`
+forwards unrecognized args straight through to the underlying target
+command (e.g. `eslint .`), so `--files={staged_files}` becomes
+`eslint . <path>` and errors on any path that doesn't match eslint's own
+glob expectations. `--base=HEAD` (comparing against the last commit) is
+what makes `nx affected` scope correctly to a pre-commit hook's staged
+changes.
+
 **`commitlint.config.js`:**
 
 ```js
@@ -335,6 +561,14 @@ exists once it compiles and passes.
 Run `pnpm dlx lefthook install` once `lefthook.yml` exists so the gate is
 active from step 2 onward.
 
+A machine with lefthook installed globally (e.g. via Homebrew) on `PATH`
+can have that version picked up by the git hook shim instead of the
+project's pinned local one, silently running different — possibly
+incompatible — behavior. After `lefthook install`, verify the hook is
+invoking the local pinned version (check `lefthook version` output during
+a commit, or that the hook script under `.git/hooks/` resolves to
+`node_modules/.bin/lefthook`) rather than a global shadow.
+
 ### Env validation (fail fast)
 
 Types-first extended to config. Boot fails immediately on a missing or
@@ -398,10 +632,58 @@ One shared config, extended everywhere:
 
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — the shared base, *without*
+  `prettier-plugin-tailwindcss` (see step 1 — it belongs in `apps/web`'s
+  own config once Tailwind exists, not the shared base).
 
 A per-app override request signals to fix the base config at the source.
 
+## Local infra: Docker, always
+
+Postgres and Redis run through the `docker-compose.yml` from step 1 on
+every project, on every host OS — macOS, Windows, Linux alike. This isn't
+a convenience default; it's what makes "clone the repo, run the stack"
+mechanically true regardless of who's building. A natively-installed
+Postgres or Redis (Homebrew, an existing Windows service, a system
+package) is a per-machine setup step that isn't in the commit history and
+isn't reproducible on the next machine — exactly the kind of
+tribal-knowledge dependency Hedgehog's enforcement exists to remove.
+
+Don't offer a "native install" path as an alternative, even if a
+contributor already has Postgres running locally for another project. One
+mechanism, every machine: `docker compose up -d` before `pnpm install`,
+every time. If Docker genuinely can't run on a target machine, that's a
+platform-support gap to raise, not a reason to quietly fall back to a
+native install for that one contributor.
+
+## Known issue: esbuild postinstall version mismatch
+
+`@nx/vite` (step 1) declares `esbuild` as an *optional* peer dependency
+(`^0.27.0 || ^0.28.0`), while `drizzle-kit` (step 2) pins a hard dependency
+on `esbuild@^0.25.4`. pnpm's isolated store correctly keeps both esbuild
+majors side by side — but esbuild's own `install.js` resolves its platform
+binary (`@esbuild/<platform>`) via **ambient** Node module resolution
+rather than a path scoped to its own package instance. With multiple
+esbuild majors in the tree, that ambient resolution can walk up and grab a
+sibling major's platform binary, hardlinking the wrong version's binary
+into a package that still claims a different version number. The result
+is a postinstall failure like:
+
+```
+Error: Expected "0.28.1" but got "0.25.12"
+```
+
+This is deterministic (not registry/store corruption) and reproduces even
+from a fully clean pnpm store — it's a real collision in esbuild's install
+script when it meets pnpm's multi-version isolation. The fix is the
+`pnpm.overrides.esbuild` pin added in step 1 above: collapsing to a single
+esbuild version (drizzle-kit's hard-pinned range, since it's non-optional
+— `@nx/vite`'s peer is optional and simply goes unfilled) removes the
+ambiguity that triggers the bug. If this resurfaces after a stack version
+bump, re-check drizzle-kit's current `esbuild` dependency range
+(`pnpm view drizzle-kit dependencies.esbuild`) and update the override to
+match rather than removing it.
+
 ## After Bootstrap
 
 Update `TODO.md`: check off every Bootstrap line now built, leave Phase
@@ -423,3 +705,7 @@ gated by lefthook, each its own commit.
 - Each of the 7 steps is its own commit, in order — same unit-of-work
   discipline as every other step in the discipline, even though this is
   infra rather than a domain module.
+- Local Postgres/Redis always run through the `docker-compose.yml` from
+  step 1, on every host OS. Never substitute a natively-installed
+  Postgres/Redis, even to match a contributor's existing local setup —
+  see **Local infra: Docker, always**.

package/src/templates/CLAUDE.md

@@ -13,8 +13,8 @@
 
 {{PROJECT_SUMMARY — 2–4 sentences the `planner` writes at Intake: what
 this project is, who it's for, and what it does. State current intent, not
-history. Keep it tight — deeper domain context lives in the commit log and
-docs/design, not here.}}
+history. Keep it tight — the full product narrative, scope boundary, and
+domain vocabulary live in docs/context.md, not here.}}
 
 This project is built with **Hedgehog**: a backend-first, one-step-at-a-time
 build discipline. The rules below aren't project preferences — they're how
@@ -28,6 +28,10 @@ whole plan in context — the plan lives in the structure:
 - **`TODO.md`** is the live checklist and the source of truth for what's
   next. Read it at the start of every session. Its only state is
   checked/unchecked.
+- **`docs/context.md`** is the product's current-state document — product
+  narrative, scope boundary, domain vocabulary. Every project has one,
+  written by `planner` at Intake and kept current on later Intakes. It
+  states what's true now, never a history of what changed.
 - **The commit log** is the record of what's built and why. Conventional
   commits (`feat(<module>): schema`, `feat(<module>): api`, …) are how
   progress is read, not a conversation summary.
@@ -63,8 +67,8 @@ steps from memory:
 ### The agents — delegate the judgment calls
 
 - **`planner`** — Intake (scope boundary + domain vocabulary) at project
-  start, and module scoping when new scope enters play. Writes `TODO.md`
-  and `docs/design/<module>-notes.md`.
+  start, and module scoping when new scope enters play. Writes `TODO.md`,
+  `docs/context.md`, and `docs/design/<module>-notes.md`.
 - **`ux-planner`** — once per module in Phase B, after the hook exists and
   before the screen: writes `docs/design/<module>.md`.
 - **`ui-builder`** — builds screens from the ux-planner rationale.
@@ -77,11 +81,13 @@ steps from memory:
 ### Stack (locked)
 
 Nx monorepo · pnpm · **NestJS** (all domain logic + DB access) · **Drizzle**
-(+ `drizzle-zod`) · **PostgreSQL** · Railway · **ts-rest** contracts · **Zod**
-validation · **Better Auth** · **TanStack Query** hooks · **Next.js** + ShadCN
-+ Tailwind (web, UI only) · Expo + React Native Reusables + NativeWind
-(mobile, optional) · **BullMQ + Redis** (queues) · Pino logging · Vitest +
-Playwright (tests) · Conventional Commits + commitlint + lefthook · Sentry.
+(+ `drizzle-zod`) · **PostgreSQL** · **Docker Compose** (local Postgres +
+Redis, every host OS) · Railway · **ts-rest** contracts · **Zod**
+validation · **Better Auth** · **TanStack Query** hooks · **Next.js** +
+ShadCN + Tailwind (web, UI only) · Expo + React Native Reusables +
+NativeWind (mobile, optional) · **BullMQ + Redis** (queues) · Pino logging ·
+Vitest + Playwright (tests) · Conventional Commits + commitlint + lefthook ·
+Sentry.
 
 Don't substitute libraries. If a package or generator name changed
 upstream, verify against current docs before running — don't swap in a
@@ -90,6 +96,7 @@ different library.
 ### Layout
 
 ```
+docker-compose.yml   local Postgres + Redis — every host OS, no native install
 apps/
   web        Next.js — UI only
   mobile     Expo — optional
@@ -106,6 +113,7 @@ packages/
 libs/
   <module>/port · <module>/repository · <module>/service   (one triplet per table)
 docs/
+  context.md product narrative, scope boundary, domain vocabulary (Intake)
   design     <module>-notes.md (Intake) and <module>.md (ux-planner)
 ```
 
@@ -125,6 +133,9 @@ docs/
   (lefthook gate).
 - **Fix wrong steps at the source** via the Correction Protocol — never a
   downstream workaround.
+- **Local Postgres/Redis always run through `docker-compose.yml`**, on
+  every host OS. Never a natively-installed Postgres/Redis, even to match
+  a contributor's existing local setup.
 - **`packages/config` is the single source** for shared config. A per-app
   override request means fix the base config, not add an override.
 
@@ -147,7 +158,8 @@ off. Keep it thin.
 **When the build is done:** once every module in scope has both phases
 checked, the build session is complete. **Delete `TODO.md`** — a finished
 checklist is noise, and the commit log is the durable record of what was
-built.
+built. **`docs/context.md` stays** — it's the product's current-state
+document, not a checklist.
 
 ## Managing context
 
@@ -159,8 +171,9 @@ context small:
   `TODO.md` and continue. Nothing is lost, because the checklist, commits,
   and code hold all the state. Prefer this over letting one session
   accumulate the entire project.
-- **A cleared or new session recovers by reading `TODO.md` + the commit
-  log**, never by needing the prior conversation.
+- **A cleared or new session recovers by reading `TODO.md`,
+  `docs/context.md`, and the commit log**, never by needing the prior
+  conversation.
 - **Delegate heavy work to agents.** Intake elicitation (`planner`),
   screen builds (`ui-builder`), and reviews (`reviewer`) each run in their
   own isolated context — so that work doesn't pile up in the main thread.

package/src/templates/TODO.md

@@ -1,16 +1,16 @@
 # TODO
  
-<!-- 2-3 sentences: what is this project. Link out to a deeper context
-file (e.g. docs/context.md) only if the domain genuinely needs it — most
-projects shouldn't need one. -->
+<!-- 2-3 sentences: what is this project. Full product narrative, scope
+boundary, and domain vocabulary live in docs/context.md — every project
+has one, written by planner at Intake. -->
  
 ## Context
  
-(fill in per project)
+(fill in per project — see docs/context.md for the full picture)
  
 ## Bootstrap
  
-- [ ] Nx workspace + `packages/config`
+- [ ] Nx workspace + `packages/config` (incl. `docker-compose.yml` for local Postgres/Redis)
 - [ ] `packages/db` — Drizzle client
 - [ ] `packages/auth` — Better Auth config
 - [ ] `apps/api` — Nest shell, global guard, Pino