@bonesofspring/ai-rules 0.2.29 → 0.2.31

package/presets/cursor/next/agents/code-reviewer.md

@@ -24,6 +24,35 @@ You **issue** reviews. Implementers acting on your findings must verify each ite
 - User-flow changes without e2e plan/spec updates → note in warnings; REQUEST_CHANGES when AC requires e2e.
 - If the MR touches `docs/specs/**`, load **`product-specs`** (+ **`product-specs-authoring`** when new/changed specs): **WARN** code/spec drift; **FAIL** broken INDEX `path` link or missing required frontmatter keys/arrays on touched spec files; required body headings missing → **FAIL** on touched files. Do not invent missing product behavior.
 
+## UI / Figma parity gate (UI-touching MR)
+
+When the diff touches **UI / layout / styling** — paths under `app/src/ui/**` (components, pages, styles, hooks used by UI), or edits to global layout/CSS/tokens, or renamed/reordered UI files — AND a Figma mockup reference exists in `brief.md` / `decomposition.md` (Figma URL, fileKey, or node id) **or** `mockup-review.md` is present in the task:
+
+- **Do a detailed, pixel-accurate comparison** of the implementation against the mockup, **across every viewport the project uses**. The project’s accepted viewport set is the one declared in the `mockup-review` AC-8 / Stack notes (web buckets ~375 / ~768 / ~1280 mapped to small / medium / large) and/or the Storybook viewport toolbar in this repo — fetch the full set, do not sample.
+- For each viewport: pull the Figma frame via Figma MCP `get_screenshot` (prefer the node-link if present) and capture the running app at the same width (Playwright MCP / Chrome DevTools MCP). Compare structure, spacing, typography, color, iconography, states, and interactive affordances. **Storybook visual baselines are not a substitute.**
+
+### Per-element parity checklist (mandatory)
+
+For every UI element in the diff scope, verify against the Figma node and the `mockup-review.md` `## Design contract` (when present) and the **`design-tokens-binding`** discipline. Findings cite **`path:line`** + Figma node id + viewport.
+
+1. **Typography** — font-family, size, line-height, weight, letter-spacing, color. Must match the Figma text style / `tokens-typography` mapping. A `Text variant="…"` DS component is the safe mirror; a raw `font-size: 14px; line-height: 20px;` wrapper is a finding unless the Figma text style maps to a raw token (and the token is used, not a literal).
+2. **Color** — fills, strokes, icon color, link color, placeholder color. Must bind to `@sds/tokens-colors` / `@sds/brand-colors` / the project token module (or the Figma variable mapped in the Design contract). Raw `#…` / `rgb(…)` is a finding. Hover / active / focus / disabled states must use the bound state color from the token set, not a literal.
+3. **Spacing** — padding, gap, margin, border-radius. Must match the Figma spacing / radius variable (Design contract) or the repo spacing scale. Raw `padding: 16px;` is a finding if a token exists. Auto-layout intent (direction, gap, alignment) preserved — no reflow to absolute positioning without a brief reason.
+4. **Imagery & icons** — image `src`, intrinsic `width`/`height`, aspect ratio match the Figma asset / `get_design_context` recommendation; rendered with `next/image` (or repo convention). Icons must use the `@sds/icon` (or DS) symbol name from the Figma component instance. A `placeholder`, an invented image URL, a guessed icon name, or a stretched aspect ratio is a finding. `alt` text matches the Figma node copy when meaningful.
+5. **States** — empty / loading / error / success / disabled / validation visible in the Figma must be implemented. Missing states present in the mockup → `blocker`.
+6. **Structure & responsive** — direction (row / column), alignment, wrap, overflow match the Figma. The implementation responds to the project viewport set without horizontal scroll or clipped content at any accepted width (unless the Figma explicitly clips).
+7. **Auto-layout vs absolute** — for a region that is the only responsive evidence in Figma, the implementation must use flex / grid with the same gap / padding, not absolute positioning.
+
+### Findings, severity, and section
+
+- Findings cite `path:line` + Figma node id + viewport + severity. Layout / style deviations from the mockup → **`important`**; user-visible / broken / missing-state → **`blocker`**; latent / cosmetic → **`nit`**.
+- Emit a `## Figma parity (UI)` section in `review.md` with the per-viewport verdict, a findings table, and screenshots / links. The section must reference the `## Design contract` from `mockup-review.md` and the **`design-tokens-binding`** discipline. **If you cannot perform the comparison** (no Figma URL in brief, or Figma MCP down with no manual screenshots) → still emit the section with verdict `unable_to_compare` and a one-line reason. **Never** skip the section on a UI-touching MR with a Figma reference.
+- **Hard rules:**
+  - UI-touching MR with a Figma reference and a missing or `unable_to_compare` parity section → **REQUEST_CHANGES**.
+  - Unbound raw values where a token exists (typography / color / spacing / imagery) → `blocker` (user-visible) or `important` (latent). Do not approve on Storybook baselines alone.
+
+The gate does **not** apply to MRs with no UI/layout diff and no Figma reference (e.g. pure store/reducer or test-only changes).
+
 ## Review artifact
 
 Write `.ai.local/team/tasks/<slug>/review.md` with this format:
