@fitlab-ai/agent-infra 0.9.0 → 0.9.2

package/lib/internal/release-workflow.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import semver from 'semver';
 
@@ -17,12 +18,101 @@ type CommandResult = ReturnType<typeof command>;
 type CommandRunner = (cwd: string, executable: string, args: string[]) => CommandResult;
 type DemoResult = {
   status: 'recorded' | 'skipped' | 'failed';
-  reasonCode: 'VHS_MISSING' | 'FFMPEG_MISSING' | 'DEMO_COMMAND_FAILED' | 'DEMO_OUTPUT_MISSING' | null;
+  reasonCode: 'DEMO_INPUTS_UNCHANGED' | 'GIT_LFS_MISSING' | 'VHS_MISSING' | 'FFMPEG_MISSING'
+    | 'DEMO_COMMAND_FAILED' | 'DEMO_OUTPUT_MISSING' | 'DEMO_OUTPUT_INVALID'
+    | 'DEMO_OUTPUT_TOO_LARGE' | 'DEMO_DIGEST_FAILED' | null;
   message: string | null;
   outputPath: string | null;
 };
 
+const DEMO_INPUT_PATHS = [
+  'assets/demo-init.tape',
+  'scripts/demo-regen.sh',
+  'scripts/normalize-gif-duration.py',
+  'bin/cli.ts',
+  'lib/init.ts',
+  'lib/log.ts',
+  'lib/prompt.ts',
+  'lib/paths.ts',
+  'lib/render.ts',
+  'lib/builtin-tuis.ts',
+  'lib/sandbox/engines/',
+  'src/sync-templates.js',
+  'templates/'
+] as const;
+const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';
+const DEMO_OUTPUT_PATH = 'assets/demo-init.gif';
+const DEMO_MAX_BYTES = 4 * 1024 * 1024;
+
+function demoInputFiles(cwd: string): string[] {
+  const files = new Set<string>();
+  for (const input of DEMO_INPUT_PATHS) {
+    if (input.endsWith('/')) {
+      const listed = command(cwd, 'git', ['ls-files', '--', input]);
+      if (listed.status !== 0) throw new Error(String(listed.stderr || `Unable to list ${input}`));
+      const directoryFiles = String(listed.stdout).split('\n').filter(Boolean);
+      if (!directoryFiles.length) throw new Error(`Canonical demo input directory is empty: ${input}`);
+      for (const file of directoryFiles) files.add(file.replaceAll('\\', '/'));
+    } else {
+      files.add(input);
+    }
+  }
+  const sorted = [...files].sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
+  if (!sorted.length) throw new Error('Canonical demo input set is empty');
+  for (const file of sorted) {
+    const absolute = path.join(cwd, file);
+    if (!fs.statSync(absolute).isFile()) throw new Error(`Canonical demo input is not a file: ${file}`);
+  }
+  return sorted;
+}
+
+function computeDemoInputDigest(cwd: string): string {
+  const hash = crypto.createHash('sha256');
+  for (const file of demoInputFiles(cwd)) {
+    const bytes = fs.readFileSync(path.join(cwd, file));
+    hash.update(file);
+    hash.update('\0');
+    hash.update(String(bytes.byteLength));
+    hash.update('\0');
+    hash.update(bytes);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function validGif(filePath: string): boolean {
+  if (!fs.existsSync(filePath)) return false;
+  const header = fs.readFileSync(filePath).subarray(0, 6).toString('ascii');
+  return header === 'GIF87a' || header === 'GIF89a';
+}
+
+function writeDigestAtomically(cwd: string, digest: string): void {
+  const target = path.join(cwd, DEMO_DIGEST_PATH);
+  const temporary = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${digest}\n`);
+  fs.renameSync(temporary, target);
+}
+
 function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult {
+  let digest: string;
+  try {
+    digest = computeDemoInputDigest(cwd);
+  } catch (error) {
+    return { status: 'failed', reasonCode: 'DEMO_DIGEST_FAILED', message: String(error), outputPath: null };
+  }
+  const digestPath = path.join(cwd, DEMO_DIGEST_PATH);
+  const priorDigest = fs.existsSync(digestPath) ? fs.readFileSync(digestPath, 'utf8').trim() : '';
+  if (/^[0-9a-f]{64}$/.test(priorDigest) && priorDigest === digest) {
+    return { status: 'skipped', reasonCode: 'DEMO_INPUTS_UNCHANGED', message: null, outputPath: null };
+  }
+  const lfs = run(cwd, 'git', ['lfs', 'version']);
+  if (lfs.status !== 0) {
+    return { status: 'failed', reasonCode: 'GIT_LFS_MISSING', message: String(lfs.stderr || lfs.stdout), outputPath: null };
+  }
+  const lfsAttribute = run(cwd, 'git', ['check-attr', 'filter', '--', DEMO_OUTPUT_PATH]);
+  if (lfsAttribute.status !== 0 || !String(lfsAttribute.stdout).trim().endsWith(': lfs')) {
+    return { status: 'failed', reasonCode: 'GIT_LFS_MISSING', message: `${DEMO_OUTPUT_PATH} is not tracked by Git LFS`, outputPath: null };
+  }
   const vhs = run(cwd, 'vhs', ['--version']);
   if (vhs.status !== 0) return { status: 'skipped', reasonCode: 'VHS_MISSING', message: null, outputPath: null };
   const ffmpeg = run(cwd, 'ffmpeg', ['-version']);
@@ -36,7 +126,7 @@ function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult
       outputPath: null
     };
   }
-  const outputPath = 'assets/demo-init.gif';
+  const outputPath = DEMO_OUTPUT_PATH;
   if (!fs.existsSync(path.join(cwd, outputPath))) {
     return {
       status: 'failed',
@@ -45,14 +135,73 @@ function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult
       outputPath: null
     };
   }
+  const absoluteOutput = path.join(cwd, outputPath);
+  if (!validGif(absoluteOutput)) {
+    return { status: 'failed', reasonCode: 'DEMO_OUTPUT_INVALID', message: `${outputPath} is not a GIF`, outputPath: null };
+  }
+  if (fs.statSync(absoluteOutput).size > DEMO_MAX_BYTES) {
+    return { status: 'failed', reasonCode: 'DEMO_OUTPUT_TOO_LARGE', message: `${outputPath} exceeds 4 MiB`, outputPath: null };
+  }
+  const pointer = run(cwd, 'git', ['lfs', 'pointer', `--file=${outputPath}`]);
+  if (pointer.status !== 0 || !String(pointer.stdout).includes(`size ${fs.statSync(absoluteOutput).size}`)) {
+    return { status: 'failed', reasonCode: 'DEMO_OUTPUT_INVALID', message: 'Git LFS could not produce a matching pointer', outputPath: null };
+  }
+  writeDigestAtomically(cwd, digest);
   return { status: 'recorded', reasonCode: null, message: null, outputPath };
 }
 
-function git(cwd: string, args: string[]): string | null {
-  const result = command(cwd, 'git', args);
+function git(cwd: string, args: string[], run: CommandRunner = command): string | null {
+  const result = run(cwd, 'git', args);
   return result.status === 0 ? String(result.stdout).trim() : null;
 }
 
+function inspectLocalReleaseFacts(cwd: string, version: string, run: CommandRunner = command) {
+  const tag = `v${version}`;
+  const head = git(cwd, ['rev-parse', 'HEAD'], run);
+  const tagCommit = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`], run);
+  const localTag = Boolean(tagCommit && tagCommit === head);
+  const localTagAncestor = Boolean(
+    tagCommit && head && !localTag
+    && run(cwd, 'git', ['merge-base', '--is-ancestor', tagCommit, head]).status === 0
+  );
+  const localTagConflict = Boolean(tagCommit && !localTag && !localTagAncestor);
+  const postSubject = `chore: prepare next dev iteration after v${version}`;
+  const postLog = localTag || localTagAncestor
+    ? git(cwd, ['log', '--format=%s', `${tag}..HEAD`], run) ?? ''
+    : '';
+  const postCommit = postLog.split('\n').some((subject) => subject === postSubject);
+  return { localTag, localTagAncestor, localTagConflict, postCommit };
+}
+
+function releaseSmokeStatus(workflows: Array<Record<string, unknown>>, version: string, tagCommit: string | null): ReleaseFacts['smoke'] {
+  const manualTitle = `Post-Release Smoke v${version}`;
+  const targets = workflows.filter((run) => {
+    if (String(run.workflowName || run.name) !== 'Post-Release Smoke') return false;
+    if (String(run.event) === 'workflow_run') return Boolean(tagCommit && String(run.headSha) === tagCommit);
+    return String(run.event) === 'workflow_dispatch' && String(run.displayTitle) === manualTitle;
+  }).sort((left, right) => {
+    const leftOrder = [Date.parse(String(left.createdAt || '')) || 0, Number(left.databaseId) || 0, Number(left.attempt) || 0];
+    const rightOrder = [Date.parse(String(right.createdAt || '')) || 0, Number(right.databaseId) || 0, Number(right.attempt) || 0];
+    for (let index = 0; index < leftOrder.length; index += 1) {
+      if (leftOrder[index] !== rightOrder[index]) return rightOrder[index]! - leftOrder[index]!;
+    }
+    return 0;
+  });
+  const latest = targets[0];
+  if (!latest) return null;
+  if (String(latest.status) !== 'completed') return 'pending';
+  return String(latest.conclusion) === 'success' ? 'success' : 'failed';
+}
+
+function inspectPostWorktree(cwd: string) {
+  const inspected = inspectGitWorkflow(cwd);
+  if (!inspected.snapshot) return inspected.error ?? { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' };
+  if (inspected.snapshot.worktree.length || inspected.snapshot.staged.length) {
+    return { code: 'WORKTREE_DIRTY', message: 'Release post requires a clean worktree' };
+  }
+  return null;
+}
+
 async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts> {
   const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')) as { name: string };
   const config = JSON.parse(fs.readFileSync(path.join(cwd, '.agents', '.airc.json'), 'utf8')) as { project: string; org: string };
@@ -60,6 +209,7 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
   const branch = git(cwd, ['branch', '--show-current']) || '';
   const head = git(cwd, ['rev-parse', 'HEAD']);
   const localTagTarget = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`]);
+  const local = inspectLocalReleaseFacts(cwd, version);
   const remoteBranch = branch ? git(cwd, ['ls-remote', '--heads', 'origin', branch]) : null;
   const remoteTag = git(cwd, ['ls-remote', '--tags', 'origin', `refs/tags/${tag}`]);
   const platform = inspectPlatformRelease(tag, { cwd });
@@ -67,18 +217,14 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
   const formulaUrl = `https://raw.githubusercontent.com/${config.org}/homebrew-tap/main/Formula/${config.project}.rb`;
   const homebrew = await inspectHomebrewChannel(formulaUrl, version);
   const workflows = platform.workflows as Array<Record<string, unknown>>;
-  const smokeRun = workflows.find((run) => String(run.name).toLowerCase().includes('post-release-smoke') && String(run.headBranch) === tag);
-  const smoke = smokeRun ? String(smokeRun.conclusion) === 'success' ? 'success' : String(smokeRun.status) === 'completed' ? 'failed' : 'pending' : null;
-  const postMessage = git(cwd, ['log', '-1', '--pretty=%s']) || '';
+  const smoke = releaseSmokeStatus(workflows, version, localTagTarget);
   return {
-    localTag: Boolean(localTagTarget && localTagTarget === head),
-    localTagConflict: Boolean(localTagTarget && localTagTarget !== head),
+    ...local,
     remoteBranch: Boolean(remoteBranch && remoteBranch.split(/\s+/)[0] === head), remoteTag: Boolean(remoteTag),
     githubRelease: platform.platform.type !== 'github'
       ? true
       : platform.status === 'blocked' ? null : Boolean(platform.release?.published),
-    npm: npm.published, homebrew: homebrew.published, smoke,
-    postCommit: postMessage.includes(`after v${version}`)
+    npm: npm.published, homebrew: homebrew.published, smoke
   };
 }
 
@@ -116,12 +262,11 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   }
   const before = releaseSnapshot(version, await inspectFacts(cwd, version));
   if (action === 'inspect') { process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`); return; }
+  if (before.facts.localTagConflict) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} is not reachable from HEAD` } })}\n`);
+    process.exitCode = 1; return;
+  }
   if (action === 'prepare') {
-    if (before.facts.localTagConflict) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} does not point to HEAD` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
     if (before.phase !== 'unprepared') {
       const milestones = reconcileReleaseMilestones(version, { cwd });
       process.stdout.write(`${JSON.stringify({ ...milestones, snapshot: before })}\n`);
@@ -152,16 +297,25 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     process.exitCode = failed ? 1 : blocked ? 2 : 0; return;
   }
   if (action === 'publish') {
-    if (!['prepared', 'partially-published'].includes(before.phase)) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`); process.exitCode = 1; return; }
+    if (!before.facts.localTag || !['prepared', 'partially-published'].includes(before.phase)) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`); process.exitCode = 1; return; }
     const branch = git(cwd, ['branch', '--show-current']) || '';
     const refs = [...(!before.facts.remoteBranch ? [branch] : []), ...(!before.facts.remoteTag ? [`refs/tags/v${version}`] : [])];
     const result = pushGitRefs({ cwd, remote: 'origin', refs });
     process.stdout.write(`${JSON.stringify({ ...result, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`); process.exitCode = result.status === 'failed' ? 1 : result.status === 'degraded' ? 2 : 0; return;
   }
