@pavp/wavefront 1.2.1 → 1.2.2

package/agents/i18n-tokens.md

@@ -9,7 +9,8 @@ The localization + design-token enforcer for scaffold-nextjs-app. Sweeps a modul
 
 ## Operating rules
 - Always: read the i18n + tokens skills first; replace visible literals with `t('namespace.key')`; namespace keys by module; replace hardcoded spacing/scale/color with `tokens.*`; swap raw `@mui/material` imports for `@/ui`; swap `next/link`/`next/navigation` for `@/i18n/routing`; keep Zod validation messages as i18n keys rendered through `t()`.
-- Always: run `yarn lint` + `tsc --noEmit` after edits; verify no behavior change.
+- Always (new namespace): if you introduce a namespace that isn't already registered, **add its entry to the `messages` object in `src/i18n/request.ts`** (mirror the existing `common` fetch) — a namespace with no `request.ts` entry resolves to nothing. Prefer reusing `common` for app-wide strings; only add a namespace when the feature warrants one. See [[i18n-next-intl]].
+- Always: run `yarn lint:fix` (eslint + stylelint auto-fix; fall back to `eslint . --fix && stylelint --fix` if no `lint:fix` script — never bare `eslint --fix <file>`), then `yarn lint` + `tsc --noEmit` to confirm clean after edits; verify no behavior change.
 - Ask first: registering the actual translation values (messages are remote-fetched per `src/i18n/request.ts` — coordinate with the translation backend, don't invent a local messages file unless the project uses one); introducing a new token (prefer existing tokens; new tokens touch Style Dictionary).
 - Never: leave user-facing copy as literals; hardcode spacing/color when a token exists; import raw `@mui/material` in feature code; use `next/link` for locale routes; change component logic while localizing.
 
@@ -28,7 +29,7 @@ The localization + design-token enforcer for scaffold-nextjs-app. Sweeps a modul
    - Imports → `@/ui`, `@/i18n/routing`.
    - Zod messages → ensure rendered via `t(errors.field?.message)`.
 5. List the new translation keys introduced; flag that their values must be registered with the translation source.
-6. Run `yarn lint` + `tsc --noEmit`; confirm clean. Hand off to reviewer.
+6. Run `yarn lint:fix`, then `yarn lint` + `tsc --noEmit`; confirm clean. Hand off to reviewer.
 
 ## Examples
 

package/agents/module-builder.md

@@ -16,7 +16,7 @@ The implementer that owns the full Clean Architecture chain for a feature module
 - 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.
-- Always: after generating, run `tsc --noEmit` (or `yarn typecheck`) and `yarn lint`; fix what you generated until clean; then hand off to `tester` and `reviewer`.
+- Always: after generating, run `yarn lint:fix` (the project's combined eslint + stylelint auto-fixer — covers CSS/SCSS too; fall back to `eslint . --fix && stylelint --fix` only if there is no `lint:fix` script). Never hand-fix file-by-file with bare `eslint --fix <file>`. Then run `tsc --noEmit` (or `yarn typecheck`) and `yarn lint` to confirm clean; fix any remaining issues; then hand off to `tester` and `reviewer`.
 - Ask first: adding a new dependency; changing shared files (`@/api/endpoints`, `@/types/gateway.types`, theme/tokens); deviating from a documented pattern; generating a non-http gateway (localStorage/mock) when not requested.
 - Always (modify mode): start from the mapper change-plan; touch ONLY files it lists as ADD/MODIFY; preserve existing public API unless the plan says to change it; keep edits minimal and local; run the module's existing tests after editing and keep them green (regression).
 - Never: skip a layer (no View/component calling api or gateway directly — go through the repository); put side effects in render; use `any` at boundaries; hardcode URLs (use `endpoints`), spacing/color (use tokens), or user-facing strings (use next-intl); import raw `@mui/material` in feature code; call raw `create` from zustand (use `createStoreWithMiddleware`).
@@ -55,7 +55,7 @@ The implementer that owns the full Clean Architecture chain for a feature module
    g. `views/[view]/` — `*.view.tsx` + `hooks/use-*-business` + `hooks/use-*-controller` + view `helpers/`.
    h. `components/` — presentational components from `@/ui` + tokens.
    i. `index.ts` — module public API barrel.
-5. Verify: `tsc --noEmit` + `yarn lint`; self-check against `module-structure`.
+5. Verify: `yarn lint:fix` (eslint + stylelint auto-fix), then `tsc --noEmit` + `yarn lint` to confirm clean; self-check against `module-structure`.
 6. Hand off: tell `tester` to add colocated tests and `reviewer` to validate.
 
 ## Examples

package/agents/reviewer.md

@@ -35,7 +35,7 @@ Convention and architecture guardian for scaffold-nextjs-app projects. Reads cod
    - Imports: import-sort order; restricted-import rule (test bits from `@test/utils/test-utils`).
    - UI/responsive: UI from `@/ui` (not raw `@mui/material`); spacing/color via tokens (no literals); strings via next-intl; **responsive present** — no fixed pixel widths that overflow mobile, breakpoint usage via theme keys (`minMobile`/`minTablet`/`minDesktop`, not xs/sm/md); the four states (loading/empty/error/populated) handled — for a data-fetching view the **error** state must render a recoverable error+retry UI (error-boundary pattern wired to `refetch`); BLOCKER if a failed query renders blank.
    - Composition: UI decomposed into `components/` subcomponents (no monolithic view holding form+list+states inline); composition over inheritance; no boolean-prop explosion; each component independently testable. **Flag inline JSX inside `.map()`** — a mapped row/item must be its own component (e.g. list → item), not inline markup. Apply the "when to extract" rule (map / distinct responsibility / own state / ~30–40+ lines); also flag over-fragmentation of trivial markup.
-   - Test coverage (per layer): flag any logic layer WITHOUT a colocated test — api, gateway, repository queries+mutations, store, selectors, business+controller hooks, helpers, each component, view. One happy-path test ≠ covered. Note missing unit vs integration.
+   - Test coverage (per layer) — **BLOCKER if incomplete:** enumerate the module's logic files and flag ANY without a colocated test — `*-api.ts` (`*-api.test.ts`), gateway, **`*.repository.queries.ts` AND `*.repository.mutations.ts` (each needs its own test)**, store, each selector, business+controller hooks, helpers, **EACH `components/*` subcomponent**, view. A partial test set (e.g. hooks tested but components/api/repository.queries missing) is a BLOCKER, not a nit. One happy-path test ≠ covered. Note missing unit vs integration.
 4. Tooling pass: run `yarn lint` and `yarn typecheck` if present; capture real errors.
 5. Report: grouped by BLOCKER / WARNING / NIT, each `path:line — problem — fix`. End with PASS/FAIL verdict + concise fix list. No edits.
 

package/agents/tester.md

@@ -31,6 +31,13 @@ Mirror the bundled reference (`.claude/reference/module/note-module.md` shows a
 
 A module is NOT done when only the happy-path hook is tested. Missing-layer tests are a gap to fill, not optional.
 
+## Completeness gate (BLOCKING — do this before handing off)
+Coverage discipline is NOT a suggestion — verify it. After writing tests:
+1. **Enumerate** the module's generated files with logic. `Glob`/`ls` the module dir for: `*-api.ts`, `gateways/**/*.ts`, `*.repository.queries.ts`, `*.repository.mutations.ts`, `*.store.ts`, `selectors/**/*.hook.ts`, `*-business.hook.ts`, `*-controller.hook.ts`, `*.helper.ts`, `components/**/*.component.tsx`, `*.view.tsx`.
+2. **For EACH** of those, confirm a sibling `*.test.ts(x)` exists. Build the checklist explicitly — name every source file and whether its test is present.
+3. **If ANY is missing, you are NOT done** — write the missing test(s) now. Do not hand off a partial test set. Common misses to double-check every time: **each `components/*` subcomponent**, **`*-api.test.ts`**, **`*.repository.queries.test.ts`** AND **`*.repository.mutations.test.ts`** (both, separately).
+4. Only after every logic layer has its colocated test, run the suite and hand off.
+
 ## Operating rules
 - Always: read the testing skill first; colocate tests next to source; import test helpers ONLY from `@test/utils` (RTL/react-dom direct import is a lint error); use faker factories from `@test/entities/[entity].mock.ts` (create one if missing); query by role/label before text/testid; wrap async assertions in `waitFor`; clear `jest.fn()` mocks in `beforeEach`.
 - Always: cover EVERY logic layer (see Coverage discipline above), not just one hook; include edge/error cases + the four UI states, not only the happy path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/wavefront",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "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"

package/skills/component-composition/SKILL.md

@@ -20,7 +20,7 @@ src/modules/<m>/
 │   └── index.ts
 └── views/<m>-management/<m>-management.view.tsx   # composes the above + hooks
 ```
-Reference: `src/modules/todo/components/{todo-form,todo-item,todo-list,todo-filters}` — each its own dir, `*.component.tsx`, `*.test.tsx`. The view wires them to the business/controller hooks.
+Reference: the bundled `.claude/reference/module/note-module.md` (§9 components — `note-form`, `note-item`, `note-list`, `error-boundary`) — each its own dir, `*.component.tsx`, `*.test.tsx`. The view wires them to the business/controller hooks. (Don't depend on the app keeping `src/modules/todo`.)
 
 ## When to extract a subcomponent (decision rule)
 

package/skills/design-system-inventory/SKILL.md

@@ -12,7 +12,7 @@ The continuity engine. Whatever the design source (or none), generated UI must l
 ## Step 0 — inventory the actual app (do this each run)
 1. `@/ui` exports: read `src/ui/index.ts` → the available components (Button, TextField, Selector, Dialog, Modal, Card, Box, Typography, Container, Grid, List, Checkbox, RadioButton, Switch, Pagination, Toast, etc. — read the real list, it evolves).
 2. Tokens: read `src/styles/tokens.ts` + subdirs → `tokens.spacing.scaleN`, `tokens.colors.*`, `tokens.typography.*`, `tokens.breakpoints.*`. Use these, never literals.
-3. Composition patterns: read 1–2 existing views (`src/modules/todo/views/...`, `src/modules/about/...`) → how they lay out forms, lists, cards; what wraps what; how loading/empty/error states render.
+3. Composition patterns: `Glob` `src/modules/*/views/**/*.view.tsx` and read 1–2 of whatever views the app ACTUALLY has → how they lay out forms, lists, cards; what wraps what; how loading/empty/error states render. Don't assume a specific module (`todo`/`about` may not exist — real projects delete the examples). If the app has no feature views yet, fall back to the bundled `.claude/reference/module/note-module.md` for the composition pattern.
 
 ## Component selection map (intent → @/ui)
 Match design intent to the real component, never raw `@mui/material`:

package/skills/i18n-next-intl/SKILL.md

@@ -31,11 +31,30 @@ import { Link, redirect, usePathname, useRouter } from '@/i18n/routing';
 ```
 `routing` is built with `defineRouting({ locales, defaultLocale })` + `createNavigation`. Locales come from `config.translation`. Routes use the `[locale]` App Router segment.
 
-## Messages are remote-fetched
+## Messages are remote-fetched, and each namespace is registered in `request.ts`
 
-`src/i18n/request.ts` (`getRequestConfig`) fetches messages from the settings API per locale into the `common` namespace (with `revalidate`). There is **no local `messages/en.json`** to edit by default — translation strings live server-side. When adding a key:
-- Reference it in code (`t('feature.key')`).
-- Coordinate the actual translation value with the settings/translation backend (per `docs/intl.md`), not a local file — unless the project has been changed to local messages.
+`src/i18n/request.ts` (`getRequestConfig`) fetches messages from the settings API per locale. There is **no local `messages/en.json`** by default — strings live server-side. Crucially, the `messages` object lists **one entry per namespace**, each its own fetch:
+
+```ts
+return {
+  locale,
+  messages: {
+    common: await fetch(`${config.apiUrl}${endpoints.SETTINGS.TRANSLATION}/${locale}/common`, {
+      next: { revalidate },
+    } as RequestInit)
+      .then((res) => res.json())
+      .catch(() => ({})),
+    // each additional namespace needs its OWN entry, mirroring `common`:
+    // favorites: await fetch(`${config.apiUrl}${endpoints.SETTINGS.TRANSLATION}/${locale}/favorites`, …).then(...).catch(() => ({})),
+  },
+};
+```
+
+**A new namespace does not exist until you add it here.** Using `useTranslations('favorites')` without a `favorites:` entry in `request.ts` yields missing messages. So when introducing a new feature namespace:
+- **Edit `src/i18n/request.ts`** — add a `<namespace>: await fetch(\`${config.apiUrl}${endpoints.SETTINGS.TRANSLATION}/${locale}/<namespace>\`, { next: { revalidate } } as RequestInit).then((res) => res.json()).catch(() => ({}))` entry to `messages`, mirroring `common`.
+- Reference keys in code (`t('feature.key')` with `useTranslations('feature')`, or fully-qualified from `common`).
+- Register the actual values with the settings/translation backend (per `docs/intl.md`).
+- (Reuse `common` instead of a new namespace when the strings are app-wide — only add a namespace when the feature warrants its own.)
 
 ## Validation messages = i18n keys
 
@@ -54,6 +73,7 @@ See [[forms-rhf-zod]].
 ## Rules
 - Components stay copy-free: text via `t()`, links via `@/i18n/routing`.
 - New keys: add usage in code + register the value with the translation source.
+- **New namespace: add its `messages` entry in `src/i18n/request.ts` (mirror `common`) — without it the namespace resolves to nothing.**
 
 ## Related skills
 [[forms-rhf-zod]] · [[mui-design-tokens]] · [[testing-jest-rtl]]

package/skills/module-structure/SKILL.md

@@ -44,7 +44,7 @@ src/modules/[module-name]/
 └── [module].types.ts             # module types
 ```
 
-Reference modules in scaffold: `src/modules/todo` (full: stores, repositories, components, hooks, api, selectors, views), `src/modules/auth` (stores, repositories, api, selectors, views). Mirror their shape.
+Canonical reference: the bundled `.claude/reference/module/note-module.md` shows the full module shape (stores, repositories, components, hooks, api, selectors, views) — mirror it. Do NOT rely on `src/modules/todo`/`auth` existing in the target app; real projects delete the example modules.
 
 Nesting note: components, views, selectors, hooks each use a **one-dir-per-unit** pattern (`use-x-selector/use-x-selector.hook.ts`). Views and components may nest their own `hooks/` (business+controller) and `helpers/`. Tests colocate next to source as `*.test.ts(x)`.