@@ -43,6 +72,12 @@ APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES
 ## Suggestions (nice to have)
 - ...
 
+## Figma parity (UI)
+- Viewports compared: …
+- Per-viewport verdict: …
+- Findings: `path:line` | node id | viewport | severity | note
+- (If UI gate not applicable: `N/A — no UI diff / no Figma reference`.)
+
 ## AC coverage
 | Criterion | Status | Notes |
 |-----------|--------|-------|
@@ -62,7 +97,7 @@ Do not mix this output with retrospective facilitation — keep review and retro
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
-- **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation, validation evidence, and the scoped git diff.
+- **Owned outputs:** `review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/next/agents/debugger.md

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

package/presets/cursor/next/agents/feature-developer.md

@@ -14,6 +14,7 @@ You are a senior frontend developer working in a Next.js monorepo with strict la
 3. Read `pipeline.json` for step context and scope.
 4. Follow the **`feature-delivery` skill** (layer order, reference features, validation handoff).
 5. **Verify carry-over at HEAD before applying** (refactor intent only). When the brief comes from a prior review's carry-over findings list, for each item run `git show HEAD:<path>` or `grep` to confirm the finding still applies at the current HEAD; if the file already contains the fix (carry-over was closed in a prior uncommitted batch), mark it as **NO-OP at HEAD** in `implementation.md` and skip the edit; if the file is unchanged, apply the fix and cite file:line. Target ≤2 NO-OP items per refactor pipeline.
+6. **Figma node-link precondition.** If `brief.md` / `decomposition.md` / the prompt contains a Figma URL with a node id (`?node-id=…`), do **not** start UI implementation until `mockup-review.md` contains **both** a `## Design contract` section (Figma variables, text styles, components/assets with the repo mapping) **and** a `## Node decomposition (AC-2)` section (child→component map with bindings) for that node. If either section is missing or empty, emit `blocked` and hand back to the analyst / mockup-reviewer (or ask the user to re-run mockup-review). The Design contract is the binding table for typography / color / spacing / imagery; the Node decomposition is the component map. Load requestable rule **`design-tokens-binding`** before writing UI — bind every value to a Figma variable / text style / repo token; raw `#…` / `px` are a finding.
 
 ## Task execution rules
 
@@ -58,6 +59,27 @@ Do not perform formal code review — that is the code-reviewer subagent's job.
 
 Before handoff, IDENTIFY→RUN→READ→VERIFY the scoped checks for this WP, THEN claim. Do not say the work is done without that evidence in the same turn. Full-project lint is `build-verifier`.
 
