@bonesofspring/ai-rules 0.2.29 → 0.2.31

package/presets/opencode/mcp-ts/rules/agent-team-orchestrator.md

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

package/presets/opencode/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "opencode",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "d4543a561129f18289d5c83d94038bbf7a973c57bb498f9b58c2ed37ceca3a07",
+  "sourceRevision": "be3247c939b52878a3d3d93245cd63c02e259418104111458f04ef0b737e5d27",
   "entries": [
     {
       "source": "AGENTS.md",
@@ -490,6 +490,14 @@
       "reason": "Requestable Cursor rule: lazy Read from .opencode/rules; not auto-loaded",
       "sharedCoreStem": "quality/design-guidance.md"
     },
+    {
+      "source": "rules/design-tokens-binding.mdc",
+      "target": "rules/design-tokens-binding.md",
+      "category": "rules",
+      "disposition": "transform",
+      "loadMode": "referenced",
+      "reason": "Requestable Cursor rule: lazy Read from .opencode/rules; not auto-loaded"
+    },
     {
       "source": "rules/feature-delivery-workflow.mdc",
       "target": "rules/feature-delivery-workflow.md",

package/presets/opencode/next/agents/accessibility-reviewer.md

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

package/presets/opencode/next/agents/api-contract-reviewer.md

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

package/presets/opencode/next/agents/build-verifier.md

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

package/presets/opencode/next/agents/ci-investigator.md

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

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

@@ -47,6 +47,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:
@@ -66,6 +95,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 |
 |-----------|--------|-------|
@@ -85,7 +120,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/opencode/next/agents/debugger.md

@@ -99,8 +99,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/opencode/next/agents/feature-developer.md

@@ -49,6 +49,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
 
@@ -93,6 +94,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`.
@@ -137,7 +159,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/opencode/next/agents/migration-specialist.md

@@ -84,8 +84,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/opencode/next/agents/mockup-reviewer.md

@@ -56,9 +56,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
 
@@ -74,8 +100,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/opencode/next/agents/openspec-author.md

@@ -145,8 +145,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/opencode/next/agents/performance-auditor.md

@@ -83,8 +83,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/opencode/next/agents/qa-tester.md

@@ -59,8 +59,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/opencode/next/agents/security-reviewer.md

@@ -73,8 +73,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/opencode/next/agents/solution-architect.md

@@ -83,8 +83,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/opencode/next/agents/task-analyst.md

@@ -190,6 +190,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/opencode/next/agents/task-router.md

@@ -202,6 +202,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/opencode/next/agents/tech-writer.md

@@ -77,8 +77,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/opencode/next/agents/unit-test-generator.md

@@ -47,8 +47,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/opencode/next/agents/unit-test-healer.md

@@ -48,8 +48,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/opencode/next/agents/unit-test-planner.md

@@ -72,8 +72,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/opencode/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/opencode/next/rules/agent-team-orchestrator.md

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

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

@@ -51,3 +51,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/opencode/next/rules/design-tokens-binding.md

@@ -0,0 +1,35 @@
+# 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`.