@bonesofspring/ai-rules 0.2.12 → 0.2.14

package/presets/claude/php-hexagonal/agents/build-verifier.md

@@ -12,8 +12,8 @@ You are the build verifier for **PHP hexagonal** services (and for **ai-rules pr
 1. Detect Composer from `composer.json` / `composer.lock`; prefer Composer scripts when present.
 2. Run from module/project root: `composer test` or `vendor/bin/phpunit` (or Pest if that is the repo default / CI).
 3. If present in **repo or CI**: formatter + static analysis (PHP-CS-Fixer, Pint, PHPStan, Psalm, or project-equivalent) per `php-tooling` / `post-change-test`. Mirror CI gates locally when configs/scripts exist; do **not** invent a tool the repo does not use.
-4. Write `.cursor/team/tasks/<slug>/validation-report.md` (or `.claude/team/...`) with commands + results.
-5. On failure: set status `validation_failed` — do **not** patch production code (developer retries).
+4. Write `.claude/team/tasks/<slug>/validation-report.md` with commands + results.
+5. On failure: emit receipt outcome `validation_failed` — do **not** patch production code (developer retries).
 
 **Never** require Playwright, XCUITest, `lint:js`/`lint:css`, `xcodebuild`/`SwiftLint`, `mvn`, or `gradlew` as the PHP gate.
 
@@ -36,10 +36,17 @@ Hard gates for the **php-hexagonal** stack (and peers):
 
 Also document:
 
-1. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java|mcp-ts|php-hexagonal`) must ship `REPO_AGENTS.md` → **FAIL** if missing.
+1. **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` → **FAIL** if missing.
 2. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
 3. **No react-performance / Playwright / a11y on backend stacks:** skill directory / required handoff must be absent under go, java, php-hexagonal, php-laravel, mcp-ts → **FAIL** (leakage). Prefer `check:preset-leakage`.
 4. **Shared-core drift (hard in `check:preset-structure`):** `check-shared-core-drift` with `AI_RULES_DRIFT_FAIL=1`.
 5. **Rule eval (WARN):** `yarn check:rule-eval` is **next-only** (`eval/next/`); optional for maintainers; not part of default `check:preset-structure`. Missing php-hexagonal eval stems is not a FAIL.
 
 Document PASS/FAIL in `validation-report.md`.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/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/claude/php-hexagonal/agents/code-reviewer.md

@@ -33,8 +33,15 @@ Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundari
 
 ## Artifact
 
-Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update `status.json` accordingly.
+Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
 
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/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/claude/php-hexagonal/agents/feature-developer.md

@@ -36,7 +36,7 @@ Implement PHP features following hexagonal boundaries.
 
 When editing ai-rules `presets/**/php-hexagonal/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift/go/java/mcp-ts (see `preset-no-cross-stack-leakage`).
 
-Update `.claude/team/tasks/<slug>/implementation.md` and `status.json`.
+Update `.claude/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
 
 ## Design guidance
 
@@ -45,3 +45,10 @@ Update `.claude/team/tasks/<slug>/implementation.md` and `status.json`.
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/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/claude/php-hexagonal/agents/task-analyst.md

@@ -18,8 +18,15 @@ Use domain, application/ports, driving/driven adapters, composition root — not
 
 ## Gates
 
-Set `awaiting_approval` when humanGates require it after analysis.
+Emit an analysis receipt; the runtime applies any configured human gate.
 
 ## 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 `.claude/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/claude/php-hexagonal/agents/task-router.md

@@ -39,6 +39,27 @@ You are a task router for a **PHP hexagonal backend** agent team. You **do not**
 
 **Never skip `build-verifier`** after developer when PHP 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 integration-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 other presets:
@@ -62,12 +83,19 @@ Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/pipeline.json` and initial `status.json` via the **Write** tool (creates parents; do not Shell-`mkdir`); set `.claude/team/active-task.json`.
+Write `.claude/team/tasks/<slug>/pipeline.json` and initialize the routing entry in `artifact-manifest.json`; set `.claude/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 `.claude/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/claude/php-hexagonal/commands/task.md

@@ -24,14 +24,16 @@ description: Route a natural-language task through the agent-team pipeline: task
 
 ## Алгоритм
 
-1. **Slug** — kebab-case из описания (≤48 символов). Создай `.claude/team/tasks/<slug>/` через запись файла (Write / Edit) — **не** полагайся на Shell `mkdir` как единственный способ создать каталог.
+1. **Slug** — kebab-case из описания (≤48 символов). Создай `.claude/team/tasks/<slug>/` через запись файла (Write / Edit); runtime/hook владеет `status.json` — **не** полагайся на Shell `mkdir` как единственный способ создать каталог.
 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>`).
 
 ## Не делать
 