+## UI self-check vs Figma (mandatory for UI WPs with a Figma reference)
+
+When this WP touched UI / layout / styling (paths under `app/src/ui/**`, global layout/CSS/tokens) AND a Figma reference exists in `brief.md` / `decomposition.md` (or `mockup-review.md` is present):
+
+1. **Render** the changed routes at **each project viewport** (the set from `mockup-review` AC-8 / Stack notes — web buckets ~375 / ~768 / ~1280 small/medium/large — and the repo’s Storybook viewport toolbar). Use Playwright MCP or Chrome DevTools MCP (the app must be running; if not, note the limitation and still perform the self-check as far as possible).
+2. **Compare** each rendered viewport to the Figma `get_screenshot` (prefer the node-link). For each UI element in the diff scope, check the per-element parity list in the `code-reviewer` UI / Figma parity gate: typography, color, spacing, imagery, states, structure/responsive, auto-layout intent.
+3. **Fix** obvious deviations before the implementation receipt (font family / size / line-height / color / spacing / image src+size / icon name / state). Bind to the Design contract; load **`design-tokens-binding`** if a value is missing.
+4. **Record** a `## UI self-check vs Figma` block in `implementation.md`:
+
+   ```markdown
+   ## UI self-check vs Figma
+   - Viewports checked: <e.g. 375, 768, 1280>
+   - MCP / app status: <ok | degraded: reason>
+   - Deviations fixed: `path:line` | node id | viewport | what | fix
+   - Remaining gaps / known limits: <… or none>
+   ```
+
+   If the app was not runnable or MCP was down, still emit the block with the limitation and what you could not check — the reviewer will gate.
+
+This is the developer-side counterpart to the `code-reviewer` UI / Figma parity gate; together they close the fidelity loop (extract contract → bind → self-check → review-block on unbound).
+
 ## Anti-hallucination (Next / React / RTK)
 
 - When editing `app/**/*.{ts,tsx}`, load / follow rule `react-next-anti-hallucination`.
@@ -102,7 +124,7 @@ Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools M
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
-- **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
+- **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/next/agents/migration-specialist.md

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

package/presets/cursor/next/agents/mockup-reviewer.md

@@ -34,9 +34,35 @@ MCP unavailable or OAuth fail → verdict `BLOCKED_MCP`. Do not invent DS claims
 
 Follow the requestable `mockup-review` checklist (DS components, tokens, quality, coverage, viewports). Do not duplicate that checklist here.
 
+## Node-link input: child→component decomposition (AC-2, mandatory)
+
+When the Figma URL (in prompt, `brief.md`, or `decomposition.md`) contains a node id (`?node-id=…` or `…/node/…`):
+
+1. **Inspect the node subtree** via Figma MCP `get_metadata` for the exact node (not the whole file). Depth ≤3 named-frame levels; ≤12 child rows in the map.
+2. **Classify each child node** as one of: library component instance (check `search_design_system` / library metadata), custom frame, text/icon/asset, container, layout-only, unknown. Skip pure decorative leaves unless they constrain the child component.
+3. **Map each child node → target component** using repo conventions:
+   - existing `app/src/ui/**` component → name it (e.g. `RiskProfilePage/components/ProfileHealthCard`);
+   - attached library component (e.g. `@sds/*`) → name the library symbol and the local wrapper;
+   - no analog → mark `new: <ProposedName>` and the parent component it belongs to.
+4. **Emit the map** in the report under `## Node decomposition (AC-2)` as a table (node id, node name, type, target component / action). Add a short prose summary of grouping / boundaries.
+5. **Extract the Design contract** (mandatory for node-link input) and emit it as a separate `## Design contract` section, **above** the Node decomposition table — the developer reads it first:
+   - **Figma variables** (one `get_variable_defs` call per file): list the variables used by the subtree (color, spacing, radius, effect). Map each to the repo equivalent: `@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens` / project token module (e.g. `var(--text-primary, …)`).
+   - **Text styles**: list the Figma text style names used (e.g. `Body/M`, `Heading/L`). Map to the repo typography component / token (`@sds/tokens-typography`, `Text variant="…"`, Linaria `var(--font-…, …)`).
+   - **Components / assets**: list library component instances (`@sds/*` symbol name), image fills (asset URL / `get_design_context` recommendation), and icons (`@sds/icon` symbol name).
+   - Call this once per file; do not dump the whole variable set — only what the subtree uses.
+6. **Extend the AC-2 table** with a concise `Bindings` column (or a per-row note) capturing the text style, fill / spacing tokens, and asset source for that node. Keep the table scannable; put the long form in the Design contract section.
+7. **Verdict rule.** Missing map **or** missing Design contract on a node-link input → verdict `FAIL` (mandatory pre-implementation step) unless MCP returned `BLOCKED_MCP`. Refusal to produce the map / contract on a node-link task is not an option — narrow the node with the user first (do not silently fall back to whole-file review).
+
+The map and the Design contract are the implementation contract the developer reads before coding; the DS/tokens/quality/coverage/viewport dimensions still apply on top.
+
 ## Output
 
