@bonesofspring/ai-rules 0.2.30 → 0.2.32

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

@@ -137,7 +137,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);
@@ -221,9 +235,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;
@@ -238,6 +276,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/claude/next/rules/README.md

@@ -44,6 +44,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
 | `mcp-usage.mdc` | `tooling-and-review/mcp-usage.md` |
 | `next-app-router.mdc` | `stack/next-app-router.md` |
+| `next-static-export.mdc` | `stack/next-static-export.md` |
 | `arrow-functions.mdc` | `stack/arrow-functions.md` |
 | `types-jsdoc.mdc` | `stack/types-jsdoc.md` |
 | `no-type-assertion-as-import-export.mdc` | `stack/no-type-assertion.md` |
@@ -62,6 +63,8 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `store-rtk.mdc` | `api-and-data/store-rtk.md` |
 | `react-ui.mdc` | `ui-and-accessibility/react-ui.md` |
 | `design-tokens-binding.mdc` | `ui-and-accessibility/design-tokens-binding.md` | Figma → repo token binding (typography/color/spacing/imagery); per-element parity + self-check |
+| `component-catalog-gate.mdc` | `ui-and-accessibility/component-catalog-gate.md` | Storybook/catalog is the UI dev + visual-review surface; stories ship with the change |
+| `forms-validation.mdc` | `ui-and-accessibility/forms-validation.md` | Forms via the repo form library + DS fields + shared validators |
 | `react-a11y-coding.mdc` | `ui-and-accessibility/react-a11y-coding.md` |
 | `no-props-spread.mdc` | `ui-and-accessibility/no-props-spread.md` |
 | `css-property-order-stylelint.mdc` | `ui-and-accessibility/css-property-order.md` |

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

@@ -11,6 +11,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 **`stack/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 |
@@ -56,6 +63,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-and-data/api-services.md`, `api-and-data/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 (`stack/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/claude/next/rules/api-and-data/store-rtk.md

@@ -49,6 +49,12 @@ impact: HIGH
   - 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-and-data/api-services.md` and `api-and-data/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/claude/next/rules/architecture/feature-delivery-workflow.md

@@ -8,6 +8,10 @@ paths:
 
 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 (`ui-and-accessibility/component-catalog-gate.md`).
+
+**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**.
@@ -16,7 +20,7 @@ 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 `ui-and-accessibility/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.

package/presets/claude/next/rules/architecture/product-specs-authoring.md

@@ -119,5 +119,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/claude/next/rules/architecture/product-specs.md

@@ -63,5 +63,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/claude/next/rules/architecture/reference-features.md

@@ -27,6 +27,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
 

package/presets/claude/next/rules/stack/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 (`stack/next-app-router.md`, `stack/navigation-router.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 (`stack/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/claude/next/rules/stack/next-static-export.md

@@ -0,0 +1,36 @@
+---
+description: Static-export / SPA Next.js (output 'export') — no server runtime; what is unavailable and what to use instead
+impact: HIGH
+paths:
+  - app/next.config.*
+  - app/src/pages/**/*
+---
+
+# 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/claude/next/rules/testing/tests-e2e-structure.md

@@ -77,6 +77,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.

package/presets/claude/next/rules/testing/tests-unit.md

@@ -87,6 +87,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/claude/next/rules/tooling-and-review/agent-team-orchestrator.md

@@ -91,7 +91,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - 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 records producer, status, authoritative paths, 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 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.
 
@@ -129,6 +129,8 @@ On each `subagentStop`, the hook reconciles `status.state` from the completing p
 | `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. |
 
 ## Pipeline step options
 

package/presets/claude/next/rules/tooling-and-review/ai-local-overlay.md

@@ -12,8 +12,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.
 
@@ -29,6 +30,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%.
@@ -40,4 +53,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/claude/next/rules/tooling-and-review/code-review-mr.md

@@ -69,3 +69,7 @@ When the diff touches UI / layout / styling (paths under `app/src/ui/**`, global
 - 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.

package/presets/claude/next/rules/tooling-and-review/mcp-usage.md

@@ -93,6 +93,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/claude/next/rules/tooling-and-review/post-change-lint.md

@@ -19,6 +19,10 @@ Exceptions: documentation edits outside `app/`, CI configs, `.claude/rules/**`,
 
 **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 duty. 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 — **`tooling-and-review/package-manager.md`**.

package/presets/claude/next/rules/tooling-and-review/security-next.md

@@ -1,5 +1,6 @@
 ---
 description: Next.js frontend security — secrets, auth, XSS, Server Actions, env
+impact: CRITICAL
 paths:
   - "app/src/**/*.{ts,tsx}"
   - "app/**/app/**/*.{ts,tsx}"
@@ -14,6 +15,8 @@ paths:
 
 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).
@@ -26,6 +29,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
 
@@ -51,6 +55,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/claude/next/rules/ui-and-accessibility/component-catalog-gate.md

@@ -0,0 +1,39 @@
+---
+description: Component catalog (Storybook/Ladle) is the required UI dev + visual-review surface — stories ship with the UI change
+impact: MEDIUM
+paths:
+  - app/src/ui/**/*
+  - storybook/**/*
+---
+
+# 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/claude/next/rules/ui-and-accessibility/design-tokens-binding.md

@@ -29,7 +29,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/claude/next/rules/ui-and-accessibility/forms-validation.md

@@ -0,0 +1,35 @@
+---
+description: Forms and validation — use the repo's form library + design-system fields + shared validators, not ad-hoc state
+impact: MEDIUM
+paths:
+  - app/src/**/*Form*.tsx
+  - app/src/**/*Form*.ts
+  - app/src/**/*Modal*.tsx
+---
+
+# 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/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
+
+- `ui-and-accessibility/react-ui.md` — component structure and decomposition.
+- `architecture/architecture-boundaries-ui.md` — no API/DTO in UI.

package/presets/claude/next/rules/ui-and-accessibility/react-ui.md

@@ -24,6 +24,24 @@ impact: HIGH
 - 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
@@ -99,7 +117,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: `ui-and-accessibility/css-property-order.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 **`ui-and-accessibility/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 **`ui-and-accessibility/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/claude/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/claude/nuxt/agents/accessibility-reviewer.md

@@ -74,8 +74,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/claude/nuxt/agents/api-contract-reviewer.md

@@ -72,8 +72,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/claude/nuxt/agents/build-verifier.md

@@ -117,7 +117,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/claude/nuxt/agents/ci-investigator.md

@@ -90,8 +90,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/claude/nuxt/agents/code-reviewer.md

@@ -80,7 +80,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.