@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/scripts/test-agent-task-metrics-hooks.mjs

@@ -0,0 +1,895 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageDirectory = path.resolve(scriptDirectory, '..');
+const presetsDirectory = path.join(packageDirectory, 'presets');
+const hooks = [
+  ...fs.readdirSync(path.join(presetsDirectory, 'cursor')).map((stack) => path.join(presetsDirectory, 'cursor', stack, 'hooks', 'chain-team-phases.sh')),
+  ...fs.readdirSync(path.join(presetsDirectory, 'claude')).map((stack) => path.join(presetsDirectory, 'claude', stack, 'hooks', 'chain-team-phases.sh')),
+];
+
+assert.equal(hooks.length, 14, 'expected every packaged Cursor and Claude hook');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function invokeHook(hook, workingDirectory, attemptId) {
+  return execFileSync('bash', [hook], {
+    cwd: workingDirectory,
+    encoding: 'utf8',
+    input: JSON.stringify({ status: 'completed', attemptId }),
+  });
+}
+
+function invokeHookAsync(hook, workingDirectory, attemptId) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('bash', [hook], { cwd: workingDirectory, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(`${hook} exited ${code}: ${stderr}`));
+    });
+    child.stdin.end(JSON.stringify({ status: 'completed', attemptId }));
+  });
+}
+
+function writeTask(root, hook, slug, pipeline, status, metrics, artifacts = {}) {
+  const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+  const teamRoot = path.join(root, `.${platform}`, 'team');
+  const taskDirectory = path.join(teamRoot, 'tasks', slug);
+  fs.mkdirSync(taskDirectory, { recursive: true });
+  writeJson(path.join(teamRoot, 'active-task.json'), { slug });
+  writeJson(path.join(taskDirectory, 'pipeline.json'), pipeline);
+  writeJson(path.join(taskDirectory, 'status.json'), status);
+  writeJson(path.join(taskDirectory, 'metrics.json'), metrics);
+  for (const [name, content] of Object.entries(artifacts)) {
+    fs.writeFileSync(path.join(taskDirectory, name), content);
+  }
+  return taskDirectory;
+}
+
+function prepareTask(root, hook) {
+  const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+  const teamRoot = path.join(root, `.${platform}`, 'team');
+  const taskDirectory = path.join(teamRoot, 'tasks', 'reverse-parallel');
+  fs.mkdirSync(taskDirectory, { recursive: true });
+  writeJson(path.join(teamRoot, 'active-task.json'), { slug: 'reverse-parallel' });
+  writeJson(path.join(taskDirectory, 'pipeline.json'), {
+    autoChain: true,
+    steps: [
+      { agent: 'starter' },
+      { agent: ['alpha', 'beta'], parallel: true },
+      { agent: 'gamma' },
+    ],
+  });
+
+  const runId = 'reverse-parallel-run';
+  const starterAttemptId = `${runId}:step-0:starter:attempt-1`;
+  writeJson(path.join(taskDirectory, 'status.json'), {
+    slug: 'reverse-parallel',
+    intent: 'feature',
+    pipelineIndex: 0,
+    currentAgent: 'starter',
+    phase: 'executing',
+    state: 'completed',
+    activeAttempts: {
+      [starterAttemptId]: {
+        agent: 'starter',
+        stepIndex: 0,
+        attempt: 1,
+        startedAt: '2026-01-01T00:00:00.000Z',
+        parallelGroupId: null,
+      },
+    },
+    metricsRunId: runId,
+  });
+  writeJson(path.join(taskDirectory, 'metrics.json'), {
+    schemaVersion: 1,
+    task: { runId, slug: 'reverse-parallel', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+    events: [
+      { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+      { eventId: `${runId}:starter`, type: 'attempt_started', attemptId: starterAttemptId, agent: 'starter', stepIndex: 0, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+    ],
+  });
+  return { taskDirectory, starterAttemptId };
+}
+
+function setCompleted(taskDirectory) {
+  const statusPath = path.join(taskDirectory, 'status.json');
+  const status = readJson(statusPath);
+  writeJson(statusPath, { ...status, state: 'completed' });
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-'));
+  try {
+    const { taskDirectory, starterAttemptId } = prepareTask(root, hook);
+    const parallelHandoff = JSON.parse(invokeHook(hook, root, starterAttemptId)).followup_message;
+    const statusAfterScheduling = readJson(path.join(taskDirectory, 'status.json'));
+    const activeAttempts = statusAfterScheduling.activeAttempts;
+    const alphaAttemptId = Object.keys(activeAttempts).find((attemptId) => activeAttempts[attemptId].agent === 'alpha');
+    const betaAttemptId = Object.keys(activeAttempts).find((attemptId) => activeAttempts[attemptId].agent === 'beta');
+
+    assert.ok(alphaAttemptId && betaAttemptId, `${hook}: parallel attempts were not activated`);
+    assert.match(parallelHandoff, new RegExp(`alpha=${alphaAttemptId}`), `${hook}: alpha attempt ID missing from handoff`);
+    assert.match(parallelHandoff, new RegExp(`beta=${betaAttemptId}`), `${hook}: beta attempt ID missing from handoff`);
+
+    setCompleted(taskDirectory);
+    const results = await Promise.all([
+      invokeHookAsync(hook, root, betaAttemptId),
+      invokeHookAsync(hook, root, alphaAttemptId),
+    ]);
+    const finalStatus = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(finalStatus.pipelineIndex, 2, `${hook}: parallel step did not advance`);
+    assert.equal(finalStatus.currentAgent, 'gamma', `${hook}: next agent was not scheduled`);
+    assert.deepEqual(finalStatus.parallelCompleted, [], `${hook}: parallel completion state was not reset`);
+    assert.ok(
+      results.some((result) => /gamma/.test(JSON.parse(result).followup_message || '')),
+      `${hook}: expected one next-agent handoff`,
+    );
+
+    const finishedAgents = readJson(path.join(taskDirectory, 'metrics.json')).events
+      .filter((event) => event.type === 'attempt_finished')
+      .map((event) => event.attemptId);
+    assert.ok(finishedAgents.includes(alphaAttemptId) && finishedAgents.includes(betaAttemptId), `${hook}: both reverse-order attempts must finish`);
+    assert.equal(new Set(finishedAgents).size, finishedAgents.length, `${hook}: parallel completion emitted duplicate terminal events`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-retry-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'serial-retry-run';
+    const reviewerAttemptId = `${runId}:step-5:security-reviewer:attempt-1`;
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'serial-retry',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'feature-developer', scope: 'wp-1' },
+          { agent: 'build-verifier', scope: 'wp-1' },
+          { agent: 'security-reviewer', scope: 'wp-1' },
+          { agent: 'feature-developer', scope: 'wp-2' },
+          { agent: 'build-verifier', scope: 'wp-2' },
+          { agent: 'security-reviewer', scope: 'wp-2' },
+        ],
+      },
+      {
+        slug: 'serial-retry',
+        intent: 'feature',
+        pipelineIndex: 5,
+        currentAgent: 'security-reviewer',
+        phase: 'executing',
+        state: 'changes_requested',
+        activeAttempts: {
+          [reviewerAttemptId]: {
+            agent: 'security-reviewer',
+            stepIndex: 5,
+            attempt: 1,
+            startedAt: '2026-01-01T00:00:00.000Z',
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'serial-retry', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:reviewer-start`, type: 'attempt_started', attemptId: reviewerAttemptId, agent: 'security-reviewer', stepIndex: 5, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        ],
+      },
+    );
+
+    const fixHandoff = JSON.parse(invokeHook(hook, root, reviewerAttemptId)).followup_message;
+    const fixStatus = readJson(path.join(taskDirectory, 'status.json'));
+    const developerAttempts = Object.entries(fixStatus.activeAttempts).filter(([, entry]) => entry.agent === 'feature-developer');
+    assert.equal(fixStatus.pipelineIndex, 3, `${hook}: retry must target the nearest preceding developer step`);
+    assert.equal(developerAttempts.length, 1, `${hook}: retry must activate exactly one developer attempt`);
+    const developerAttemptId = developerAttempts[0][0];
+    assert.match(fixHandoff, new RegExp(developerAttemptId), `${hook}: developer retry attempt ID missing from handoff`);
+    assert.notEqual(developerAttemptId, reviewerAttemptId, `${hook}: retry attempt ID collided with predecessor`);
+
+    setCompleted(taskDirectory);
+    const reviewHandoff = JSON.parse(invokeHook(hook, root, developerAttemptId)).followup_message;
+    const reviewStatus = readJson(path.join(taskDirectory, 'status.json'));
+    const reviewerAttempts = Object.entries(reviewStatus.activeAttempts).filter(([, entry]) => entry.agent === 'security-reviewer');
+    assert.equal(reviewStatus.pipelineIndex, 5, `${hook}: completed fix must return to the requesting reviewer step`);
+    assert.equal(reviewerAttempts.length, 1, `${hook}: reviewer retry must activate exactly one attempt`);
+    const retriedReviewerAttemptId = reviewerAttempts[0][0];
+    assert.match(reviewHandoff, new RegExp(retriedReviewerAttemptId), `${hook}: reviewer retry attempt ID missing from handoff`);
+    assert.match(retriedReviewerAttemptId, /attempt-2$/, `${hook}: reviewer retry ordinal must increment`);
+
+    const beforeDuplicate = readJson(path.join(taskDirectory, 'status.json'));
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, developerAttemptId)), {}, `${hook}: stale duplicate stop must be ignored`);
+    assert.deepEqual(readJson(path.join(taskDirectory, 'status.json')), beforeDuplicate, `${hook}: stale duplicate stop mutated status`);
+    const developerFinishes = readJson(path.join(taskDirectory, 'metrics.json')).events.filter(
+      (event) => event.type === 'attempt_finished' && event.attemptId === developerAttemptId,
+    );
+    assert.equal(developerFinishes.length, 1, `${hook}: stale duplicate stop emitted a second terminal event`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-no-chain-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'no-chain-run';
+    const attemptId = `${runId}:step-0:feature-developer:attempt-1`;
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'no-chain',
+      { autoChain: false, steps: [{ agent: 'feature-developer' }] },
+      {
+        slug: 'no-chain',
+        intent: 'feature',
+        pipelineIndex: 0,
+        currentAgent: 'feature-developer',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [attemptId]: {
+            agent: 'feature-developer',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: '2026-01-01T00:00:00.000Z',
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'no-chain', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:start`, type: 'attempt_started', attemptId, agent: 'feature-developer', stepIndex: 0, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        ],
+      },
+    );
+
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, attemptId)), {}, `${hook}: non-chaining stop must not hand off`);
+    assert.equal(Object.keys(readJson(path.join(taskDirectory, 'status.json')).activeAttempts).length, 0, `${hook}: finished non-chaining attempt was not persisted`);
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, attemptId)), {}, `${hook}: repeated non-chaining stop must be ignored`);
+    const terminals = readJson(path.join(taskDirectory, 'metrics.json')).events.filter(
+      (event) => event.type === 'attempt_finished' && event.attemptId === attemptId,
+    );
+    assert.equal(terminals.length, 1, `${hook}: repeated non-chaining stop duplicated terminal metrics`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-mixed-parallel-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'mixed-parallel-run';
+    const alphaAttemptId = `${runId}:step-1:code-reviewer:attempt-1`;
+    const betaAttemptId = `${runId}:step-1:security-reviewer:attempt-1`;
+    const groupId = `${runId}:step-1`;
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'mixed-parallel',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'feature-developer' },
+          { agent: ['code-reviewer', 'security-reviewer'], parallel: true },
+        ],
+      },
+      {
+        slug: 'mixed-parallel',
+        intent: 'feature',
+        pipelineIndex: 1,
+        currentAgent: 'code-reviewer',
+        phase: 'executing',
+        state: 'changes_requested',
+        parallelCompleted: [],
+        activeAttempts: {
+          [alphaAttemptId]: { agent: 'code-reviewer', stepIndex: 1, attempt: 1, startedAt: '2026-01-01T00:00:00.000Z', parallelGroupId: groupId },
+          [betaAttemptId]: { agent: 'security-reviewer', stepIndex: 1, attempt: 1, startedAt: '2026-01-01T00:00:00.000Z', parallelGroupId: groupId },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'mixed-parallel', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:alpha`, type: 'attempt_started', attemptId: alphaAttemptId, agent: 'code-reviewer', stepIndex: 1, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:beta`, type: 'attempt_started', attemptId: betaAttemptId, agent: 'security-reviewer', stepIndex: 1, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        ],
+      },
+    );
+
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, betaAttemptId)), {}, `${hook}: parallel failure must wait for join`);
+    let status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.pipelineIndex, 1, `${hook}: parallel failure advanced before join`);
+    assert.ok(status.activeAttempts[alphaAttemptId], `${hook}: parallel sibling was lost before join`);
+    assert.equal(
+      Object.values(status.activeAttempts).filter((entry) => entry.agent === 'feature-developer').length,
+      0,
+      `${hook}: developer retry started before join`,
+    );
+
+    setCompleted(taskDirectory);
+    const handoff = JSON.parse(invokeHook(hook, root, alphaAttemptId)).followup_message;
+    status = readJson(path.join(taskDirectory, 'status.json'));
+    const developerAttempts = Object.values(status.activeAttempts).filter((entry) => entry.agent === 'feature-developer');
+    assert.equal(status.pipelineIndex, 0, `${hook}: joined retry must target preceding developer`);
+    assert.equal(developerAttempts.length, 1, `${hook}: joined parallel failure must schedule exactly one developer retry`);
+    assert.equal(status.retryAfterFix, 'security-reviewer', `${hook}: mixed outcomes lost requesting reviewer`);
+    assert.match(handoff, /feature-developer/, `${hook}: joined retry handoff missing developer`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-skip-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'skip-run';
+    const starterAttemptId = `${runId}:step-0:starter:attempt-1`;
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'skip',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'starter' },
+          { agent: 'debugger', skipIf: 'debugger.fixed' },
+          { agent: 'gamma' },
+        ],
+      },
+      {
+        slug: 'skip',
+        intent: 'bugfix',
+        pipelineIndex: 0,
+        currentAgent: 'starter',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [starterAttemptId]: {
+            agent: 'starter',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: '2026-01-01T00:00:00.000Z',
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'skip', preset: 'ai-rules', stack: 'test', platform, intent: 'bugfix', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:starter`, type: 'attempt_started', attemptId: starterAttemptId, agent: 'starter', stepIndex: 0, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        ],
+      },
+      { 'debug-report.md': 'fixApplied: true\n' },
+    );
+
+    invokeHook(hook, root, starterAttemptId);
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.pipelineIndex, 2, `${hook}: skipIf did not advance to the next executable step`);
+    const skipped = readJson(path.join(taskDirectory, 'metrics.json')).events.filter((event) => event.type === 'attempt_skipped');
+    assert.equal(skipped.length, 1, `${hook}: skipIf must emit exactly one attempt_skipped event`);
+    assert.equal(skipped[0].agent, 'debugger', `${hook}: attempt_skipped attributed to the wrong agent`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const command of [
+  ...fs.readdirSync(path.join(presetsDirectory, 'cursor')).map((stack) => path.join(presetsDirectory, 'cursor', stack, 'commands', 'task-continue.md')),
+  ...fs.readdirSync(path.join(presetsDirectory, 'claude')).map((stack) => path.join(presetsDirectory, 'claude', stack, 'commands', 'task-continue.md')),
+]) {
+  const source = fs.readFileSync(command, 'utf8');
+  assert.match(source, /action":"end_human_gate"/, `${command}: must invoke installed hook end_human_gate action`);
+  assert.match(source, /hooks\/chain-team-phases\.sh/, `${command}: must reference installed chain-team-phases.sh`);
+  assert.match(source, /single authority/, `${command}: must declare hook as single authority for gate resume`);
+  assert.match(source, /\*\*Do not\*\* manually increment/, `${command}: must forbid manual pipelineIndex advance before hook`);
+  assert.doesNotMatch(
+    source,
+    /Сбрось gate:[\s\S]*pipelineIndex \+ 1[\s\S]*end_human_gate/,
+    `${command}: must not document pre-hook status advance`,
+  );
+}
+
+for (const hook of hooks) {
+  // Initialized-consumer regression following task-continue.md:
+  // pre-resume status → hook end_human_gate (no manual pipelineIndex++) → invoke from status.currentAgent.
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-gate-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const stack = path.basename(path.dirname(path.dirname(hook)));
+    const presetCommand = path.join(path.dirname(path.dirname(hook)), 'commands', 'task-continue.md');
+    const installedHook = path.join(root, `.${platform}`, 'hooks', 'chain-team-phases.sh');
+    const installedCommand = path.join(root, `.${platform}`, 'commands', 'task-continue.md');
+    fs.mkdirSync(path.dirname(installedHook), { recursive: true });
+    fs.mkdirSync(path.dirname(installedCommand), { recursive: true });
+    fs.copyFileSync(hook, installedHook);
+    fs.copyFileSync(presetCommand, installedCommand);
+    const commandSource = fs.readFileSync(installedCommand, 'utf8');
+    assert.match(commandSource, /single authority/);
+    assert.match(commandSource, /\*\*Do not\*\* manually increment/);
+
+    const teamRoot = path.join(root, `.${platform}`, 'team');
+    const taskDirectory = path.join(teamRoot, 'tasks', 'gate-resume');
+    fs.mkdirSync(taskDirectory, { recursive: true });
+    const runId = 'gate-resume-run';
+    const gateEventId = `${runId}:gate:1`;
+    writeJson(path.join(teamRoot, 'active-task.json'), { slug: 'gate-resume' });
+    writeJson(path.join(taskDirectory, 'pipeline.json'), {
+      autoChain: true,
+      steps: [{ agent: 'task-analyst' }, { agent: 'feature-developer', label: 'Implement' }],
+    });
+    writeJson(path.join(taskDirectory, 'status.json'), {
+      slug: 'gate-resume',
+      intent: 'feature',
+      pipelineIndex: 0,
+      currentAgent: 'task-analyst',
+      phase: 'human_gate',
+      state: 'awaiting_approval',
+      awaitingHumanGate: true,
+      activeHumanGateEventId: gateEventId,
+      metricsRunId: runId,
+      activeAttempts: {},
+    });
+    writeJson(path.join(taskDirectory, 'metrics.json'), {
+      schemaVersion: 1,
+      task: { runId, slug: 'gate-resume', preset: 'ai-rules', stack, platform, intent: 'feature', profile: 'standard' },
+      events: [
+        { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+        { eventId: `${runId}:analyst`, type: 'attempt_started', attemptId: `${runId}:step-0:task-analyst:attempt-1`, agent: 'task-analyst', stepIndex: 0, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        { eventId: `${runId}:analyst-done`, type: 'attempt_finished', attemptId: `${runId}:step-0:task-analyst:attempt-1`, outcome: 'completed', durationMs: 1000, at: '2026-01-01T00:00:01.000Z' },
+        { eventId: gateEventId, type: 'human_gate_started', at: '2026-01-01T00:00:01.000Z' },
+      ],
+    });
+
+    const handoff = JSON.parse(
+      execFileSync('bash', [installedHook], {
+        cwd: root,
+        encoding: 'utf8',
+        input: JSON.stringify({ status: 'completed', action: 'end_human_gate', activateNext: true }),
+      }),
+    );
+    assert.match(handoff.followup_message || '', /feature-developer/, `${hook}: consumer hook must hand off next agent`);
+
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.awaitingHumanGate, false, `${hook}: gate remained active`);
+    assert.equal(status.activeHumanGateEventId, undefined, `${hook}: gate event ID remained active`);
+    assert.equal(status.pipelineIndex, 1, `${hook}: gate resume did not advance`);
+    assert.equal(status.currentAgent, 'feature-developer', `${hook}: gate resume targeted wrong agent`);
+
+    const types = readJson(path.join(taskDirectory, 'metrics.json')).events.map((event) => event.type);
+    const gateEndedAt = types.lastIndexOf('human_gate_ended');
+    const nextAttemptAt = types.lastIndexOf('attempt_started');
+    assert.ok(gateEndedAt >= 0, `${hook}: human_gate_ended missing from ledger`);
+    assert.ok(nextAttemptAt > gateEndedAt, `${hook}: attempt_started must come after human_gate_ended`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-manifest-reconcile-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'manifest-reconcile-run';
+    const reviewerAttemptId = `${runId}:step-1:code-reviewer:attempt-1`;
+    const nowIso = '2026-01-01T00:00:00.000Z';
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'manifest-reconcile',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'feature-developer', artifactOutputId: 'implementation' },
+          { agent: 'code-reviewer', artifactInputIds: ['implementation'], artifactOutputId: 'review' },
+        ],
+      },
+      {
+        slug: 'manifest-reconcile',
+        intent: 'review-only',
+        pipelineIndex: 1,
+        currentAgent: 'code-reviewer',
+        phase: 'executing',
+        state: 'in_progress',
+        activeAttempts: {
+          [reviewerAttemptId]: {
+            agent: 'code-reviewer',
+            stepIndex: 1,
+            attempt: 1,
+            startedAt: nowIso,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: {
+          runId,
+          slug: 'manifest-reconcile',
+          preset: 'ai-rules',
+          stack: 'test',
+          platform,
+          intent: 'review-only',
+          profile: 'test',
+        },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: nowIso },
+          {
+            eventId: `${runId}:review-start`,
+            type: 'attempt_started',
+            attemptId: reviewerAttemptId,
+            agent: 'code-reviewer',
+            stepIndex: 1,
+            attempt: 1,
+            at: nowIso,
+          },
+        ],
+      },
+      {
+        'artifact-manifest.json': `${JSON.stringify(
+          {
+            schemaVersion: 1,
+            slug: 'manifest-reconcile',
+            updatedAt: nowIso,
+            artifacts: [
+              {
+                id: 'review',
+                producer: 'code-reviewer',
+                status: 'blocked',
+                authoritativePaths: ['review.md'],
+                acceptanceCriteriaIds: [],
+                taskIds: [],
+                timestamps: { createdAt: nowIso, updatedAt: nowIso, completedAt: nowIso },
+                receipt: {
+                  outcome: 'changes_requested',
+                  attemptId: reviewerAttemptId,
+                  summary: 'Review found blockers.',
+                  evidencePaths: ['review.md'],
+                },
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+        'review.md': '# review\nREQUEST_CHANGES\n',
+      },
+    );
+
+    const handoff = JSON.parse(invokeHook(hook, root, reviewerAttemptId)).followup_message;
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.currentAgent, 'feature-developer', `${hook}: manifest receipt must drive retry to developer`);
+    assert.equal(status.retryAfterFix, 'code-reviewer', `${hook}: retryAfterFix must point at reviewer`);
+    assert.match(handoff || '', /feature-developer/, `${hook}: expected developer handoff after receipt reconcile`);
+
+    const finished = readJson(path.join(taskDirectory, 'metrics.json')).events.find(
+      (event) => event.type === 'attempt_finished' && event.attemptId === reviewerAttemptId,
+    );
+    assert.ok(finished, `${hook}: missing attempt_finished after receipt reconcile`);
+    assert.equal(finished.outcome, 'changes_requested', `${hook}: metrics outcome must come from manifest receipt`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-blocked-receipt-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'blocked-receipt-run';
+    const attemptId = `${runId}:step-0:feature-developer:attempt-1`;
+    const startedAt = '2026-02-01T00:00:00.000Z';
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'blocked-receipt',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'feature-developer', artifactInputIds: ['analysis'], artifactOutputId: 'implementation-wp1' },
+          { agent: 'build-verifier', artifactInputIds: ['implementation-wp1'], artifactOutputId: 'validation-wp1' },
+        ],
+      },
+      {
+        slug: 'blocked-receipt',
+        intent: 'feature',
+        pipelineIndex: 0,
+        currentAgent: 'feature-developer',
+        phase: 'executing',
+        state: 'in_progress',
+        activeAttempts: {
+          [attemptId]: {
+            agent: 'feature-developer',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'blocked-receipt', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: startedAt },
+          { eventId: `${runId}:developer-start`, type: 'attempt_started', attemptId, agent: 'feature-developer', stepIndex: 0, attempt: 1, at: startedAt },
+        ],
+      },
+      {
+        'artifact-manifest.json': `${JSON.stringify(
+          {
+            schemaVersion: 1,
+            slug: 'blocked-receipt',
+            updatedAt: startedAt,
+            artifacts: [
+              {
+                id: 'implementation-wp1',
+                producer: 'feature-developer',
+                status: 'blocked',
+                authoritativePaths: ['implementation.md'],
+                acceptanceCriteriaIds: ['AC-1'],
+                taskIds: ['T1'],
+                timestamps: { createdAt: startedAt, updatedAt: startedAt, completedAt: startedAt },
+                receipt: {
+                  outcome: 'blocked',
+                  attemptId,
+                  summary: 'Implementation requires a user decision.',
+                  evidencePaths: ['implementation.md'],
+                },
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      },
+    );
+
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, attemptId)), {}, `${hook}: blocked receipt must not hand off`);
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.pipelineIndex, 0, `${hook}: blocked receipt advanced the pipeline`);
+    assert.equal(status.currentAgent, 'feature-developer', `${hook}: blocked receipt changed the active producer`);
+    assert.equal(status.state, 'blocked', `${hook}: blocked receipt did not persist blocked state`);
+    assert.equal(status.phase, 'blocked', `${hook}: blocked receipt did not persist blocked phase`);
+    assert.equal(Object.keys(status.activeAttempts).length, 0, `${hook}: blocked terminal attempt remained active`);
+
+    const terminal = readJson(path.join(taskDirectory, 'metrics.json')).events.find(
+      (event) => event.type === 'attempt_finished' && event.attemptId === attemptId,
+    );
+    assert.equal(terminal?.outcome, 'blocked', `${hook}: blocked receipt outcome missing from metrics`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-stale-receipt-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'stale-receipt-run';
+    const attemptId = `${runId}:step-2:code-reviewer:attempt-2`;
+    const startedAt = '2026-02-01T00:00:00.000Z';
+    const staleAt = '2026-01-01T00:00:00.000Z';
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'stale-receipt',
+      {
+        autoChain: true,
+        steps: [
+          { agent: 'code-reviewer', artifactOutputId: 'review-wp1' },
+          { agent: 'feature-developer', artifactInputIds: ['review-wp1'], artifactOutputId: 'implementation-wp2' },
+          { agent: 'code-reviewer', artifactInputIds: ['implementation-wp2'], artifactOutputId: 'review-wp2' },
+          { agent: 'build-verifier', artifactInputIds: ['review-wp2'], artifactOutputId: 'validation-wp2' },
+        ],
+      },
+      {
+        slug: 'stale-receipt',
+        intent: 'feature',
+        pipelineIndex: 2,
+        currentAgent: 'code-reviewer',
+        phase: 'executing',
+        state: 'in_progress',
+        activeAttempts: {
+          [attemptId]: {
+            agent: 'code-reviewer',
+            stepIndex: 2,
+            attempt: 2,
+            startedAt,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'stale-receipt', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: staleAt },
+          { eventId: `${runId}:review-start`, type: 'attempt_started', attemptId, agent: 'code-reviewer', stepIndex: 2, attempt: 2, at: startedAt },
+        ],
+      },
+      {
+        'artifact-manifest.json': `${JSON.stringify(
+          {
+            schemaVersion: 1,
+            slug: 'stale-receipt',
+            updatedAt: staleAt,
+            artifacts: [
+              {
+                id: 'review-wp1',
+                producer: 'code-reviewer',
+                status: 'blocked',
+                authoritativePaths: ['review.md'],
+                acceptanceCriteriaIds: ['AC-1'],
+                taskIds: ['T1'],
+                timestamps: { createdAt: staleAt, updatedAt: staleAt, completedAt: staleAt },
+                receipt: {
+                  outcome: 'changes_requested',
+                  summary: 'Prior work package requested changes.',
+                  evidencePaths: ['review.md'],
+                },
+              },
+              {
+                id: 'review-wp2',
+                producer: 'code-reviewer',
+                status: 'completed',
+                authoritativePaths: ['review.md'],
+                acceptanceCriteriaIds: ['AC-2'],
+                taskIds: ['T2'],
+                timestamps: { createdAt: staleAt, updatedAt: staleAt, completedAt: staleAt },
+                receipt: {
+                  outcome: 'completed',
+                  summary: 'Stale receipt from before the active attempt.',
+                  evidencePaths: ['review.md'],
+                },
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      },
+    );
+
+    assert.deepEqual(JSON.parse(invokeHook(hook, root, attemptId)), {}, `${hook}: stale receipt must not hand off`);
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.pipelineIndex, 2, `${hook}: stale receipt advanced the pipeline`);
+    assert.equal(status.currentAgent, 'code-reviewer', `${hook}: stale receipt changed the active producer`);
+    assert.equal(status.state, 'awaiting_artifact_receipt', `${hook}: stale receipt did not enter receipt-wait state`);
+    assert.ok(status.activeAttempts[attemptId], `${hook}: stale receipt consumed the active attempt`);
+    assert.equal(
+      readJson(path.join(taskDirectory, 'metrics.json')).events.filter(
+        (event) => event.type === 'attempt_finished' && event.attemptId === attemptId,
+      ).length,
+      0,
+      `${hook}: stale receipt emitted terminal metrics`,
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+{
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-aggregate-'));
+  try {
+    const tasksDirectory = path.join(root, 'tasks');
+    const missingDirectory = path.join(tasksDirectory, 'missing-ledger');
+    const malformedDirectory = path.join(tasksDirectory, 'malformed-ledger');
+    const invalidDirectory = path.join(tasksDirectory, 'invalid-ledger');
+    const duplicateDirectory = path.join(tasksDirectory, 'duplicate-attempt-id');
+    fs.mkdirSync(missingDirectory, { recursive: true });
+    fs.mkdirSync(malformedDirectory, { recursive: true });
+    fs.mkdirSync(invalidDirectory, { recursive: true });
+    fs.mkdirSync(duplicateDirectory, { recursive: true });
+    fs.writeFileSync(path.join(malformedDirectory, 'metrics.json'), '{not-json\n');
+    writeJson(path.join(invalidDirectory, 'metrics.json'), {
+      schemaVersion: 1,
+      task: { runId: 'invalid-ledger-run', slug: 'invalid-ledger' },
+      events: [null],
+    });
+    writeJson(path.join(duplicateDirectory, 'metrics.json'), {
+      schemaVersion: 1,
+      task: {
+        runId: 'duplicate-attempt-id-run',
+        slug: 'duplicate-attempt-id',
+        preset: 'ai-rules',
+        stack: 'next',
+        platform: 'cursor',
+        intent: 'feature',
+        profile: 'test',
+      },
+      events: [
+        {
+          eventId: 'duplicate-attempt-id-run:start-1',
+          type: 'attempt_started',
+          attemptId: 'duplicate-attempt-id-run:step-0:feature-developer:attempt-1',
+          agent: 'feature-developer',
+          stepIndex: 0,
+          attempt: 1,
+          at: '2026-01-01T00:00:00.000Z',
+        },
+        {
+          eventId: 'duplicate-attempt-id-run:start-duplicate',
+          type: 'attempt_started',
+          attemptId: 'duplicate-attempt-id-run:step-0:feature-developer:attempt-1',
+          agent: 'feature-developer',
+          stepIndex: 0,
+          attempt: 1,
+          at: '2026-01-01T00:00:01.000Z',
+        },
+      ],
+    });
+
+    const aggregate = JSON.parse(
+      execFileSync(
+        process.execPath,
+        [path.join(scriptDirectory, 'aggregate-agent-task-metrics.mjs'), '--team-root', root],
+        { encoding: 'utf8' },
+      ),
+    );
+    assert.equal(aggregate.completeness.missingLedgerCount, 1, 'aggregator must count missing ledgers separately');
+    assert.equal(aggregate.completeness.malformedLedgerCount, 1, 'aggregator must count malformed ledgers separately');
+    assert.equal(aggregate.completeness.invalidLedgerCount, 1, 'aggregator must count structurally invalid ledgers separately');
+    assert.equal(aggregate.completeness.duplicateAttemptIdCount, 1, 'aggregator must reject duplicate attempt IDs');
+    assert.ok(
+      aggregate.incomplete.some((entry) => entry.category === 'missing_ledger'),
+      'aggregator missing-ledger category was not reported',
+    );
+    assert.ok(
+      aggregate.incomplete.some((entry) => entry.category === 'malformed_json'),
+      'aggregator malformed-JSON category was not reported',
+    );
+    assert.ok(
+      aggregate.incomplete.some((entry) => entry.category === 'invalid_ledger'),
+      'aggregator invalid-ledger category was not reported',
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+console.log(`Verified retry, parallel, skip, gate, manifest-reconcile, and aggregation lifecycle in ${hooks.length} hooks.`);