-Write `.ai.local/team/tasks/<slug>/mockup-review.md` using the report headings in the `mockup-review` rule.
+Write `.ai.local/team/tasks/<slug>/mockup-review.md` using the report headings in the `mockup-review` rule. When the input is a node-link, the report **must** additionally include:
+
+- `## Design contract` (above Node decomposition) — Figma variables, text styles, components/assets used by the subtree, with the repo mapping (`@sds/tokens-*` / DS components / project token module). This is the binding table the developer uses for typography, color, spacing, and imagery.
+- `## Node decomposition (AC-2)` — the child→component map (table) plus a short prose summary, with a `Bindings` column / per-row note for the Figma design bindings.
+
+Both sections are the developer’s pre-implementation contract; do not omit either on a node-link input.
 
 ## Verdicts and receipts
 
@@ -52,8 +78,8 @@ Standalone FAIL must **not** set `changes_requested`. Embedded FAIL is a FAIL-on
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for routing + analysis when present (standalone may have only the prompt + URL).
-- **Owned outputs:** `mockup-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `mockup-review`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for routing + analysis when present (standalone may have only the prompt + URL).
+- **Owned outputs:** `mockup-review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `mockup-review`) and preserve all foreign items in `manifest.artifacts[]`.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed`, `changes_requested`, or `blocked` per the table above. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 

package/presets/cursor/next/agents/openspec-author.md

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

package/presets/cursor/next/agents/performance-auditor.md

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

package/presets/cursor/next/agents/qa-tester.md

@@ -38,8 +38,8 @@ When the task is mostly e2e, prefer invoking the dedicated `playwright-test-plan
 
 ## 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, reviewer notes when present, and prior implementation/validation artifacts.
-- **Owned outputs:** changed/added test paths (and any QA notes written under the slug dir); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `qa-tester`) 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, reviewer notes when present, and prior implementation/validation artifacts.
+- **Owned outputs:** changed/added test paths (and any QA notes written under the slug dir); upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `qa-tester`) 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/cursor/next/agents/security-reviewer.md

@@ -51,8 +51,8 @@ PASS | PASS_WITH_NOTES | FAIL
 
 ## 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, prior `review.md` when present, and the scoped git diff.
-- **Owned outputs:** `security-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `security-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, prior `review.md` when present, and the scoped git diff.
+- **Owned outputs:** `security-review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `security-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/cursor/next/agents/solution-architect.md

@@ -61,8 +61,8 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and applicable prior analysis artifacts.
-- **Owned outputs:** `architecture.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `architecture`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition and applicable prior analysis artifacts.
+- **Owned outputs:** `architecture.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `architecture`) 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/cursor/next/agents/task-analyst.md