+  if (before.phase === 'complete') {
+    process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`);
+    return;
+  }
   const channelsComplete = before.facts.githubRelease === true && before.facts.npm === true && before.facts.homebrew === true;
   if (!['published', 'post-pending'].includes(before.phase) || !channelsComplete || before.facts.smoke !== 'success') {
     process.stdout.write(`${JSON.stringify({ status: before.facts.smoke === 'failed' ? 'failed' : 'blocked', changed: false, snapshot: before, error: { code: 'RELEASE_CHANNELS_PENDING', message: 'Release channels or smoke workflow are not complete' } })}\n`); process.exitCode = before.facts.smoke === 'failed' ? 1 : 2; return;
   }
+  const worktreeError = inspectPostWorktree(cwd);
+  if (worktreeError) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: worktreeError })}\n`);
+    process.exitCode = 1; return;
+  }
   const built = command(cwd, 'npm', ['run', 'build']);
   if (built.status !== 0) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(built.stderr || built.stdout) } })}\n`);
@@ -182,5 +336,5 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   process.stdout.write(`${JSON.stringify({ ...pushed, demo, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`); process.exitCode = pushed.status === 'failed' ? 1 : pushed.status === 'degraded' ? 2 : 0;
 }
 
-export { inspectFacts, releaseWorkflow, runOptionalDemo };
+export { computeDemoInputDigest, inspectFacts, inspectLocalReleaseFacts, inspectPostWorktree, releaseSmokeStatus, releaseWorkflow, runOptionalDemo };
 export type { CommandRunner, DemoResult };

package/lib/internal/task-orchestration.ts

@@ -0,0 +1,132 @@
+import {
+  activateMatchingOrchestrationDelegation,
+  activateOrchestrationDelegation,
+  advanceOrchestration,
+  beginOrResumeOrchestration,
+  completeCommitOrchestrationStage,
+  pauseOrchestration,
+  prepareOrchestrationDelegation,
+  routeOrchestration,
+  sealMatchingOrchestrationDelegation,
+  sealOrchestrationDelegation,
+  statusOrchestration
+} from '../task/orchestration.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|stage-completed|hook-stop|advance|pause|status> [options]\n';
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed', changed: false,
+    error: { code: 'ORCHESTRATION_PAYLOAD_INVALID', message }
+  })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskOrchestration(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    usageFailure('task ref and intent are required');
+    return;
+  }
+  const [taskRef, intent] = args;
+  if (!['begin-or-resume', 'route', 'prepare', 'hook-start', 'stage-completed', 'hook-stop', 'advance', 'pause', 'status'].includes(intent!)) {
+    usageFailure(`unknown intent '${intent}'`);
+    return;
+  }
+  const values: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (![
+      '--max-steps', '--client', '--requested-model', '--parent-id', '--before-fingerprint',
+      '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--fallback-reason',
+      '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent'
+    ].includes(flag)) {
+      usageFailure(`unknown option '${flag}'`);
+      return;
+    }
+    if (seen.has(flag)) {
+      usageFailure(`duplicate option '${flag}'`);
+      return;
+    }
+    seen.add(flag);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      usageFailure(`option '${flag}' requires a value`);
+      return;
+    }
+    values[flag] = value;
+  }
+  const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
+  let result;
+  if (intent === 'begin-or-resume') {
+    const maxSteps = values['--max-steps'] === undefined ? undefined : Number(values['--max-steps']);
+    if (maxSteps !== undefined && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
+      usageFailure('--max-steps must be a positive integer'); return;
+    }
+    result = beginOrResumeOrchestration(taskRef!, { maxSteps });
+  } else if (intent === 'route') {
+    result = routeOrchestration(taskRef!);
+  } else if (intent === 'status') {
+    result = statusOrchestration(taskRef!);
+  } else if (intent === 'prepare') {
+    const missing = requireValues(['--client']);
+    if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
+    result = prepareOrchestrationDelegation(taskRef!, {
+      client: values['--client'] as AgentClientId,
+      requestedModel: values['--requested-model']
+    });
+  } else if (intent === 'hook-start') {
+    const missing = requireValues([
+      ...(taskRef === 'auto' ? ['--client'] : []),
+      '--native-agent', '--child-id', '--parent-id', '--spawn-mode'
+    ]);
+    if (missing) { usageFailure(`intent 'hook-start' requires '${missing}'`); return; }
+    const event = {
+      nativeAgent: values['--native-agent']!, childId: values['--child-id']!,
+      parentId: values['--parent-id']!, spawnMode: values['--spawn-mode']!,
+      actualModel: values['--actual-model'], modelFallbackReason: values['--fallback-reason']
+    };
+    result = taskRef === 'auto'
+      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event)
+      : activateOrchestrationDelegation(taskRef!, event);
+  } else if (intent === 'hook-stop') {
+    if (taskRef === 'auto') {
+      const missing = requireValues(['--client', '--native-agent', '--child-id']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
+        nativeAgent: values['--native-agent']!, childId: values['--child-id']!
+      });
+    } else {
+      const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      const exitCode = Number(values['--exit-code']);
+      if (!Number.isInteger(exitCode)) { usageFailure('--exit-code must be an integer'); return; }
+      result = sealOrchestrationDelegation(taskRef!, {
+        childId: values['--child-id']!, exitCode,
+        afterFingerprint: values['--after-fingerprint']!,
+        changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
+      });
+    }
+  } else if (intent === 'stage-completed') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'stage-completed' requires '${missing}'`); return; }
+    result = completeCommitOrchestrationStage(taskRef!, values['--agent']!);
+  } else if (intent === 'advance') {
+    result = advanceOrchestration(taskRef!);
+  } else {
+    const missing = requireValues(['--code', '--message', '--recoverable']);
+    if (missing) { usageFailure(`intent 'pause' requires '${missing}'`); return; }
+    if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
+    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true');
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskOrchestration };

