@bonesofspring/ai-rules 0.2.30 → 0.2.32

package/presets/mavis/next/ai-local/rules-library/storybook-csf-authoring.md

@@ -0,0 +1,100 @@
+globs: storybook/**/*.stories.tsx, storybook/**/*.fixtures.ts, storybook/**/*.fixtures.data.ts, storybook/**/*.stories.meta.ts
+
+## Body
+
+# Storybook CSF authoring
+
+When editing CSF/fixtures, acknowledge: `Using .ai.local: storybook-csf-authoring(, …)*`.
+
+## CSF3 skeleton
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta = {
+  title: 'UI/Pages/ExamplePage',
+  component: ExamplePage,
+  tags: ['test', 'snapshot'],
+  decorators: [withStoreProvider({ preloadedState })],
+  parameters: { layout: 'fullscreen', viewport: { defaultViewport: 'desktop' } },
+} satisfies Meta<typeof ExamplePage>;
+
+export default meta;
+type TStory = StoryObj<typeof meta>;
+
+/** S01 — default loaded state */
+export const Default: TStory = { /* … */ };
+```
+
+## Imports
+
+- Production: `@/ui/...`, `@/store/...`, `@/types/...`.
+- Storybook: the project's shared decorators/helpers (`withStoreProvider`, `withGreyCanvas`, `withStorybookSearchParams`, `withDocumentReferrer`), the shared MSW helper, and the test utilities (`expect`, `within`, `userEvent`, `fn`, `waitFor`).
+- Play helpers: co-locate in `*.stories.meta.ts` or `*.fixtures.ts` — do not duplicate selectors.
+
+## Data & decorators
+
+- MSW: `parameters: { ...storyMsw(handlers) }` from the shared MSW helper.
+- Store: `decorators: [withStoreProvider({ preloadedState })]` — use fixture builders.
+- Search params: `withStorybookSearchParams({ key: 'value' })`.
+- Browser globals (render-time): `withDocumentReferrer('')` — `document.referrer` and in-app list session signals are **story fixtures**, not play-only setup. Reset session keys when production reads them at render.
+- White-card isolated blocks **only** (a solid white surface token): `withGreyCanvas`. Do not use on grey primary/secondary roots.
+- **Never** `parameters.nextjs.appDirectory`. Do not null-guard production `useSearchParams`.
+
+## Fixtures
+
+Split: handlers/ids (`*.fixtures.ts`), static data (`*.fixtures.data.ts`), play constants (`*.stories.meta.ts`).
+Reuse page fixtures before inventing ids. Document story-local id ranges in the README.
+
+## One CSF file per `title` (strict)
+
+Allowed: `PageName.stories.tsx`, `Components/<Block>.stories.tsx`, `modals/<Domain>/<Modal>.stories.tsx`.
+
+**Forbidden:**
+
+- New `*.p1.stories.tsx`, `*.p2.stories.tsx`, or any `*.pN.stories.tsx`.
+- Adding exports to existing p1/p2 files.
+- Numbered overflow siblings sharing the same `title`.
+
+Existing p1/p2 in a repo are **legacy — do not copy or extend**. If the main file is large, extract a page block into `Components/` (new `title`).
+
+## No mobile/viewport duplicates (strict)
+
+One desktop canvas per logical state; reviewers use the Storybook viewport toolbar.
+
+**Ban:** `export const Mobile*`, `Mobile_*`, `defaultViewport: 'mobile1'` / `'mobile2'`, `isMobile: true` preloads, `*MobileMediaPreload` fixtures, dedicated `*Mobile*.stories.tsx` for viewport variants.
+
+**Keep only** product UI whose name is Mobile (a distinct component, not a second viewport of a page).
+
+## Play vs visual
+
+- Every snapshot story has a `play` asserting primary `data-testid`s or visible copy.
+- Call the visual-settle helper after icon/header paint (~300ms) when flaking — use it on isolated blocks/modals with masked icons before vis.
+- Portals: assert `within(canvasElement.ownerDocument.body)`.
+- **Loading / spinner vis:** preload the store slice (`loadingStatus: 'loading'`) or MSW `delay('infinite')`. **Forbidden:** click download/submit then vis the in-flight frame without pinning the request.
+- Freeze animations only on spinner/QR/skeleton stories, as the last line of `play`; then `--update -t` that story only.
+- **Intentional** `LoadFailed` export (MSW 500) ≠ an accidental "failed to load the page" (missing API mocking).
+
+## Tags & layout
+
+- `tags: ['test', 'snapshot']` on visual catalog entries.
+- Page: `layout: 'fullscreen'`, `viewport.defaultViewport: 'desktop'`.
+- Isolated block: `layout: 'centered'` unless the block needs width.
+
+## Grey canvas (white cards only)
+
+Apply the grey-canvas decorator **only** when the production root is a solid white surface. Use the project's grey-surface token. Never hex.
+
+```tsx
+import { withGreyCanvas } from '<shared-decorators>' // adjust depth
+
+decorators: [withGreyCanvas], // outer; width shells stay inside
+```
+
+**Do not apply** when the root is already grey, transparent, a fullscreen page, or a modal. Grey-on-grey hides radius and rest/hover fills.
+
+**Forbidden:** `parameters.backgrounds` hex lists; a grey wrapper the same size as the card (edge still invisible).
+
+## After batch
+
+Mandatory: **`storybook-ui-quality-gate`** — preview stories, compare canvas vs mockup, then run story tests. Then **`storybook-keep-tests-current`**: fix play/fixtures, targeted vitest, `--update` vis after intentional visual changes, re-run green. Then **`storybook-cleanup-temp-screenshots`** — delete dump PNGs from this turn; do not commit them.

package/presets/mavis/next/ai-local/rules-library/storybook-dev-compare-figma.md

@@ -0,0 +1,67 @@
+globs: app/src/ui/**/*.tsx, app/src/ui/**/*.ts, storybook/stories/**/*.stories.tsx
+
+## Body
+
+# Storybook dev-time Figma visual compare (mandatory)
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-dev-compare-figma(, …)*`.
+
+While implementing or refactoring `app/src/ui/**` (new component, visual/interaction change, layout, styles, copy, hover/open), the **source of visual truth is Figma** — not Storybook vis-baselines. Vis-baselines are a **regression detector** (they catch "you broke what was working"), not a design spec (they do not validate "this matches the Figma mockup"). They can lock in a wrong implementation as the baseline if `--update` is run before the implementation is correct.
+
+This rule makes the dev-loop **mandatory** and forbids the failure mode where an agent captures a `--update` baseline against a wrong implementation, the wrong implementation becomes the "correct" baseline, and the next round of changes is compared against the wrong baseline — drift is hidden forever.
+
+## The required loop (every visual change)
+
+1. **Read Figma first** — `figma_get_metadata` for the node structure, `figma_get_design_context` for the actual styles/tokens, `figma_get_variable_defs` for design tokens, `figma_get_screenshot` for the visual reference. Do not pick the wrong reference node (e.g. a wrapper frame instead of the card component). Pick the **innermost** matching node.
+2. **Implement to spec** — every token (color, padding, gap, font, radius) must come from `figma_get_design_context` / `figma_get_variable_defs`, not from memory or from guessing. If a style is not in the Figma spec, the implementation is wrong; do not invent.
+3. **Open the story in a browser** — navigate to the story URL (e.g. `http://localhost:6006/?path=/story/<story-id>`). If Storybook is not running, start it with `yarn storybook` from `storybook/`.
+4. **Take a screenshot** — of the **opened dialog / visible state**, not the Storybook iframe placeholder.
+5. **Visual compare with Figma** — open the Figma screenshot in the same view (saved PNG of the Figma node). Compare element-by-element:
+   - Title (font, size, weight, color, line-height, letter-spacing)
+   - Subtitle / supporting text (same)
+   - Container (background, border, radius, padding, gap)
+   - Icon (image content, size, container styling)
+   - Status / state (text + color)
+   - Disclosure / actions (icon, size, position)
+   - Hover state (compare in both the Figma "Hover" variant AND Storybook hover)
+6. **Diff and fix** — if the Storybook render does not match the Figma, fix the production code (or fixture, if the data was wrong) and re-screenshot. Do not `--update` the baseline until the Figma match is confirmed by a human-readable visual side-by-side.
+7. **Only then `--update`** — `yarn vitest run --project=storybook <path> --update` records the now-correct baseline. After the rewrite, run **without** `--update` once to confirm the new baseline is stable.
+
+## Why baselines are NOT enough
+
+A baseline is a pixel diff against an existing image. If the existing image is wrong, the baseline silently approves future wrongness.
+
+The failure mode this guards against: an agent implements UI with wrong border, wrong icon, wrong font, and wrong background; captures a `--update` baseline; vis-tests go green. The next round tightens tokens but keeps the wrong icon; `--update` again; still green. An operator later opens the story and it looks nothing like Figma. The "green" vis-tests had been comparing to a wrong baseline for two rounds.
+
+The fix is not "more `--update` discipline". The fix is a **mandatory dev-time visual compare with Figma** before any `--update`.
+
+## Forbidden
+
+- Running `yarn vitest -u` against a story that has not been visually compared with Figma in the current session.
+- "Vis-tests are green" used as evidence the UI matches Figma.
+- Comparing only via a single Figma screenshot and then trusting memory for the rest of the change.
+- Using a Figma screenshot of a **different node** as the reference (e.g. the outer modal instead of the card component, the empty state instead of the loaded state, the desktop variant instead of the mobile variant).
+- Skipping the dev-time compare and relying on the operator to spot drift after the fact.
+
+## Required when
+
+Mandatory for any change under `app/src/ui/**` that affects:
+
+- Layout, padding, gap, alignment
+- Typography (font, size, weight, color)
+- Color, background, border, radius, shadow
+- Icon / image / illustration
+- Hover / open / focused / error / empty / loading visual states
+- Storybook vis-baseline first capture (`--update`) or any intentional change to baselines
+
+## MCP wiring
+
+- `chrome-devtools_*` (in the session MCP catalog) is the preferred browser navigation / screenshot tool for the dev-time compare. If it is `error` / `needsAuth` / `loading`, **stop** and report the block, do not approximate.
+- `playwright` MCP can be used as a substitute **only if** `chrome-devtools` is unavailable — but `chrome-devtools` is preferred because it gives a real DOM + screenshot of the running app.
+- A `localhost:6006` reached via a browser MCP is the right way; a screenshot of the production Next.js route is **not** an acceptable substitute (per `mcp-required-for-ui-layout.md`).
+
+## Reference
+
+- `storybook-ui-quality-gate.md` — this rule makes its "compare with mockup" step mandatory and dev-time, not at-the-end.
+- `storybook-keep-tests-current.md` — the post-change half (play + baseline refresh); this rule is the pre-`--update` half.
+- `mcp-required-for-ui-layout.md` — Figma + Storybook MCP gate.