@@ -168,6 +168,6 @@ If the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is r
 ## Artifact contract
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
-- **Owned outputs:** `brief.md` and `decomposition.md` (plus `ux-design.md` when produced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md` (plus `ux-design.md` when produced); upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `analysis`) 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/cursor/next/agents/task-router.md

@@ -180,6 +180,6 @@ Return the routing receipt to the orchestrator. The orchestration runtime/hook e
 ## Artifact contract
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume the user request and any existing authoritative task/decision entries.
-- **Owned outputs:** `pipeline.json` and the routing manifest entry; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `routing`) and preserve all foreign entries.
+- **Owned outputs:** `pipeline.json` and the routing entry in `manifest.artifacts[]`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `routing`) 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/cursor/next/agents/tech-writer.md

@@ -54,8 +54,8 @@ Post-delivery: when behavior or public docs changed and `docs/specs/` is in play
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
-- **Owned outputs:** `documentation.md` (and any explicitly requested docs paths); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `documentation`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition and available architecture/migration/review artifacts.
+- **Owned outputs:** `documentation.md` (and any explicitly requested docs paths); upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `documentation`) 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/cursor/next/agents/unit-test-generator.md

@@ -28,8 +28,8 @@ Run affected unit tests from `app/` when feasible. Report files changed, command
 
 ## 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 `unit-test-plan.md`, brief/decomposition when present, and target modules.
-- **Owned outputs:** generated/updated `*.spec.ts` / `*.spec.tsx` paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-generator`) 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 `unit-test-plan.md`, brief/decomposition when present, and target modules.
+- **Owned outputs:** generated/updated `*.spec.ts` / `*.spec.tsx` paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `unit-test-generator`) 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/cursor/next/agents/unit-test-healer.md

@@ -29,8 +29,8 @@ Report root cause, files changed, validation result, and remaining risk.
 
 ## 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 failing test evidence, `unit-test-plan.md` when present, and recent diff.
-- **Owned outputs:** healed `*.spec.ts` / `*.spec.tsx` paths (and minimal production fixes only when evidenced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-healer`) 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 failing test evidence, `unit-test-plan.md` when present, and recent diff.
+- **Owned outputs:** healed `*.spec.ts` / `*.spec.tsx` paths (and minimal production fixes only when evidenced); upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `unit-test-healer`) 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/cursor/next/agents/unit-test-planner.md

@@ -49,8 +49,8 @@ Test titles in the plan must follow Russian capitalization rules from `tests-uni
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and target modules under `app/src/**`.
-- **Owned outputs:** `unit-test-plan.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-planner`) and preserve all foreign entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition and target modules under `app/src/**`.
+- **Owned outputs:** `unit-test-plan.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `unit-test-planner`) 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/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`
+- **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`
 - **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`, …)
 
@@ -54,6 +54,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads (not all of `app/src
 | `navigation-router-ui.mdc` | `app/src/ui/**/*.tsx` | Brief navigation guide |
 | `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 |
 
 **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).
 
@@ -94,6 +95,7 @@ Fill **`reference-features.mdc`** (TBD → real paths) after `init` in the targe
 | `tests-unit.mdc` | Unit tests and HTTP client behavior tests |
 | `playwright-agents.mdc`, `tests-e2e-structure.mdc` | E2E |
 | `react-ui.mdc` | React/Next UI: component structure, adjacent `ComponentName.data.ts` / `.utils.ts`, styles, props |
+| `design-tokens-binding.mdc` | Figma → repo token binding (typography/color/spacing/imagery); per-element parity + self-check discipline; referenced by `feature-developer` and `code-reviewer` |
 
 **Wording collisions:** type and API imports — source of truth **`public-imports.mdc`**; duplicates ESLint `no-restricted-imports` in `app/eslint.config.mjs`.
 

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 in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
 - 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/code-review-mr.mdc

