@bonesofspring/ai-rules 0.2.12 → 0.2.14

package/presets/cursor/go/team/README.md

@@ -30,10 +30,21 @@
 
 Bootstrap `tasks/<slug>/` by **writing** artifacts (Write tool), not Shell `mkdir`. Cursor sandbox → `Operation not permitted` otherwise (worse on Desktop/Documents).
 
+## Artifact manifest and receipts
+
+Each slug stores one context index at `.cursor/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
+
+Producer/consumer rules:
+
+- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
+- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
+- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
+- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
+
 ## Local metrics ledger
 
-`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The router writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The orchestration runtime writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
 
-`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
 
 Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .cursor/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.

package/presets/cursor/ios-swift/agents/build-verifier.md

@@ -35,7 +35,7 @@ When validating **ios-swift preset** changes (or `scope: preset-structure-valida
 3. **Forbidden handoff strings** in ios-swift `chain-team-phases.sh` (Cursor + Claude): `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`, and positive yarn lint recipes (`lint:js` / `lint:css` as commands to run — negation prose alone is not enough; prefer zero occurrences). See `preset-no-cross-stack-leakage.mdc`.
 4. **Required handoff stems:** `AGENT_HANDOFF` must include `xcuitest-test-planner` (or generator/healer) and `build-verifier` text must mention `xcodebuild` or `post-change-build` / `xcode-tooling`.
 5. **Roster:** 21 agent stems; no `playwright-test-*` files under ios-swift `agents/`.
-6. **Twin presence (hard):** Cursor rule change → Claude twin present **same PR** — **FAIL** if missing (next, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel).
+6. **Twin presence (hard):** Cursor rule change → Claude twin present **same PR** — **FAIL** if missing (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel).
 7. **Mapping / README:** `claude/ios-swift/rules/README.md` mapping table present; core→stack mapping documented when `_shared` consumers exist.
 8. **shared-core consumers:** if `_shared/core/**` changed, every matching `<!-- shared-core: … -->` consumer in this PR must be updated (or intentional fork documented).
 9. **Session-start body budget:** sum of the **3** intended always-on / session-start rule bodies ≤ **140** lines (stretch ≤120); do **not** include `**/README.md` — record in report.
