@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/claude/next/hooks/chain-team-phases.sh

@@ -50,6 +50,8 @@ if (!slug) {
 const taskDir = path.join(TEAM_ROOT, 'tasks', slug);
 const statusPath = path.join(taskDir, 'status.json');
 const pipelinePath = path.join(taskDir, 'pipeline.json');
+const METRICS_PATH = path.join(taskDir, 'metrics.json');
+const METRICS_LOCK = `${METRICS_PATH}.lock`;
 
 if (!fs.existsSync(statusPath)) {
   process.stdout.write('{}');
@@ -57,18 +59,190 @@ if (!fs.existsSync(statusPath)) {
 }
 
 let status;
+const now = new Date().toISOString();
+const STACK = 'next';
+const PLATFORM = 'claude';
+
+function waitForMetricsLock() {
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    try { fs.mkdirSync(METRICS_LOCK); return; } catch (error) {
+      if (error && error.code !== 'EEXIST') throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  throw new Error('metrics lock timeout');
+}
+let taskLockHeld = false;
+function releaseTaskLock() {
+  if (!taskLockHeld) return;
+  taskLockHeld = false;
+  try { fs.rmdirSync(METRICS_LOCK); } catch {}
+}
+waitForMetricsLock();
+taskLockHeld = true;
+process.on('exit', releaseTaskLock);
 try {
   status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
 } catch {
+  releaseTaskLock();
   process.stdout.write('{}');
   process.exit(0);
 }
+function mutateMetrics(mutator) {
+  const acquiredHere = !taskLockHeld;
+  if (acquiredHere) waitForMetricsLock();
+  try {
+    let metrics;
+    try { metrics = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8')); } catch {
+      const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+      status.metricsRunId = runId;
+      metrics = { schemaVersion: 1, task: { runId, slug, preset: 'ai-rules', stack: STACK, platform: PLATFORM, intent: status.intent || 'unknown', profile: 'unknown' }, events: [] };
+      metrics.events.push({ eventId: `${runId}:task_started`, type: 'task_started', at: now, source: 'hook', attributionConfidence: 'high' });
+    }
+    mutator(metrics);
+    const temporary = `${METRICS_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(metrics, null, 2) + '\n');
+    fs.renameSync(temporary, METRICS_PATH);
+  } finally {
+    if (acquiredHere) { try { fs.rmdirSync(METRICS_LOCK); } catch {} }
+  }
+}
+function appendMetric(event) { mutateMetrics((metrics) => metrics.events.push({ eventId: `${metrics.task.runId}:${Date.now()}:${Math.random().toString(16).slice(2)}`, ...event })); }
+function nextAttemptOrdinal(stepIndex, agent) {
+  try {
+    const metrics = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+    return metrics.events.reduce((highest, event) => event.type === 'attempt_started' && event.stepIndex === stepIndex && event.agent === agent ? Math.max(highest, Number(event.attempt) || 0) : highest, 0) + 1;
+  } catch { return 1; }
+}
+function roleFor(agent) {
+  if (/analyst|architect|router|migration/.test(agent || '')) return 'planning';
+  if (/verifier/.test(agent || '')) return 'validation';
+  if (/reviewer|auditor/.test(agent || '')) return 'review';
+  if (/test|qa/.test(agent || '')) return 'testing';
+  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;
+  for (const agent of agents) {
+    const attempt = nextAttemptOrdinal(stepIndex, agent); const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    status.metricsRunId = runId; const attemptId = `${runId}:step-${stepIndex}:${agent}:attempt-${attempt}`;
+    if (active[attemptId]) continue;
+    active[attemptId] = { agent, stepIndex, attempt, startedAt: now, parallelGroupId };
+    appendMetric({ type: 'attempt_started', at: now, attemptId, stepIndex, stepLabel: step.label || null, agent, role: roleFor(agent), attempt, parallelGroupId, source: 'hook', attributionConfidence: 'high' });
+  }
+  status.activeAttempts = active;
+}
+function resolvedAttempt() {
+  const active = status.activeAttempts || {}; const entries = Object.entries(active);
+  const stableAttemptId = hookInput.attemptId;
+  if (stableAttemptId) {
+    return active[stableAttemptId] ? { attemptId: stableAttemptId, entry: active[stableAttemptId], confidence: 'high' } : null;
+  }
+  if (entries.length === 1) return { attemptId: entries[0][0], entry: entries[0][1], confidence: 'high' };
+  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);
+  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() {
+  if (!status.activeHumanGateEventId || status.awaitingHumanGate || status.state === 'awaiting_approval') return;
+  appendMetric({ type: 'human_gate_ended', at: now, gateStartedEventId: status.activeHumanGateEventId, source: 'hook', attributionConfidence: 'high' });
+  delete status.activeHumanGateEventId;
+}
+function completeTaskMetrics() { appendMetric({ type: 'task_completed', at: now, outcome: status.state === 'completed' ? 'completed' : 'unknown', source: 'hook', attributionConfidence: 'high' }); }
+function recordSkippedStep(step, stepIndex) {
+  for (const agent of getStepAgents(step)) {
+    const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    status.metricsRunId = runId;
+    const attempt = nextAttemptOrdinal(stepIndex, agent);
+    appendMetric({ type: 'attempt_skipped', at: now, attemptId: `${runId}:step-${stepIndex}:${agent}:attempt-${attempt}`, stepIndex, stepLabel: step.label || null, agent, role: roleFor(agent), attempt, outcome: 'skipped', source: 'hook', attributionConfidence: 'high' });
+  }
+}
 
-const now = new Date().toISOString();
 
 function writeStatus(next) {
   status = { ...status, ...next, slug, updatedAt: now };
-  fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
+  const temporary = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(status, null, 2) + '\n');
+  fs.renameSync(temporary, statusPath);
 }
 
 function out(message) {
@@ -105,9 +279,8 @@ function skipIfMatches(skipIf, dir) {
 
 function findNextExecutableStep(steps, startIdx, dir) {
   for (let i = startIdx; i < steps.length; i++) {
-    if (!skipIfMatches(steps[i].skipIf, dir)) {
-      return { step: steps[i], index: i };
-    }
+    if (!skipIfMatches(steps[i].skipIf, dir)) return { step: steps[i], index: i };
+    recordSkippedStep(steps[i], i);
   }
   return null;
 }
@@ -115,54 +288,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; 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 architecture/feature-delivery-workflow.md and architecture/reference-features.md. Include unit tests for mappers/logic before handoff. Update status.json when done.`,
+    `Follow architecture/feature-delivery-workflow.md and architecture/reference-features.md. Include unit tests 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}". Run lint:js, lint:css, type-check, and targeted unit tests 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 UI diff; write a11y-review.md. Update status.json when done.`,
+    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review UI diff; 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}". Write perf-report.md. Update status.json when done.`,
+    `Invoke performance-auditor (readonly) for slug "${s}". 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 tooling-and-review/code-review-mr.md. ` +
-    `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 tests per brief. Follow testing/playwright-agents.md. Update status.json when done.`,
+    `Add/update tests per brief. Follow testing/playwright-agents.md. 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. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-planner for slug "${s}". Write 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-generator': (s) =>
-    `Invoke unit-test-generator for slug "${s}". Implement specs from unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-generator for slug "${s}". Implement specs 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.`,
   'playwright-test-planner': (s) =>
     `Invoke playwright-test-planner for slug "${s}". Create/update app/__tests__/e2e/**/*.cases.md. ` +
-    `Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+    `Follow testing/playwright-agents.md and the playwright-e2e skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'playwright-test-generator': (s) =>
     `Invoke playwright-test-generator for slug "${s}". Generate/update *.spec.ts from matching *.cases.md. ` +
-    `Use playwright MCP when available. Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and the playwright-e2e skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'playwright-test-healer': (s) =>
     `Invoke playwright-test-healer for slug "${s}". Fix failing/flaky e2e while preserving cases.md assertions. ` +
-    `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. Update status.json when done.`,
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. 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([
@@ -172,16 +345,35 @@ const REVIEW_AGENTS = new Set([
   'api-contract-reviewer',
 ]);
 
-function handoffForAgent(agent, scope) {
+function metricsHandoff(agent) {
+  const matches = Object.entries(status.activeAttempts || {}).filter(([, entry]) => entry.agent === agent);
+  if (matches.length === 1) {
+    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 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];
-  return fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
+  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) {
   const agents = getStepAgents(step);
+  const attemptIds = Object.entries(status.activeAttempts || {})
+    .filter(([, entry]) => agents.includes(entry.agent))
+    .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.`
   );
 }
 
@@ -213,34 +405,42 @@ function legacyFlow() {
     out(handoffForAgent('qa-tester'));
     process.exit(0);
   }
-  if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
+  function scheduleLegacyRetry(agent, retryAfterFix) {
+    const stepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+    const predecessorAttemptId = status.lastCompletedAttempt?.attemptId || null;
+    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') {
+    const reviewer = status.currentAgent;
+    if (!reviewer) {
+      process.stdout.write('{}');
+      process.exit(0);
+    }
+    scheduleLegacyRetry('feature-developer', reviewer);
     writeStatus({
       currentAgent: 'feature-developer',
       state: 'in_progress',
       phase: 'executing',
-      retryAfterFix: status.currentAgent,
+      retryAfterFix: reviewer,
     });
-    out(
-      handoffForAgent('feature-developer') +
-        ` After fixes, re-run ${status.currentAgent}.`,
-    );
+    out(handoffForAgent('feature-developer') + ` After fixes, re-run ${reviewer}.`);
     process.exit(0);
   }
   if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+    scheduleLegacyRetry('feature-developer', 'build-verifier');
     writeStatus({
       currentAgent: 'feature-developer',
       state: 'in_progress',
       phase: 'executing',
       retryAfterFix: 'build-verifier',
     });
-    out(
-      handoffForAgent('feature-developer') +
-        ` Read validation-report.md. After fixes, re-run build-verifier.`,
-    );
+    out(handoffForAgent('feature-developer') + ' Read validation-report.md. After fixes, re-run build-verifier.');
     process.exit(0);
   }
   if (status.state === 'completed' && status.retryAfterFix) {
     const retry = status.retryAfterFix;
+    scheduleLegacyRetry(retry, null);
     writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
     out(handoffForAgent(retry));
     process.exit(0);
@@ -254,6 +454,56 @@ function legacyFlow() {
   process.exit(0);
 }
 
+
+if (hookInput.action === 'end_human_gate') {
+  status.awaitingHumanGate = false;
+  if (status.state === 'awaiting_approval') {
+    status.state = 'in_progress';
+    status.phase = status.phase === 'human_gate' ? 'executing' : status.phase;
+  }
+  if (status.activeHumanGateEventId) {
+    appendMetric({
+      type: 'human_gate_ended',
+      at: now,
+      gateStartedEventId: status.activeHumanGateEventId,
+      source: 'orchestrator',
+      attributionConfidence: 'high',
+    });
+    delete status.activeHumanGateEventId;
+  }
+  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+    let resumePipeline = null;
+    try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
+    if (resumePipeline) {
+      const resumeSteps = resumePipeline.steps || [];
+      const resumeStart = (typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0) + 1;
+      const resumeNext = findNextExecutableStep(resumeSteps, resumeStart, taskDir);
+      if (resumeNext) {
+        const resumeAgents = getStepAgents(resumeNext.step);
+        activateAttempts(resumeNext.step, resumeNext.index);
+        writeStatus({
+          pipelineIndex: resumeNext.index,
+          currentAgent: resumeAgents[0],
+          phase: 'executing',
+          state: 'in_progress',
+          awaitingHumanGate: false,
+          parallelCompleted: [],
+        });
+        if (resumeNext.step.parallel && resumeAgents.length > 1) out(handoffForParallelStep(resumeNext.step));
+        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
+        process.exit(0);
+      }
+    }
+  }
+  writeStatus({
+    awaitingHumanGate: false,
+    state: status.state,
+    phase: status.phase,
+  });
+  process.stdout.write(JSON.stringify({ ok: true, action: 'end_human_gate', activeHumanGateEventId: status.activeHumanGateEventId || null }));
+  process.exit(0);
+}
+
 if (!fs.existsSync(pipelinePath)) {
   legacyFlow();
 }
@@ -266,7 +516,30 @@ try {
 }
 
 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('{}');
+  process.exit(0);
+}
+endHumanGateIfResumed();
 if (steps.length === 0 || pipeline.autoChain === false) {
+  writeStatus({});
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -276,68 +549,136 @@ if (status.awaitingHumanGate || status.state === 'awaiting_approval') {
   process.exit(0);
 }
 
-if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
-  const reviewer = status.currentAgent;
+function nearestPrecedingStepIndex(agent, fromIndex, fallback) {
+  for (let index = fromIndex - 1; index >= 0; index -= 1) {
+    if (getStepAgents(steps[index]).includes(agent)) return index;
+  }
+  const match = steps.findIndex((step) => getStepAgents(step).includes(agent));
+  return match >= 0 ? match : fallback;
+}
+function scheduleRetry(agent, retryAfterFix, predecessor, explicitStepIndex = null) {
+  const currentIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+  const stepIndex = Number.isInteger(explicitStepIndex) ? explicitStepIndex : nearestPrecedingStepIndex(agent, currentIndex, currentIndex);
+  const predecessorAttemptId = predecessor?.attemptId || status.lastCompletedAttempt?.attemptId || null;
+  appendMetric({ type: 'retry_scheduled', at: now, attemptId: predecessorAttemptId, nextAgent: agent, retryAfterFix: retryAfterFix || null, source: 'hook', attributionConfidence: predecessor ? predecessor.confidence : 'unknown' });
+  activateAttempts(steps[stepIndex] || { agent }, stepIndex);
+  return stepIndex;
+}
+
+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({
+    pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
     state: 'in_progress',
     phase: 'executing',
     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);
 }
 
 if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+  const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+  const developerIndex = scheduleRetry('feature-developer', 'build-verifier', finishedAttempt);
   writeStatus({
+    pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
     state: 'in_progress',
     phase: 'executing',
     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);
 }
 
 if (status.state === 'completed' && status.retryAfterFix) {
   const retry = status.retryAfterFix;
-  writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
-  out(handoffForAgent(retry));
+  const retryIndex = scheduleRetry(retry, null, finishedAttempt, status.retryAfterFixStepIndex);
+  writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
+  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 = 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({
     awaitingHumanGate: true,
     state: 'awaiting_approval',
@@ -349,6 +690,7 @@ if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
 
 const next = findNextExecutableStep(steps, idx + 1, taskDir);
 if (!next) {
+  completeTaskMetrics();
   writeStatus({
     pipelineIndex: steps.length,
     phase: 'done',
@@ -363,6 +705,7 @@ if (!next) {
 const { step: nextStep, index: nextIdx } = next;
 const nextAgents = getStepAgents(nextStep);
 
+activateAttempts(nextStep, nextIdx);
 writeStatus({
   pipelineIndex: nextIdx,
   currentAgent: nextAgents[0],
@@ -375,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