@@ -56,3 +56,13 @@ On-demand rule for review flows. **Procedure and output format:** skill `code-re
 - Security: `security-next.mdc`
 - Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
 - Lint gate before final report: `post-change-lint.mdc`
+
+### UI / Figma parity (web)
+
+When the diff touches UI / layout / styling (paths under `app/src/ui/**`, global layout/CSS/tokens) AND a Figma mockup is referenced in `brief.md` / `decomposition.md` (URL, fileKey, or node id) **or** `mockup-review.md` is present:
+
+- The `code-reviewer` agent must perform a **detailed, pixel-accurate** comparison of the implementation against the mockup, **across every viewport the project uses** (the `mockup-review` AC-8 / Stack notes set — web buckets ~375 / ~768 / ~1280 small/medium/large — and the Storybook viewport toolbar in this repo). Figma frames via Figma MCP `get_screenshot`; the running app via Playwright MCP / Chrome DevTools MCP at the matching width.
+- The comparison is a **per-element parity check** (typography / color / spacing / imagery / states / structure / auto-layout intent) per the `code-reviewer` UI / Figma parity gate. Bind to the `mockup-review.md` `## Design contract` and the **`design-tokens-binding.mdc`** discipline (`@sds/tokens-*` / DS components, no raw `#…` / `px` where a token exists).
+- 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.

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

@@ -0,0 +1,41 @@
+---
+description: Bind UI to Figma design tokens — typography, color, spacing, imagery. No raw design values when a token exists.
+globs: app/src/ui/**/*.{ts,tsx,css},app/src/styles/**/*.{css,ts,tsx}
+impact: HIGH
+---
+
+# Design-token binding (Figma → repo)
+
+The implementation must mirror the Figma mockup token-for-token. Raw design values where a token exists are a finding. This rule is the web-stack discipline; the reporter (`mockup-reviewer`) emits the bindings, the implementer (`feature-developer`) binds, the reviewer (`code-reviewer`) blocks on unbound raw values.
+
+## Typography
+
+- Bind to the Figma **text style** used by the node — extract via Figma MCP `get_design_context` / `get_variable_defs` and the node metadata. Do not invent `font-size: 14px; line-height: 20px;` when a Figma text style exists.
+- Repo mapping: font family, size, line-height, weight, letter-spacing → `@sds/tokens-typography` (or the project token module). In Linaria / styled: `font: var(--font-body-m, …)` / equivalent token.
+- Prefer a typography variant / DS text component that already binds the token (e.g. `Text variant="body-m"`) over a styled wrapper with raw values.
+
+## Color
+
+- Bind to the Figma **fill / stroke variable** (`get_variable_defs`). Do not write raw `#…` or `rgb(…)`.
+- Repo mapping: `@sds/tokens-colors`, `@sds/brand-colors`, or the project token module (`color: var(--text-primary, …)`).
+- A raw value is allowed only with an inline `// token-pending: <Figma-variable-name>` comment and a follow-up to bind it. The reviewer treats unbound raw values as a finding.
+
+## Spacing / radius / shadow
+
+- Bind to Figma **spacing / radius / effect variables** or the repo spacing scale. Do not write raw `padding: 16px; gap: 12px;` if a token exists.
+- Repo mapping: spacing tokens from `@sds/tokens` / the project scale; Linaria `css\`…\`` uses `var(--space-…, …)`.
+- **Auto-layout intent:** respect Figma auto-layout (direction, gap, padding, alignment). Switching to absolute positioning for a region that is the only responsive evidence is a finding. `display: flex` with the same gap/padding is the safe mirror; do not reflow to a different layout without a reason in the brief.
+
+## 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.
+- **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.
+
+## Self-check before handoff
+
+For UI WPs with a Figma reference: render the page at each project viewport (Playwright MCP / Chrome DevTools MCP) and compare to the Figma `get_screenshot`. Fix obvious typography / color / spacing / imagery deviations before the implementation receipt. Record a short **UI self-check vs Figma** block in `implementation.md` (viewports checked, deviations fixed, remaining gaps, MCP / app status). If the app is not runnable or MCP is down, note the limitation — the reviewer will gate.
+
+## Reviewer contract
+
+The `code-reviewer` UI / Figma parity gate enforces this. A UI-touching MR with a Figma reference and unbound raw values where tokens exist → `blocker` (user-visible) or `important` (latent). Missing self-check on a UI WP with a Figma reference → `important`.

