@pavp/wavefront 1.1.0 → 1.2.0

package/README.md

@@ -3,178 +3,87 @@
 Claude Code agent framework for apps generated by **scaffold-nextjs-app**
 (Next.js 15 · React 19 · MUI 7 · React Query · Zustand · RHF + Zod · next-intl · Jest/RTL · Clean Architecture).
 
-5 specialist agents + 20 self-contained skills + a 9-command orchestration loop, so you describe work items instead of writing boilerplate. Generates responsive, composed UI continuous with your app — from a Figma export, screenshot, description, or nothing — with a colocated test in every layer.
+**5 specialist agents + 20 self-contained skills + a 9-command orchestration loop**, so you describe work items instead of writing boilerplate. Generates responsive, composed UI continuous with your app — from a Figma export, screenshot, description, or nothing — with a colocated test in every layer.
 
 > Distilled from real scaffold code, pinned at commit `8edaa0b` (modules `todo`/`auth`, `about-view`, `test/`, `src/i18n`). Not from docs — from the source. E2E-validated against a generated app.
 
----
-
-## Install
+## Documentation
 
-### Via npm (no clone)
-```bash
-npx @pavp/wavefront install --local  /path/to/your-next-app            # copy the surface
-npx @pavp/wavefront install --global /path/to/your-next-app            # install to ~/.wavefront + symlink
-npx @pavp/wavefront install --global /path/to/your-next-app --with-hooks
-npx @pavp/wavefront uninstall /path/to/your-next-app
-```
-Or install the command globally: `npm i -g @pavp/wavefront` then `wavefront install --local <app>`. The CLI wraps the same scripts below (needs `bash`; macOS/Linux or WSL).
+| If you want to… | Read |
+|---|---|
+| **Get started** — install + first module + first feature, copy-paste | **[docs/USAGE.md](docs/USAGE.md)** |
+| **Understand the model** — agents vs skills vs commands, the loop, why self-contained | **[docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)** |
+| **Fix a problem** — symptom → cause → fix (users + contributors) | **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** |
+| **Author the framework** — file-format spec for agents/skills/commands | [docs/conventions.md](docs/conventions.md) |
+| **See the history** — phase plan + roadmap | [docs/plan.md](docs/plan.md) · [docs/roadmap.md](docs/roadmap.md) |
 
-### Via git clone (source of truth)
-```bash
-git clone https://github.com/pavp/wavefront.git && cd wavefront
-```
+New here? Start with **[USAGE](docs/USAGE.md)**. The rest of this page is a reference.
 
-Two install modes into a target generated app:
+---
 
-### Global + symlink (recommended)
-```bash
-./install.sh --global /path/to/your-next-app
-```
-Installs the surface to `~/.wavefront/` and symlinks `agents/`, `skills/`, `commands/` into the app's `.claude/`. One source, central updates (re-pull this repo → all projects updated). Uninstall: `./uninstall.sh /path/to/your-next-app`.
+## Install
 
-### Copy project-local
 ```bash
-./install.sh --local /path/to/your-next-app
+# via npm (no clone)
+npx @pavp/wavefront install --global /path/to/your-next-app --with-hooks   # ~/.wavefront + symlink
+npx @pavp/wavefront install --local  /path/to/your-next-app                # copy into the app
+npx @pavp/wavefront uninstall /path/to/your-next-app
 ```
-Copies the surface into the app's `.claude/` (self-contained, no global state, manual updates).
 
