@bonesofspring/ai-rules 0.2.30 → 0.2.32

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/presets/cursor/next/rules/README.md

@@ -12,7 +12,7 @@
 - **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — base invariants (Cursor/Claude 3–5):
   - Cursor: `next-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`
   - Claude: `next-app-core`, `package-manager`, `code-quality`
-- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, product-specs, product-specs-authoring, next-app-router, `security-next`, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`, `design-tokens-binding`
+- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, product-specs, product-specs-authoring, next-app-router, next-static-export, `security-next`, react-a11y-coding, component-catalog-gate, forms-validation, `technical-retro`, `mockup-review`, `ux-design`, `design-tokens-binding`
 - **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
 - **Skills** — long procedures (`feature-delivery`, `spec-authoring`, `spec-discovery`, `code-review`, …)
 
@@ -55,6 +55,9 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads (not all of `app/src
 | `no-props-spread.mdc` | `app/src/**/*.tsx` | Explicit props |
 | `arrow-functions.mdc` | `app/src/**` | Syntax |
 | `design-tokens-binding.mdc` | `app/src/ui/**/*.{ts,tsx,css}`, `app/src/styles/**` | Figma → repo token binding (typography/color/spacing/imagery); no raw values where a token exists |
+| `component-catalog-gate.mdc` | `app/src/ui/**`, `storybook/**` | Stories ship with the UI; catalog tests green |
+| `forms-validation.mdc` | `app/src/**/*Form*.tsx`, `app/src/**/*Modal*.tsx` | Repo form library + DS fields + shared validators |
+| `next-static-export.mdc` | `app/src/pages/**`, `app/next.config.*` | No server runtime; what to use instead |
 
 **Not loaded on typical UI edit:** `architecture-boundaries` (api/store/types/lib), `layer-barrel-exports` (only `index.ts`), `navigation-router-stack` (only `app/src/app/**`). Colocated styles — in `react-ui.mdc` (deprecated stub `no-cross-component-styles-import` removed).
 

package/presets/cursor/next/rules/agent-team-orchestrator.mdc

@@ -95,7 +95,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.
 
@@ -133,6 +133,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/cursor/next/rules/ai-local-overlay.mdc

@@ -13,8 +13,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.
 
@@ -30,6 +31,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/cursor/next/rules/code-review-mr.mdc

@@ -66,3 +66,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/cursor/next/rules/component-catalog-gate.mdc

@@ -0,0 +1,38 @@
+---
+description: Component catalog (Storybook/Ladle) is the required UI dev + visual-review surface — stories ship with the UI change
+globs: app/src/ui/**/*,storybook/**/*,stories/**/*
+alwaysApply: false
+impact: MEDIUM
+---
+
+# 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.mdc` — Figma → repo token binding for the implementation.
+- `mockup-review.mdc` — the reviewer-side parity gate.

package/presets/cursor/next/rules/design-tokens-binding.mdc

@@ -28,7 +28,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/cursor/next/rules/feature-delivery-workflow.mdc

@@ -11,6 +11,10 @@ alwaysApply: false
 
 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**.
@@ -19,7 +23,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 `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.

package/presets/cursor/next/rules/forms-validation.mdc

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

package/presets/cursor/next/rules/mcp-usage.mdc

@@ -92,6 +92,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/cursor/next/rules/next-app-core.mdc

@@ -13,6 +13,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.mdc`, `navigation-router-stack.mdc`).
+- **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.mdc`).
+- **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/cursor/next/rules/next-static-export.mdc

@@ -0,0 +1,35 @@
+---
+description: Static-export / SPA Next.js (output 'export') — no server runtime; what is unavailable and what to use instead
+globs: app/next.config.*,app/src/pages/**/*,app/src/pages/_*.tsx
+alwaysApply: false
+impact: HIGH
+---
+
+# 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.mdc`, `api-services.mdc`).
+- 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.mdc` — phantom-import banlist for this deployment model.
+- `navigation-router-stack.mdc` — Pages Router vs App Router.

package/presets/cursor/next/rules/post-change-lint.mdc

@@ -15,6 +15,10 @@ Exceptions: documentation edits outside `app/`, CI configs, `.cursor/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** 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.mdc`**.

package/presets/cursor/next/rules/product-specs-authoring.mdc

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