@skyf0xx/hedgehog 0.1.2 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

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

@@ -99,6 +99,13 @@ 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.
+
 ## Steps (run in sequence, one commit per step)
 
 ### 1. Nx workspace + `packages/config`
@@ -119,6 +126,14 @@ 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.
+
 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
@@ -143,6 +158,18 @@ files:
   declares the project tags table below (`scope:*`, `type:*`) as comments
   or a lookup, so every later generator step tags its project correctly.
 
+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
@@ -301,13 +328,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 +342,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 +370,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
@@ -402,6 +445,34 @@ One shared config, extended everywhere:
 
 A per-app override request signals to fix the base config at the source.
 
+## 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

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.
@@ -106,6 +110,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)
 ```
 
@@ -147,7 +152,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 +165,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,12 +1,12 @@
 # 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