package/presets/mavis/next/ai-local/rules-library/storybook-keep-tests-current.md

@@ -0,0 +1,75 @@
+globs: storybook/**/*.stories.tsx, storybook/**/*.fixtures.ts, storybook/**/*.fixtures.data.ts, storybook/**/*.stories.meta.ts, storybook/stories/**/README.md, app/src/ui/**/*.tsx, app/src/ui/**/*.ts
+
+## Body
+
+# Storybook keep tests current
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-keep-tests-current(, …)*`.
+
+## When (mandatory)
+
+Storybook tests and vis baselines are **part of the change**. Do not finish with red or stale snapshots.
+
+Triggers:
+
+1. Add or edit a story, fixture, `*.stories.meta.ts`, or page Storybook README.
+2. Change production UI a story imports (`app/src/ui/**`) — layout, styles, copy, `data-testid`, states. New/refactored UI must already have stories via **`storybook-ui-quality-gate`** (preview vs mockup); this rule is the test/baseline half.
+3. Change mocks / domain / store fields that stories preload — grep `storybook/stories` and apply this gate.
+
+Leaving play broken or skipping `--update` after an intentional visual change is incomplete work.
+
+## Find related stories
+
+Grep `storybook/stories` for the component name and its import. Cover **all** hits: page, `Components/<Block>`, cards, modals — not only the file you opened. Check the page `README.md` state map.
+
+## Keep working
+
+- **Play:** selectors, copy, `data-testid`s, settle/portal helpers must match the new UI.
+- **Fixtures / MSW / preloadedState:** match domain after mapper or store changes.
+- New production visual state → new story export (catalog structure). Removed UI → delete or retarget the story.
+- Page `README.md`: state → export → fixture id.
+
+**Forbidden:** commenting out `play`; dropping `test` / `snapshot` tags to silence failures; ignoring vis drift.
+
+## Computed copy & browser fixtures
+
+When play asserts **visible copy** that production derives from `document.referrer`, sessionStorage, in-app signals, or i18n: stub those inputs in a **decorator** (sync before mount). Play is too late.
+
+- Do not treat a hard-coded label as a stable selector when the same `data-testid` can show two production strings. Assert the variant's **inputs** first, then the copy.
+- After adding/changing a story that depends on browser document state, grep production for `document.referrer` / session keys used at render.
+
+## Play queries & timeouts
+
+- Static shells (no fetch): prefer `getByTestId` / `getByRole` so a missing node fails immediately, not `Test timed out in 30000ms`.
+- `findBy*` / `waitFor` only when UI is actually async (MSW, loader). Cap timeout (e.g. 3–5s). Never wait for a testid that production does not mount without mocks.
+- Vitest `testTimeout` includes the vis auto-snapshot `afterEach`. A 30s timeout on a story with a tiny `play` is often vis (icon masks, large SVG, full header/footer), not a missing node. Isolated green + full-suite 30s timeout → cap the wait, do not raise `testTimeout`.
+- Any `new Image()` / mask-URL wait **must** have a 3–5s cap. Unbounded `Image()` → full-suite hang while isolated still passes.
+- **Vis loading race:** a `userEvent.click` that dispatches an unmocked thunk (download, fetch) → vis captures spinner **or** idle. Pin the frame: preload the store slice (`loadingStatus: 'loading'`) or MSW `delay('infinite')`. **Forbidden:** click-then-snapshot an in-flight request.
+
+## Run (from `storybook/`)
+
+Targeted path only — do not `--update` the whole catalog.
+
+```bash
+yarn vitest run --project=storybook <path>
+```
+
+Play / fixture failures: **fix CSF**, then re-run. Do not `--update` to hide a broken `play`.
+
+After an **intentional** visual change, refresh baselines (`--update` **after** the path):
+
+```bash
+yarn vitest run --project=storybook <path> --update
+yarn vitest run --project=storybook <path> -t '<Story name>' --update
+```
+
+`--update` on a **file path** rewrites **every** export in that file. A spinner/animation-freeze story can recapture siblings not yet painted. Use `-t '<Story name>'` for one snapshot. Review each rewritten PNG; do not blind-accept.
+
+Re-run **without** `--update` until exit 0. After a vis/timeout flake: re-run the **originally failing files together** (isolated green ≠ full-suite green).
+
+## Baselines
+
+- Local: `storybook/__vis__/local` (gitignored) — still refresh so the next local run is green.
+- CI: `storybook/__vis__/<platform>/__baselines__` — add when those files exist in git.
+- Done only when targeted vitest is green **without** `--update`.
+- Done only after **`storybook-cleanup-temp-screenshots`**: no leftover dump PNGs from this turn.

package/presets/mavis/next/ai-local/rules-library/storybook-modals.md

@@ -0,0 +1,64 @@
+globs: storybook/stories/modals/**
+
+## Body
+
+# Storybook modals catalog
+
+When editing modal stories, acknowledge: `Using .ai.local: storybook-modals(, …)*`.
+
+## Scope
+
+- Isolated modal components only — no page underlay.
+- No "card wrapper" stories when `UI/Modals/...` already covers the trigger (see the modals README reuse table).
+- A component-catalog open-by-default `ConfirmModal` is a component-catalog exception — **do not copy** that pattern here.
+
+## Title & path
+
+- Title: `UI/Modals/<Domain>/<ModalName>` matching `storybook/stories/modals/<Domain>/`.
+- Never place modal titles under `UI/Pages/` or `UI/Components/`.
+
+## Closed by default
+
+First paint shows a labeled trigger (`BasicButton`), not an open dialog.
+
+- Trigger: a stable `data-testid` (e.g. `modal-story__open-trigger`).
+- **Forbidden:** always-open default export; snapshot variants that skip the closed state unless separately named + justified in README.
+
+## Render helpers
+
+From the shared modal decorators module:
+
+- `createReduxModalStoryRender` — dispatch prod open actions from a closed `preloadedState`.
+- `createLocalModalStoryRender` — `useState(isOpen)` harness.
+- A `ModalStoryShell` wrapper; pass `isMounted` when prod conditionally mounts the modal.
+
+## Play sequence
+
+1. `expectNoModalDialog`
+2. `clickModalStoryTrigger`
+3. `expectVisibleTextInModal` / `expectVisibleTestIdInModal`
+4. Close via prod affordances (overlay, cancel/confirm) — no story-only close button.
+
+Portals: assert `within(canvasElement.ownerDocument.body)`.
+
+## Visual
+
+Vis addon snapshots **after** play (opened dialog + trigger). Document per-modal exceptions (e.g. a modal that closes after confirm).
+
+- After open + copy assertions: call the visual-settle helper when the dialog has masked icons. Isolated green + full-suite `Test timed out in 30000ms` → vis afterEach / unbounded icon wait, not a missing node.
+- Do not add `new Image()` / mask waits without a 3–5s cap.
+- Do not raise story `testTimeout` to hide a CDN hang.
+
+After add/edit/UI refactor: **`storybook-ui-quality-gate`** (preview vs mockup) then **`storybook-keep-tests-current`** — play + `--update` + re-run green.
+
+## MSW / store / query-open
+
+- Fetch-on-mount: shared MSW helper + store provider (same as pages).
+- Postpayment / query-open modals: shell-controlled `isOpen` + `withStorybookSearchParams` when prod uses query params.
+
+## Forbidden
+
+- Always-open default export.
+- Duplicate card modals under `modals/` when listed in the modals README reuse table.
+- Viewport-duplicate modal stories (`Mobile*`, `defaultViewport: 'mobile*'`).
+- New `*.pN.stories.tsx` overflow files — one CSF per modal `title`.

package/presets/mavis/next/ai-local/rules-library/storybook-no-app-node-modules.md

@@ -0,0 +1,40 @@
+glob: always
+
+## Body
+
+# Storybook must not resolve packages from app/node_modules
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-no-app-node-modules`.
+
+## Rule
+
+When Storybook lives in its own package (`storybook/package.json`, `storybook/yarn.lock`, `storybook/node_modules`), it **must not** load npm dependencies from the app's `node_modules`.
+
+Categorical. Missing a design-system package, "versions match `app/`", ESLint plugin lookup, a Vite alias, or a Docker `COPY` of `app/node_modules` do not waive it. Do not cite an existing violation as a pattern to copy.
+
+## Forbidden
+
+Any mechanism that makes Storybook (dev, build, test, lint, typecheck, Docker) import an installed package from `app/node_modules`:
+
+- Vite/webpack `resolve.alias`, `resolve.modules`, `optimizeDeps`, `dedupe`, or a plugin `resolveId` aimed at `app/node_modules` / `../app/node_modules`.
+- `paths` in any `storybook/**/tsconfig*.json` that point at `../app/node_modules/**`.
+- `NODE_PATH`, yarn/npm/pnpm link, workspace hoisting, or a symlink from `storybook/node_modules` into `app/node_modules`.
+- Docker `COPY`, volume, or bind-mount of `app/node_modules` into a Storybook stage or image.
+- ESLint, Stylelint, Vitest, or another Storybook tool resolving plugins or packages from `app/node_modules`.
+
+## Allowed
+
+Application **source and static files**, not installed packages:
+
+- `@/` → `app/src/**`
+- `app/next.config.ts`, `app/environment.d.ts`, `app/public/**`, `app/src/assets/**`
+
+`server.fs.allow` may include `app/` so Vite can read that source. It must not be used to import from `app/node_modules`.
+
+## If a package is missing
+
+Add it to `storybook/package.json`, install it into `storybook/node_modules`, and align the version with `app/package.json`. Do not alias it into `app/node_modules`.
+
+## Known violations — do not extend
+
+Existing aliases, `paths`, and Docker `COPY` sites that resolve through `app/node_modules` today are violations, not a pattern. A change that edits one of those sites removes that `app/node_modules` binding in the same change.

package/presets/mavis/next/ai-local/rules-library/storybook-ui-quality-gate.md

@@ -0,0 +1,38 @@
+glob: always
+
+## Body
+
+# Storybook UI quality gate
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-ui-quality-gate(, …)*`.
+
+Storybook is the **mandatory** surface for developing and refactoring UI. Use it to compare the canvas with the mockup and to control visual/interaction quality. A Next.js route screenshot, source-only review, or unit tests without stories is **not** enough.
+
+## When (mandatory)
+
+Triggers:
+
+1. New page, block, modal, or reusable component (`app/src/ui/**`).
+2. Visual or interaction refactor — layout, styles, tokens, copy, hover/open, empty/error/loading.
+3. Existing UI that already has stories (then also **`storybook-keep-tests-current`**).
+
+**Skip:** types / API / store / mocks with **no** render or style change.
+
+## Loop (do not skip steps)
+
+1. **Before UI code:** read the Storybook story instructions (Storybook MCP) if available. Copy the nearest analog CSF. If the brief has a `figma.com` URL, keep that node as the visual SoT.
+2. **Stories with the UI — not after.** Cover **every implemented visual state** (see `storybook-catalog-structure`). New state without an export is incomplete work.
+3. **Compare with mockup:** preview the stories and open **every** returned URL. Side-by-side story canvas vs Figma (or vs AC / `ux-design.md` when there is no Figma). Check spacing, tokens, typography, empty/error/loading, hover/open. Use the viewport **toolbar** — no `Mobile*` duplicate stories.
+4. **Quality:** run the story tests, then **`storybook-keep-tests-current`** (play + vis green without `--update`). Then **`storybook-cleanup-temp-screenshots`**.
+
+Mismatch with the mockup → fix **production** (or the fixture if data was wrong), then preview again. Do not "accept" drift.
+
+MCP down: `yarn storybook` + folder README analog; still visually review the canvas and run vitest from `storybook/`.
+
+## Forbidden
+
+- Shipping UI without stories for new/changed visual states.
+- "Looks fine on the Next.js page" without Storybook preview.
+- Skipping preview / story tests when MCP is up.
+- Treating Storybook as post-hoc docs after the feature is "done".
+- Closing the task while canvas ≠ mockup for a state that was in scope.

package/presets/mavis/next/ai-local/rules-library/task-levels.md

@@ -0,0 +1,28 @@
+glob: always
+
+## Body
+
+# Task artifact levels (L0–L3)
+
+When sizing a task before starting, acknowledge: `Using .ai.local: task-levels(, …)*`.
+
+Every non-trivial task must live as a file artifact, never only in chat. Pick one level by size and impact; when unsure, pick the higher level.
+
+## Levels
+
+| Level | When | Where | Required files |
+|---|---|---|---|
+| **L0 — note** | 1 file, < 30 min, no plan needed | chat todos + `git diff` | none |
+| **L1 — team task** | 2–10 files, one feature/fix with discrete steps | `.ai.local/team/tasks/<slug>/` | `pipeline.json` + `status.json` + `brief.md` + `decomposition.md` + `.memlog.md` (+ per-agent artifacts) |
+| **L2 — change spec** | architecture / boundary change, compliance boundary touched, > 10 files, or multi-role review | `openspec/changes/<YYYY-MM-DD>-<slug>/` | `proposal.md` + `design.md` + `tasks.md` |
+| **L3 — hybrid** | formal change that also needs an execution pipeline | L2 (contract) + L1 (execution), cross-referenced | all of L2 + L1 |
+
+## Selection order (apply in order)
+
+1. Touches PD / medical data / analytics / third-party scripts / SSR-cookie shape → **L2 minimum** (with a compliance block).
+2. Changes the data flow or a module boundary → **L2**.
+3. > 10 files or > 1 subsystem → **L2**.
+4. Otherwise multi-step (planning + implementation + verification) → **L1**.
+5. Otherwise → **L0**.
+
+Never demote a task to keep the artifact small.

package/presets/mavis/next/ai-local/rules-library/ui-change-review-gate.md

@@ -0,0 +1,14 @@
+globs: app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# UI change review gate
+
+Before a UI change is considered complete, acknowledge: `Using .ai.local: ui-change-review-gate(, …)*`.
+
+## Required before completion
+
+1. **Mockup review artifact.** If the task scope contains `app/src/ui/**`, a terminal `mockup-review.md` with verdict `PASS`/`PASS_WITH_NOTES` exists — even when no `figma.com` URL was supplied (then review against AC / `ux-design.md`). Missing artifact = incomplete work, not a warning.
+2. **Composed frame.** For a page or block, the review node set includes the **composed page frame**, not only isolated component sets. A node id claimed by another task must be declared in `## Scope`.
+3. **Same-day rewrite.** Do not rewrite a block shipped the same day without a new review artifact and an owner (single-writer rule).
+4. **Storybook tests run.** Targeted storybook tests green without `--update`.

package/presets/mavis/next/hooks/chain-team-phases.sh

@@ -119,7 +119,21 @@ function mutateMetrics(mutator) {
     try { metrics = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8')); } catch {
       const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
       status.metricsRunId = runId;
-      metrics = { schemaVersion: 1, task: { runId, slug, preset: 'ai-rules', stack: STACK, platform: PLATFORM, intent: status.intent || 'unknown', profile: 'unknown' }, events: [] };
+      // Resolve profile from pipeline.json (preferred) or status.json, falling back to 'unknown'.
+      // The router/agent must never write profile into status.json — pipeline.json is the SoT.
+      let profile = 'unknown';
+      try {
+        if (fs.existsSync(pipelinePath)) {
+          const pipe = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
+          if (pipe && (pipe.profile === 'light' || pipe.profile === 'standard' || pipe.profile === 'full')) {
+            profile = pipe.profile;
+          }
+        }
+      } catch {}
+      if (profile === 'unknown' && (status.profile === 'light' || status.profile === 'standard' || status.profile === 'full')) {
+        profile = status.profile;
+      }
+      metrics = { schemaVersion: 1, task: { runId, slug, preset: 'ai-rules', stack: STACK, platform: PLATFORM, intent: status.intent || 'unknown', profile }, events: [] };
       metrics.events.push({ eventId: `${runId}:task_started`, type: 'task_started', at: now, source: 'hook', attributionConfidence: 'high' });
     }
     mutator(metrics);
@@ -205,9 +219,33 @@ function readBoundReceiptOutcome(agent, step, resolved) {
   if (!fs.existsSync(manifestPath)) return { outcome: null, receiptRequired: false };
   try {
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    // Guard: the schema key is `artifacts` (see agent-artifact-contracts.md). A top-level
+    // `entries` key is a silent bug — producer wrote to a wrong field, hook would not
+    // see the receipt, and the step hangs in `awaiting_artifact_receipt`. Warn loudly.
+    if (manifest && typeof manifest === 'object' && !Array.isArray(manifest.artifacts) && Array.isArray(manifest.entries)) {
+      process.stderr.write(`WARNING: ${manifestPath} has top-level "entries" but no "artifacts" array; reading only "artifacts" per schema. The producer likely upserted into the wrong key. See agent-artifact-contracts.md (Schema field name).` + '\n');
+    } else if (manifest && typeof manifest === 'object' && Array.isArray(manifest.entries) && Array.isArray(manifest.artifacts)) {
+      process.stderr.write(`WARNING: ${manifestPath} has both "artifacts" and "entries" keys; reading only "artifacts" per schema. Foreign "entries" content is ignored.` + '\n');
+    }
     const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
     const expectedOutputId = artifactOutputIdFor(step, agent);
     const attemptStartedAt = Date.parse(resolved.entry.startedAt);
+    // Pre-scan: warn on the silent-bug classes the filter below would otherwise drop.
+    // A receipt with a non-matching attemptId is dropped silently; without this warning,
+    // the step hangs in `awaiting_artifact_receipt` with no signal of why. Same for
+    // receipts whose terminal timestamp is older than the active attempt (stale retry).
+    const activeIds = new Set(Object.keys(status.activeAttempts || {}));
+    for (const entry of artifacts) {
+      if (!entry || entry.producer !== agent || !entry.receipt || typeof entry.receipt.outcome !== 'string') continue;
+      const rid = entry.receipt.attemptId;
+      if (typeof rid === 'string' && rid !== resolved.attemptId && !activeIds.has(rid)) {
+        process.stderr.write(`WARNING: ${manifestPath} receipt for producer "${agent}" id "${entry.id}" carries attemptId "${rid}" that does not match the active attempt "${resolved.attemptId}". The receipt is being dropped; step will hang in \`awaiting_artifact_receipt\` unless the producer retries. Common cause: agent reused an attemptId from a prior failed attempt. See agent-artifact-contracts.md (Receipt binding).` + '\n');
+      }
+      const terminalAt = Date.parse(entry.timestamps?.completedAt || entry.timestamps?.updatedAt || '');
+      if (Number.isFinite(attemptStartedAt) && Number.isFinite(terminalAt) && terminalAt < attemptStartedAt) {
+        process.stderr.write(`WARNING: ${manifestPath} receipt for producer "${agent}" id "${entry.id}" has timestamps.completedAt older than the active attempt's startedAt. Likely a stale receipt from a previous attempt; it is being dropped. See agent-artifact-contracts.md (Receipt binding).` + '\n');
+      }
+    }
     const owned = artifacts
       .filter((entry) => {
         if (!entry || entry.producer !== agent || !entry.receipt || typeof entry.receipt.outcome !== 'string') return false;
@@ -222,6 +260,13 @@ function readBoundReceiptOutcome(agent, step, resolved) {
         const tb = Date.parse(b.timestamps?.completedAt || b.timestamps?.updatedAt || 0) || 0;
         return tb - ta;
       });
+    // Bonus: warn if the active attempt's receipts all lack attemptId in a non-parallel step.
+    // The orchestrator always provides attemptId, so a missing one means the agent dropped it
+    // (model output, JSON.stringify omission, etc.). boundByOutput still binds the receipt by
+    // expectedOutputId, so this is not fatal — but it is a contract violation worth flagging.
+    if (owned.length > 0 && owned[0].receipt.attemptId == null && !(step && step.parallel && Array.isArray(getStepAgents(step)) && getStepAgents(step).length > 1)) {
+      process.stderr.write(`WARNING: ${manifestPath} receipt for producer "${agent}" id "${owned[0].id}" lacks entry.receipt.attemptId on a non-parallel step. The receipt is bound by output-id fallback; the agent should always include the attemptId the orchestrator provides. See agent-artifact-contracts.md (Receipt binding).` + '\n');
+    }
     return { outcome: owned[0]?.receipt?.outcome || null, receiptRequired: true };
   } catch {
     return { outcome: null, receiptRequired: false };

package/presets/mavis/next/rules/agent-team-orchestrator.md

@@ -109,7 +109,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Th
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest points to authoritative paths and records producer, status, timestamps, outcome, and evidence paths.
-- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite unrelated state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 
@@ -145,6 +145,8 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Th
 | `awaiting_approval` | Human gate; wait for `/task-continue` |
 | `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
 | `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+| `blocked` | Pipeline / step cannot proceed (e.g. `pipeline_parse_error`, completion of a parallel step whose producer's receipt was missing — see `agent-artifact-contracts.md` § Completion receipts) |
+| `awaiting_artifact_receipt` | Producer stopped but the bound or assigned-output receipt was missing or stale; hook keeps the attempt active and does not advance. See `agent-artifact-contracts.md` (Schema field name + Receipt binding) for the silent-bug class that lands here. |
 
 On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt (`completed` \| `changes_requested` \| `validation_failed`) when agents left lifecycle fields untouched. Parent orchestrators must wait for that handoff before invoking the next step.
 

package/presets/mavis/next/rules/ai-local-overlay.md

@@ -7,8 +7,9 @@ This rule is mandatory. **You MUST** obey it on every turn, without exception.
 1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
 2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
 3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. Do **not** load `.ai.local/team/**` as rules (shared pipeline artifacts). The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
-4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
-5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+4. **Activate seeds** — if `.ai.local/rules-library/<seed>.md` exists and matches the current task scope, treat it as the applicable local rule and tell the owner to move it into `.ai.local/rules/`. Seeds are **staged-inactive** templates shipped by `init` (e.g. `router-pages`, `no-react-fc`, `storybook-ui-quality-gate`, `component-child-decomposition`); they do **not** apply until moved.
+5. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+6. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
 
 If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
 
@@ -24,6 +25,18 @@ Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses
 
 Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
 
+## What `init` overwrites vs preserves
+
+`init` manages the tool trees; they are **not** the home of durable project config.
+
+| Overwritten / merged by `init` | Preserved |
+|---|---|
+| `.cursor/**`, `.claude/**`, `.mavis/**`, `.opencode/**` (rules, agents, skills, commands, hooks) | `.ai.local/**` |
+| root `AGENTS.md` (from `REPO_AGENTS.md`) | `docs/specs/**`, `openspec/**` |
+| tool MCP config (`.cursor/mcp.json`; `opencode.json` — `mcp` merged, other blocks may be rewritten) | repo-root `.mcp.json`, `.ai/context/**`, `.ai.local/rules/**` |
+
+Put durable project-owned agent config and authoritative specs **outside** the tool trees (`.ai.local/`, `.ai/context/`, repo-root `.mcp.json`). After any re-init, verify consumer-owned blocks you added to a managed file (e.g. `opencode.json` `instructions` / `permission.bash`) survived.
+
 ## Limitations (read this)
 
 - Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
@@ -34,4 +47,5 @@ Keep files ≤ 120 lines. Match the style of preset rules (short sections, bulle
 
 - Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
 - Living gotchas: `.ai.local/conventions.md`. Pipeline artifacts: `.ai.local/team/` (do not load as rules).
+- Staged seeds: `.ai.local/rules-library/**` (move a matching seed into `.ai.local/rules/` to activate).
 - Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/mavis/next/rules/code-quality-and-refactoring.md

@@ -48,6 +48,6 @@ Style enforcement (formatter / linter / post-change gate) lives in the **stack t
 ## Stack notes
 
 - Before adding a new UI control, check existing UI code and project packages.
-- Public API: index/barrel files and explicitly exported entities (`public-imports.mdc`, `layer-barrel-exports.mdc`).
+- Public API: index/barrel files and explicitly exported entities (`public-imports.md`, `layer-barrel-exports.md`).
 - Allowed examples: shared hook/utility; typing `any`/`unknown`; splitting a large component; CSS tokens instead of “magic” values.
-- Lint/stylelint — only **`post-change-lint.mdc`**; ESLint config: `app/eslint.config.mjs`. Disabling a rule (`eslint-disable`) — only **locally** (line/small block) with a short “why” comment. Style prose in domain rules stays thin — prefer ESLint/Stylelint over duplicating formatter recipes.
+- Lint/stylelint — only **`post-change-lint.md`**; ESLint config: `app/eslint.config.mjs`. Disabling a rule (`eslint-disable`) — only **locally** (line/small block) with a short “why” comment. Style prose in domain rules stays thin — prefer ESLint/Stylelint over duplicating formatter recipes.

package/presets/mavis/next/rules/code-review-mr.md

@@ -45,19 +45,23 @@ On-demand rule for review flows. **Procedure and output format:** skill `code-re
 
 ### Checklist references
 
-- Architecture layers: `architecture-boundaries.mdc`, `next-app-core.mdc`; network: `http-client.mdc`
-- Imports: `public-imports.mdc`, `layer-barrel-exports.mdc`
-- UI: `react-ui.mdc`
-- Security: `security-next.mdc`
-- Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
-- Lint gate before final report: `post-change-lint.mdc`
+- Architecture layers: `architecture-boundaries.md`, `next-app-core.md`; network: `http-client.md`
+- Imports: `public-imports.md`, `layer-barrel-exports.md`
+- UI: `react-ui.md`
+- Security: `security-next.md`
+- Tests: `tests-unit.md`, `playwright-agents.md`, `tests-e2e-structure.md`
+- Lint gate before final report: `post-change-lint.md`
 
 ### UI / Figma parity (web)
 
 When the diff touches UI / layout / styling (paths under `app/src/ui/**`, global layout/CSS/tokens) AND a Figma mockup is referenced in `brief.md` / `decomposition.md` (URL, fileKey, or node id) **or** `mockup-review.md` is present:
 
 - The `code-reviewer` agent must perform a **detailed, pixel-accurate** comparison of the implementation against the mockup, **across every viewport the project uses** (the `mockup-review` AC-8 / Stack notes set — web buckets ~375 / ~768 / ~1280 small/medium/large — and the Storybook viewport toolbar in this repo). Figma frames via Figma MCP `get_screenshot`; the running app via Playwright MCP / Chrome DevTools MCP at the matching width.
-- The comparison is a **per-element parity check** (typography / color / spacing / imagery / states / structure / auto-layout intent) per the `code-reviewer` UI / Figma parity gate. Bind to the `mockup-review.md` `## Design contract` and the **`design-tokens-binding.mdc`** discipline (`@sds/tokens-*` / DS components, no raw `#…` / `px` where a token exists).
+- The comparison is a **per-element parity check** (typography / color / spacing / imagery / states / structure / auto-layout intent) per the `code-reviewer` UI / Figma parity gate. Bind to the `mockup-review.md` `## Design contract` and the **`design-tokens-binding.md`** discipline (`@sds/tokens-*` / DS components, no raw `#…` / `px` where a token exists).
 - Findings: `path:line` + Figma node id + viewport + severity. Emit a `## Figma parity (UI)` section in `review.md`.
 - **Storybook visual baselines are not a substitute.** Approving a UI MR on Storybook baselines alone is not acceptable when a Figma reference exists.
 - Missing or `unable_to_compare` parity section on a UI-touching MR with a Figma reference → `REQUEST_CHANGES`. Unbound raw values where a token exists (typography / color / spacing / imagery) → `blocker` / `important`. The full gate lives in the `code-reviewer` agent prompt; this rule cross-references it.
+
+### Spec / docs sync (behaviour change)
+
+When the diff changes documented `app/src/**` behaviour and the repo carries a spec tree (`docs/specs/**`, `openspec/specs/**`, `docs/qa/**`, or `*.cases.md`), the same changeset must update the linked page / spec / QA case (or record an explicit open-question gap). A missing update on an **AC-named** surface → `REQUEST_CHANGES`; on a non-AC surface → `important`. Do not treat `docs/specs` and `openspec` as substitutes for each other — keep both in sync.