@skyf0xx/hedgehog 4.2.0 → 4.2.2

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

@@ -87,10 +87,12 @@ stop — an operation that seems to want async processing on a Queue-off
 project is a signal to revisit that add-on decision with `planner`, not
 to build a one-off queue outside the add-on's scaffolding.
 
-Standard Nx generators (`@nx/nest`, `@nx/next`, `@nx/expo`, `@nx/js`)
-scaffold the app/lib shell. Each step's actual content (schema, contract,
-repository, service, controller, hook) is hand-built, following this
-sequence.
+Every layer scaffolds from its own generator in `tools/generators/` (see
+"Scaffolding a layer" below) — package shell, tags, files, barrel wiring,
+and the layer's conventional shape all land in one deterministic step.
+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)
 
@@ -211,6 +213,102 @@ Correction Protocol. Valid task statuses are `planned`, `ready`,
 also carries a `blocked_reason` (`scope_violation`, `verification_failed`,
 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,...>'
+nx g ./tools/generators:repository --module=<module>
+nx g ./tools/generators:service    --module=<module>
+nx g ./tools/generators:controller --module=<module> --fields='<name:type,...>'
+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. `hook`'s optional `--toggleField` names a boolean field from the
+schema to expose as a dedicated toggle mutation.
+
+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.
+
+**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.
+
 ## First arrival in a package
 
 Every layer scope names a directory *inside* a package
@@ -223,15 +321,25 @@ 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.
+
 Widen that one task, before building it:
 
 ```bash
 hedgehog override add TASKS-CONTRACT \
   --scope 'packages/contracts/*' \
-  --scope 'packages/contracts/src/index.ts' \
+  --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,
@@ -245,57 +353,15 @@ 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.
+`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.
-
-**Generate the shell — never hand-author it.** `@nx/js:lib` produces a
-correct, non-buildable, Vitest-wired `package.json`/`tsconfig*.json`/
-`vitest.config.mts`/`src/index.ts` in one deterministic step; hand-copying
-a sibling package invites exactly the kind of drift (missing `nx.tags`,
-missing project references) `hedgehog verify`'s lint step then has to
-catch. Run the generator for the layer that's first-arriving, then add its
-tags — the pair `eslint-base.js`'s `depConstraints` expects (see its own
-tag reference table) — to the generated `package.json`'s `"nx".tags`:
-
-```bash
-# contract — first module through this layer only
-npx nx g @nx/js:lib packages/contracts --bundler=none --unitTestRunner=vitest
-# then set "nx": { "tags": ["scope:contracts", "type:contract"] } in packages/contracts/package.json
-
-# hook — first module through this layer only
-npx nx g @nx/js:lib packages/hooks --bundler=none --unitTestRunner=vitest
-# then set "nx": { "tags": ["scope:hooks", "type:hook"] } in packages/hooks/package.json
-
-# repository — every module, new lib each time
-npx nx g @nx/js:lib libs/{module}/repository --bundler=none --unitTestRunner=vitest
-# then set "nx": { "tags": ["scope:{module}", "type:adapter"] } in libs/{module}/repository/package.json
-
-# service — every module, new lib each time
-npx nx g @nx/js:lib libs/{module}/service --bundler=none --unitTestRunner=vitest
-# then set "nx": { "tags": ["scope:{module}", "type:service"] } in libs/{module}/service/package.json
-```
-
-**Wire the new package in before reporting the layer done.** 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. `nx sync` writes root
-`tsconfig.json`, which sits outside every module-scoped layer's scope — it
-belongs to no layer and is not part of the override above. Commit it
-separately as `chore(workspace): sync project references`, before
-`hedgehog verify` runs, so the layer's own commit stays exactly the layer.
-
-This is the building agent'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.
+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.
 
 ## Intra-step conventions