@@ -47,7 +47,7 @@ When validating **ios-swift preset** changes (or `scope: preset-structure-valida
 - **Thin aliases:** `agent-team-intake`, `technical-retro` may be &lt;15 body lines. Enforce ≥15 on **domain** rules (navigation, persistence, security, modules, networking, UI).
 - Embed vs lineage modes: `docs/PRESET-CONTRIBUTION.md`, `_shared/README.md`.
 
-12. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java|mcp-ts|php-hexagonal`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+12. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|nuxt|svelte|ios-swift|go|java|mcp-ts|php-hexagonal|php-laravel`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
 13. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
 14. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 15. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
@@ -75,4 +75,11 @@ PASS | FAIL
 
 ## On completion
 
-Update `status.json`: `currentAgent: build-verifier`, `state: completed` (or `validation_failed` on FAIL). Do not fix code — report only.
+Write the owned validation receipt (`completed` or `validation_failed`). Do not fix code — report only; the runtime owns `status.json`.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/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.
+- **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/cursor/ios-swift/agents/code-reviewer.md

@@ -5,7 +5,7 @@ readonly: false
 model: fast
 ---
 
-You are a senior iOS / Swift / SwiftUI code reviewer. You may write only review artifacts under `.cursor/team/**` and update task `status.json`; do not modify production code.
+You are a senior iOS / Swift / SwiftUI code reviewer. You may write only review artifacts under `.cursor/team/**` and terminal receipts; do not modify production code.
 
 ## Inputs
 
@@ -58,22 +58,17 @@ APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "code-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If **REQUEST_CHANGES**, set `"state": "changes_requested"` (hook will re-invoke feature-developer).
+Write the owned terminal receipt described under **Artifact contract**. If **REQUEST_CHANGES**, emit receipt outcome `changes_requested`; the hook decides retry state.
 
 Do not mix this output with retrospective facilitation — keep review and retro separate.
 
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/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.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
+- **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

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

@@ -45,7 +45,7 @@ When copying from `next` into `ios-swift` (or another stack):
 
 ## On completion
 
-`status.json`: `currentAgent: feature-developer`, `state: completed`. Handoff by layer + gaps for verifier/reviewer. No formal code review.
+Emit the owned implementation receipt with outcome `completed`. Handoff by layer + gaps for verifier/reviewer. No formal code review.
 
 ## Design guidance
 
@@ -54,3 +54,10 @@ When copying from `next` into `ios-swift` (or another stack):
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/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.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
+- **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

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

@@ -20,10 +20,17 @@ Ask only blocking questions (AC gaps, Feature scope, platforms, offline/auth, AP
 
 1. `brief.md` — goal, AC, out of scope, assumptions.
 2. `decomposition.md` — ordered WPs with Depends on / Done when; mark unit/UI test WPs.
-3. Update `status.json` → `awaiting_approval` if human gate after analyst.
+3. Emit the analysis receipt; the runtime applies the configured analyst human gate.
 
 Do not invent architecture stacks (TCA, SwiftData, …) — frame «как в репо».
 
 ## Design guidance (optional)
 
 - Optional: Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit — only when decomposing refactor/architecture tasks (not default).
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/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.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
+- **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/ios-swift/agents/task-router.md

@@ -40,6 +40,27 @@ You are a task router for an **iOS Swift/SwiftUI** agent team. You **do not** im
 
 **Never skip `build-verifier`** after developer when Swift/Xcode sources changed.
 
+## Routing decision rubric
+
+Keep top-level `profile` and emit this top-level object in every new `pipeline.json`:
+
+```json
+"routingDecision": {
+  "complexity": "low | moderate | high",
+  "riskFlags": [],
+  "routingReasons": ["Concrete request signal and its routing consequence."],
+  "estimatedWorkPackages": 1,
+  "openDecisionCount": 0
+}
+```
+
+- `low`: one bounded layer/file set, explicit AC, reversible, no risk flags/open decisions → `light` when verification policy permits.
+- `moderate`: adjacent concerns or a regression/refactor with known boundaries → usually `standard`.
+- `high`: cross-layer/public contract, security, migration/destructive or concurrency/state risk, broad UI-test surface, unclear AC, or multiple work packages → usually `full`.
+- Use concrete flags: `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression`.
+- `routingReasons` must be non-empty and explain profile, gates, specialists, skips, or checkpoints; never write “standard by default.”
+- `estimatedWorkPackages` is an integer ≥1; `openDecisionCount` is an integer ≥0. Do not lower complexity because implementation is familiar.
+
 ## Model tiers (`steps[].model`)
 
 Optional: `"model": "cheap" | "standard" | "strong"`. Same policy as **cursor/next** `task-router.md`:
@@ -64,12 +85,19 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 
 ## Output
 
-Write `.cursor/team/tasks/<slug>/pipeline.json` and initial `status.json` via the **Write** tool (creates parents; do not Shell-`mkdir`); set `.cursor/team/active-task.json`.
+Write `.cursor/team/tasks/<slug>/pipeline.json` and initialize the routing entry in `artifact-manifest.json`; set `.cursor/team/active-task.json`. The orchestration runtime creates and owns `status.json`.
 
 ## Handoff
 
 Intent + steps table + skipped + gates → invoke `steps[0].agent` (unless retro).
 
-## Metrics initialization
+## Runtime initialization
+
+Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.
+
+## Artifact contract
 
-Alongside `pipeline.json` and `status.json`, create `metrics.json` with `schemaVersion: 1`, immutable task dimensions, `task_started`, and a generated `runId`. Before the parent invokes each agent, append `attempt_started` and set `status.activeAttempts[attemptId]` with agent, step index, attempt number, and host-clock `startedAt`. For parallel work create one entry per agent; do not use `currentAgent` to identify their completion.
+- **Authoritative inputs:** read `.cursor/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.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
+- **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/ios-swift/commands/task.md

@@ -25,14 +25,16 @@ description: Route a natural-language task through the agent-team pipeline: task
 
 ## Алгоритм
 
-1. **Slug** — kebab-case из описания (≤48 символов). Создай `.cursor/team/tasks/<slug>/` через **Write** (например сразу `status.json` или пустой placeholder) — **не** через Shell `mkdir` (песочница → `Operation not permitted`).
+1. **Slug** — kebab-case из описания (≤48 символов). Создай `.cursor/team/tasks/<slug>/` через **Write** (например placeholder `pipeline.json` или пустой marker) — runtime/hook владеет `status.json` — **не** через Shell `mkdir` (песочница → `Operation not permitted`).
 2. **Router** — вызови subagent **task-router** с описанием задачи и путём к slug.
 3. **План** — покажи пользователю таблицу из `pipeline.json`: intent, steps, skipped, humanGates.
 4. **Intent retro** — если `intent === "retro"`, выполни `/technical-retro` и **остановись**.
-5. **Старт** — вызови subagent для `pipeline.steps[0].agent`:
-   - передай slug, пути к артефактам, scope из step (если есть);
-   - обнови `status.json`: `pipelineIndex: 0`, `currentAgent`, `state: in_progress`.
-6. **Human gate** — если после текущего шага есть gate в `humanGates` (`after:<agent>`), после завершения агента **остановись** и попроси `/task-continue <slug>` (или `/feature-continue <slug>`).
+5. **Старт** — после router:
+   - подтверди `pipeline.json` и `active-task.json`;
+   - **не** пиши lifecycle-поля `status.json` / `metrics.json` сам — их владеет orchestration runtime/hook (см. **agent-artifact-contracts**). Если `status.json` отсутствует, допустим только минимальный bootstrap (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **не** увеличивай `pipelineIndex` вручную;
+   - вызови subagent для `pipeline.steps[0].agent` (slug, пути к артефактам, scope).
+6. **После каждого агента** — дождись hook handoff / reconciliation terminal receipt → `status.state`; не запускай следующий шаг, пока `status.json` не отражает handoff (или пока нет `followup_message` от hook).
+7. **Human gate** — если после текущего шага есть gate в `humanGates` (`after:<agent>`), после завершения агента **остановись** и попроси `/task-continue <slug>` (или `/feature-continue <slug>`).
 
 ## Не делать
 
@@ -51,4 +53,4 @@ description: Route a natural-language task through the agent-team pipeline: task
 
 ## Metrics
 
-Initialize `metrics.json` before the first invocation with frozen task dimensions and `task_started`; add one `activeAttempts[attemptId]` entry plus `attempt_started` per scheduled agent. On `/task-continue`, append `human_gate_ended` (referencing the stored gate event) before activating the next attempt. Do not calculate durations in agents.
+Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On `/task-continue`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.

package/presets/cursor/ios-swift/hooks/chain-team-phases.sh

@@ -122,6 +122,27 @@ function roleFor(agent) {
   if (/writer/.test(agent || '')) return 'docs';
   return 'implementation';
 }
+const DEFAULT_ARTIFACT_OUTPUT_IDS = {
+  'task-router': 'routing',
+  'task-analyst': 'analysis',
+  'solution-architect': 'architecture',
+  'migration-specialist': 'migration-plan',
+  debugger: 'debug',
+  'ci-investigator': 'ci',
+  'feature-developer': 'implementation',
+  'build-verifier': 'validation',
+  'code-reviewer': 'review',
+  'security-reviewer': 'security-review',
+  'accessibility-reviewer': 'a11y-review',
+  'performance-auditor': 'perf-report',
+  'api-contract-reviewer': 'api-contract-review',
+  'tech-writer': 'documentation',
+};
+function artifactOutputIdFor(step, agent) {
+  if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
+  if (step?.artifactOutputIds && typeof step.artifactOutputIds[agent] === 'string') return step.artifactOutputIds[agent];
+  return DEFAULT_ARTIFACT_OUTPUT_IDS[agent] || agent;
+}
 function activateAttempts(step, stepIndex) {
   const active = { ...(status.activeAttempts || {}) }; const agents = getStepAgents(step);
   const parallelGroupId = step.parallel && agents.length > 1 ? `${status.metricsRunId || slug}:step-${stepIndex}` : null;
@@ -144,11 +165,61 @@ function resolvedAttempt() {
   try { const receipts = JSON.parse(fs.readFileSync(path.join(taskDir, '.metrics-receipts.json'), 'utf8')); const receipt = Array.isArray(receipts) ? receipts.find((item) => active[item.attemptId]) : null; if (receipt) return { attemptId: receipt.attemptId, entry: active[receipt.attemptId], confidence: 'fallback', source: 'agent' }; } catch {}
   return null;
 }
+function readBoundReceiptOutcome(agent, step, resolved) {
+  if (!agent || !resolved) return { outcome: null, receiptRequired: false };
+  const manifestPath = path.join(taskDir, 'artifact-manifest.json');
+  if (!fs.existsSync(manifestPath)) return { outcome: null, receiptRequired: false };
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+    const expectedOutputId = artifactOutputIdFor(step, agent);
+    const attemptStartedAt = Date.parse(resolved.entry.startedAt);
+    const owned = artifacts
+      .filter((entry) => {
+        if (!entry || entry.producer !== agent || !entry.receipt || typeof entry.receipt.outcome !== 'string') return false;
+        const boundByAttempt = typeof entry.receipt.attemptId === 'string' && entry.receipt.attemptId === resolved.attemptId;
+        const boundByOutput = entry.receipt.attemptId == null && entry.id === expectedOutputId;
+        if (!boundByAttempt && !boundByOutput) return false;
+        const terminalAt = Date.parse(entry.timestamps?.completedAt || entry.timestamps?.updatedAt || '');
+        return Number.isFinite(terminalAt) && (!Number.isFinite(attemptStartedAt) || terminalAt >= attemptStartedAt);
+      })
+      .sort((a, b) => {
+        const ta = Date.parse(a.timestamps?.completedAt || a.timestamps?.updatedAt || 0) || 0;
+        const tb = Date.parse(b.timestamps?.completedAt || b.timestamps?.updatedAt || 0) || 0;
+        return tb - ta;
+      });
+    return { outcome: owned[0]?.receipt?.outcome || null, receiptRequired: true };
+  } catch {
+    return { outcome: null, receiptRequired: false };
+  }
+}
+function reconcileStatusFromManifest(agent, step, resolved) {
+  const terminal = new Set(['completed', 'blocked', 'changes_requested', 'validation_failed']);
+  const { outcome, receiptRequired } = readBoundReceiptOutcome(agent, step, resolved);
+  if (terminal.has(outcome)) {
+    status.state = outcome;
+    return outcome;
+  }
+  if (receiptRequired) {
+    status.state = 'awaiting_artifact_receipt';
+    status.phase = 'blocked';
+    return status.state;
+  }
+  if (terminal.has(status.state)) return status.state;
+  // Host reported subagent completed and no blocking receipt → treat as completed for metrics/advance.
+  if (hookInput.status === 'completed') {
+    status.state = 'completed';
+    return 'completed';
+  }
+  return status.state;
+}
+
 function finishActiveAttempt() {
   const resolved = resolvedAttempt(); if (!resolved) return null;
   const durationMs = Date.parse(now) - Date.parse(resolved.entry.startedAt);
-  appendMetric({ type: 'attempt_finished', at: now, attemptId: resolved.attemptId, outcome: ['completed', 'changes_requested', 'validation_failed'].includes(status.state) ? status.state : 'unknown', durationMs: Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : null, retryAfterFix: status.retryAfterFix || null, source: resolved.source || 'hook', attributionConfidence: resolved.confidence });
-  const active = { ...(status.activeAttempts || {}) }; delete active[resolved.attemptId]; status.activeAttempts = active; status.lastCompletedAttempt = { attemptId: resolved.attemptId, completedAt: now }; return resolved;
+  const outcome = ['completed', 'blocked', 'changes_requested', 'validation_failed'].includes(status.state) ? status.state : 'unknown';
+  appendMetric({ type: 'attempt_finished', at: now, attemptId: resolved.attemptId, outcome, durationMs: Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : null, retryAfterFix: status.retryAfterFix || null, source: resolved.source || 'hook', attributionConfidence: resolved.confidence });
+  const active = { ...(status.activeAttempts || {}) }; delete active[resolved.attemptId]; status.activeAttempts = active; status.lastCompletedAttempt = { attemptId: resolved.attemptId, completedAt: now }; return { ...resolved, outcome };
 }
 function beginHumanGate() { const eventId = `${status.metricsRunId || slug}:gate:${Date.now()}`; appendMetric({ eventId, type: 'human_gate_started', at: now, source: 'hook', attributionConfidence: 'high' }); status.activeHumanGateEventId = eventId; }
 function endHumanGateIfResumed() {
@@ -217,56 +288,56 @@ function findNextExecutableStep(steps, startIdx, dir) {
 const AGENT_HANDOFF = {
   'task-analyst': (s) =>
     `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .cursor/team/tasks/${s}/. ` +
-    `Set status.json: phase executing, state awaiting_approval if human gate applies. Do not use legacy phase analysis.`,
+    `Upsert the analysis receipt in artifact-manifest.json; do not mutate status.json lifecycle fields. Do not use legacy phase analysis.`,
   debugger: (s) =>
     `Invoke debugger subagent for slug "${s}". Investigate root cause; write debug-report.md with fixApplied: true/false. ` +
-    `Update status.json when done.`,
+    `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'solution-architect': (s) =>
-    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md. Update status.json when done.`,
+    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'migration-specialist': (s) =>
-    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md. Update status.json when done.`,
+    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'api-contract-reviewer': (s) =>
-    `Invoke api-contract-reviewer (readonly) for slug "${s}". Write api-contract-review.md. Update status.json when done.`,
+    `Invoke api-contract-reviewer (readonly) for slug "${s}". Write api-contract-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'ci-investigator': (s) =>
     `Invoke ci-investigator for slug "${s}". Diagnose CI failure; write ci-report.md; apply minimal fix. ` +
-    `Use ci-investigation skill. Update status.json when done.`,
+    `Use ci-investigation skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'feature-developer': (s) =>
     `Invoke feature-developer for slug "${s}". Read brief.md, decomposition.md, validation-report.md, review.md, architecture.md, migration-plan.md, api-contract-review.md, debug-report.md if present. ` +
     `Follow feature-delivery-workflow.mdc and reference-features.mdc. Prefer Features/Presentation/Domain/Data (or SPM module) paths over app/src. ` +
-    `Include XCTest/Swift Testing unit coverage for mappers/logic before handoff. Update status.json when done.`,
+    `Include XCTest/Swift Testing unit coverage for mappers/logic before handoff. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'build-verifier': (s) =>
     `Invoke build-verifier (readonly) for slug "${s}". Follow xcode-tooling.mdc and post-change-build.mdc. ` +
     `Run xcodebuild (or swift build/test for SPM-only), SwiftLint/SwiftFormat if configured, and targeted unit smoke — never yarn/ESLint/Stylelint from app/. ` +
-    `Write validation-report.md. Set state completed or validation_failed. Do not edit production code.`,
+    `Write validation-report.md and emit receipt outcome completed or validation_failed. Do not edit production code.`,
   'accessibility-reviewer': (s) =>
-    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review Presentation/SwiftUI (or UIKit) diff for VoiceOver/Dynamic Type/accessibilityIdentifier; write a11y-review.md. Update status.json when done.`,
+    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review Presentation/SwiftUI (or UIKit) diff for VoiceOver/Dynamic Type/accessibilityIdentifier; write a11y-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'performance-auditor': (s) =>
-    `Invoke performance-auditor (readonly) for slug "${s}". Audit launch/SwiftUI performance risks; write perf-report.md. Update status.json when done.`,
+    `Invoke performance-auditor (readonly) for slug "${s}". Audit launch/SwiftUI performance risks; write perf-report.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'code-reviewer': (s) =>
     `Invoke code-reviewer subagent (readonly) for slug "${s}". Review git diff vs brief.md per code-review-mr.mdc. ` +
-    `Update status.json when done.`,
+    `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'security-reviewer': (s) =>
-    `Invoke security-reviewer (readonly) for slug "${s}". Write security-review.md. Update status.json when done.`,
+    `Invoke security-reviewer (readonly) for slug "${s}". Write security-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'qa-tester': (s, scope) =>
     `Invoke qa-tester for slug "${s}"${scope ? ` (scope: ${scope})` : ''}. ` +
-    `Add/update XCTest and XCUITest (*UITests) per brief. Follow tests-ui.mdc and skill xcuitest-e2e. Update status.json when done.`,
+    `Add/update XCTest and XCUITest (*UITests) per brief. Follow tests-ui.mdc and skill xcuitest-e2e. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-planner': (s) =>
-    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md for XCTest/Swift Testing. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md for XCTest/Swift Testing. Use unit-testing skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-generator': (s) =>
-    `Invoke unit-test-generator for slug "${s}". Implement *Tests from unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-generator for slug "${s}". Implement *Tests from unit-test-plan.md. Use unit-testing skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-healer': (s) =>
-    `Invoke unit-test-healer for slug "${s}". Fix failing unit tests. Use unit-testing and debug-investigation skills. Update status.json when done.`,
+    `Invoke unit-test-healer for slug "${s}". Fix failing unit tests. Use unit-testing and debug-investigation skills. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'xcuitest-test-planner': (s) =>
     `Invoke xcuitest-test-planner for slug "${s}". Create/update XCUITest plans (*UITests / *.cases.md if used). ` +
-    `Follow tests-ui.mdc and the xcuitest-e2e skill. Do not use Playwright MCP. Update status.json when done.`,
+    `Follow tests-ui.mdc and the xcuitest-e2e skill. Do not use Playwright MCP. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'xcuitest-test-generator': (s) =>
     `Invoke xcuitest-test-generator for slug "${s}". Generate/update *UITests from matching plans/*.cases.md. ` +
-    `Follow tests-ui.mdc and the xcuitest-e2e skill. Do not use Playwright MCP. Update status.json when done.`,
+    `Follow tests-ui.mdc and the xcuitest-e2e skill. Do not use Playwright MCP. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'xcuitest-test-healer': (s) =>
     `Invoke xcuitest-test-healer for slug "${s}". Fix failing/flaky XCUITest while preserving plan assertions. ` +
-    `Follow tests-ui.mdc, xcuitest-e2e, and debug-investigation. Do not use Playwright MCP. Update status.json when done.`,
+    `Follow tests-ui.mdc, xcuitest-e2e, and debug-investigation. Do not use Playwright MCP. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'tech-writer': (s) =>
-    `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Update status.json when done.`,
+    `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
 };
 
 const REVIEW_AGENTS = new Set([
@@ -279,15 +350,20 @@ const REVIEW_AGENTS = new Set([
 function metricsHandoff(agent) {
   const matches = Object.entries(status.activeAttempts || {}).filter(([, entry]) => entry.agent === agent);
   if (matches.length === 1) {
-    return ` Metrics attemptId: ${matches[0][0]}; update normal status only. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not calculate duration.`;
+    return ` Metrics attemptId: ${matches[0][0]}; write owned artifact-manifest receipt outcome. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not mutate status.json or calculate duration.`;
   }
   return ' Metrics: use the supplied attemptId when available; for a parallel completion, write a minimal { attemptId, outcome } receipt to .metrics-receipts.json rather than relying on currentAgent. Do not calculate duration.';
 }
 
-function handoffForAgent(agent, scope) {
+function artifactHandoff(step, agent) {
+  const inputIds = Array.isArray(step?.artifactInputIds) ? step.artifactInputIds.join(', ') : 'manifest defaults';
+  return ` Artifact inputs: ${inputIds}; owned output ID: ${artifactOutputIdFor(step, agent)}. Bind the terminal receipt to the supplied attemptId.`;
+}
+
+function handoffForAgent(agent, scope, step = null) {
   const fn = AGENT_HANDOFF[agent];
-  const handoff = fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
-  return handoff + metricsHandoff(agent);
+  const handoff = fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`;
+  return handoff + artifactHandoff(step, agent) + metricsHandoff(agent);
 }
 
 function handoffForParallelStep(step) {
@@ -297,7 +373,8 @@ function handoffForParallelStep(step) {
     .map(([attemptId, entry]) => `${entry.agent}=${attemptId}`);
   return (
     `Invoke IN PARALLEL (one message, multiple Task calls): ${agents.join(' AND ')} for slug "${slug}". ` +
-    `Each agent writes its artifact and appends itself to status.json parallelCompleted when done. ` +
+    `Each agent writes its artifact and owned receipt; the hook records parallelCompleted from stops. Do not mutate status.json lifecycle fields. ` +
+    `Artifact inputs: ${Array.isArray(step.artifactInputIds) ? step.artifactInputIds.join(', ') : 'manifest defaults'}; owned output IDs: ${agents.map((agent) => `${agent}=${artifactOutputIdFor(step, agent)}`).join('; ')}. ` +
     `Metrics attemptIds: ${attemptIds.join('; ')}. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not calculate duration.`
   );
 }
@@ -336,8 +413,12 @@ function legacyFlow() {
     appendMetric({ type: 'retry_scheduled', at: now, attemptId: predecessorAttemptId, nextAgent: agent, retryAfterFix: retryAfterFix || null, source: 'hook', attributionConfidence: 'unknown' });
     activateAttempts({ agent }, stepIndex);
   }
-  if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
+  if (status.state === 'changes_requested') {
     const reviewer = status.currentAgent;
+    if (!reviewer) {
+      process.stdout.write('{}');
+      process.exit(0);
+    }
     scheduleLegacyRetry('feature-developer', reviewer);
     writeStatus({
       currentAgent: 'feature-developer',
@@ -411,7 +492,7 @@ if (hookInput.action === 'end_human_gate') {
           parallelCompleted: [],
         });
         if (resumeNext.step.parallel && resumeAgents.length > 1) out(handoffForParallelStep(resumeNext.step));
-        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope));
+        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
     }
@@ -440,6 +521,19 @@ const steps = pipeline.steps || [];
 const initialIdx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
 const initialStep = steps[initialIdx];
 const activeAttemptCountBeforeFinish = Object.keys(status.activeAttempts || {}).length;
+const completingAgentHint = (() => {
+  const resolved = resolvedAttempt();
+  if (resolved?.entry?.agent) return resolved.entry.agent;
+  if (status.currentAgent) return status.currentAgent;
+  return getStepAgents(initialStep)[0];
+})();
+const reconcilingAttempt = resolvedAttempt();
+reconcileStatusFromManifest(completingAgentHint, initialStep, reconcilingAttempt);
+if (status.state === 'awaiting_artifact_receipt') {
+  writeStatus({});
+  process.stdout.write('{}');
+  process.exit(0);
+}
 const finishedAttempt = finishActiveAttempt();
 if (!finishedAttempt && (hookInput.attemptId || activeAttemptCountBeforeFinish > 0)) {
   process.stdout.write('{}');
@@ -447,6 +541,7 @@ if (!finishedAttempt && (hookInput.attemptId || activeAttemptCountBeforeFinish >
 }
 endHumanGateIfResumed();
 if (steps.length === 0 || pipeline.autoChain === false) {
+  writeStatus({});
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -472,8 +567,73 @@ function scheduleRetry(agent, retryAfterFix, predecessor, explicitStepIndex = nu
   return stepIndex;
 }
 
-if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
-  const reviewer = status.currentAgent;
+const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+const currentStep = steps[idx];
+const completedAgent = finishedAttempt?.entry?.agent || status.currentAgent || getStepAgents(currentStep)[0];
+const stepAgents = getStepAgents(currentStep);
+
+if (currentStep?.parallel && stepAgents.length > 1) {
+  const done = [...(status.parallelCompleted || [])];
+  const outcomes = { ...(status.parallelOutcomes || {}) };
+  if (finishedAttempt && completedAgent) {
+    if (!done.includes(completedAgent)) done.push(completedAgent);
+    outcomes[completedAgent] = {
+      outcome: finishedAttempt.outcome || status.state,
+      attemptId: finishedAttempt.attemptId,
+      confidence: finishedAttempt.confidence,
+    };
+  }
+  writeStatus({ parallelCompleted: done, parallelOutcomes: outcomes });
+  const remaining = stepAgents.filter((agent) => !done.includes(agent));
+  if (remaining.length > 0) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  const blockedProducer = stepAgents.find((agent) => outcomes[agent]?.outcome === 'blocked');
+  if (blockedProducer) {
+    writeStatus({ parallelCompleted: [], parallelOutcomes: {}, state: 'blocked', phase: 'blocked', currentAgent: blockedProducer });
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+
+  const retryReviewer = stepAgents.find((agent) => outcomes[agent]?.outcome === 'changes_requested');
+  if (retryReviewer) {
+    const retryAfterFixStepIndex = idx;
+    const predecessor = outcomes[retryReviewer]
+      ? {
+          attemptId: outcomes[retryReviewer].attemptId,
+          confidence: outcomes[retryReviewer].confidence,
+        }
+      : finishedAttempt;
+    const developerIndex = scheduleRetry('feature-developer', retryReviewer, predecessor);
+    writeStatus({
+      pipelineIndex: developerIndex,
+      currentAgent: 'feature-developer',
+      state: 'in_progress',
+      phase: 'executing',
+      retryAfterFix: retryReviewer,
+      retryAfterFixStepIndex,
+      parallelCompleted: [],
+      parallelOutcomes: {},
+    });
+    out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ` After fixes, re-run ${retryReviewer}.`);
+    process.exit(0);
+  }
+  writeStatus({ parallelCompleted: [], parallelOutcomes: {}, state: 'completed' });
+}
+
+if (status.state === 'blocked') {
+  writeStatus({ state: 'blocked', phase: 'blocked', currentAgent: completedAgent });
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (status.state === 'changes_requested') {
+  const reviewer = status.currentAgent || finishedAttempt?.entry?.agent;
+  if (!reviewer) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
   const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
   const developerIndex = scheduleRetry('feature-developer', reviewer, finishedAttempt);
   writeStatus({
@@ -484,7 +644,7 @@ if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgen
     retryAfterFix: reviewer,
     retryAfterFixStepIndex,
   });
-  out(handoffForAgent('feature-developer') + ` After fixes, re-run ${reviewer}.`);
+  out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ` After fixes, re-run ${reviewer}.`);
   process.exit(0);
 }
 
@@ -499,7 +659,7 @@ if (status.state === 'validation_failed' && status.currentAgent === 'build-verif
     retryAfterFix: 'build-verifier',
     retryAfterFixStepIndex,
   });
-  out(handoffForAgent('feature-developer') + ' Read validation-report.md. After fixes, re-run build-verifier.');
+  out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ' Read validation-report.md. After fixes, re-run build-verifier.');
   process.exit(0);
 }
 
@@ -507,35 +667,16 @@ if (status.state === 'completed' && status.retryAfterFix) {
   const retry = status.retryAfterFix;
   const retryIndex = scheduleRetry(retry, null, finishedAttempt, status.retryAfterFixStepIndex);
   writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
-  out(handoffForAgent(retry));
+  out(handoffForAgent(retry, steps[retryIndex]?.scope, steps[retryIndex]));
   process.exit(0);
 }
 
-const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
-const currentStep = steps[idx];
 if (!currentStep) {
   writeStatus({ phase: 'done', state: 'completed', currentAgent: null });
   out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
   process.exit(0);
 }
 
-const completedAgent = finishedAttempt?.entry?.agent || status.currentAgent || getStepAgents(currentStep)[0];
-const stepAgents = getStepAgents(currentStep);
-
-if (currentStep.parallel && stepAgents.length > 1) {
-  const done = [...(status.parallelCompleted || [])];
-  if (completedAgent && !done.includes(completedAgent)) {
-    done.push(completedAgent);
-  }
-  writeStatus({ parallelCompleted: done });
-  const remaining = stepAgents.filter((a) => !done.includes(a));
-  if (remaining.length > 0) {
-    process.stdout.write('{}');
-    process.exit(0);
-  }
-  writeStatus({ parallelCompleted: [] });
-}
-
 if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
   beginHumanGate();
   writeStatus({
@@ -577,6 +718,6 @@ writeStatus({
 if (nextStep.parallel && nextAgents.length > 1) {
   out(handoffForParallelStep(nextStep));
 } else {
-  out(handoffForAgent(nextAgents[0], nextStep.scope));
+  out(handoffForAgent(nextAgents[0], nextStep.scope, nextStep));
 }
 NODE