@bonesofspring/ai-rules 0.2.29 → 0.2.31

package/presets/mavis/ios-swift/agents/code-reviewer.md

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

package/presets/mavis/ios-swift/agents/feature-developer.md

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

package/presets/mavis/ios-swift/agents/mockup-reviewer.md

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

package/presets/mavis/ios-swift/agents/openspec-author.md

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

package/presets/mavis/ios-swift/agents/task-analyst.md

@@ -102,6 +102,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/mavis/ios-swift/agents/task-router.md

@@ -154,6 +154,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/mavis/ios-swift/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/mavis/java/agents/build-verifier.md

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

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

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

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

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

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

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

package/presets/mavis/java/agents/task-analyst.md

@@ -81,6 +81,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`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md`; 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/mavis/java/agents/task-router.md

@@ -143,6 +143,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/mavis/java/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/mavis/mcp-ts/agents/build-verifier.md

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

package/presets/mavis/mcp-ts/agents/feature-developer.md

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

package/presets/mavis/mcp-ts/agents/task-analyst.md

@@ -84,6 +84,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`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md`; 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/mavis/mcp-ts/agents/task-router.md

@@ -139,6 +139,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/mavis/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/mavis/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "d4543a561129f18289d5c83d94038bbf7a973c57bb498f9b58c2ed37ceca3a07",
+  "sourceRevision": "be3247c939b52878a3d3d93245cd63c02e259418104111458f04ef0b737e5d27",
   "entries": [
     {
       "source": "AGENTS.md",
@@ -490,6 +490,14 @@
       "reason": "Requestable Cursor rule: referenced from entry files; not claimed as MiniMax auto-load",
       "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: referenced from entry files; not claimed as MiniMax auto-load"
+    },
     {
       "source": "rules/feature-delivery-workflow.mdc",
       "target": "rules/feature-delivery-workflow.md",

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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