@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/task/manual-validation-transaction.ts

@@ -0,0 +1,304 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+import { validateManualValidationReceipt } from './manual-validation-receipt.ts';
+import {
+  MANUAL_VALIDATION_ARTIFACT as ARTIFACT,
+  MANUAL_VALIDATION_SHA40 as SHA40,
+  MANUAL_VALIDATION_SHA64 as SHA64,
+  MANUAL_VALIDATION_TASK_ID as TASK_ID,
+  exactKeys,
+  isRecord,
+  validTimestamp,
+  writeJsonAtomic
+} from './manual-validation-shared.ts';
+
+const MANUAL_VALIDATION_TRANSACTION_SCHEMA = 'agent-infra/manual-validation-transaction';
+const MANUAL_VALIDATION_TRANSACTION_VERSION = 1;
+const TRANSACTION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+type ManualValidationTransactionPhase = 'prepared' | 'summary-staged' | 'receipt-committed' | 'final-promotion-in-progress' | 'committed' | 'aborted' | 'recovery-required';
+type ManualValidationSummaryPreimage = Readonly<{ commentId: number | string | null; body: string; digest: string }>;
+type ManualValidationTransaction = Readonly<{
+  schema: typeof MANUAL_VALIDATION_TRANSACTION_SCHEMA;
+  version: typeof MANUAL_VALIDATION_TRANSACTION_VERSION;
+  transactionId: string;
+  taskId: string;
+  prNumber: number;
+  prHeadSha: string;
+  evidenceDigest: string;
+  summaryPreimage: ManualValidationSummaryPreimage;
+  pendingSummaryDigest: string;
+  finalSummaryDigest: string;
+  artifact: string;
+  phase: ManualValidationTransactionPhase;
+  committedReceipt: string | null;
+  eventAppended: boolean;
+  attempt: number;
+  postWriteVerified: boolean;
+  createdAt: string;
+  updatedAt: string;
+  error: string | null;
+}>;
+type ManualValidationTransactionInput = Omit<ManualValidationTransaction, 'schema' | 'version' | 'phase' | 'committedReceipt' | 'eventAppended' | 'postWriteVerified' | 'error'> & {
+  transactionId?: string;
+};
+type ManualValidationTransactionPatch = Partial<Pick<ManualValidationTransaction, 'committedReceipt' | 'eventAppended' | 'postWriteVerified' | 'error' | 'updatedAt' | 'attempt'>>;
+type ManualValidationTransactionErrorCode =
+  | 'MANUAL_VALIDATION_TRANSACTION_INVALID'
+  | 'MANUAL_VALIDATION_TRANSACTION_MISSING'
+  | 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH'
+  | 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID';
+type ManualValidationTransactionError = { code: ManualValidationTransactionErrorCode; message: string };
+type ManualValidationTransactionResult =
+  | { ok: true; value: ManualValidationTransaction }
+  | { ok: false; error: ManualValidationTransactionError };
+type ManualValidationGenerationArchiveOptions = Readonly<{
+  afterReceiptMove?: () => void;
+}>;
+
+function invalid(message: string): ManualValidationTransactionResult {
+  return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_INVALID', message } };
+}
+
+function summaryPreimageDigest(body: string): string {
+  return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+
+function validateManualValidationTransaction(value: unknown, expected?: Partial<Pick<ManualValidationTransaction, 'transactionId' | 'taskId' | 'prNumber' | 'prHeadSha' | 'evidenceDigest' | 'artifact'>>): ManualValidationTransactionResult {
+  if (!isRecord(value)) return invalid('transaction must be a JSON object');
+  const keys = ['schema', 'version', 'transactionId', 'taskId', 'prNumber', 'prHeadSha', 'evidenceDigest', 'summaryPreimage', 'pendingSummaryDigest', 'finalSummaryDigest', 'artifact', 'phase', 'committedReceipt', 'eventAppended', 'attempt', 'postWriteVerified', 'createdAt', 'updatedAt', 'error'];
+  const keyError = exactKeys(value, keys, 'transaction');
+  if (keyError) return invalid(keyError);
+  if (value.schema !== MANUAL_VALIDATION_TRANSACTION_SCHEMA || value.version !== MANUAL_VALIDATION_TRANSACTION_VERSION) return invalid('transaction schema or version is unsupported');
+  if (typeof value.transactionId !== 'string' || !TRANSACTION_ID.test(value.transactionId)) return invalid('transactionId is invalid');
+  if (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId)) return invalid('taskId is invalid');
+  const prNumber = value.prNumber;
+  if (!Number.isSafeInteger(prNumber) || (prNumber as number) <= 0) return invalid('prNumber is invalid');
+  if (typeof value.prHeadSha !== 'string' || !SHA40.test(value.prHeadSha)) return invalid('prHeadSha is invalid');
+  if (typeof value.evidenceDigest !== 'string' || !SHA64.test(value.evidenceDigest)) return invalid('evidenceDigest is invalid');
+  if (!isRecord(value.summaryPreimage)) return invalid('summaryPreimage is invalid');
+  const preimage = value.summaryPreimage;
+  const preimageKeyError = exactKeys(preimage, ['commentId', 'body', 'digest'], 'summaryPreimage');
+  if (preimageKeyError) return invalid(preimageKeyError);
+  if (preimage.commentId !== null && typeof preimage.commentId !== 'number' && typeof preimage.commentId !== 'string') return invalid('summaryPreimage.commentId is invalid');
+  if (typeof preimage.body !== 'string' || typeof preimage.digest !== 'string' || !SHA64.test(preimage.digest) || summaryPreimageDigest(preimage.body) !== preimage.digest) return invalid('summaryPreimage digest is invalid');
+  for (const field of ['pendingSummaryDigest', 'finalSummaryDigest'] as const) if (typeof value[field] !== 'string' || !SHA64.test(value[field])) return invalid(`${field} is invalid`);
+  if (typeof value.artifact !== 'string' || !ARTIFACT.test(value.artifact)) return invalid('artifact is invalid');
+  if (!['prepared', 'summary-staged', 'receipt-committed', 'final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'].includes(value.phase as string)) return invalid('phase is invalid');
+  if (value.committedReceipt !== null && (typeof value.committedReceipt !== 'string' || !SHA64.test(value.committedReceipt))) return invalid('committedReceipt is invalid');
+  if (typeof value.eventAppended !== 'boolean' || typeof value.postWriteVerified !== 'boolean') return invalid('transaction completion flags are invalid');
+  const attempt = value.attempt;
+  if (!Number.isSafeInteger(attempt) || (attempt as number) < 1) return invalid('attempt is invalid');
+  if (!validTimestamp(value.createdAt) || !validTimestamp(value.updatedAt)) return invalid('transaction timestamps are invalid');
+  if (value.error !== null && (typeof value.error !== 'string' || !value.error || /[\r\n]/u.test(value.error))) return invalid('transaction error is invalid');
+  if (['receipt-committed', 'final-promotion-in-progress', 'committed'].includes(value.phase as string) && value.committedReceipt === null) return invalid('receipt-backed phases require committedReceipt');
+  if (['final-promotion-in-progress', 'committed'].includes(value.phase as string) && !value.eventAppended) return invalid('final promotion requires an appended completion event');
+  if (value.phase === 'committed' && !value.postWriteVerified) return invalid('committed phase requires post-write verification');
+  const transaction = value as unknown as ManualValidationTransaction;
+  if (expected && Object.entries(expected).some(([key, expectedValue]) => expectedValue !== undefined && transaction[key as keyof ManualValidationTransaction] !== expectedValue)) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH', message: 'transaction identity does not match the expected operation' } };
+  }
+  return { ok: true, value: transaction };
+}
+
+function createManualValidationTransaction(input: ManualValidationTransactionInput): ManualValidationTransaction {
+  const transaction: ManualValidationTransaction = {
+    schema: MANUAL_VALIDATION_TRANSACTION_SCHEMA,
+    version: MANUAL_VALIDATION_TRANSACTION_VERSION,
+    transactionId: input.transactionId ?? `mv-${randomUUID()}`,
+    taskId: input.taskId,
+    prNumber: input.prNumber,
+    prHeadSha: input.prHeadSha,
+    evidenceDigest: input.evidenceDigest,
+    summaryPreimage: input.summaryPreimage,
+    pendingSummaryDigest: input.pendingSummaryDigest,
+    finalSummaryDigest: input.finalSummaryDigest,
+    artifact: input.artifact,
+    phase: 'prepared',
+    committedReceipt: null,
+    eventAppended: false,
+    attempt: input.attempt,
+    postWriteVerified: false,
+    createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
+    error: null
+  };
+  const checked = validateManualValidationTransaction(transaction);
+  if (!checked.ok) throw new Error(`${checked.error.code}: ${checked.error.message}`);
+  return checked.value;
+}
+
+const allowedTransitions: Record<ManualValidationTransactionPhase, readonly ManualValidationTransactionPhase[]> = {
+  prepared: ['prepared', 'summary-staged', 'aborted', 'recovery-required'],
+  'summary-staged': ['summary-staged', 'receipt-committed', 'aborted', 'recovery-required'],
+  'receipt-committed': ['receipt-committed', 'final-promotion-in-progress', 'aborted', 'recovery-required'],
+  'final-promotion-in-progress': ['final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'],
+  committed: ['committed'],
+  aborted: ['aborted', 'prepared'],
+  'recovery-required': ['recovery-required', 'prepared']
+};
+
+function transitionManualValidationTransaction(
+  current: ManualValidationTransaction,
+  phase: ManualValidationTransactionPhase,
+  patch: ManualValidationTransactionPatch = {}
+): ManualValidationTransactionResult {
+  if (!allowedTransitions[current.phase].includes(phase)) return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: `cannot transition from ${current.phase} to ${phase}` } };
+  if (phase === 'final-promotion-in-progress' && (!current.eventAppended && patch.eventAppended !== true)) return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final promotion requires an appended completion event' } };
+  const next: ManualValidationTransaction = {
+    ...current,
+    phase,
+    committedReceipt: patch.committedReceipt !== undefined ? patch.committedReceipt : current.committedReceipt,
+    eventAppended: patch.eventAppended ?? current.eventAppended,
+    postWriteVerified: patch.postWriteVerified ?? current.postWriteVerified,
+    attempt: patch.attempt ?? current.attempt,
+    error: patch.error !== undefined ? patch.error : current.error,
+    updatedAt: patch.updatedAt ?? new Date().toISOString()
+  };
+  const checked = validateManualValidationTransaction(next);
+  if (!checked.ok) return checked;
+  return checked;
+}
+
+function retryManualValidationTransaction(current: ManualValidationTransaction, now = new Date().toISOString()): ManualValidationTransactionResult {
+  if (!['aborted', 'recovery-required'].includes(current.phase)) return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'only aborted or recovery-required transactions can be retried' } };
+  return transitionManualValidationTransaction(current, 'prepared', {
+    updatedAt: now,
+    error: null,
+    committedReceipt: null,
+    eventAppended: false,
+    postWriteVerified: false,
+    attempt: current.attempt + 1
+  });
+}
+
+function manualValidationTransactionPath(taskDir: string): string {
+  return path.join(taskDir, '.manual-validation', 'transaction.json');
+}
+
+function manualValidationGenerationPaths(taskDir: string, transaction: ManualValidationTransaction): {
+  receipt: { current: string; history: string };
+  transaction: { current: string; history: string };
+} {
+  const stateDir = path.join(taskDir, '.manual-validation');
+  const historyDir = path.join(stateDir, 'history');
+  return {
+    receipt: {
+      current: path.join(stateDir, 'receipt.json'),
+      history: path.join(historyDir, `receipt-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+    },
+    transaction: {
+      current: manualValidationTransactionPath(taskDir),
+      history: path.join(historyDir, `transaction-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+    }
+  };
+}
+
+function readReceiptAt(file: string, transaction: ManualValidationTransaction): 'missing' | 'valid' {
+  let value: unknown;
+  try {
+    value = JSON.parse(fs.readFileSync(file, 'utf8')) as unknown;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';
+    throw new Error(`manual-validation receipt is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const checked = validateManualValidationReceipt(value, {
+    transactionId: transaction.transactionId,
+    taskId: transaction.taskId,
+    prNumber: transaction.prNumber,
+    prHeadSha: transaction.prHeadSha,
+    evidenceDigest: transaction.evidenceDigest,
+    artifact: transaction.artifact
+  });
+  if (!checked.ok) throw new Error(`manual-validation receipt is invalid: ${checked.error.message}`);
+  if (transaction.committedReceipt !== null && checked.value.receiptDigest !== transaction.committedReceipt) {
+    throw new Error('manual-validation receipt does not match the committed transaction');
+  }
+  return 'valid';
+}
+
+function validateManualValidationGenerationArchive(taskDir: string, transaction: ManualValidationTransaction, requireReceipt = false): void {
+  const paths = manualValidationGenerationPaths(taskDir, transaction);
+  const currentTransaction = fs.existsSync(paths.transaction.current);
+  const archivedTransaction = fs.existsSync(paths.transaction.history);
+  if (currentTransaction && archivedTransaction) throw new Error(`manual-validation archive has conflicting transaction files for ${transaction.transactionId}`);
+  if (!currentTransaction && !archivedTransaction) throw new Error(`manual-validation archive source is missing: ${paths.transaction.current}`);
+  const currentReceipt = requireReceipt
+    ? readReceiptAt(paths.receipt.current, transaction)
+    : (fs.existsSync(paths.receipt.current) ? 'valid' : 'missing');
+  const archivedReceipt = requireReceipt
+    ? readReceiptAt(paths.receipt.history, transaction)
+    : (fs.existsSync(paths.receipt.history) ? 'valid' : 'missing');
+  if (requireReceipt && currentReceipt === 'missing' && archivedReceipt === 'missing') {
+    throw new Error(`manual-validation receipt is missing for transaction ${transaction.transactionId}`);
+  }
+  if (currentReceipt === 'valid' && archivedReceipt === 'valid') {
+    throw new Error(`manual-validation archive has conflicting receipt files for ${transaction.transactionId}`);
+  }
+}
+
+function archiveManualValidationGeneration(
+  taskDir: string,
+  transaction: ManualValidationTransaction,
+  requireReceipt = false,
+  options: ManualValidationGenerationArchiveOptions = {}
+): void {
+  const paths = manualValidationGenerationPaths(taskDir, transaction);
+  validateManualValidationGenerationArchive(taskDir, transaction, requireReceipt);
+  fs.mkdirSync(path.dirname(paths.receipt.history), { recursive: true });
+  const move = (source: string, target: string, required: boolean): void => {
+    if (!fs.existsSync(source)) {
+      if (fs.existsSync(target) || !required) return;
+      throw new Error(`manual-validation archive source is missing: ${source}`);
+    }
+    if (fs.existsSync(target)) throw new Error(`manual-validation archive target already exists: ${target}`);
+    fs.renameSync(source, target);
+  };
+  move(paths.receipt.current, paths.receipt.history, requireReceipt);
+  options.afterReceiptMove?.();
+  move(paths.transaction.current, paths.transaction.history, true);
+}
+
+function writeManualValidationTransactionAtomic(taskDir: string, transaction: ManualValidationTransaction): string {
+  const checked = validateManualValidationTransaction(transaction);
+  if (!checked.ok) throw new Error(`${checked.error.code}: ${checked.error.message}`);
+  const target = manualValidationTransactionPath(taskDir);
+  return writeJsonAtomic(target, transaction);
+}
+
+function readManualValidationTransaction(taskDir: string, expected?: Parameters<typeof validateManualValidationTransaction>[1]): ManualValidationTransactionResult {
+  const file = manualValidationTransactionPath(taskDir);
+  let value: unknown;
+  try { value = JSON.parse(fs.readFileSync(file, 'utf8')) as unknown; }
+  catch (error) {
+    return { ok: false, error: { code: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'MANUAL_VALIDATION_TRANSACTION_MISSING' : 'MANUAL_VALIDATION_TRANSACTION_INVALID', message: error instanceof Error ? error.message : String(error) } };
+  }
+  return validateManualValidationTransaction(value, expected);
+}
+
+export {
+  MANUAL_VALIDATION_TRANSACTION_SCHEMA,
+  MANUAL_VALIDATION_TRANSACTION_VERSION,
+  archiveManualValidationGeneration,
+  createManualValidationTransaction,
+  manualValidationTransactionPath,
+  validateManualValidationGenerationArchive,
+  readManualValidationTransaction,
+  retryManualValidationTransaction,
+  summaryPreimageDigest,
+  transitionManualValidationTransaction,
+  validateManualValidationTransaction,
+  writeManualValidationTransactionAtomic
+};
+export type {
+  ManualValidationSummaryPreimage,
+  ManualValidationTransaction,
+  ManualValidationTransactionError,
+  ManualValidationTransactionErrorCode,
+  ManualValidationTransactionInput,
+  ManualValidationTransactionPatch,
+  ManualValidationTransactionPhase,
+  ManualValidationTransactionResult
+};

package/lib/task/markdown.ts

@@ -0,0 +1,70 @@
+type SourceLine = {
+  start: number;
+  end: number;
+  text: string;
+};
+
+type VisibleHeading = SourceLine & {
+  level: number;
+  text: string;
+};
+
+type VisibleAnchor = SourceLine & {
+  id: string;
+};
+
+type VisibleMarkdown = {
+  hasUnclosedFence: boolean;
+  lines: SourceLine[];
+  headings: VisibleHeading[];
+  anchors: VisibleAnchor[];
+};
+
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)\s*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})\s*$/;
+const ANCHOR = /^\s*<a\s+id=(['"])([^'"]+)\1\s*><\/a>\s*$/;
+
+function sourceLines(content: string): SourceLine[] {
+  const lines: SourceLine[] = [];
+  let start = 0;
+  while (start < content.length) {
+    const newline = content.indexOf('\n', start);
+    const end = newline === -1 ? content.length : newline;
+    lines.push({ start, end, text: content.slice(start, end).replace(/\r$/, '') });
+    start = newline === -1 ? content.length : newline + 1;
+  }
+  return lines;
+}
+
+function scanVisibleMarkdown(content: string): VisibleMarkdown {
+  const lines = sourceLines(content);
+  const visible: SourceLine[] = [];
+  const headings: VisibleHeading[] = [];
+  const anchors: VisibleAnchor[] = [];
+  let fence: { character: '`' | '~'; length: number } | null = null;
+
+  for (const line of lines) {
+    if (fence) {
+      const close = line.text.match(FENCE_CLOSE);
+      if (close && close[1]![0] === fence.character && close[1]!.length >= fence.length) fence = null;
+      continue;
+    }
+    const open = line.text.match(FENCE_OPEN);
+    const marker = open?.[1];
+    const info = open?.[2] ?? '';
+    if (marker && !(marker[0] === '`' && info.includes('`'))) {
+      fence = { character: marker[0] as '`' | '~', length: marker.length };
+      continue;
+    }
+    visible.push(line);
+    const heading = line.text.match(HEADING);
+    if (heading) headings.push({ ...line, level: heading[1]!.length, text: heading[2]!.trim() });
+    const anchor = line.text.match(ANCHOR);
+    if (anchor) anchors.push({ ...line, id: anchor[2]! });
+  }
+  return { lines: visible, headings, anchors, hasUnclosedFence: fence !== null };
+}
+
+export { scanVisibleMarkdown };
+export type { SourceLine, VisibleHeading, VisibleMarkdown };

package/lib/task/orchestration.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 
+import { artifactName, maxArtifactRound } from './artifact-name.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import { validateCurrentTaskContract } from './current-contract.ts';
 import { parseReviewSummary } from './review-artifacts.ts';
@@ -39,6 +40,7 @@ import type {
   OrchestrationModelPolicy,
   OrchestrationRolePolicy
 } from '../agent-clients/types.ts';
+import type { LifecycleRecoveryAttestationV1 } from './control-authority.ts';
 import {
   captureRepositorySnapshot,
   captureWorkspaceSnapshot,
@@ -173,6 +175,7 @@ type OrchestrationOptions = {
   supportsLifecycleDelegation?: (client: AgentClientId) => boolean;
   validateLifecycleCapability?: () => Exclude<OrchestrationResult['error'], null> | null;
   consumeLifecycleCapability?: () => Exclude<OrchestrationResult['error'], null> | null;
+  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
   token?: () => string;
   monotonicNow?: () => number;
   sleep?: (milliseconds: number) => Promise<void>;
@@ -275,7 +278,7 @@ function isRecovery(value: unknown): value is OrchestrationRecovery {
     && value.resultingStatus === 'running';
 }
 
-function isCompletionEvidence(value: unknown): value is CleanCompletionEvidence {
+export function isCompletionEvidence(value: unknown): value is CleanCompletionEvidence {
   return hasExactKeys(value, [
     'kind', 'observedAt', 'head', 'headTree', 'worktreeTree', 'lastReviewedCommit', 'prNumber', 'prHead'
   ])
@@ -604,25 +607,13 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
   return { status: 'running', changed: true, taskId: resolved.taskId, run, next: null, error: null };
 }
 
-function highestRound(taskDir: string, family: string): number {
-  const pattern = new RegExp(`^${family}(?:-r(\\d+))?\\.md$`);
-  return fs.readdirSync(taskDir).reduce((max, name) => {
-    const match = pattern.exec(name);
-    return match ? Math.max(max, match[1] ? Number(match[1]) : 1) : max;
-  }, 0);
-}
-
-function artifactName(family: string, round: number): string {
-  return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
-}
-
 function validateSavedCurrentDiffBase(
   repoRoot: string,
   metadata: ReturnType<typeof parseTypedTaskFrontmatter>,
   taskDir: string,
   reviewedHead: string
 ): Readonly<{ code: string; message: string }> | null {
-  const reviewRound = highestRound(taskDir, 'review-code');
+  const reviewRound = maxArtifactRound(fs.readdirSync(taskDir), 'review-code');
   const reviewContent = fs.readFileSync(path.join(taskDir, artifactName('review-code', reviewRound)), 'utf8');
   const savedTargetHead = extractReviewTargetHead(reviewContent);
   const savedDiffBase = extractReviewDiffBase(reviewContent);
@@ -660,10 +651,9 @@ function routeFromFacts(facts: LifecycleFacts): Omit<OrchestrationNext, 'request
   const action = recommendation.action;
   if (action === 'manual-validation' || action === 'validation-run') return null;
   const family = action === 'analysis' ? 'analysis' : action;
-  const round = Math.max(0, ...[...(facts.artifacts[family] ?? []), ...(facts.staleArtifacts?.[family] ?? [])].map((name) => {
-    const match = /-r(\d+)\.md$/.exec(name);
-    return match ? Number(match[1]) : 1;
-  })) + 1;
+  const round = maxArtifactRound([
+    ...(facts.artifacts[family] ?? []), ...(facts.staleArtifacts?.[family] ?? [])
+  ], family) + 1;
   const command = action === 'analysis' ? 'analyze-task' : action === 'plan' ? 'plan-task' : action === 'code' ? 'code-task' : action;
   const role = action.startsWith('review-') ? 'reviewer' : 'executor';
   return { action: command, role, stage: action, round, artifact: artifactName(family, round) };
@@ -719,7 +709,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   const routed = routeFromFacts(facts.facts);
   if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
   if ('completion' in routed) {
-    const reviewRound = highestRound(resolved.taskDir, 'review-code');
+    const reviewRound = maxArtifactRound(fs.readdirSync(resolved.taskDir), 'review-code');
     const review = parseReviewSummary(fs.readFileSync(
       path.join(resolved.taskDir, artifactName('review-code', reviewRound)),
       'utf8'
@@ -830,6 +820,7 @@ function prepareOrchestrationDelegationUnlocked(
     requestedModel?: string;
     requestedReasoningEffort?: string;
     lifecycleProvenance?: DelegationLifecycleProvenance;
+    lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
   }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
@@ -866,6 +857,13 @@ function prepareOrchestrationDelegationUnlocked(
   if (input.client === 'codex' && !input.lifecycleProvenance) {
     return failed('ORCHESTRATION_CODEX_PROVENANCE_REQUIRED', 'Codex prepare requires lifecycle provenance', resolved.taskId);
   }
+  if (input.lifecycleRecoveryAttestation
+    && (input.lifecycleRecoveryAttestation.phase !== 'orchestration.prepare'
+      || input.lifecycleRecoveryAttestation.taskId !== resolved.taskId
+      || input.lifecycleRecoveryAttestation.artifact !== next.artifact
+      || input.lifecycleRecoveryAttestation.round !== next.round)) {
+    return failed('LIFECYCLE_AUTHORITY_TUPLE_MISMATCH', 'orchestration authority does not match the routed stage', resolved.taskId);
+  }
   const expectedPolicy = run.modelPolicy[next.role];
   if (input.requestedModel !== expectedPolicy.model) {
     return failed('ORCHESTRATION_REQUESTED_MODEL_MISMATCH', `requested model does not match the persisted ${next.role} model`, resolved.taskId);
@@ -930,6 +928,7 @@ function prepareOrchestrationDelegation(
     requestedModel?: string;
     requestedReasoningEffort?: string;
     lifecycleProvenance?: DelegationLifecycleProvenance;
+    lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
   }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
@@ -1606,6 +1605,7 @@ export {
   statusOrchestration,
 };
 export type {
+  CleanCompletionEvidence,
   OrchestrationCompletionPlanResult,
   OrchestrationModelPolicy,
   OrchestrationNext,

package/lib/task/qualification-audit.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto';
 
+import { parseArtifactName } from './artifact-name.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { parseTable } from './sections.ts';
+import { findSectionRange, parseTable } from './sections.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 const TASK_CONSTRAINT_HEADINGS = ['约束', 'Constraints'] as const;
 const TASK_CANDIDATE_HEADINGS = ['候选与否决方案', 'Candidate and Rejected Options', 'Candidates and Rejected Options', 'Candidates and Rejected Alternatives'] as const;
@@ -170,21 +172,9 @@ function taskInputDigest(qualification: Pick<TaskQualification, 'constraints' |
   return digest(canonicalTaskInput(qualification));
 }
 
-function sectionBody(content: string, aliases: readonly string[], level = 2): string | null {
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  const marker = '#'.repeat(level);
-  const match = new RegExp(`^${marker}\\s+(${heading})\\s*$`, 'm').exec(content);
-  if (!match) return null;
-  const rest = content.slice((match.index ?? 0) + match[0].length);
-  const end = rest.search(new RegExp(`^#{2,${level}}\\s+`, 'm'));
-  return rest.slice(0, end < 0 ? rest.length : end);
-}
-
-function stripSection(content: string, aliases: readonly string[]): string {
-  const body = sectionBody(content, aliases);
-  if (body === null) return normalizeText(content);
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  return normalizeText(content.replace(new RegExp(`^##\\s+(?:${heading})\\s*$[\\s\\S]*?(?=^##\\s+|(?![\\s\\S]))`, 'm'), ''));
+function sectionBody(content: string, aliases: readonly string[], level: 2 | 3 = 2): string | null {
+  const section = findSectionRange(content, aliases, level);
+  return section ? content.slice(section.bodyStart, section.end) : null;
 }
 
 function stripFrontmatter(content: string): string {
@@ -218,7 +208,7 @@ function nonConstraintInputDigest(content: string): string {
     ['返工意图', 'Rework Intents'],
     CONFIRMATION_HEADINGS,
     ['完成检查清单', 'Completion Checklist']
-  ].reduce((value, aliases) => stripSection(value, aliases), projection);
+  ].reduce((value, aliases) => stripSectionAtLevel(value, aliases, 2), projection);
   return digest(projection);
 }
 
@@ -231,12 +221,9 @@ function stripTaskInputSection(content: string, aliases: readonly string[]): str
   return stripSectionAtLevel(result, aliases, 2);
 }
 
-function stripSectionAtLevel(content: string, aliases: readonly string[], level: number): string {
-  const body = sectionBody(content, aliases, level);
-  if (body === null) return normalizeText(content);
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  const marker = '#'.repeat(level);
-  return normalizeText(content.replace(new RegExp(`^${marker}\\s+(?:${heading})\\s*$[\\s\\S]*?(?=^#{2,${level}}\\s+|(?![\\s\\S]))`, 'm'), ''));
+function stripSectionAtLevel(content: string, aliases: readonly string[], level: 2 | 3): string {
+  const section = findSectionRange(content, aliases, level);
+  return normalizeText(section ? content.slice(0, section.start) + content.slice(section.end) : content);
 }
 
 function parseTaskQualification(content: string): { ok: true; qualification: TaskQualification } | { ok: false; code: string; message: string } {
@@ -246,12 +233,14 @@ function parseTaskQualification(content: string): { ok: true; qualification: Tas
   const hasCandidateHeading = candidateBody !== null;
   if ((!hasConstraintHeading && !hasCandidateHeading)
     || (hasConstraintHeading && hasCandidateHeading
-      && !/^\s*\|/m.test(constraintBody!) && !/^\s*\|/m.test(candidateBody!))) {
+      && !scanVisibleMarkdown(constraintBody!).lines.some((line) => line.text.trim().startsWith('|'))
+      && !scanVisibleMarkdown(candidateBody!).lines.some((line) => line.text.trim().startsWith('|')))) {
     return { ok: true, qualification: { present: false, constraints: [], candidates: [], constraintDigest: digest([]), taskInputDigest: digest({ constraints: [], candidates: [] }), nonConstraintInputDigest: nonConstraintInputDigest(content) } };
   }
   if (!hasConstraintHeading || !hasCandidateHeading) {
-    const hasCanonicalTable = new RegExp(`\\|\\s*${CONSTRAINT_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(content)
-      || new RegExp(`\\|\\s*${CANDIDATE_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(content);
+    const visible = scanVisibleMarkdown(content).lines.map((line) => line.text).join('\n');
+    const hasCanonicalTable = new RegExp(`\\|\\s*${CONSTRAINT_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(visible)
+      || new RegExp(`\\|\\s*${CANDIDATE_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(visible);
     if (hasCanonicalTable) return { ok: false, code: 'QUALIFICATION_TASK_CONTRACT_INVALID', message: 'task qualification requires both constraints and candidates sections' };
     return { ok: true, qualification: { present: false, constraints: [], candidates: [], constraintDigest: digest([]), taskInputDigest: digest({ constraints: [], candidates: [] }), nonConstraintInputDigest: nonConstraintInputDigest(content) } };
   }
@@ -315,10 +304,10 @@ function parseAuditTable(content: string, heading: (typeof AUDIT_SUBSECTIONS)[nu
   return table?.rows.map((row) => ({ ...row.values })) ?? null;
 }
 
-function parseArtifactName(value: string): { family: ArtifactFamily; round: number } | null {
-  const match = /^(analysis|review-analysis|plan|review-plan|code|review-code)(?:-r([2-9]|[1-9]\d+))?\.md$/.exec(value);
-  if (!match) return null;
-  return { family: match[1] as ArtifactFamily, round: match[2] ? Number(match[2]) : 1 };
+function parseAuditArtifactName(value: string): { family: ArtifactFamily; round: number } | null {
+  const identity = parseArtifactName(value);
+  return identity && ARTIFACT_FAMILIES.includes(identity.family as ArtifactFamily)
+    ? { family: identity.family as ArtifactFamily, round: identity.round } : null;
 }
 
 function upstreamArtifactDigest(rows: readonly UpstreamRelation[]): string {
@@ -327,7 +316,7 @@ function upstreamArtifactDigest(rows: readonly UpstreamRelation[]): string {
 }
 
 function validateUpstreamRelation(row: UpstreamRelation): void {
-  const identity = parseArtifactName(row.upstreamArtifact);
+  const identity = parseAuditArtifactName(row.upstreamArtifact);
   if (!ARTIFACT_FAMILIES.includes(row.upstreamFamily) || !identity || identity.family !== row.upstreamFamily
     || identity.round !== row.upstreamRound || !Number.isSafeInteger(row.upstreamRound)
     || !/^[a-f0-9]{64}$/i.test(row.upstreamSha256) || !RELATIONS.includes(row.relation)) {
@@ -368,7 +357,7 @@ function expectedQualificationRelations(
   const inputName = family === 'code' ? frontmatter.code_input_artifact : family.startsWith('review-') ? frontmatter.review_input_artifact : '';
   const inputSha256 = family === 'code' ? frontmatter.code_input_sha256 : family.startsWith('review-') ? frontmatter.review_input_sha256 : '';
   if (typeof inputName !== 'string' || !inputName || typeof inputSha256 !== 'string' || !inputSha256) return { ok: true, relations: undefined };
-  const identity = parseArtifactName(inputName);
+  const identity = parseAuditArtifactName(inputName);
   if (!identity) return { ok: false, code: 'QUALIFICATION_STARTED_INPUT_INVALID', message: `started input '${inputName}' is not canonical` };
   const relation: UpstreamRelation = {
     upstreamFamily: identity.family, upstreamArtifact: inputName, upstreamRound: identity.round,
@@ -507,7 +496,7 @@ function validateQualificationAudit(
     || upstreamArtifactDigest(options.expectedUpstreamRelations) !== upstreamArtifactDigest(audit.audit.upstreamRelations)
   )) return { ok: false, code: 'QUALIFICATION_UPSTREAM_RELATION_MISMATCH', message: 'qualification audit upstream relations do not match the started artifact inputs' };
   if (options.family && options.artifact) {
-    const identity = parseArtifactName(options.artifact);
+    const identity = parseAuditArtifactName(options.artifact);
     if (!identity || identity.family !== options.family) return { ok: false, code: 'QUALIFICATION_ARTIFACT_IDENTITY_INVALID', message: `artifact '${options.artifact}' is not canonical for '${options.family}'` };
   }
   return { ok: true, qualification: task.qualification, audit: audit.audit };

package/lib/task/review-artifacts.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { scanVisibleMarkdown } from './decision-details.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 type ReviewFindingCounts = {
   blocker: number;
@@ -53,23 +53,6 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function maxRound(entries: string[], stem: string): number {
-  let max = 0;
-  for (const entry of entries) {
-    if (entry === `${stem}.md`) {
-      max = Math.max(max, 1);
-      continue;
-    }
-    const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
-    if (match) max = Math.max(max, Number(match[1]));
-  }
-  return max;
-}
-
-function artifactName(stem: string, round: number): string {
-  return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
-}
-
 function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
   const value = String(raw).trim().toLowerCase();
   if (value === '通过' || value === 'approved') return 'Approved';
@@ -260,12 +243,10 @@ function parseVerdict(reviewPath: string): PathVerdictResult {
 }
 
 export {
-  artifactName,
   equalCounts,
   escapeRegExp,
   extractSection,
   finalizeReviewSummaryContent,
-  maxRound,
   normalizeVerdict,
   parseReviewSummary,
   parseVerdict,