@bonesofspring/ai-rules 0.2.30 → 0.2.32

package/presets/mavis/next/rules/component-catalog-gate.md

@@ -0,0 +1,31 @@
+# Component catalog gate (UI quality)
+
+When the repo ships a **component catalog** (Storybook, Ladle, Chromatic, or a `stories/` tree), it is the required surface for developing and reviewing UI. A route screenshot, a source-only review, or unit tests without stories is **not** enough.
+
+## Scope
+
+- Triggers: a new `app/src/ui/**` component / page / block / modal, or a visual/interaction refactor (layout, styles, tokens, copy, hover/open, empty / error / loading).
+- Skip: types / API / store / mocks with no render or style change.
+
+## Rules
+
+- **Stories ship with the UI**, in the same change — not after.
+- **Compare against the design source** (Figma, else the AC): the catalog is the canvas, the design is the truth. Visual baselines are a **regression detector**, not a design spec — fix the implementation first, then update the baseline.
+- **Package isolation:** when the catalog is its own package (own `package.json` / lockfile / `node_modules`), it resolves dependencies from **its own** `node_modules` — never the app's. Missing package ⇒ add it to the catalog manifest; never alias into the app.
+- **Clean up** temp screenshots you created this turn; keep only intentional baselines and product assets.
+- Keep catalog tests green — do not finish with red or stale baselines.
+
+## Stack notes
+
+- Catalog: Storybook. Developer loop: read Figma → implement → preview the story → screenshot → compare → fix → **update baselines last**.
+- Run the catalog runner from the catalog directory (e.g. its own Vitest project), not the app's unit runner.
+
+## Handoff
+
+- `feature-developer`: a UI work package in a catalog repo is **not done** without a story and a green catalog test run.
+- `code-reviewer`: a UI-touching MR with a catalog present and no story → `REQUEST_CHANGES`.
+
+## Related
+
+- `design-tokens-binding.md` — Figma → repo token binding for the implementation.
+- `mockup-review.md` — the reviewer-side parity gate.

package/presets/mavis/next/rules/design-tokens-binding.md

@@ -22,7 +22,7 @@ The implementation must mirror the Figma mockup token-for-token. Raw design valu
 
 ## Imagery & icons
 
-- **Images:** use the Figma asset source from `get_design_context` / the node’s image fill. Repo: `next/image` (or repo convention) with `src`, `width`, `height` derived from Figma. Do not use a placeholder, do not invent a URL, do not change aspect ratio.
+- **Images:** use the Figma asset source from `get_design_context` / the node’s image fill. Repo: **the project’s image primitive** — check the nearest component in the same layer (often a plain `<img>` or a DS image component; `next/image` only where the config keeps the optimizer enabled). Derive `src`, `width`, `height` from Figma. Do not use a placeholder, do not invent a URL, do not change aspect ratio.
 - **Icons:** use the `@sds/icon` (or project DS) symbol name from the Figma component instance / metadata. Do not invent icon names. The Figma node’s component name (e.g. `Icon / chevron-right`) maps to the DS symbol.
 - `alt` text from the Figma node name when meaningful; otherwise from the design context copy.
 

package/presets/mavis/next/rules/feature-delivery-workflow.md

@@ -52,6 +52,10 @@ Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names
 
 When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
 
+**UI-scope gate (no Figma).** When the scope touches `app/src/ui/**` or the component-catalog root on `feature` / `refactor`, a terminal `mockup-review.md` is required **even without** a `figma.com` URL — reviewed against the AC / `ux-design.md`. Where the repo ships a component catalog, stories ship with the UI and `build-verifier` runs the catalog suite green (`component-catalog-gate`).
+
+**Consumer context.** When `.ai/context/**` exists, read it before deriving architecture, domain vocabulary, or test placement.
+
 ## Style discovery (mandatory)
 
 Before writing a new file in a layer, open **1–2 analog files** in the same layer and mirror: export shape, name prefixes (`T` / `I` where the repo uses them), file suffixes (`.apiMethods.ts`, `.endpoints.ts`, `.data.ts`, `.hooks.ts`, `styles.ts`), mapper / selector / thunk naming, and barrel shape. Record the analogs in the handoff. Where this preset's examples differ from the repo, **the repo wins**.
@@ -60,32 +64,32 @@ Before writing a new file in a layer, open **1–2 analog files** in the same la
 
 When the prompt or `brief.md` contains a Figma URL with a node id (`?node-id=…`), `mockup-reviewer` must walk the node subtree via Figma MCP and emit **two sections** in `mockup-review.md`:
 