package/lib/internal/task-review.ts

@@ -0,0 +1,65 @@
+import { finalizeReviewSummary } from '../task/review-finalization.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--dry-run]\n';
+
+function failUsage(message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    intent: 'finalize-summary',
+    error: { code: 'REVIEW_PAYLOAD_INVALID', message }
+  })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskReview(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    failUsage('task ref and intent are required');
+    return;
+  }
+  if (args[1] !== 'finalize-summary') {
+    failUsage(`unknown intent '${args[1]}'`);
+    return;
+  }
+  let stage = '';
+  let artifact = '';
+  let dryRun = false;
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--stage', '--artifact', '--dry-run'].includes(flag)) {
+      failUsage(`unknown option '${flag}'`);
+      return;
+    }
+    if (seen.has(flag)) {
+      failUsage(`duplicate option '${flag}'`);
+      return;
+    }
+    seen.add(flag);
+    if (flag === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failUsage(`option '${flag}' requires a value`);
+      return;
+    }
+    if (flag === '--stage') stage = value;
+    else artifact = value;
+  }
+  if (!stage || !artifact) {
+    failUsage("options '--stage' and '--artifact' are required");
+    return;
+  }
+  const result = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, dryRun });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskReview };

package/lib/merge.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { info, ok } from './log.ts';
+import { removeDirRecursive } from './remove-dir.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
@@ -690,7 +691,7 @@ function mergeMutableSections({ sourceWorkspace, localWorkspace, backupRoot, rep
       if (comparison > 0) {
         backupTaskDir(backupRoot, localMatch.section, localMatch.taskDir, localMatch.taskId);
         report.backupCount += 1;
-        fs.rmSync(localMatch.taskDir, { recursive: true, force: true });
+        removeDirRecursive(localMatch.taskDir);
 
         const destinationDir = copyTaskToSection(sourceTask, localWorkspace);
         localIndex.set(sourceTask.taskId, {

package/lib/platform/adapters.ts

@@ -1,4 +1,4 @@
-import type { PlatformResult } from './types.ts';
+import type { PlatformError, PlatformResult } from './types.ts';
 
 type PlatformAdapterContext = {
   cwd: string;
@@ -6,9 +6,71 @@ type PlatformAdapterContext = {
   client?: unknown;
 };
 
+type PlatformChangeRequestSnapshot = {
+  repository: string;
+  number: number;
+  nodeId: string;
+  url: string;
+  state: 'open' | 'closed';
+  title: string;
+  body: string;
+  draft: boolean;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+  mergedAt: string | null;
+  mergeCommitSha: string | null;
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+};
+
+type PlatformCheckSnapshot = {
+  name: string;
+  bucket: 'pass' | 'fail' | 'pending' | 'cancel';
+  workflow?: string | null;
+  conclusion?: string | null;
+  detailsUrl?: string | null;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};
+
+type PlatformInspectionResult<T> = {
+  ok: boolean;
+  value?: T;
+  error?: PlatformError;
+};
+
+type ChangeRequestInspectionContext = PlatformAdapterContext & {
+  repository: string;
+  number: number;
+};
+
+type RequiredChecksInspectionContext = ChangeRequestInspectionContext & {
+  headSha: string;
+};
+
+type ChangeRequestGitEvidenceContext = ChangeRequestInspectionContext & {
+  pullRequest: PlatformChangeRequestSnapshot;
+};
+
+type PlatformChangeRequestGitEvidenceSpec = {
+  remoteUrl: string;
+  reviewedHeadRef: string;
+  targetHeadRef: string;
+};
+
 type PlatformAdapter = {
   type: string;
   resolveContext(context: PlatformAdapterContext): PlatformResult;
+  inspectChangeRequest?(
+    context: ChangeRequestInspectionContext
+  ): PlatformInspectionResult<PlatformChangeRequestSnapshot>;
+  inspectRequiredChecks?(
+    context: RequiredChecksInspectionContext
+  ): PlatformInspectionResult<PlatformCheckSnapshot[]>;
+  resolveChangeRequestGitEvidence?(
+    context: ChangeRequestGitEvidenceContext
+  ): PlatformInspectionResult<PlatformChangeRequestGitEvidenceSpec>;
 };
 
 const adapters = new Map<string, PlatformAdapter>();
@@ -22,9 +84,86 @@ function getPlatformAdapter(type: string | null): PlatformAdapter | null {
   return type ? adapters.get(type) ?? null : null;
 }
 
+function registerPlatformCapabilities(
+  type: string,
+  capabilities: Pick<
+    PlatformAdapter,
+    'inspectChangeRequest' | 'inspectRequiredChecks' | 'resolveChangeRequestGitEvidence'
+  >
+): void {
+  const adapter = adapters.get(type);
+  if (!adapter) throw new Error(`Platform adapter '${type}' must be registered before its capabilities`);
+  adapters.set(type, { ...adapter, ...capabilities });
+}
+
+function hasPlatformCapability(
+  type: string | null,
+  capability: 'change-request' | 'required-checks' | 'change-request-git-evidence'
+): boolean {
+  const adapter = getPlatformAdapter(type);
+  if (capability === 'change-request') return typeof adapter?.inspectChangeRequest === 'function';
+  if (capability === 'required-checks') return typeof adapter?.inspectRequiredChecks === 'function';
+  return typeof adapter?.resolveChangeRequestGitEvidence === 'function';
+}
+
+function unsupported<T>(type: string | null, capability: string): PlatformInspectionResult<T> {
+  return {
+    ok: false,
+    error: {
+      code: 'PLATFORM_CAPABILITY_UNSUPPORTED',
+      message: `Platform '${type || 'none'}' does not provide ${capability}`,
+      retryable: false
+    }
+  };
+}
+
+function inspectPlatformChangeRequest(
+  type: string | null,
+  context: ChangeRequestInspectionContext
+): PlatformInspectionResult<PlatformChangeRequestSnapshot> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.inspectChangeRequest?.(context) ?? unsupported(type, 'change-request inspection');
+}
+
+function inspectPlatformRequiredChecks(
+  type: string | null,
+  context: RequiredChecksInspectionContext
+): PlatformInspectionResult<PlatformCheckSnapshot[]> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.inspectRequiredChecks?.(context) ?? unsupported(type, 'required-checks inspection');
+}
+
+function resolvePlatformChangeRequestGitEvidence(
+  type: string | null,
+  context: ChangeRequestGitEvidenceContext
+): PlatformInspectionResult<PlatformChangeRequestGitEvidenceSpec> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.resolveChangeRequestGitEvidence?.(context) ??
+    unsupported(type, 'change-request Git evidence');
+}
+
 function listPlatformAdapters(): string[] {
   return [...adapters.keys()].sort();
 }
 
-export { getPlatformAdapter, listPlatformAdapters, registerPlatformAdapter };
-export type { PlatformAdapter, PlatformAdapterContext };
+export {
+  getPlatformAdapter,
+  hasPlatformCapability,
+  inspectPlatformChangeRequest,
+  inspectPlatformRequiredChecks,
+  listPlatformAdapters,
+  registerPlatformAdapter,
+  registerPlatformCapabilities,
+  resolvePlatformChangeRequestGitEvidence
+};
+export type {
+  ChangeRequestGitEvidenceContext,
+  ChangeRequestInspectionContext,
+  PlatformAdapter,
+  PlatformAdapterContext,
+  PlatformChangeRequestGitEvidenceSpec,
+  PlatformChangeRequestSnapshot,
+  PlatformCheckSnapshot,
+  PlatformInspectionResult,
+  RequiredChecksInspectionContext
+};