@@ -50,4 +52,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/claude/php-hexagonal/hooks/README.md

@@ -13,4 +13,4 @@ Claude Code may not use Cursor `hooks.json`. Wire scripts per project docs when
 
 Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
 
-To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **java**). Cursor twin examples under `presets/cursor/php-hexagonal/hooks/examples/` are the same allowlist forks.
+To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **php-hexagonal**). Cursor twin examples under `presets/cursor/php-hexagonal/hooks/examples/` are the same allowlist forks.

package/presets/claude/php-hexagonal/hooks/chain-team-phases.sh

@@ -124,6 +124,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;
@@ -146,11 +167,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() {
@@ -219,54 +290,54 @@ function findNextExecutableStep(steps, startIdx, dir) {
 const AGENT_HANDOFF = {
   'task-analyst': (s) =>
     `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .claude/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 with composer test / vendor/bin/phpunit / logs; 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 for PHP hexagonal layers. Update status.json when done.`,
+    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md for PHP hexagonal layers. 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 for PHP build/toolchain. Update status.json when done.`,
+    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md for PHP build/toolchain. 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}". Review OpenAPI/Protobuf vs adapters; write api-contract-review.md. Update status.json when done.`,
+    `Invoke api-contract-reviewer (readonly) for slug "${s}". Review OpenAPI/Protobuf vs adapters; 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 (composer test / vendor/bin/phpunit / phpstan or preset-structure); 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 src domain|application|adapters and Composition/Composition/* composition root. ` +
-    `Include PHPUnit/Pest via composer test coverage for domain/use cases before handoff. Update status.json when done.`,
+    `Include PHPUnit/Pest via composer test coverage for domain/use cases 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 php-tooling.mdc and post-change-test.mdc. ` +
     `Run composer test / vendor/bin/phpunit and configured static analysis if present in repo/CI — never yarn/ESLint/Stylelint. ` +
-    `For preset packaging: yarn check:preset-structure. Write validation-report.md. Set state completed or validation_failed. Do not edit production code.`,
+    `For preset packaging: yarn check:preset-structure. Write validation-report.md and emit receipt outcome completed or validation_failed. Do not edit production code.`,
   'performance-auditor': (s) =>
-    `Invoke performance-auditor (readonly) for slug "${s}". Audit PHP hot paths/allocs/DB N+1/profiler/JFR risks; write perf-report.md. Update status.json when done.`,
+    `Invoke performance-auditor (readonly) for slug "${s}". Audit PHP hot paths/allocs/DB N+1/profiler/JFR 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 (hexagonal boundaries). ` +
-    `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}". Follow security-php.mdc; write security-review.md. Update status.json when done.`,
+    `Invoke security-reviewer (readonly) for slug "${s}". Follow security-php.mdc; 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 PHPUnit unit and integration tests per brief. Follow tests-unit.mdc, tests-integration.mdc, and skill integration-testing. Update status.json when done.`,
+    `Add/update PHPUnit unit and integration tests per brief. Follow tests-unit.mdc, tests-integration.mdc, and skill integration-testing. 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 PHPUnit/Pest via composer test. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md for PHPUnit/Pest via composer test. 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 *Test.php / *Tests.php from unit-test-plan.md under tests. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-generator for slug "${s}". Implement *Test.php / *Tests.php from unit-test-plan.md under tests. 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.`,
   'integration-test-planner': (s) =>
     `Invoke integration-test-planner for slug "${s}". Create/update integration test plans (HTTP controller tests/integration DB fixtures/testcontainers/adapter contracts). ` +
-    `Follow tests-integration.mdc and the integration-testing skill. Do not use browser e2e tooling. Update status.json when done.`,
+    `Follow tests-integration.mdc and the integration-testing skill. Do not use browser e2e tooling. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'integration-test-generator': (s) =>
     `Invoke integration-test-generator for slug "${s}". Generate/update *IT.php / *IntegrationTest.php from plans. ` +
-    `Follow tests-integration.mdc and the integration-testing skill. Do not use browser e2e tooling. Update status.json when done.`,
+    `Follow tests-integration.mdc and the integration-testing skill. Do not use browser e2e tooling. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'integration-test-healer': (s) =>
     `Invoke integration-test-healer for slug "${s}". Fix failing/flaky integration tests while preserving plan assertions. ` +
-    `Follow tests-integration.mdc, integration-testing, and debug-investigation. Do not use browser e2e tooling. Update status.json when done.`,
+    `Follow tests-integration.mdc, integration-testing, and debug-investigation. Do not use browser e2e tooling. 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,74 @@ 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 +645,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 +660,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 +668,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 +719,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