-- `## Design contract` — Figma variables, text styles, components/assets used by the subtree, with the repo mapping (`@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens-typography` / `@sds/tokens` / DS components / `next/image` with Figma-derived `src/width/height`). This is the binding table the developer uses for typography, color, spacing, and imagery.
+- `## Design contract` — Figma variables, text styles, components/assets used by the subtree, with the repo mapping (`@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens-typography` / `@sds/tokens` / DS components / the project image primitive with Figma-derived `src/width/height`). This is the binding table the developer uses for typography, color, spacing, and imagery.
 - `## Node decomposition (AC-2)` — the child→component map (with a `Bindings` column for the Figma design bindings).
 
-`feature-developer` must **not** start UI implementation until both sections are present, and must load requestable `design-tokens-binding.mdc` to bind every value to a Figma variable / text style / repo token (raw `#…` / `px` are a finding). The full procedure and verdict rule live in the `mockup-reviewer` agent prompt and the `mockup-review` Stack notes.
+`feature-developer` must **not** start UI implementation until both sections are present, and must load requestable `design-tokens-binding.md` to bind every value to a Figma variable / text style / repo token (raw `#…` / `px` are a finding). The full procedure and verdict rule live in the `mockup-reviewer` agent prompt and the `mockup-review` Stack notes.
 
 ## UI MR — Figma parity gate (mandatory in code review)
 
-When the MR touches UI / layout / styling (`app/src/ui/**`, global layout/CSS/tokens) and a Figma reference exists in `brief.md` / `decomposition.md` or `mockup-review.md` is present, `code-reviewer` must perform a **detailed, pixel-accurate** comparison of the implementation against the mockup across **every project viewport** (mockup-review AC-8 / Stack notes set and the repo’s Storybook viewport toolbar). The comparison is a per-element parity check (typography / color / spacing / imagery / states / structure / auto-layout intent) bound to the `## Design contract` and the `design-tokens-binding.mdc` discipline. Findings go in `## Figma parity (UI)` in `review.md`. **Storybook visual baselines are not a substitute.** Missing or `unable_to_compare` parity on a UI MR with a Figma reference → `REQUEST_CHANGES`. The full gate lives in the `code-reviewer` agent prompt and the `code-review-mr` Stack notes.
+When the MR touches UI / layout / styling (`app/src/ui/**`, global layout/CSS/tokens) and a Figma reference exists in `brief.md` / `decomposition.md` or `mockup-review.md` is present, `code-reviewer` must perform a **detailed, pixel-accurate** comparison of the implementation against the mockup across **every project viewport** (mockup-review AC-8 / Stack notes set and the repo’s Storybook viewport toolbar). The comparison is a per-element parity check (typography / color / spacing / imagery / states / structure / auto-layout intent) bound to the `## Design contract` and the `design-tokens-binding.md` discipline. Findings go in `## Figma parity (UI)` in `review.md`. **Storybook visual baselines are not a substitute.** Missing or `unable_to_compare` parity on a UI MR with a Figma reference → `REQUEST_CHANGES`. The full gate lives in the `code-reviewer` agent prompt and the `code-review-mr` Stack notes.
 
 ## UI self-check vs Figma (mandatory in implementation)
 
 For UI WPs with a Figma reference, `feature-developer` performs a **self-check vs Figma** at each project viewport (Playwright MCP / Chrome DevTools MCP) before the implementation receipt, fixes obvious typography / color / spacing / imagery / state deviations, and records a `## UI self-check vs Figma` block in `implementation.md`. This is the developer-side counterpart to the parity gate and closes the fidelity loop (extract contract → bind → self-check → review-block).
 
-Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `next-app-core.mdc`.
+Typical feature with backend data and shared state. Layer details — `architecture-boundaries.md`, `next-app-core.md`.
 
 ## Checklist (work order)
 
-1. **Domain types** — `app/src/types/**`, export via barrel (`public-imports.mdc`, **`layer-barrel-exports.mdc`**); JSDoc — `types-jsdoc.mdc`.
+1. **Domain types** — `app/src/types/**`, export via barrel (`public-imports.md`, **`layer-barrel-exports.md`**); JSDoc — `types-jsdoc.md`.
 2. **API contract** — DTOs where the repo uses them; domain types in `@/types`.