package/presets/cursor/next/rules/feature-delivery-workflow.mdc

@@ -15,6 +15,23 @@ When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mo
 
 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**.
 
+## Figma node-link — child→component decomposition (mandatory pre-implementation)
+
+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.
+- `## 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.
+
+## UI MR — Figma parity gate (mandatory in code review)
+
+When the MR touches UI / layout / styling (`app/src/ui/**`, global layout/CSS/tokens) and a Figma reference exists in `brief.md` / `decomposition.md` or `mockup-review.md` is present, `code-reviewer` must perform a **detailed, pixel-accurate** comparison of the implementation against the mockup across **every project viewport** (mockup-review AC-8 / Stack notes set and the repo’s Storybook viewport toolbar). The comparison is a per-element parity check (typography / color / spacing / imagery / states / structure / auto-layout intent) bound to the `## Design contract` and the `design-tokens-binding.mdc` discipline. Findings go in `## Figma parity (UI)` in `review.md`. **Storybook visual baselines are not a substitute.** Missing or `unable_to_compare` parity on a UI MR with a Figma reference → `REQUEST_CHANGES`. The full gate lives in the `code-reviewer` agent prompt and the `code-review-mr` Stack notes.
+
+## UI self-check vs Figma (mandatory in implementation)
+
+For UI WPs with a Figma reference, `feature-developer` performs a **self-check vs Figma** at each project viewport (Playwright MCP / Chrome DevTools MCP) before the implementation receipt, fixes obvious typography / color / spacing / imagery / state deviations, and records a `## UI self-check vs Figma` block in `implementation.md`. This is the developer-side counterpart to the parity gate and closes the fidelity loop (extract contract → bind → self-check → review-block).
+
 Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `next-app-core.mdc`.
 
 ## Checklist (work order)

package/presets/cursor/next/rules/mockup-review.mdc

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

package/presets/cursor/next/rules/react-ui.mdc

@@ -97,6 +97,7 @@ For a reusable component:
 - **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
 - CSS / `styled` order — Stylelint idiomatic-order: `css-property-order-stylelint.mdc` (loads on `styles.ts` / `.css`).
 - For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
+- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, `next/image`). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`design-tokens-binding.mdc`**. 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/cursor/next/skills/code-review/SKILL.md

@@ -20,6 +20,7 @@ Use the local repository as the source of truth: `git status`, `git diff`, task
 7. **Reuse lens:** flag new helpers that duplicate existing utilities; prefer adjacent shared modules over copy-paste.
 8. **Efficiency lens:** unnecessary work, sequential ops that should be parallel, hot-path bloat, no-op store updates, overly broad reads.
 9. Report validation gaps: lint, stylelint, type-check, or relevant tests not run.
+10. **UI / Figma parity (when the diff touches UI/layout AND a Figma reference exists):** perform a detailed, pixel-accurate comparison of the implementation against the mockup across **every project viewport** (mockup-review AC-8 / Stack notes set and the repo’s Storybook viewport toolbar). Figma frames via Figma MCP `get_screenshot`; the running app via Playwright MCP / Chrome DevTools MCP at the matching width. Compare **per element** — typography, color, spacing, imagery, states, structure/responsive, auto-layout intent — bound to the `mockup-review.md` `## Design contract` and the `design-tokens-binding` discipline (`@sds/tokens-*` / DS components; raw `#…` / `px` where a token exists is a finding). Emit a `## Figma parity (UI)` section in `review.md`. **Storybook visual baselines are not a substitute.** Missing or `unable_to_compare` parity on a UI MR with a Figma reference → `REQUEST_CHANGES`. Unbound raw values → `blocker` / `important`.
 
 ## Output