-Claude Code auto-discovers `agents/` and `skills/` under `.claude/`. No build step. Self-contained — no dependency on the scaffold's `docs/`.
+- **Global + symlink** (recommended for multiple apps): one source in `~/.wavefront/`, re-pull/upgrade once → all projects updated.
+- **Local**: a self-contained copy in the app's `.claude/`, no global state.
+- Needs `bash` (macOS/Linux or WSL). Claude Code auto-discovers `agents/`+`skills/`+`commands/` under `.claude/` — no build step.
+- `--with-hooks` also installs quality-gate hooks (eslint/stylelint on edit, tsc at end of turn; warn-only). It writes `.claude/settings.wavefront.json` for you to **merge** into your `settings.json` (never clobbers it); needs `jq`. Details + walkthrough in [USAGE](docs/USAGE.md#1-install-into-your-app).
 
-> Layout is portable by design (no absolute paths, single root) — that's what lets the same files work project-local, global-symlinked, or in this standalone repo.
-
-### Optional: quality-gate hooks
-
-Add `--with-hooks` to either install mode to also install machine gates:
-```bash
-./install.sh --global /path/to/your-next-app --with-hooks
-```
-- **PostToolUse (Edit/Write `*.{ts,tsx,js,jsx,css,scss}`)** → `eslint`/`stylelint --fix` on the touched file. Fast, per-file, **warn-only** (never blocks).
-- **Stop (end of turn)** → `tsc --noEmit` project-wide, **warn-only**. (tsc needs the `@/` path graph, so it runs once at the end, not per-edit.)
-- Installer copies `hooks/` into `.claude/hooks/` and writes `.claude/settings.wavefront.json` — **merge its `hooks` block into your `.claude/settings.json`** (the installer never overwrites your settings). Requires `jq` on PATH.
-- Hooks are the cheap machine gate; the `reviewer` agent stays the semantic PASS/FAIL gate.
+You can also `git clone` this repo and run `./install.sh --global|--local <app>` directly — same surface.
 
 ---
 
 ## Agents
 
-| Agent | Use it to | Tools | Edits? |
-|---|---|---|---|
-| `module-builder` | Generate a full feature module across the Clean Arch chain (types/schemas → api → gateways → repository → store → selectors → hooks → views/components → barrels) | full | yes |
-| `tester` | Write/fix colocated Jest + RTL tests using `@test/utils` + faker factories | full | yes |
-| `i18n-tokens` | De-hardcode UI: strings → next-intl keys, values → design tokens, raw MUI → `@/ui`, `next/link` → `@/i18n/routing` | edit | yes |
-| `reviewer` | Validate naming, layer direction, dependency inversion, hook split, lint/tsc (code-review mode) — OR run a skill-drift `sync-audit` (audit mode) | read-only | no |
-
-Invoke a subagent by name in Claude Code (e.g. "use module-builder to add a `notifications` module").
-
-### Recommended flow (build → test → localize → review)
-
-```
-module-builder   →  generate the module
-tester           →  add colocated tests, run yarn test
-i18n-tokens      →  replace literals with keys/tokens
-reviewer         →  final PASS/FAIL gate (naming, layers, lint, tsc)
-```
-
-`reviewer` is read-only and safe to run anytime. `module-builder` ends by running `tsc`/`lint` and handing off to tester + reviewer.
-
----
-
-## Orchestration loop (F2a — new feature)
+| Agent | Use it to | Edits? |
+|---|---|---|
+| `module-builder` | Generate/modify a feature module across the Clean Arch chain (types → api → gateways → repository → store → selectors → hooks → views/components → barrels) | yes |
+| `tester` | Write/fix colocated Jest + RTL tests (`@test/utils` + faker factories) | yes |
+| `i18n-tokens` | De-hardcode UI: strings → next-intl, values → tokens, raw MUI → `@/ui`, `next/link` → `@/i18n/routing` | yes |
+| `reviewer` | PASS/FAIL gate (naming, layers, dependency inversion, hook split, lint/tsc) — or a skill-drift `sync-audit` | read-only |
+| `mapper` | Map an existing module before a change (ADD/MODIFY/KEEP plan + regression surface) | read-only |
 
-Beyond invoking agents by hand, wavefront ships a command loop that drives them through a work item with session-surviving planning artifacts in `.claude/.planning/`.
+Invoke by name ("use `module-builder` to add a `notifications` module"), or let the loop drive them. Recommended by-hand order: **`module-builder` → `tester` → `i18n-tokens` → `reviewer`**. Full walkthrough: [USAGE §2](docs/USAGE.md#2-your-first-module--by-hand-the-agent-flow).
 
-```
-/wavefront-init                       once per project — scaffold .planning/ + describe the project
-/wavefront-feature "<prompt|story>"   interactive intake → REQUIREMENTS (asks + suggests gaps)
-/wavefront-plan "<title>"             REQUIREMENTS → executable PHASE_PLAN (agents × layers)
-/wavefront-execute "<title>"          builder → tester → i18n-tokens, sequential, STATE after each
-/wavefront-verify "<title>"           reviewer + tests + acceptance-criteria check → PASS/FAIL
-/wavefront-ship "<title>"             branch + commit + PR (confirms first; verified items only)
-/wavefront-state                      where am I? (safe, read-only)
-```
-
-- **Intake is interactive + proactive:** accepts a prompt, a user story, or a spec; asks blocking questions and *suggests* gaps it spots (edge cases, error states, i18n/a11y, implicit criteria) before any planning.
-- **Resumable:** every command updates `.claude/.planning/STATE.md`, so a run continues cleanly after an interruption.
-- **Fresh context:** execute dispatches each agent with only its task slice, fighting context rot.
-- Commands are manual-invoke (`disable-model-invocation`) since they have side effects. `/wavefront-state` is the exception.
-
-### Parallel waves (F3 — multi-module items)
-
-When a work item spans **independent** modules, `/wavefront-plan` groups them into waves and `/wavefront-execute` builds same-wave modules concurrently (multiple builders in one dispatch). Within a module, the layer chain stays sequential. Off by default (`parallelization` config) — single-module work is unchanged. Items touching the same shared file are never parallelized (avoids write races). Note: this is parallelism across modules, NOT a per-layer agent split (that was analyzed and rejected — the layers are a dependency chain).
-
-### Change existing code (F2b)
-
-```
-/wavefront-change "<prompt|story>"   intake → MAP (read-only) → plan → execute(modify) → verify(+regression) → ship
-```
-- **Map-first (mandatory):** the `mapper` agent reads the target module and produces a change-plan (ADD/MODIFY/KEEP, blast radius, regression surface) before any edit. Modifying working code is the highest-risk op — no edit without a map.
-- `module-builder` runs in **modify mode**: edits only the planned files, preserves existing public API, doesn't regenerate.
-- **Regression is part of the gate:** verify runs the reviewer in diff-aware mode + new tests + the module's existing tests; PASS requires no regression.
+## Orchestration loop
 
-### Fix a bug (F2c)
+Slash commands that drive the agents through a work item with resumable state in `.claude/.planning/`:
 
 ```
-/wavefront-fix "<bug / repro>"   intake/repro → diagnose+locate → regression RED → patch → GREEN → verify → ship
+/wavefront-init          scaffold .planning/ (once per project)
+/wavefront-feature       intake a prompt/story → REQUIREMENTS
+/wavefront-plan          REQUIREMENTS → executable PHASE_PLAN
+/wavefront-execute       builder → tester → i18n, STATE after each (resumable)
+/wavefront-verify        reviewer + tests + acceptance criteria → PASS/FAIL
+/wavefront-ship          branch + commit + PR (verified only, confirms first)
+/wavefront-change        modify existing code (map-first, modify mode + regression)
+/wavefront-fix           bug fix (diagnose → RED→GREEN → verify)
+/wavefront-state         where am I? (read-only)
 ```
-- **Diagnose-first:** `reviewer` in diagnose mode traces the data flow and reports root cause as `file:line + why + fix direction` (read-only).
-- **Test before fix (RED→GREEN):** `tester` writes a regression test that FAILS against the broken code (RED) — proving it captures the bug — then module-builder patches (minimal change), and the test must PASS (GREEN) with existing tests still green.
-- The regression test stays permanently, preventing recurrence.
 
----
+Resumable, fresh-context per agent, parallel waves across independent modules (off by default). How it all fits together: [HOW-IT-WORKS](docs/HOW-IT-WORKS.md). Step-by-step: [USAGE §3–5](docs/USAGE.md#3-your-first-feature--the-loop).
 
-## Design → UI (F6)
+## Design → UI
 
-Any design source becomes UI built from `@/ui` + `@/styles/tokens`, composed like the rest of the app:
+Any design source becomes UI built from `@/ui` + `@/styles/tokens`, composed like the rest of the app: **live Figma MCP** (official Dev Mode or Framelink — exact frames + variables → tokens), Figma export/screenshot/image, pasted HTML, a reference screen, a text description, or nothing (continuity). Responsive is mandatory (mobile-first, theme breakpoints). Details: [USAGE §6](docs/USAGE.md#6-building-from-a-design).
 
-| Source | How |
-|---|---|
-| Figma via MCP (live) | pull exact frames + variables from a configured Figma MCP → map variables to `@/styles/tokens` |
-| Figma export / screenshot / image | read multimodally → infer layout → map to `@/ui` (fallback when no Figma MCP) |
-| Pasted HTML/CSS | translate markup → `@/ui` (not copied) |
-| Reference screen ("like the todo page") | replicate that screen's pattern |
-| Text description | infer from the design-system inventory |
-| **Nothing** | continuity: mirror the closest existing screen |
-
-`design-intake` produces a design-spec (layout, intent→`@/ui` map, tokens, the four states loading/empty/error/populated, **responsive behavior**, gaps); `design-system-inventory` keeps it continuous; module-builder implements it. **Responsive is mandatory** (mobile-first, theme breakpoints `minMobile/minTablet/minDesktop`) — when a design is one-viewport, intake asks how it adapts before building. Elements with no `@/ui` equivalent are flagged (approximate or add to `@/ui`, never hand-rolled). **Live Figma MCP** is supported when configured: intake detects the official Dev Mode MCP (`get_code`/`get_variable_defs`/`get_image`) or Framelink (`get_figma_data`/`download_figma_images`), pulls exact frames + variables, and maps Figma variables → `@/styles/tokens`; with no Figma MCP present it degrades to the image path. You configure your own server — wavefront ships only the detection + mapping rules.
-
----
+## Skills
 
-## Skills (knowledge the agents read)
+Knowledge the agents read before acting — one pattern each, distilled from real scaffold code. Every skill carries `source` + `source_version` (pinned `8edaa0b`) for drift tracking via `sync-audit`.
 
-Core (architecture):
-- `clean-architecture` — layers, data flow, 5 dependency rules
-- `module-structure` — exact folder/file shape, placement, `@/` aliases
-- `naming-conventions` — lint-enforced naming + suffixes
+- **Architecture:** `clean-architecture` · `module-structure` · `naming-conventions`
+- **Patterns:** `data-fetching-react-query` · `gateway-pattern` · `repository-pattern` · `store-zustand` · `selector-pattern` · `hook-patterns` · `forms-rhf-zod` · `mui-design-tokens`
+- **UI:** `component-composition` · `responsive-layouts` · `error-boundary` · `design-system-inventory` · `design-intake`
+- **Cross-cutting:** `testing-jest-rtl` · `i18n-next-intl`
+- **Meta:** `sync-audit` · `requirement-intake`
 
-Patterns (layer-by-layer):
-- `data-fetching-react-query` — api service + Zod + endpoints
-- `gateway-pattern` — `createXGateway(dataSource)` + interfaces
-- `repository-pattern` — key factory + query/mutation options + combined repo
-- `store-zustand` — `createStoreWithMiddleware` + immer + persist
-- `selector-pattern` — derived state via `useMemo`
-- `hook-patterns` — business vs controller split (mandatory)
-- `forms-rhf-zod` — `useForm` + `zodResolver` + `@/ui` inputs
-- `mui-design-tokens` — `@/ui` + `@/styles/tokens`, never raw MUI
-
-Cross-cutting:
-- `testing-jest-rtl` — `renderWithProviders` + factories + colocated tests
-- `i18n-next-intl` — `useTranslations` + `@/i18n/routing` + remote messages
-
-Design:
-- `design-system-inventory` — real `@/ui`/token catalog + how existing screens compose (continuity engine)
-- `design-intake` — normalize any design source (Figma export/image/HTML/reference/description/none) → design-spec mapped to `@/ui`+tokens
-- `responsive-layouts` — mandatory mobile-first responsive: theme breakpoints + responsive `sx` + `useResponsiveScreen`
-- `component-composition` — decompose into subcomponents; composition over inheritance; compound components (Modal pattern)
-- `error-boundary` — recoverable error+retry state every data-fetching view renders when its query fails
-
-Meta:
-- `sync-audit` — detect skill drift vs scaffold `source_version` (used by `reviewer` audit mode)
-- `requirement-intake` — normalize prompt/story/spec → REQUIREMENTS + acceptance criteria (used by the loop)
-
-Each skill carries `source` + `source_version` frontmatter (pinned `8edaa0b`) for drift tracking via `sync-audit`.
-
----
+Plus a **bundled reference module** (`reference/module/note-module.md`) — a canonical end-to-end Clean-Arch example the agents read to copy idioms, so generation works even after a project deletes the scaffold's example modules. Self-contained: no dependency on `src/modules/todo` surviving in the target app.
 
 ## Conventions (hard rules the agents enforce)
 
@@ -182,46 +91,32 @@ Each skill carries `source` + `source_version` frontmatter (pinned `8edaa0b`) fo
 - Layer direction: View → business hook → repository → gateway → api. Never skip.
 - UI from `@/ui` (not `@mui/material`); spacing/color from `@/styles/tokens`.
 - Strings via next-intl `t()`; locale links via `@/i18n/routing`.
-- Tests colocated; import test helpers only from `@test/utils`.
-- Zod validates at the api boundary; schemas live in `*.types.ts`.
+- Tests colocated; import helpers only from `@test/utils`.
+- Zod validates at the api boundary; schemas in `*.types.ts`.
 
-Full detail: `docs/conventions.md` (format spec) + the skills above.
-
----
-
-## Smoke checklist (verify in a generated app)
-
-After installing into an app with deps installed:
-
-- [ ] `reviewer` on an existing module (`src/modules/todo`) → PASS.
-- [ ] `module-builder` generates a new small module (one entity, http only).
-- [ ] `tsc --noEmit` clean on the new module.
-- [ ] `yarn lint` clean on the new module.
-- [ ] `tester` adds colocated tests → `yarn test` green.
-- [ ] `i18n-tokens` leaves no hardcoded strings/spacing; lint stays clean.
-- [ ] `reviewer` on the new module → PASS.
-
-> Status: E2E-validated (2026-05-23) — built a full `notification` module in a generated app to tsc-clean + lint-clean + test-green. See `docs/plan.md`.
+Format spec: [docs/conventions.md](docs/conventions.md).
 
 ---
 
 ## Contributing
 
-This repo follows **Conventional Commits**, enforced by commitlint (`commit-msg` hook) — versioning is automatic.
+This repo follows **Conventional Commits**, enforced by commitlint (`commit-msg` hook) — versioning is automatic. (Full gotcha list: [TROUBLESHOOTING § Contributing](docs/TROUBLESHOOTING.md#contributing-to-this-repo).)
 
-- **Commit format:** `type(scope): subject` — lowercase subject, ≤72 chars.
+- **Commit format:** `type(scope): subject` — **lowercase** subject (rejects any uppercase, incl. filenames/acronyms), ≤72 chars.
   - **types:** `feat` `fix` `docs` `chore` `perf` `refactor` `test` `hotfix`
-  - **scopes (optional):** `agents` `skills` `commands` `hooks` `planning` `cli` `bin` `install` `npm` `ci` `config` `husky` `docs` `deps`
+  - **scopes (optional):** `agents` `skills` `commands` `hooks` `reference` `planning` `cli` `bin` `install` `npm` `ci` `config` `husky` `docs` `deps`
 - **Branch names:** `type/description` (lowercase + hyphens), e.g. `feat/figma-mcp-source`. Enforced on `pre-push` (skipped in CI / on `main`).
-- **Releases are automatic:** push to `main` → [semantic-release](https://semantic-release.gitbook.io) reads the commits, bumps the version (SemVer: `feat`→minor, `fix`→patch, `BREAKING CHANGE`/`!`→major), updates `CHANGELOG.md`, tags + creates a GitHub Release, then publishes to npm via OIDC Trusted Publishing (no stored token). Do **not** bump `version` or tag by hand.
+- **No `Co-Authored-By: Claude`** or AI-attribution trailers in commits/PRs.
+- **Releases are automatic:** push to `main` → [semantic-release](https://semantic-release.gitbook.io) bumps the version (`feat`→minor, `fix`→patch, breaking→major), updates `CHANGELOG.md`, tags + GitHub Release, then OIDC publish to npm. **Never** bump `version`/tag/CHANGELOG by hand. **After a release, `git pull --ff-only` before new work** (semantic-release commits the bump back to `main`).
 - Setup after clone: `npm install` (wires husky hooks).
 
-## Roadmap (see `docs/plan.md` + `docs/roadmap.md`)
+## Roadmap
+
+All phases resolved — see [docs/roadmap.md](docs/roadmap.md).
 
 - ✅ **MVP** — 5 agents + 20 skills, E2E-validated.
-- ✅ **F4** — `sync-audit` drift detection (reviewer audit mode).
-- ✅ **F5** — quality-gate hooks (eslint/stylelint on edit, tsc on stop).
-- ✅ **F1** — standalone repo + global/local install + **npm distribution (F1d)**. Scaffold auto-injection (F1c) not pursued.
-- ✅ **F2** — orchestration loop (`/wavefront-*`) + parallel waves + change/fix flows.
+- ✅ **F1** — standalone repo + global/local install + **npm distribution**.
+- ✅ **F2** — orchestration loop + parallel waves + change/fix flows.
+- ✅ **F4/F5** — sync-audit drift detection · quality-gate hooks.
 - ✅ **F6/F7** — design intake (incl. live Figma MCP) + component composition.
-- ❌ **F3** — per-layer agent subdivision — **won't ship**: linear layer deps mean zero intra-module parallelism, and F2 waves already parallelize across modules. Broad builder stands.
+- ❌ **F3** — per-layer agent subdivision — won't ship (linear layer deps; F2 waves already parallelize across modules).

package/agents/module-builder.md

@@ -5,14 +5,14 @@ tools: Read, Write, Edit, Grep, Glob, Bash
 ---
 
 # Role
-The implementer that owns the full Clean Architecture chain for a feature module in scaffold-nextjs-app. The developer describes a feature; this agent generates or edits the layered files so they don't write boilerplate. It mirrors the scaffold's reference modules (`src/modules/todo`, `src/modules/auth`) exactly rather than inventing structure.
+The implementer that owns the full Clean Architecture chain for a feature module in scaffold-nextjs-app. The developer describes a feature; this agent generates or edits the layered files so they don't write boilerplate. It mirrors the **bundled canonical reference** (`.claude/reference/module/note-module.md`) exactly rather than inventing structure — do NOT depend on the target app having `src/modules/todo`/`auth`, since real projects routinely delete the example modules.
 
 ## Two modes
 - **Create (default):** new module from scratch — full chain, bottom-up (workflow below).
 - **Modify / patch:** change an EXISTING module. **Requires a `mapper` change-plan first** (which files ADD vs MODIFY vs KEEP). Edit only the files in the plan; respect the surrounding code; don't regenerate working files. "Patch" posture (bug fixes) = the smallest change that fixes it. After editing, the touched layers must still honor layer direction + conventions, and **existing tests must still pass** (regression). Hand off to tester (extend tests + regression) and reviewer (diff-aware).
 
 ## Operating rules
-- Always: read the knowledge skills before generating; mirror the `todo`/`auth` reference modules; use kebab-case + correct suffixes; respect layer direction (View → business hook → repository → gateway → api); type boundaries with interfaces; validate at the api boundary with Zod; build UI from `@/ui` + `@/styles/tokens`; create `index.ts` barrels; pass `dataSource` (default `'http'`) through repository/selector/hook signatures.
+- Always: read the knowledge skills before generating; mirror the bundled reference (`.claude/reference/module/note-module.md`); use kebab-case + correct suffixes; respect layer direction (View → business hook → repository → gateway → api); type boundaries with interfaces; validate at the api boundary with Zod; build UI from `@/ui` + `@/styles/tokens`; create `index.ts` barrels; pass `dataSource` (default `'http'`) through repository/selector/hook signatures.
 - Always (UI): before writing views/components, read `design-system-inventory` (catalog + continuity) and `responsive-layouts`; if a design-spec exists, implement it. With NO design, follow the continuity rule — mirror the closest existing screen's components/layout/spacing. Always implement the four states (loading/empty/error/populated). For the **error** state, every data-fetching view returns the error-boundary pattern (an error+retry component wired to the query's `refetch`) when its business hook reports `error` — never let a failed fetch render blank (see `error-boundary` skill). Never hand-roll raw `<div>`/`<input>` to match a visual — translate to `@/ui` + tokens.
 - Always (responsive — mandatory): every view/component is mobile-first responsive using the theme's custom breakpoints (`minMobile`/`minTablet`/`minDesktop`/`largeScreen`, NOT xs/sm/md) via `sx` objects (`{ minMobile: ..., minTablet: ... }`) or `useResponsiveScreen` for branching. No fixed pixel widths that overflow mobile; the four states are responsive too.
 - Always (composition — mandatory): decompose UI into focused subcomponents under `components/` (mirror todo: `*-form`, `*-item`, `*-list`, sections) — the view ORCHESTRATES + wires hooks, it does NOT hold all markup inline. Apply the `component-composition` "when to extract" decision rule: **anything rendered inside `.map()` is ALWAYS its own component** (a list extracts its item — never inline JSX in the map); also extract on distinct responsibility, reuse, own state/handlers, ~30–40+ line JSX blocks. Extraction is recursive — components have subcomponents too. Compose via children/props; for multi-part UI use the compound-component pattern. NO inheritance, NO boolean-prop explosion. Each component independently renderable + testable. Don't over-fragment trivial markup.
@@ -44,7 +44,7 @@ The implementer that owns the full Clean Architecture chain for a feature module
 ## Workflow
 1. Read all knowledge skills.
 2. Clarify inputs: module name (kebab), entity/entities, fields, which CRUD ops, data sources needed (default `http` only), whether a validated form is needed.
-3. Inspect a reference: read the matching slice of `src/modules/todo` (or `auth`) to copy current idioms exactly.
+3. Inspect the reference: read the matching layer of the bundled `.claude/reference/module/note-module.md` to copy current idioms exactly. (Optional cross-check: if the target app still has `src/modules/todo`, you may compare — but the bundled reference is the source of truth; never require the live module.)
 4. Generate in dependency order (bottom-up):
    a. `[entity].types.ts` — TS types + Zod schemas (request/response/filters).
    b. `api/[entity]-api.ts` — `XApiContract` + `createXApiService()` singleton, `httpClient` + `endpoints` + Zod. (Add endpoints to `@/api/endpoints` only after Ask-first.)

package/agents/tester.md

@@ -16,7 +16,7 @@ When fixing a bug, the test comes FIRST:
 The regression test stays in the suite permanently (prevents recurrence). If your "reproducing" test passes before the fix, it doesn't actually capture the bug — rewrite it until it's RED first.
 
 ## Coverage discipline (mandatory — per layer)
-Mirror the scaffold (`src/modules/todo` has a colocated test in EVERY layer). For a module, write a colocated `*.test.ts(x)` for each piece that has logic:
+Mirror the bundled reference (`.claude/reference/module/note-module.md` shows a colocated test per layer; don't rely on the target app keeping `src/modules/todo`). For a module, write a colocated `*.test.ts(x)` for each piece that has logic:
 - **api** (`*-api.test.ts`) — request/response shape, Zod validation, endpoints called.
 - **gateway** (`http-gateway.test.ts`, + localStorage if present) — delegates correctly, source info.
 - **repository** (`*.repository.queries.test.ts` + `*.repository.mutations.test.ts`) — hooks fetch/mutate, cache effects (invalidate/setQueryData).

package/commands/wavefront-change.md

@@ -13,7 +13,7 @@ Change request: $ARGUMENTS
 
 ## Steps
 1. **Intake** — read `requirement-intake` skill; classify as a CHANGE; produce/append the work item in `.claude/.planning/REQUIREMENTS.md` (Type: change). Interactive + proactive: ask blocking questions, suggest gaps (esp. what existing behavior must be preserved).
-2. **Map (mandatory, read-only)** — dispatch the `mapper` agent over the target module(s). It reports current state + a change-plan (ADD/MODIFY/KEEP, layers, blast radius, regression surface). Do NOT skip this. Write the change-plan into `PHASE_PLAN.md`.
+2. **Map (mandatory, read-only)** — dispatch the `mapper` agent over the target module(s). It reports current state + a change-plan (ADD/MODIFY/KEEP, layers, blast radius, regression surface). Do NOT skip this. Write the change-plan into `PHASE_PLAN.md` and set its `type: change` (so `/wavefront-execute` runs modify mode and refuses to overwrite the module).
 3. **Plan** — turn the change-plan into ordered tasks (each tagged module-builder modify / tester / i18n-tokens / reviewer). Map new acceptance criteria → tests; note the regression set (existing tests that must stay green).
 4. **Execute (modify mode)** — dispatch `module-builder` in MODIFY mode with the mapper change-plan; it edits only the planned files, preserves existing code/public API. Then `tester`: extend tests for new criteria AND confirm the regression set still passes. Then `i18n-tokens` if UI strings/tokens changed. Update `STATE.md` after each task.
 5. **Verify (mandatory regression)** — `/wavefront-verify` style: reviewer in **change-review (diff-aware)** mode + run new tests AND the full module's existing tests (`yarn test --testPathPatterns=<module>`) + tsc + lint. PASS requires: reviewer PASS, new criteria covered, AND no regression (existing tests green).

package/commands/wavefront-execute.md

@@ -10,19 +10,24 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent
 Execute the plan for: $ARGUMENTS
 
 ## Steps
-1. Read `.claude/.planning/PHASE_PLAN.md` (item $ARGUMENTS) and `STATE.md`. Resume at the first wave/task not marked done. Check the `parallelization` config flag (default off).
+1. Read `.claude/.planning/PHASE_PLAN.md` (item $ARGUMENTS) and `STATE.md`. Resume at the first wave/task not marked done (and read STATE's `Resume context` if present — the interrupted task + last error). Check the `parallelization` config flag (default off).
+1b. **Determine build mode from the plan's `type:` field** (PHASE_PLAN § Work item):
+   - `type: feature` → **create mode** (build from scratch). If the target module dir already exists, STOP — a create plan must not overwrite working code; tell the user to run `/wavefront-change` instead.
+   - `type: change` or `type: fix` → **modify mode** — the plan MUST carry a `mapper` change-plan (ADD/MODIFY/KEEP file list). If it doesn't (e.g. the plan came from `/wavefront-plan`, not `/wavefront-change`/`/wavefront-fix`), STOP and ask the user to re-plan via the change/fix flow. Pass the change-plan to module-builder; it edits ONLY listed files.
 2. Execute **wave by wave** (a single-module item is just one wave with one item):
-   - **If `parallelization` is on AND the wave has multiple independent items:** dispatch their `module-builder` subagents **in parallel** — multiple Agent calls in ONE message. Each builder gets ONLY its module slice (target files + relevant skills + acceptance criteria). Wait for the whole wave to finish before the next wave.
+   - **Before any parallel dispatch — collision check:** confirm the wave's items declare NO shared-file overlap (compare each item's target files + the plan's Risks/shared-file notes). If two items in the wave touch the same file (`@/api/endpoints`, global types, etc.), DO NOT parallelize them — run those two serially even when `parallelization` is on. Only genuinely disjoint items go parallel.
+   - **If `parallelization` is on AND the wave has multiple independent items (collision check passed):** dispatch their `module-builder` subagents **in parallel** — multiple Agent calls in ONE message. Each builder gets ONLY its module slice (target files + relevant skills + acceptance criteria). Wait for the whole wave to finish before the next wave.
    - **Otherwise (default):** run items sequentially.
    - Within any single module, tasks are always sequential (layer chain): types→api→gateway→repo→store→selector→hook→view→barrels.
 3. Per item, after build: dispatch `tester`, then `i18n-tokens` if UI changed. (These can also run per-item within the wave.)
-4. After EACH task/item: mark done in `PHASE_PLAN.md`, update `STATE.md` (current wave, last step, next step). Resume point.
+4. After EACH task/item: mark done in `PHASE_PLAN.md`, update `STATE.md` (current wave, last step, next step). Resume point. **On a task FAILURE (agent error, tsc/lint/test red that can't be auto-fixed):** stop, and write STATE's `Resume context` — the failed task, the owning agent, and the exact error — so the next run resumes WITH that context instead of blindly re-dispatching.
 5. After a wave: run `tsc --noEmit` + `yarn lint`; fix failures (route to owning agent) before the next wave.
 6. Do NOT run the reviewer here — that's `/wavefront-verify`. Stop after the build/test/i18n tasks and report status + next command (`/wavefront-verify "<title>"`).
 
 ## Rules
-- Persist STATE after each task AND each wave (interruption-safe; resume mid-plan).
+- Persist STATE after each task AND each wave (interruption-safe; resume mid-plan). On failure, persist `Resume context` (failed task + agent + error).
 - Fresh-context dispatch: each subagent gets only its slice.
-- Parallel only across INDEPENDENT items in the same wave; never parallelize items that touch the same shared file.
+- Parallel only across INDEPENDENT items in the same wave; **run the collision check first** — never parallelize items that touch the same shared file, even with the flag on.
+- Build mode follows the plan's `type:`: feature→create (refuse to overwrite an existing module), change/fix→modify (requires a mapper change-plan; edit only listed files).
 - Within a module, always sequential (dependency chain).
 - Stop and ask on Ask-first (new dep, shared-file edit, breaking change).

package/commands/wavefront-fix.md

@@ -13,7 +13,7 @@ Bug: $ARGUMENTS
 
 ## Steps
 1. **Intake / repro** — read `requirement-intake` skill; classify as a FIX. Capture the bug as a work item in `.claude/.planning/REQUIREMENTS.md` (Type: fix): expected vs actual behavior, reproduction steps, affected area. Ask for repro details if missing (a bug you can't reproduce, you can't verify fixed).
-2. **Diagnose + locate (read-only)** — dispatch the `reviewer` agent in **diagnose mode**. It traces the data flow through the layers and reports root cause as `file:line + why wrong + fix direction`. Write the diagnosis into `PHASE_PLAN.md`. No edits yet.
+2. **Diagnose + locate (read-only)** — dispatch the `reviewer` agent in **diagnose mode**. It traces the data flow through the layers and reports root cause as `file:line + why wrong + fix direction`. Write the diagnosis into `PHASE_PLAN.md` and set its `type: fix` (so `/wavefront-execute`, if used, runs modify/patch mode — never create). No edits yet.
 3. **Regression test RED** — dispatch the `tester` agent (bug regression flow): write a colocated test that reproduces the bug and **fails against current code** (RED). Confirm it's actually red (run it). This captures the bug.
 4. **Patch** — dispatch `module-builder` in **patch mode** (smallest focused change at the diagnosed location; respects surrounding code; touches only what's needed).
 5. **GREEN + regression** — re-run the new test → must PASS. Run the module's existing tests + tsc + lint → no regression.

package/commands/wavefront-verify.md

@@ -12,11 +12,15 @@ Verify the work item: $ARGUMENTS
 ## Steps
 1. Read the item's `REQUIREMENTS` (acceptance criteria) + `PHASE_PLAN` (what was built).
 2. Dispatch the `reviewer` subagent (code-review mode) over the changed module/files → expect PASS/FAIL with BLOCKER/WARNING/NIT.
-3. Run the tests for the work item (`yarn test --testPathPatterns=<module>`) and `yarn typecheck` + `yarn lint`. Note: a single-module test run trips the 85% global coverage gate (exit 1) even when tests pass — judge by `Tests: N passed`, not the exit code.
+3. Run the tests for the work item (`yarn test --testPathPatterns=<module>`) and `yarn typecheck` + `yarn lint`.
+   - **Coverage-gate discriminator (do NOT judge by exit code alone):** a single-module run trips the 85% GLOBAL coverage gate → `exit 1` even when every test passed. Distinguish by parsing the Jest summary:
+     - Read the `Tests:` line. **Real failure** = it shows `N failed` (N≥1), OR a `FAIL <path>` test-suite line, OR a tsc/lint error. → tests NOT green.
+     - **Coverage-only failure** = `Tests: M passed` with `0 failed`, exit 1, and the only error is the coverage threshold (`Jest: "global" coverage threshold ... not met`). → tests ARE green; the gate trip is expected for a single-module run, not a verdict failure.
+   - tsc/lint are judged normally (any reported error = fail).
 4. Check each **acceptance criterion** is actually covered by a passing test. List any uncovered.
 5. Verdict:
-   - **PASS** (reviewer PASS + tests green + criteria covered) → update `STATE.md` (status: verified, next = `/wavefront-ship`). Report.
-   - **FAIL** → write a concise fix plan (what failed, which file, which agent should fix) into `STATE.md` blockers + report. Do not ship.
+   - **PASS** (reviewer PASS + tests green per the discriminator + criteria covered) → update `STATE.md` (status: verified, next = `/wavefront-ship`). Report.
+   - **FAIL** (real test failures, tsc/lint errors, reviewer FAIL, or uncovered criteria) → write a concise fix plan (what failed, which file, which agent should fix) into `STATE.md` blockers + `Resume context` + report. Do not ship. A coverage-only gate trip with all tests passing is NOT a fail.
 6. Do NOT edit code here — verify is read-only/dispatch. Fixes go back through `/wavefront-execute` or the owning agent.
 
 ## Rules

package/install.sh

@@ -8,7 +8,7 @@ set -euo pipefail
 
 REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HOME_DIR="${WAVEFRONT_HOME:-$HOME/.wavefront}"
-SURFACE=(agents skills commands planning-templates)
+SURFACE=(agents skills commands reference planning-templates)
 
 die() { echo "error: $*" >&2; exit 1; }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/wavefront",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Claude Code frontend-engineering agent framework for scaffold-nextjs-app apps (Next.js/React/MUI/Clean Architecture). Installs agents, skills, and an orchestration loop into a project's .claude/.",
   "bin": {
     "wavefront": "bin/wavefront.js"
@@ -10,13 +10,15 @@
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run",
     "validate:commits": "commitlint --from origin/main --to HEAD --verbose",
-    "validate:branch": "node scripts/validate-branch-name.js"
+    "validate:branch": "node scripts/validate-branch-name.js",
+    "validate:links": "node scripts/validate-skill-links.js"
   },
   "files": [
     "bin/",
     "agents/",
     "skills/",
     "commands/",
+    "reference/",
     "planning-templates/",
     "hooks/",
     "install.sh",

package/planning-templates/STATE.md

@@ -14,6 +14,13 @@
 ## Execution progress
 <which PHASE_PLAN tasks are done; which is next>
 
+## Resume context
+> Set by `/wavefront-execute` (or `/wavefront-verify`) ONLY when a task fails or is interrupted. Empty on a clean run. Lets the next run resume WITH context instead of blindly re-dispatching the same task.
+- Interrupted/failed task: <task # + name from PHASE_PLAN, or empty>
+- Owning agent: <module-builder|tester|i18n-tokens|reviewer>
+- Last error: <the exact tsc/lint/test/agent error>
+- What a resume should do: <re-run as-is | needs a fix first | needs user input>
+
 ## Decisions log
 - <date> <decision> — <why>
 

package/reference/README.md

@@ -0,0 +1,14 @@
+# reference/ — the framework's own idiom anchor
+
+`module/note-module.md` is a canonical, end-to-end Clean-Arch module that agents read to copy current scaffold idioms.
+
+**Why it exists:** apps built from scaffold-nextjs-app routinely **delete the example modules** (`src/modules/todo`, `src/modules/auth`). If `module-builder` relied on reading those live, it would lose its idiom anchor the moment a real project removes them. So the framework ships its own reference instead — no dependency on the scaffold OR on the target app keeping example modules.
+
+**What it is:** one minimal CRUD entity (`note`) showing every layer once, in dependency order, with the exact idioms (`createXGateway` factory, key factory, `queryOptions`/`mutationOptions`, `createStoreWithMiddleware`, business/controller hook split, `@/ui` + tokens, the four states incl. error-boundary, colocated tests). The per-pattern detail lives in `skills/*`; this shows how the layers fit together.
+
+**Compile-inert:** stored as `.md` so a consuming app never type-checks/lints it (same trick as `skills/component-composition/examples/compound-component.md`).
+
+**Provenance / drift:** distilled from the scaffold's real `todo` module at `source_version: 8edaa0b` — the same pin the skills carry. Drift is tracked the same way: `sync-audit` (via the `reviewer` audit mode) diffs this pin against the live scaffold. When the scaffold's idioms change, re-distill this file and bump the pin.
+
+- `source:` scaffold-nextjs-app `src/modules/todo` (types, api, repository, gateways, stores, selectors, views/hooks, components)
+- `source_version:` 8edaa0b

package/reference/module/note-module.md

@@ -0,0 +1,608 @@
+# Reference module — `note` (canonical Clean-Arch chain)
+
+> **This is the framework's own idiom anchor.** Agents read THIS file to copy current scaffold idioms — they do NOT depend on the target app keeping `src/modules/todo`/`auth` (apps routinely delete the example modules).
+>
+> It is a single, minimal CRUD module for one entity (`note`: `id`, `title`, `body`, `completed`, timestamps), distilled from the scaffold's real `todo` module — same idioms, none of `todo`'s app-specific noise (test-error harness, bulk ops, prefetch/cancel surface, 7 selectors). One example per layer, in dependency order. The detailed per-pattern rules live in the individual `skills/*` — this shows how the layers fit together end to end.
+>
+> File is `.md` (compile-inert) so it never gets type-checked/linted in a consuming app. Provenance: see `reference/README.md`.
+
+Module tree this produces:
+```
+src/modules/note/
+  note.types.ts
+  api/note-api.ts
+  repositories/note/
+    gateways/
+      note.gateway.types.ts
+      http-gateway/http-gateway.ts
+      index.ts                       # createNoteGateway(source) factory
+    note.repository.keys.ts
+    note.query-options.ts
+    note.repository.queries.ts
+    note.repository.mutations.ts
+    note.repository.types.ts
+    index.ts                         # combined noteRepository object
+  stores/
+    note.store.ts
+    note.store.types.ts
+    note.store.actions.ts
+  selectors/
+    use-filtered-notes-selector/use-filtered-notes-selector.hook.ts
+  views/note-management/
+    note-management.view.tsx
+    hooks/
+      use-note-management-business/use-note-management-business.hook.ts
+      use-note-management-controller/use-note-management-controller.hook.ts
+    index.ts
+  components/
+    note-form/note-form.component.tsx
+    note-item/note-item.component.tsx
+    note-list/note-list.component.tsx
+    error-boundary/error-boundary.component.tsx
+    index.ts
+```
+
+---
+
+## 1. Types + Zod schemas (`note.types.ts`) — Zod is the source of truth
+
+```tsx
+import { z } from 'zod';
+
+export const NoteSchema = z.object({
+  id: z.number(),
+  title: z.string().min(1, 'common.validation.requiredField'), // i18n key, not a literal
+  body: z.string().optional(),
+  completed: z.boolean().default(false),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export const CreateNoteSchema = NoteSchema.omit({ id: true, createdAt: true, updatedAt: true, completed: true }).extend({
+  completed: z.boolean().optional(),
+});
+
+export const UpdateNoteSchema = CreateNoteSchema.partial();
+
+export const NoteFiltersSchema = z
+  .object({
+    completed: z.union([z.boolean(), z.string().transform((v) => v === 'true')]).optional(),
+    search: z.string().optional(),
+    page: z.union([z.number().int().positive(), z.string().transform((v) => parseInt(v, 10))]).optional(),
+    limit: z.union([z.number().int().positive(), z.string().transform((v) => parseInt(v, 10))]).optional(),
+  })
+  .loose();
+
+export const NoteArraySchema = z.array(NoteSchema);
+
+// Types are INFERRED from schemas — never hand-written interfaces for the entity.
+export type Note = z.infer<typeof NoteSchema>;
+export type CreateNoteRequest = z.infer<typeof CreateNoteSchema>;
+export type UpdateNoteRequest = z.infer<typeof UpdateNoteSchema>;
+export type NoteFilters = z.infer<typeof NoteFiltersSchema>;
+```
+
+## 2. API service (`api/note-api.ts`) — contract + Zod-validated httpClient + singleton
+
+```tsx
+import type { ApiOptions } from '@/api/api.types';
+import { endpoints } from '@/api/endpoints'; // add NOTE.* to @/api/endpoints (Ask-first — shared file)
+import { httpClient } from '@/api/http-client';
+import type { CreateNoteRequest, Note, NoteFilters, UpdateNoteRequest } from '@/modules/note/note.types';
+import { CreateNoteSchema, NoteArraySchema, NoteFiltersSchema, NoteSchema, UpdateNoteSchema } from '@/modules/note/note.types';
+
+export interface NoteApiContract {
+  getAll(filters?: NoteFilters, options?: ApiOptions): Promise<Note[]>;
+  getById(id: string | number, options?: ApiOptions): Promise<Note>;
+  create(note: CreateNoteRequest, options?: ApiOptions): Promise<Note>;
+  update(id: string | number, note: UpdateNoteRequest, options?: ApiOptions): Promise<Note>;
+  delete(id: string | number, options?: ApiOptions): Promise<void>;
+}
+
+const createNoteApiService = (): NoteApiContract => ({
+  async getAll(filters = {}, options) {
+    const response = await httpClient.get<Note[]>(endpoints.NOTE.BASE, {
+      params: filters,
+      requestSchema: NoteFiltersSchema, // request validated
+      responseSchema: NoteArraySchema, // response validated
+      signal: options?.signal,
+    });
+
+    return response.data;
+  },
+  async getById(id, options) {
+    const response = await httpClient.get<Note>(endpoints.NOTE.BY_ID(id), {
+      responseSchema: NoteSchema,
+      signal: options?.signal,
+    });
+
+    return response.data;
+  },
+  async create(note, options) {
+    const response = await httpClient.post<Note>(endpoints.NOTE.BASE, note, {
+      requestSchema: CreateNoteSchema,
+      responseSchema: NoteSchema,
+      signal: options?.signal,
+    });
+
+    return response.data;
+  },
+  async update(id, note, options) {
+    const response = await httpClient.put<Note>(endpoints.NOTE.BY_ID(id), note, {
+      requestSchema: UpdateNoteSchema,
+      responseSchema: NoteSchema,
+      signal: options?.signal,
+    });
+
+    return response.data;
+  },
+  async delete(id, options) {
+    await httpClient.delete(endpoints.NOTE.BY_ID(id), { signal: options?.signal });
+  },
+});
+
+export const noteApi = createNoteApiService(); // singleton for the whole app
+```
+
+## 3. Gateway (`repositories/note/gateways/`) — interface + http impl + factory
+
+`note.gateway.types.ts`:
+```tsx
+import type { CreateNoteRequest, Note, NoteFilters, UpdateNoteRequest } from '@/modules/note/note.types';
+import type { BaseGateway, GatewayOptions } from '@/types/gateway.types';
+
+export interface NoteGateway extends BaseGateway {
+  findAll(filters?: NoteFilters, options?: GatewayOptions): Promise<Note[]>;
+  findById(id: string | number, options?: GatewayOptions): Promise<Note>;
+  create(note: CreateNoteRequest, options?: GatewayOptions): Promise<Note>;
+  update(id: string | number, note: UpdateNoteRequest, options?: GatewayOptions): Promise<Note>;
+  delete(id: string | number, options?: GatewayOptions): Promise<void>;
+}
+```
+
+`http-gateway/http-gateway.ts`:
+```tsx
+import { noteApi } from '@/modules/note/api/note-api';
+import type { NoteGateway } from '@/modules/note/repositories/note/gateways/note.gateway.types';
+
+export const createHttpNoteGateway = (): NoteGateway => ({
+  async findAll(filters, options) {
+    return noteApi.getAll(filters, options);
+  },
+  async findById(id, options) {
+    return noteApi.getById(id, options);
+  },
+  async create(note, options) {
+    return noteApi.create(note, options);
+  },
+  async update(id, note, options) {
+    return noteApi.update(id, note, options);
+  },
+  async delete(id, options) {
+    await noteApi.delete(id, options);
+  },
+  getSourceInfo() {
+    return {
+      type: 'http',
+      name: 'HTTP API Gateway',
+      capabilities: { offline: false, realtime: true, persistence: true },
+    };
+  },
+});
+```
+
+`gateways/index.ts` — the factory (`DataSource` is `'http' | 'localStorage'` only, no `'mock'`):
+```tsx
+import { DataSource } from '@/types/gateway.types';
+
+import { createHttpNoteGateway } from './http-gateway/http-gateway';
+import type { NoteGateway } from './note.gateway.types';
+
+export const createNoteGateway = (source: DataSource = 'http'): NoteGateway => {
+  switch (source) {
+    case 'http':
+      return createHttpNoteGateway();
+    // add createLocalStorageNoteGateway() only if a localStorage source is requested
+    default:
+      return createHttpNoteGateway();
+  }
+};
+
+export { createHttpNoteGateway } from './http-gateway/http-gateway';
+export type { NoteGateway } from './note.gateway.types';
+```
+
+## 4. Repository (`repositories/note/`) — keys → options → queries → mutations → types → combined
+
+`note.repository.keys.ts` — query-key factory, namespaced by `dataSource`:
+```tsx
+import type { NoteFilters } from '@/modules/note/note.types';
+import type { DataSource } from '@/types/gateway.types';
+
+export const noteQueryKeys = {
+  all: ['notes'] as const,
+  lists: (dataSource: DataSource = 'http') => [...noteQueryKeys.all, 'list', dataSource] as const,
+  list: (filters: NoteFilters = {}, dataSource: DataSource = 'http') => [...noteQueryKeys.lists(dataSource), filters] as const,
+  details: (dataSource: DataSource = 'http') => [...noteQueryKeys.all, 'detail', dataSource] as const,
+  detail: (id: string | number, dataSource: DataSource = 'http') => [...noteQueryKeys.details(dataSource), id] as const,
+} as const;
+```
+
+`note.query-options.ts` — `queryOptions`/`mutationOptions` factories (reused by hooks + prefetch):
+```tsx
+import { mutationOptions, queryOptions } from '@tanstack/react-query';
+
+import type { DataSource } from '@/types/gateway.types';
+
+import { createNoteGateway } from './gateways';
+import { noteQueryKeys } from './note.repository.keys';
+
+const getNotesQueryOptions = (filters = {}, dataSource: DataSource = 'http') =>
+  queryOptions({
+    queryKey: noteQueryKeys.list(filters, dataSource),
+    queryFn: ({ signal }) => createNoteGateway(dataSource).findAll(filters, { signal }),
+    staleTime: 5 * 60 * 1000,
+    gcTime: 10 * 60 * 1000,
+  });
+
+const getNoteQueryOptions = (id: string | number, dataSource: DataSource = 'http') =>
+  queryOptions({
+    queryKey: noteQueryKeys.detail(id, dataSource),
+    queryFn: ({ signal }) => createNoteGateway(dataSource).findById(id, { signal }),
+    staleTime: 5 * 60 * 1000,
+    gcTime: 10 * 60 * 1000,
+    enabled: !!id,
+  });
+
+const getCreateNoteMutationOptions = (dataSource: DataSource = 'http') =>
+  mutationOptions({ mutationFn: (note: any) => createNoteGateway(dataSource).create(note), retry: 1 });
+
+const getUpdateNoteMutationOptions = (dataSource: DataSource = 'http') =>
+  mutationOptions({
+    mutationFn: ({ id, data }: { id: string | number; data: any }) => createNoteGateway(dataSource).update(id, data),
+    retry: 1,
+  });
+
+const getDeleteNoteMutationOptions = (dataSource: DataSource = 'http') =>
+  mutationOptions({ mutationFn: (id: string | number) => createNoteGateway(dataSource).delete(id), retry: 1 });
+
+export const noteQueryOptions = { notes: getNotesQueryOptions, note: getNoteQueryOptions } as const;
+export const noteMutationOptions = {
+  createNote: getCreateNoteMutationOptions,
+  updateNote: getUpdateNoteMutationOptions,
+  deleteNote: getDeleteNoteMutationOptions,
+} as const;
+```
+
+`note.repository.queries.ts` — query hooks compose the options:
+```tsx
+import { useQuery } from '@tanstack/react-query';
+
+import { noteQueryOptions } from './note.query-options';
+import type { NoteQueriesRepository } from './note.repository.types';
+
+export const noteQueriesRepository: NoteQueriesRepository = {
+  useNotes: (filters = {}, dataSource = 'http', options) =>
+    useQuery({ ...noteQueryOptions.notes(filters, dataSource), ...options }),
+  useNote: (id, dataSource = 'http', options) =>
+    useQuery({ ...noteQueryOptions.note(id, dataSource), ...options }),
+};
+```
+
+`note.repository.mutations.ts` — mutation hooks own cache writes in `onSuccess`; always forward the user's `options?.onSuccess`:
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import type { Note } from '@/modules/note/note.types';
+
+import { noteMutationOptions } from './note.query-options';
+import { noteQueryKeys } from './note.repository.keys';
+import type { NoteMutationsRepository } from './note.repository.types';
+
+export const noteMutationsRepository: NoteMutationsRepository = {
+  useCreateNote: (dataSource = 'http', options) => {
+    const queryClient = useQueryClient();
+    const baseOptions = noteMutationOptions.createNote(dataSource);
+
+    return useMutation({
+      ...baseOptions,
+      // eslint-disable-next-line max-params  ← REQUIRED: onSuccess has 4 params, lint cap is 3
+      onSuccess: (newNote, vars, onMutateResult, ctx) => {
+        queryClient.invalidateQueries({ queryKey: noteQueryKeys.lists(dataSource) });
+        queryClient.setQueryData<Note[]>(noteQueryKeys.lists(dataSource), (old) => (old ? [...old, newNote] : [newNote]));
+        options?.onSuccess?.(newNote, vars, onMutateResult, ctx);
+      },
+      ...options,
+    });
+  },
+  useUpdateNote: (dataSource = 'http', options) => {
+    const queryClient = useQueryClient();
+
+    return useMutation({
+      ...noteMutationOptions.updateNote(dataSource),
+      // eslint-disable-next-line max-params
+      onSuccess: (updated: Note, vars, onMutateResult, ctx) => {
+        queryClient.setQueryData<Note[]>(noteQueryKeys.lists(), (old) => old?.map((n) => (n.id === updated.id ? updated : n)));
+        queryClient.invalidateQueries({ queryKey: noteQueryKeys.lists(dataSource) });
+        options?.onSuccess?.(updated, vars, onMutateResult, ctx);
+      },
+      ...options,
+    });
+  },
+  useDeleteNote: (dataSource = 'http', options) => {
+    const queryClient = useQueryClient();
+
+    return useMutation({
+      ...noteMutationOptions.deleteNote(dataSource),
+      // eslint-disable-next-line max-params
+      onSuccess: (result, deletedId, onMutateResult, ctx) => {
+        queryClient.setQueryData<Note[]>(noteQueryKeys.lists(), (old) => old?.filter((n) => n.id !== deletedId));
+        queryClient.invalidateQueries({ queryKey: noteQueryKeys.lists(dataSource) });
+        options?.onSuccess?.(result, deletedId, onMutateResult, ctx);
+      },
+      ...options,
+    });
+  },
+};
+```
+
+`note.repository.types.ts` — interfaces (queries extend `BaseRepository`; options from `@/core/lib/react-query`):
+```tsx
+import { type UseMutationResult, type UseQueryResult } from '@tanstack/react-query';
+
+import type { BaseRepository } from '@/core/lib/react-query';
+import { MutationOptions, QueryOptions } from '@/core/lib/react-query';
+import type { CreateNoteRequest, Note, NoteFilters, UpdateNoteRequest } from '@/modules/note/note.types';
+import type { DataSource } from '@/types/gateway.types';
+
+export interface NoteQueriesRepository extends BaseRepository {
+  useNotes: (filters?: NoteFilters, dataSource?: DataSource, options?: QueryOptions) => UseQueryResult<Note[], Error>;
+  useNote: (id: string | number, dataSource?: DataSource, options?: QueryOptions) => UseQueryResult<Note, Error>;
+}
+export interface NoteMutationsRepository {
+  useCreateNote: (dataSource?: DataSource, options?: MutationOptions) => UseMutationResult<Note, Error, CreateNoteRequest>;
+  useUpdateNote: (dataSource?: DataSource, options?: MutationOptions) => UseMutationResult<Note, Error, { id: string | number; data: UpdateNoteRequest }>;
+  useDeleteNote: (dataSource?: DataSource, options?: MutationOptions) => UseMutationResult<void, Error, string | number>;
+}
+export interface NoteRepository {
+  queries: NoteQueriesRepository;
+  mutations: NoteMutationsRepository;
+  queryKeys: typeof import('./note.repository.keys').noteQueryKeys;
+}
+```
+
+`repositories/note/index.ts` — the combined repository object the hooks import:
+```tsx
+import { noteMutationsRepository } from './note.repository.mutations';
+import { noteQueriesRepository } from './note.repository.queries';
+import { noteQueryKeys } from './note.repository.keys';
+import type { NoteRepository } from './note.repository.types';
+
+export const noteRepository: NoteRepository = {
+  queries: noteQueriesRepository,
+  mutations: noteMutationsRepository,
+  queryKeys: noteQueryKeys,
+};
+```
+
+## 5. Store (`stores/`) — Zustand via `createStoreWithMiddleware` (never raw `create`)
+
+`note.store.types.ts`:
+```tsx
+import type { NoteFilters } from '@/modules/note/note.types';
+
+export interface NoteState {
+  selectedNoteId: number | null;
+  filters: NoteFilters;
+  setSelectedNoteId: (id: number | null) => void;
+  setFilters: (filters: NoteFilters) => void;
+}
+```
+
+`note.store.ts`:
+```tsx
+import { createStoreWithMiddleware } from '@/core/lib/zustand';
+
+import type { NoteState } from './note.store.types';
+
+export const useNoteStore = createStoreWithMiddleware<NoteState>(
+  (set) => ({
+    selectedNoteId: null,
+    filters: {},
+    setSelectedNoteId: (id) => set((state) => { state.selectedNoteId = id; }), // immer middleware → mutate draft
+    setFilters: (filters) => set((state) => { state.filters = filters; }),
+  }),
+  { name: 'note-store' },
+);
+```
+
+`note.store.actions.ts` — selector hook for actions (stable references):
+```tsx
+import { useNoteStore } from './note.store';
+
+export const useNoteActions = () =>
+  useNoteStore((s) => ({ setSelectedNoteId: s.setSelectedNoteId, setFilters: s.setFilters }));
+```
+
+## 6. Selector (`selectors/`) — derived state via `useMemo` over a query
+
+`use-filtered-notes-selector/use-filtered-notes-selector.hook.ts`:
+```tsx
+import { useMemo } from 'react';
+
+import { noteRepository } from '@/modules/note/repositories/note';
+import { useNoteStore } from '@/modules/note/stores/note.store';
+import type { DataSource } from '@/types/gateway.types';
+
+export const useFilteredNotesSelector = (dataSource: DataSource = 'http') => {
+  const filters = useNoteStore((s) => s.filters);
+  const notesQuery = noteRepository.queries.useNotes(filters, dataSource);
+
+  const data = useMemo(() => {
+    const notes = notesQuery.data ?? [];
+    if (filters.completed === undefined) return notes;
+
+    return notes.filter((n) => n.completed === filters.completed);
+  }, [notesQuery.data, filters.completed]);
+
+  return { ...notesQuery, data };
+};
+```
+
+## 7. Hooks (`views/note-management/hooks/`) — business vs controller split (mandatory)
+
+**Business hook** = data + business rules + the four states. Exposes `error` + `refetch` for the error-boundary:
+```tsx
+'use client';
+
+import { useCallback } from 'react';
+
+import { noteRepository } from '@/modules/note/repositories/note';
+import { useNoteActions } from '@/modules/note/stores/note.store.actions';
+import type { CreateNoteRequest, UpdateNoteRequest } from '@/modules/note/note.types';
+import type { DataSource } from '@/types/gateway.types';
+
+export const useNoteManagementBusiness = (dataSource: DataSource = 'http') => {
+  const { setSelectedNoteId } = useNoteActions();
+
+  const notesQuery = noteRepository.queries.useNotes({}, dataSource);
+  const createMutation = noteRepository.mutations.useCreateNote(dataSource);
+  const deleteMutation = noteRepository.mutations.useDeleteNote(dataSource);
+
+  const createNote = useCallback(
+    (data: CreateNoteRequest) => {
+      if (!data.title?.trim()) throw new Error('common.validation.requiredField');
+
+      return createMutation.mutate({ ...data, title: data.title.trim() });
+    },
+    [createMutation],
+  );
+  const deleteNote = useCallback((id: number) => deleteMutation.mutate(id), [deleteMutation]);
+
+  return {
+    notes: notesQuery.data ?? [],
+    isLoading: notesQuery.isLoading,
+    isEmpty: !notesQuery.isLoading && (notesQuery.data?.length ?? 0) === 0,
+    error: notesQuery.error ?? createMutation.error ?? deleteMutation.error, // four states: error
+    isCreating: createMutation.isPending,
+    isDeleting: deleteMutation.isPending,
+    createNote,
+    deleteNote,
+    setSelectedNoteId,
+    refetch: notesQuery.refetch, // wired to the error-boundary's onRetry
+  };
+};
+```
+
+**Controller hook** = UI orchestration (event handlers that adapt UI events → business actions). No data fetching:
+```tsx
+'use client';
+
+import { useCallback } from 'react';
+
+import type { CreateNoteRequest } from '@/modules/note/note.types';
+
+export const useNoteManagementController = () => {
+  const handleCreateSubmit = useCallback(
+    (createNote: (data: CreateNoteRequest) => void) => (data: CreateNoteRequest) => createNote(data),
+    [],
+  );
+  const handleDeleteClick = useCallback((deleteNote: (id: number) => void) => (id: number) => deleteNote(id), []);
+
+  return { handleCreateSubmit, handleDeleteClick };
+};
+```
+
+## 8. View (`views/note-management/note-management.view.tsx`) — orchestrates; returns the error state; no inline markup blocks
+
+```tsx
+'use client';
+
+import { ErrorBoundary, NoteForm, NoteList } from '@/modules/note/components';
+import tokens from '@/styles/tokens';
+import { Box, Typography } from '@/ui';
+
+import { useNoteManagementBusiness, useNoteManagementController } from './hooks';
+
+export const NoteManagementView = () => {
+  const { notes, isLoading, isCreating, isDeleting, error, createNote, deleteNote, refetch } = useNoteManagementBusiness('http');
+  const { handleCreateSubmit, handleDeleteClick } = useNoteManagementController();
+
+  // four states: ERROR — recoverable error+retry, never a blank screen (see error-boundary skill)
+  if (error) return <ErrorBoundary error={error} onRetry={refetch} />;
+
+  return (
+    <Box sx={{ p: tokens.spacing.scale6 }}>
+      <Typography gutterBottom variant="h4">
+        Notes
+      </Typography>
+      <NoteForm isCreating={isCreating} onSubmit={handleCreateSubmit(createNote)} />
+      <NoteList isDeleting={isDeleting} isLoading={isLoading} notes={notes} onDelete={handleDeleteClick(deleteNote)} />
+    </Box>
+  );
+};
+```
+
+## 9. Components (`components/`) — composed, `@/ui` + tokens, mapped row is its own component
+
+`note-list.component.tsx` — anything inside `.map()` is its own component (`NoteItem`), never inline JSX:
+```tsx
+import tokens from '@/styles/tokens';
+import { Box, Typography } from '@/ui';
+
+import { NoteItem } from '../note-item/note-item.component';
+import type { Note } from '@/modules/note/note.types';
+
+interface NoteListProps {
+  notes: Note[];
+  isLoading: boolean;
+  isDeleting: boolean;
+  onDelete: (id: number) => void;
+}
+
+export const NoteList = ({ notes, isLoading, isDeleting, onDelete }: NoteListProps) => {
+  if (isLoading) return <Typography>Loading…</Typography>; // four states: loading
+  if (notes.length === 0) return <Typography>No notes yet</Typography>; // four states: empty
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: tokens.spacing.scale4 }}>
+      {notes.map((note) => (
+        <NoteItem key={note.id} note={note} isDeleting={isDeleting} onDelete={onDelete} />
+      ))}
+    </Box>
+  );
+};
+```
+
+`error-boundary/error-boundary.component.tsx` — recoverable error+retry (see the `error-boundary` skill for the full version + test). `NoteForm` uses RHF + `zodResolver(CreateNoteSchema)` (see `forms-rhf-zod`), `NoteItem` is `memo`'d with role-based interactions.
+
+`components/index.ts` barrels every component; `views/index.ts` barrels the view; each layer dir has its `index.ts`.
+
+## 10. Tests (colocated, one per layer) — `@test/utils` + faker factories
+
+```tsx
+// note-item.component.test.tsx
+import { fireEvent, renderWithProviders, screen } from '@test/utils';
+import { createMockNote } from '@test/entities/note.mock'; // faker factory; create if missing
+
+import { NoteItem } from './note-item.component';
+
+it('calls onDelete when delete is clicked', () => {
+  const onDelete = jest.fn();
+  renderWithProviders(<NoteItem note={createMockNote()} isDeleting={false} onDelete={onDelete} />);
+  fireEvent.click(screen.getByRole('button', { name: /delete/i }));
+  expect(onDelete).toHaveBeenCalled();
+});
+```
+
+Every logic layer gets a colocated `*.test.ts(x)` (api/gateway/repository queries+mutations/store/selector/business+controller hooks/each component/view). Import test helpers ONLY from `@test/utils`; query by role/label first.
+
+---
+
+## Layer dependency direction (never violate)
+
+```
+View → controller hook + business hook → repository (queries/mutations) → gateway → api → httpClient
+                                       ↘ store / selectors (local + derived state)
+```
+A View/component never calls the api or gateway directly — always through the repository. Types flow from `*.types.ts` (Zod-inferred). UI is `@/ui` + `@/styles/tokens` only. Strings are i18n keys, not literals.

package/skills/testing-jest-rtl/SKILL.md

@@ -9,8 +9,8 @@ source_version: 8edaa0b
 
 Tests colocate next to source as `*.test.ts` / `*.test.tsx`. Everything is imported from `@test/utils` (lint forbids importing RTL / `react-dom` directly in feature tests).
 
-## Coverage is per-layer (mirror todo)
-The scaffold tests EVERY layer — `src/modules/todo` ships a colocated test for api, gateway, repository (queries + mutations), store, each selector, business + controller hooks, each helper, each component, and the view. Match that: one colocated test per piece with logic, not just the happy-path hook.
+## Coverage is per-layer
+Test EVERY layer — a colocated test for api, gateway, repository (queries + mutations), store, each selector, business + controller hooks, each helper, each component, and the view (the bundled `.claude/reference/module/note-module.md` shows this per-layer test layout; don't rely on the target app keeping `src/modules/todo`). Match that: one colocated test per piece with logic, not just the happy-path hook.
 - **Unit:** pure pieces alone — helpers, store, a presentational component with mock props.
 - **Integration:** pieces wired through providers — `renderHookWithProviders` for a business hook (hook→repository→gateway→api), a view with real hooks.
 Cover both. A module with one test is undertested.

package/uninstall.sh

@@ -5,7 +5,7 @@
 set -euo pipefail
 
 HOME_DIR="${WAVEFRONT_HOME:-$HOME/.wavefront}"
-SURFACE=(agents skills commands planning-templates)
+SURFACE=(agents skills commands reference planning-templates)
 
 die() { echo "error: $*" >&2; exit 1; }