@bonesofspring/ai-rules 0.2.12 → 0.2.13

package/presets/cursor/php-laravel/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 .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 with php artisan test / composer test / 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 Laravel layers. Update status.json when done.`,
+    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md for Laravel 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 (if present) vs routes/Resources/Form Requests; write api-contract-review.md. Update status.json when done.`,
+    `Invoke api-contract-reviewer (readonly) for slug "${s}". Review OpenAPI (if present) vs routes/Resources/Form Requests; 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 (php artisan test / composer test / 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 Laravel paths: routes → Form Request → Action/Service → Eloquent → Feature test (app/, routes/, tests/). ` +
-    `Include PHPUnit/Pest via php artisan test / composer test (Unit + Feature) before handoff. Update status.json when done.`,
+    `Include PHPUnit/Pest via php artisan test / composer test (Unit + Feature) 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 php artisan test / composer test 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 Laravel hot paths, Eloquent N+1, queue backlog; Blackfire/Xdebug/Telescope/query log if present; write perf-report.md. Update status.json when done.`,
+    `Invoke performance-auditor (readonly) for slug "${s}". Audit Laravel hot paths, Eloquent N+1, queue backlog; Blackfire/Xdebug/Telescope/query log if present; 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 (Laravel 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 Feature/integration test plans (HTTP Feature tests / DB fixtures / external HTTP fakes / Bus::fake Event::fake). ` +
-    `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 Feature tests (*Test.php under tests/Feature) 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 Feature/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

package/presets/cursor/php-laravel/rules/agent-team-orchestrator.mdc

@@ -35,7 +35,7 @@ Roster of specialists is **stack-specific** (agent names and write scopes differ
 
 **Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write team artifacts. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true`.
 
-Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`.
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
 
 ## Dynamic pipeline
 
@@ -61,9 +61,21 @@ flowchart TD
 
 **Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
 
+New pipelines retain top-level `profile` and include `routingDecision` with `complexity`, `riskFlags`, non-empty `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`. The stack `task-router` owns heuristics; this metadata is auditable evidence and does not change hook semantics.
+
 ## Metrics lifecycle
 
-Use the local `metrics.json` ledger described by **agent-task-metrics**: initialize attempts before invocation, let hooks record host-clock ends, and never guess a parallel completion from `currentAgent`.
+Use the local `metrics.json` ledger described by **agent-task-metrics**: the orchestration runtime initializes attempts before invocation, hooks record host-clock ends, and agents never guess a parallel completion from `currentAgent`.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. Schema SoT: **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 
 ## status.json (pipeline mode)
 
@@ -75,10 +87,23 @@ Use the local `metrics.json` ledger described by **agent-task-metrics**: initial
   "currentAgent": "task-analyst",
   "phase": "executing",
   "state": "in_progress",
-  "awaitingHumanGate": false
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
 }
 ```
 
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt when agents left lifecycle fields untouched. Wait for that handoff before invoking the next step.
+
 | state | Meaning |
 |-------|---------|
 | `in_progress` | Current step running |
@@ -102,7 +127,7 @@ Use the local `metrics.json` ledger described by **agent-task-metrics**: initial
 2. Read `pipeline.json` before every subagent invocation.
 3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
 4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
-5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`).
+5. Persist handoffs to disk and update the producer-owned terminal receipt in `artifact-manifest.json`; Markdown remains detailed evidence.
 6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
 7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
 8. When all steps complete, suggest `/technical-retro <slug>`.
@@ -127,7 +152,7 @@ Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
    - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
 3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
 
-After each agent completes, ensure `status.json` has `state: completed` (or `awaiting_approval` if gate applies).
+After each agent completes, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
 
 ## Legacy mode
 

package/presets/cursor/php-laravel/team/README.md

@@ -8,10 +8,21 @@
 | `feature-light.json` | developer → build-verifier (`php artisan test` / configured static analysis) |
 | `bugfix-standard.json` | debugger → fix → build-verifier |
 
+## 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.