-3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services.mdc`).
-4. **Services** — clients `app/src/api/clients/**`, barrel `@/api` (`api-services.mdc`, `http-client.mdc`, **`layer-barrel-exports.mdc`**). No `fetch` from UI/store.
-5. **State** — `createSlice` / `createAsyncThunk` (`store-rtk.mdc`); thunk → services from `@/api`.
-6. **UI** — types from `@/types`, no DTOs (`react-ui.mdc`, `architecture-boundaries-ui.mdc`, `no-props-spread.mdc`).
+3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services.md`).
+4. **Services** — clients `app/src/api/clients/**`, barrel `@/api` (`api-services.md`, `http-client.md`, **`layer-barrel-exports.md`**). No `fetch` from UI/store.
+5. **State** — `createSlice` / `createAsyncThunk` (`store-rtk.md`); thunk → services from `@/api`.
+6. **UI** — types from `@/types`, no DTOs (`react-ui.md`, `architecture-boundaries-ui.md`, `no-props-spread.md`).
 7. **Mocks** — per repo layout; register in `app/src/mocks/handlers.ts` (see below).
-8. **Tests** — unit for mappers (`tests-unit.mdc`); e2e from `*.cases.md` (`tests-e2e-structure.mdc`, `playwright-agents.mdc`).
-9. **Completion** — **`post-change-lint.mdc`**: `lint:js` + `lint:css` + `type-check`; package manager — `package-manager.mdc`. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
+8. **Tests** — unit for mappers (`tests-unit.md`); e2e from `*.cases.md` (`tests-e2e-structure.md`, `playwright-agents.md`).
+9. **Completion** — **`post-change-lint.md`**: `lint:js` + `lint:css` + `type-check`; package manager — `package-manager.md`. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
 
 ## Data flow (orientation)
 
@@ -128,7 +132,7 @@ flowchart LR
 - DTO in UI or untyped store.
 - HTTP client from a component/thunk bypassing the service.
 - Deep-import `@/api/services/**` from UI/store.
-- `{...props}` into components — `no-props-spread.mdc`.
+- `{...props}` into components — `no-props-spread.md`.
 - **Ubiquitous language:** Domain/type names reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need.
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
 - Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
@@ -137,12 +141,12 @@ flowchart LR
 
 | Zone | Rules |
 |------|-------|
-| `app/src/api/clients/**`, `app/src/lib/clients/**` | `http-client.mdc`, `tests-unit.mdc` (behavior) |
-| `app/src/api/services/**` | `api-services.mdc`, `layer-barrel-exports.mdc`, `http-client.mdc` |
-| `app/src/store/**` | `store-rtk.mdc`, `architecture-boundaries.mdc`, `public-imports.mdc` |
-| `app/src/ui/**` | `react-ui.mdc`, `no-props-spread.mdc`, `public-imports.mdc` |
-| `app/src/types/**` | `public-imports.mdc`, `types-jsdoc.mdc`, `layer-barrel-exports.mdc` |
-| `app/__tests__/e2e/**` | `tests-e2e-structure.mdc`, `playwright-agents.mdc` |
+| `app/src/api/clients/**`, `app/src/lib/clients/**` | `http-client.md`, `tests-unit.md` (behavior) |
+| `app/src/api/services/**` | `api-services.md`, `layer-barrel-exports.md`, `http-client.md` |
+| `app/src/store/**` | `store-rtk.md`, `architecture-boundaries.md`, `public-imports.md` |
+| `app/src/ui/**` | `react-ui.md`, `no-props-spread.md`, `public-imports.md` |
+| `app/src/types/**` | `public-imports.md`, `types-jsdoc.md`, `layer-barrel-exports.md` |
+| `app/__tests__/e2e/**` | `tests-e2e-structure.md`, `playwright-agents.md` |
 
 When adding or extending a feature, **walk the checklist** and the rules from the table for affected zones.
 

package/presets/mavis/next/rules/forms-validation.md

@@ -0,0 +1,26 @@
+# Forms and validation
+
+Use the form solution already in the repo (`package.json` + the nearest form component). Do not hand-roll form state with `useState` when a form library is present.
+
+## Rules
+
+- One form-hook instance per form; register design-system fields through the library's controller/wrapper (controlled) — not a raw `<input>` when a DS field exists.
+- Validate with the repo's resolver/schema library and reuse the shared validators under the repo's validation utils — never re-implement email / phone / date / length rules inline.
+- Masked inputs (phone, date, card) go through the repo's mask library, not ad-hoc regex on change.
+- Disable submit while `!isValid` / `isSubmitting`; surface field errors from the form library's error state.
+- Keep side effects out of field components: the form owns `onSubmit`; data flows to store/API through the repo's layers (`architecture-boundaries-ui.md`).
+
+## Accessibility
+
+- Every field has a visible label and an associated error message; do not rely on placeholder-only labels.
+- Field errors are announced and tied to the input; keep the DS field's wiring instead of a bespoke error node.
+
+## Stack notes
+
+- Library: `react-hook-form` + `yup` resolver; `mode: 'onTouched'`.
+- DS fields: `app/src/ui/components/_form/**`; shared validators: `app/src/lib/utils/validations/**`; masks: `imask` / `react-imask`.
+
+## Related
+
+- `react-ui.md` — component structure and decomposition.
+- `architecture-boundaries-ui.md` — no API/DTO in UI.

package/presets/mavis/next/rules/mcp-usage.md

@@ -87,6 +87,7 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 
 ## Stack notes
 
+- **Installed Next docs first:** the installed `next` may ship version-pinned agent docs at `node_modules/next/dist/docs/` and a managed `AGENTS.md` block. Prefer them for framework APIs (they match the installed major) — reach for Context7 only when they are insufficient or absent.
 - Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
 - Shipped besides Context7: browser automation MCP (`playwright` / `playwright-test` / `user-playwright`) and `chrome-devtools`.
 - **Split:** Playwright MCP → e2e agents (planner/generator/healer), selector checks, spec reproduction. Chrome DevTools MCP → `debugger` / `performance-auditor` against a **running app** (console, network, traces). Not a substitute for e2e.

package/presets/mavis/next/rules/mockup-review.md

@@ -117,4 +117,4 @@ When the Figma URL contains a node id (`?node-id=…`), `mockup-reviewer` must:
 1. Walk the node subtree via Figma MCP `get_metadata` and emit a **Node→component map** (each child node id/name/type → target `app/src/ui/**` component, attached library component (e.g. `@sds/*`), or `new: <ProposedName>`). The map goes in `mockup-review.md` under `## Node decomposition (AC-2)` as a table plus a short prose summary, with a `Bindings` column / per-row note for the Figma design bindings.
 2. Extract the **Design contract** (above the Node decomposition table): Figma variables used by the subtree (color, spacing, radius, effect — one `get_variable_defs` call per file), text styles used, and components / assets (library instances, image fills via `get_design_context`, icons). Each item mapped to the repo equivalent: `@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens-typography` / `@sds/tokens` / DS component (`@sds/icon` symbol name, `Text variant="…"`) / `next/image` with Figma-derived `src/width/height`.
 
-Both sections are the **pre-implementation contract** the developer reads before coding; the DS/tokens/quality/coverage/viewport dimensions still apply on top. Verdict: missing map **or** missing Design contract on a node-link input → `FAIL` (unless `BLOCKED_MCP`). The developer (`feature-developer`) must not start UI work until both sections are present, and must bind implementation to the Design contract (see `design-tokens-binding.mdc`).
+Both sections are the **pre-implementation contract** the developer reads before coding; the DS/tokens/quality/coverage/viewport dimensions still apply on top. Verdict: missing map **or** missing Design contract on a node-link input → `FAIL` (unless `BLOCKED_MCP`). The developer (`feature-developer`) must not start UI work until both sections are present, and must bind implementation to the Design contract (see `design-tokens-binding.md`).

package/presets/mavis/next/rules/next-app-core.md

@@ -8,6 +8,9 @@ Concrete versions come **from `package.json` and configs of the target repositor
 - `app/tsconfig.json`: `paths: { "@/*": ["./src/*"] }` (`baseUrl` may be absent with TS ≥5 / `moduleResolution: bundler` — check the file, do not add it blindly).
 - **Requirement:** `@/*` instead of relative imports that climb the tree.
 - **Router mode:** detect from the repo before adding routes — App Router (`app/src/app/**`, `page.tsx`) vs Pages Router (`app/src/pages/**`, `_app.tsx`). Do **not** assume App Router; follow the mode already in use (`next-app-router.md`, `navigation-router-stack.md`).
+- **Deployment model:** read `output` in `next.config.*`. With `output: 'export'` the app is a static SPA — no server runtime, no API routes / middleware / SSR (`next-static-export.md`).
+- **Consumer context:** when `.ai/context/**` exists, read it for the repo's compressed architecture, domain glossary, and test-placement conventions before deriving them yourself.
+- **Env access:** read `NEXT_PUBLIC_*` through the repo's config module (e.g. `@/config`); new public keys must also be listed in `next.config.*` `env`. Never read `process.env` inside components.
 
 # Architectural layers
 

package/presets/mavis/next/rules/next-static-export.md

@@ -0,0 +1,28 @@
+# Static export (Next.js `output: 'export'`)
+
+Detect the deployment model **before** writing data-fetching or routing code: read `output` in `next.config.*`. With `output: 'export'` the build produces a static SPA — there is no server runtime at request time.
+
+## Unavailable
+
+- `getServerSideProps`, `getInitialProps`.
+- API routes (`pages/api/**`, App Router `route.ts`) and `middleware.ts`.
+- Server Actions; server `cookies()` / `headers()`.
+- ISR / `revalidate` / `dynamic = 'force-dynamic'`.
+- The image optimizer when `images.unoptimized: true` (`next/image` `loader` / `sizes` buy nothing).
+
+## Available / preferred
+
+- `getStaticProps` / `getStaticPaths` run at **build** time only.
+- Runtime data comes from the browser: store thunk → `@/api` service (`store-rtk.md`, `api-services.md`).
+- Auth / session are enforced by the BFF plus a client route guard — not by a Next server.
+- `basePath` / `assetPrefix`: build local links and asset URLs from those values; never hardcode `/`.
+
+## Agent requirement
+
+- Copy the data-fetch and navigation pattern from a sibling page under `app/src/pages/**`; do not port SSR/RSC examples from docs or blogs into a static-export repo.
+- If a requested feature implies a server runtime, mark it **N/A — static export** and propose the client/BFF alternative instead of writing server code.
+
+## Related
+
+- `react-next-anti-hallucination.md` — phantom-import banlist for this deployment model.
+- `navigation-router-stack.md` — Pages Router vs App Router.

package/presets/mavis/next/rules/post-change-lint.md

@@ -10,6 +10,10 @@ Exceptions: documentation edits outside `app/`, CI configs, `.mavis/rules/**`, i
 
 **Pipeline exception:** if the task runs through the agent team and the next step is `build-verifier`, the developer may limit lint/type-check to **changed files**; full run is **`build-verifier`’s** responsibility. In single-agent mode (no pipeline) — always a full run.
 
+**Secondary packages:** when the repo has more than one package with a manifest (e.g. `app/` + `storybook/`), run each package's own scripts from its own directory. Do not conflate runners (app unit runner vs catalog runner).
+
+**Run the package script, not a bare runner:** prefer `yarn lint:js` / `yarn test` over `npx eslint` / `npx jest`. Scripts carry env (`TZ`), coverage, and reporters that CI depends on; a bare runner can diverge from CI.
+
 ## Required commands
 
 Working directory — **`app/`**. Package manager — **`package-manager.md`**.

package/presets/mavis/next/rules/product-specs-authoring.md

@@ -114,5 +114,6 @@ Block handoff via `open_questions` until fixed:
 ## Stack notes
 
 - Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- **Glossary & contrast (mandatory):** before authoring, read the repo glossary (`openspec/config.yaml` `context:`, `.ai/context/**`, domain README). Each generated spec maps product terms to code symbols + record types and adds one **contrast** requirement/scenario against the nearest confusable symbol. Declare **compliance impact** (None | Affected) for any spec touching medical/personal data or analytics.
 - Field semantics match discovery stem (`routes` = URL paths; `e2e` = Playwright).
 - Requestable — not always-on / session-start.

package/presets/mavis/next/rules/product-specs.md

@@ -58,5 +58,6 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 ## Stack notes
 
 - `routes`: app URL paths. `ui` / `store`: presentation + RTK/store paths (e.g. `app/src/ui/pages/...`). `e2e`: Playwright paths under `app/__tests__/e2e/**` (or repo equivalent).
+- **Domain glossary & contrast:** read the repo glossary first (e.g. `openspec/config.yaml` `context:`). Every spec that names a domain states a **term → code symbol + record type** mapping and includes one **contrast** scenario naming the nearest confusable symbol/page (e.g. an in-person-consultation spec contrasts `OfflineConsultation*` with `OnlineConsultationPage`). This prevents the highest-frequency domain-confusion bug in these repos.
 - Dogfood example (emedcard-web AnalysisPage): `docs/specs/domains/analysis/analysis-page.md`.
 - Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/mavis/next/rules/react-next-anti-hallucination.md

@@ -4,6 +4,13 @@ These rows **OVERRIDE** generation for the listed patterns. Before inventing an
 
 App Router–specific rows (async `params` / `cookies()`, invented auth helpers, etc.) stay in **`next-app-router.md`**. This rule covers broader React / RTK / Next phantom imports and boundary mistakes across `app/**`.
 
+## 0. Installed Next ships its own docs (read them first)
+
+The installed `next` may bundle version-pinned agent docs and a managed `AGENTS.md` block written by `next dev`:
+
+- Docs: `node_modules/next/dist/docs/` (`01-app`, `02-pages`, `03-architecture`, …). Prefer these over blog posts and over training data for framework APIs — they match the installed major.
+- Managed block: `<!-- BEGIN:nextjs-agent-rules -->` in `AGENTS.md` (see `node_modules/next/dist/server/lib/generate-agent-files.js`). **Do not delete it** — `next dev` re-creates it; commit it with your change to keep the tree clean.
+
 ## 1. Phantom / wrong Next imports
 
 | ❌ Avoid | ✅ Prefer |
@@ -49,6 +56,9 @@ App Router–specific rows (async `params` / `cookies()`, invented auth helpers,
 | `Router.push` / Pages `withRouter` patterns in `app/` UI | App Router navigation helpers already used in `app/src/ui/**` |
 | Client `fetch` / raw HTTP from UI or `page.tsx` bypassing `@/api` | Services via `@/api` / established loaders (`api-services.md`, `http-client.md`) |
 | Invented `next/link` props that siblings never use (e.g. fake prefetch enums) | Match existing `<Link>` usage; verify against installed Next |
+| `getServerSideProps` / `getInitialProps`, `pages/api/**`, `route.ts`, `middleware.ts` in an `output: 'export'` repo | build-time `getStaticProps` / `getStaticPaths` or client store/thunk fetch (`next-static-export.md`) |
+| Hardcoded `/` root for links / assets when the repo uses `basePath` / `assetPrefix` | Derive from `basePath` / `assetPrefix` |
+| `next/image` `loader` / `sizes` / `quality` expecting the optimizer in a repo with `images.unoptimized: true` | The repo's image primitive; no optimizer assumptions |
 
 ## 6. Version drift
 

package/presets/mavis/next/rules/react-ui.md

@@ -17,6 +17,24 @@
 - No nested ternaries in JSX. For not-ready / empty / error, use an early return or a dedicated `EmptyState` / `ErrorState` component.
 - A `variant` / `mode` flag that renders two unrelated layouts is **two** components, not one.
 
+# One component / one styled element — one purpose
+
+- Each component **and** each styled element serves exactly **one** purpose. Do not drive two distinct shapes (different padding, slot set, alignment, visual identity) from a `variant` / `is…` flag or branchy styles.
+- Two call sites that need visibly different markup → two named components (or two named styled exports). Share the base via a small primitive (`BaseCard` styled block + two thin extensions), not a universal branchy `Card`.
+- A flag that flips a single non-layout property (`compact`, `disabled`) is fine; a flag that flips layout, slots, or visual identity is not — split it.
+
+# CSS-in-JS interpolation functions
+
+- Inside `${…}` interpolations of a styled template (`styled.*`), do **not** write an inline arrow (`${({ tone }) => …}` or `${({ gap }) => gap}`). Reference a **module-level function** that takes the styled props: `${getPromoStatusColor}`.
+- Name it `get` + the value (`getColor`, `getGap`, `getPromoStatusColor`); keep the prop type shared between the styled generic and the function parameter.
+- A module-level function is debuggable, type-checkable in isolation, and reusable across sibling styled blocks; an inline arrow compiles to an untestable one-shot.
+
+# Async UI states
+
+- Loading, empty, error, and load-failed are **distinct** states — render each explicitly; do not collapse them into one spinner/blank branch.
+- Prefer a **per-block skeleton** over a page-level spinner, and reuse the repo's existing primitives (`Skeleton`, `EmptyState`, `ErrorState`, load-failed stub, global `ErrorBoundary`) instead of inventing new ones.
+- Error boundaries are usually mounted once at the app root; add a local boundary only when the repo already does so for that region.
+
 ## Incorrect
 
 ```tsx
@@ -90,7 +108,7 @@ For a reusable component:
 - **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
 - CSS / `styled` order — Stylelint idiomatic-order: `css-property-order-stylelint.md` (loads on `styles.ts` / `.css`).
 - For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
-- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, `next/image`). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`design-tokens-binding.md`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
+- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, the project image primitive). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`design-tokens-binding.md`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
 - Avoid:
   - inline styles except simple cases;
   - duplicating styling already covered by shared primitives;

package/presets/mavis/next/rules/reference-features.md

@@ -62,6 +62,11 @@ Replace **TBD** with real paths after team agreement (or on `ai-rules init` in t
 | Types module | **TBD** `app/src/types/<example>/` | domain types, JSDoc, barrel export |
 | Unit tests | **TBD** mirrored under `app/__tests__/unit/<rel>` | `*.spec.ts`, describe/it naming |
 | E2E area | **TBD** `app/__tests__/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+| Scaffold | **TBD** `app/src/boilerplate/**` | new-component skeleton (copy, then rename) |
+| Global singletons | **TBD** `app/src/ui/components/_singletons/**` | app-root-mounted containers (modals, sync, flags) |
+| Layout / guard | **TBD** `app/src/ui/layouts/**`, `app/src/ui/guards/**` | route wrapping (auth, chrome) |
+| Cross-feature hooks | **TBD** `app/src/core/**` | reusable feature hooks used across pages |
+| Internal slices | **TBD** `app/src/store/slices/_complexSlices/**`, `_utilsSlices/**` | cross-slice orchestration / pure helpers — **no** direct slice→slice imports |
 
 ## How to use
 
@@ -76,6 +81,6 @@ Post-init gotchas / patterns / decisions: **`.ai.local/conventions.md`** (shared
 
 ## Related rules
 
-- `code-quality-and-refactoring.mdc` — repeat patterns, no deep-import.
-- `feature-delivery-workflow.mdc` — layer order.
+- `code-quality-and-refactoring.md` — repeat patterns, no deep-import.
+- `feature-delivery-workflow.md` — layer order.
 - skill `feature-delivery` — end-to-end scenario.

package/presets/mavis/next/rules/security-next.md

@@ -2,6 +2,8 @@
 
 Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-review`.
 
+**Deployment model first.** Read `output` in `next.config.*`. With `output: 'export'` there is **no server tier**: the Server Actions / route handlers / middleware items below are **N/A**. The applicable subset is Secrets & env, XSS, redirects, data exposure, and third-party scripts — and auth/session are enforced by the BFF plus a client route guard.
+
 ## Secrets and env
 
 - Never put service / secret keys in `NEXT_PUBLIC_*` or client bundles (`sk_`, private API keys, DB URLs).
@@ -14,6 +16,7 @@ Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-re
 - Middleware may refresh sessions; do not treat middleware alone as authorization.
 - Prefer httpOnly secure cookies over `localStorage` for tokens when the repo pattern allows.
 - Never trust client-only session claims without a server verify step used by the project.
+- **Static-export / SPA repos:** there is no server session verify — use the repo's client route guard plus BFF-issued httpOnly cookies; do not invent a server verifier.
 
 ## Mutations and input
 
@@ -39,6 +42,15 @@ Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-re
 | Invented auth helpers not in `package.json` / codebase | Copy patterns from existing auth routes |
 | Putting secrets in `NEXT_PUBLIC_*` | Server-only env + server modules |
 | Auth only in middleware | Server `getUser` / session verify in layout/page/action |
+| Server session verifier / Server Action in a static-export repo | Client route guard + BFF-issued httpOnly cookie |
+
+## Compliance / personal data (regulated apps)
+
+For apps that ship medical or personal data (e.g. GDPR / local data-protection law):
+
+- Logs, traces, analytics payloads, error reports, and third-party scripts must **not** carry PD, full record text, raw auth tokens, or full URL search params.
+- Flag every new third-party script and every change to the SSR/cookie payload shape for review.
+- Any change touching PD, medical data, analytics, or third-party scripts declares a **compliance impact** block (None | Affected) in its L2+ artifact; when unclear, default to Affected and block.
 
 ## Agent requirement
 

package/presets/mavis/next/rules/store-rtk.md

@@ -43,6 +43,12 @@
   - avoid duplicating entity descriptions in multiple places.
 - **Domain boundary**: in **state**, store domain models; the client **response wrapper** type is acceptable as a thunk **return type** or interim before mapping — without duplicating DTOs in state fields unnecessarily (aligned with `api-services.md` and `http-client.md`).
 
+# Middleware and cross-slice orchestration
+
+- Cross-cutting side effects (analytics, captcha, file lifecycle, cross-slice sync) live in **listener middleware** at `app/src/store/middleware/<Domain>Middleware/`, registered in the store factory — follow the repo's `prepend`/`concat` order.
+- A slice **must not import another slice**. When two domains must react to each other, orchestrate in middleware or a dedicated `_complexSlices/<Domain>` module (`_utilsSlices` for pure helpers) — never a direct slice→slice import.
+- Prefer a thunk for a single request/response; prefer middleware for reactions that span slices or emit analytics.
+
 # Slice testing
 
 - For important slices:

package/presets/mavis/next/rules/tests-e2e-structure.md

@@ -74,6 +74,7 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 ## Stack notes
 
 - Runner: Playwright (`@playwright/test`).
+- Consolidated QA docs (`docs/qa/**`): when present they are a derived view of the spec + `*.cases.md` (route table, `as-is`/`target` marking, PREFIX map). Cite the source per case and keep them in sync on behaviour change — do not treat them as a second SoT.
 - E2E folder: `app/__tests__/e2e/**`.
 - Placement mirrors source paths: `app/src/<rel>` → `app/__tests__/e2e/<rel>`. Use the deepest folder of the source under test; page-wide scenarios mirror the page folder.
 - Scenario plans: `*.cases.md` files — canonical source of scenarios.
@@ -83,5 +84,5 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 - `data-testid` naming scheme: `{parent}__{element}` — example `history-page__title`, `history-page__recognition-banner__attach-files-button`.
 - `PREFIX-XXX` example: `OrderHistory` → `OH`, `BillingReport` → `BR`; Russian example — `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed).
 - Page object example filename: `OrderHistoryPage.ts` (the seed test pointer lives at `app/__tests__/e2e/seed.spec.ts`).
-- Cross-reference: See also **`playwright-agents.mdc`** for the e2e planner / generator / healer agents.
+- Cross-reference: See also **`playwright-agents.md`** for the e2e planner / generator / healer agents.
 - `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/mavis/next/rules/tests-unit.md

@@ -81,6 +81,7 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 - `app/src/mocks/**` — shared fixtures and MSW handlers live here (or repo equivalent).
 - Unit-test placement mirrors source paths: `app/src/<rel>` → `app/__tests__/unit/<rel>`. Do not colocate `*.spec.ts(x)` or `*.test.ts(x)` under `app/src/**`.
 - HTTP-client behavior tests live under the mirrored `app/__tests__/unit/lib/clients/**` path (prefer `*.spec.ts`).
+- Prefer the package script over a bare runner (`yarn test`, not `npx jest`): scripts carry env (`TZ`), coverage, and reporters that CI depends on.
 - UI tests live under the mirrored `app/__tests__/unit/ui/**` path. Import the source under test through the `@/` alias.
 - `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.
 

package/presets/mavis/next/team/fixtures/feature-with-ux-no-figma.json

@@ -2,16 +2,15 @@
   "slug": "example-feature-with-ux-no-figma",
   "intent": "feature",
   "profile": "standard",
-  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "summary": "UI-scope feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; UI scope forces mockup-reviewer (reviewed against AC / ux-design.md)",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "mockup-reviewer", "label": "UI review vs AC / ux-design" },
     { "agent": "feature-developer", "label": "Implement" },
     { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
     { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
   ],
   "humanGates": ["after:task-analyst"],
   "autoChain": true,
-  "skipped": [
-    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
-  ]
+  "skipped": []
 }

package/presets/mavis/nuxt/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "nuxt",
   "semanticSource": "cursor/nuxt",
-  "sourceRevision": "f7f0e3abbcd5d9c3a51bc16d2c1e1ed8d6cae98351f48f74fc9984e1e374675d",
+  "sourceRevision": "db4f3a8b5bfad0c5c168cd116ac20e482be3ad18886e250dcc74c59061363706",
   "entries": [
     {
       "source": "AGENTS.md",

package/presets/mavis/nuxt/agents/accessibility-reviewer.md

@@ -68,8 +68,8 @@ Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools M
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.
-- **Owned outputs:** `a11y-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `a11y-review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.
+- **Owned outputs:** `a11y-review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `a11y-review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/api-contract-reviewer.md

@@ -66,8 +66,8 @@ For feature-developer before or during implementation.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, architecture when present, and changed types/API/mocks against the contract docs.
-- **Owned outputs:** `api-contract-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `api-contract-review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, architecture when present, and changed types/API/mocks against the contract docs.
+- **Owned outputs:** `api-contract-review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `api-contract-review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/build-verifier.md

@@ -111,7 +111,7 @@ Do not fix code — report only. Do not advance to code-reviewer until PASS.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
-- **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation evidence, pipeline scope, and changed files.
+- **Owned outputs:** `validation-report.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/mavis/nuxt/agents/ci-investigator.md

@@ -84,8 +84,8 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition when present, failing check context, and prior validation/debug artifacts.
-- **Owned outputs:** `ci-report.md` plus any minimal fix paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `ci`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition when present, failing check context, and prior validation/debug artifacts.
+- **Owned outputs:** `ci-report.md` plus any minimal fix paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `ci`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/code-reviewer.md

@@ -74,7 +74,7 @@ Do not mix this output with retrospective facilitation — keep review and retro
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
-- **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation, validation evidence, and the scoped git diff.
+- **Owned outputs:** `review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/mavis/nuxt/agents/debugger.md

@@ -91,8 +91,8 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition when present, failing evidence, and related prior artifacts.
-- **Owned outputs:** `debug-report.md` plus any minimal fix paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `debug`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition when present, failing evidence, and related prior artifacts.
+- **Owned outputs:** `debug-report.md` plus any minimal fix paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `debug`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/feature-developer.md

@@ -129,7 +129,7 @@ Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools M
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
-- **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
+- **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/mavis/nuxt/agents/migration-specialist.md

@@ -72,8 +72,8 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and stack/version context from the repo.
-- **Owned outputs:** `migration-plan.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `migration-plan`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition and stack/version context from the repo.
+- **Owned outputs:** `migration-plan.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `migration-plan`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/mockup-reviewer.md

@@ -62,8 +62,8 @@ Standalone FAIL must **not** set `changes_requested`. Embedded FAIL is a FAIL-on
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for routing + analysis when present (standalone may have only the prompt + URL).
-- **Owned outputs:** `mockup-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `mockup-review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for routing + analysis when present (standalone may have only the prompt + URL).
+- **Owned outputs:** `mockup-review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `mockup-review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed`, `changes_requested`, or `blocked` per the table above. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/openspec-author.md

@@ -132,8 +132,8 @@ If `scope` carries multiple phases (e.g. `openspec:<change-id>:propose+apply`),
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
-- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.ai.local/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition and available architecture/migration/review artifacts.
+- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.ai.local/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign items in `manifest.artifacts[]`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths under `openspec/changes/<change-id>/**`, attach `openspec validate <change-id> --type change --strict` exit code + deltas-only summary, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/mavis/nuxt/agents/performance-auditor.md

@@ -71,8 +71,8 @@ If Chrome DevTools MCP is ready and the app is running, use it for console/netwo
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief when present and the scoped git diff / routes under audit.
-- **Owned outputs:** `perf-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `perf-report`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief when present and the scoped git diff / routes under audit.
+- **Owned outputs:** `perf-report.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `perf-report`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.