@fitlab-ai/agent-infra 0.11.2 → 0.11.4

package/lib/task/ledger-intents.ts

@@ -15,8 +15,11 @@ import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
 import { allowsManualOverride } from './guard-override.ts';
-import { parseReworkIntentDocument, reworkIntentMutation, upsertReworkIntent } from './rework-intent.ts';
-import type { ReworkIntent, ReworkTarget } from './rework-intent.ts';
+import { parseLegacyReworkIntentDocument, parseReworkIntentDocument, reworkIntentMutation, upsertReworkIntent } from './rework-intent.ts';
+import type { ReworkClassification, ReworkIntent, ReworkTarget } from './rework-intent.ts';
+import { extractSection, extractSubSection } from './sections.ts';
+import { parseLifecyclePathDecision } from './lifecycle-path.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 type ReviewSeverity = 'blocker' | 'major' | 'minor';
 type ExecutorResponse = 'accepted' | 'adjusted' | 'refuted' | 'cannot-judge';
@@ -27,7 +30,8 @@ type LedgerIntent =
   | { kind: 'finding-review'; taskRef: string; id: string; status: ReviewDisposition; evidence: string; needsImplementation?: boolean; dryRun?: boolean }
   | { kind: 'decision-next-id'; taskRef: string }
   | { kind: 'decision-upsert'; taskRef: string; id: string; stage: ReviewStage; artifact: string; needsImplementation?: boolean; dryRun?: boolean }
-  | { kind: 'rework-intent-upsert'; taskRef: string; intentId: string; findingId: string; sourceArtifact: string; sourceSha256: string; target: ReworkTarget; dryRun?: boolean };
+  | { kind: 'rework-intent-upsert'; taskRef: string; intentId: string; findingId: string; sourceArtifact: string; sourceSha256: string; classification: ReworkClassification; dryRun?: boolean }
+  | { kind: 'rework-intent-rebuild'; taskRef: string; findingId?: string; sourceArtifact?: string; sourceSha256?: string; classification?: ReworkClassification; dryRun?: boolean };
 
 type LedgerIntentError = { code: string; message: string };
 type LedgerIntentResult = {
@@ -39,6 +43,7 @@ type LedgerIntentResult = {
   before: LedgerRow | null;
   after: LedgerRow | null;
   operations: readonly TaskOperationSummary[];
+  rebuild?: Readonly<{ mode: 'format-only' | 'pending-reclassification'; beforeSha256: string; afterSha256: string; converted: number; newIntentId: string | null }>;
   error: LedgerIntentError | null;
 };
 
@@ -60,12 +65,53 @@ function ledgerReadErrorCode(error: unknown): string {
   return code === 'TABLE_DUPLICATE_KEY' ? 'LEDGER_DUPLICATE_ID' : 'LEDGER_DOCUMENT_INVALID';
 }
 
-function maxHandshakeRounds(repoRoot: string): number {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')) as { review?: { maxHandshakeRounds?: unknown } };
-    const value = parsed.review?.maxHandshakeRounds;
-    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : 3;
-  } catch { return 3; }
+const CLASSIFICATION_TARGET: Record<ReworkClassification, ReworkTarget> = {
+  'scope-or-requirement': 'analysis', design: 'plan', implementation: 'code',
+  'human-decision': 'pause', 'insufficient-evidence': 'pause'
+};
+
+function semanticDigest(value: string): string {
+  return createHash('sha256').update(value.normalize('NFKC').replace(/\s+/g, ' ').trim()).digest('hex');
+}
+
+function normalizedTaskFact(value: string): string {
+  return value.normalize('NFKC').replace(/\s+/g, ' ').trim();
+}
+
+function semanticFindingEvidence(reviewContent: string, heading: ReturnType<typeof scanVisibleMarkdown>['headings'][number], end: number): string {
+  const title = heading.text.replace(/^\d+[.、：:]\s*/, '').trim();
+  return `${title}\n${reviewContent.slice(heading.end, end)}`;
+}
+
+function findingEvidence(reviewContent: string, evidence: string): string | null {
+  const anchor = evidence.split('#')[1];
+  if (!anchor) return null;
+  const markdown = scanVisibleMarkdown(reviewContent);
+  const explicit = markdown.anchors.find((candidate) => candidate.id === anchor);
+  if (explicit) {
+    const heading = markdown.headings.find((candidate) => candidate.start > explicit.start);
+    const next = heading && markdown.headings.find((candidate) => candidate.start > heading.start && candidate.level <= heading.level);
+    const end = next?.start ?? reviewContent.length;
+    return heading ? semanticFindingEvidence(reviewContent, heading, end) : reviewContent.slice(explicit.end, end);
+  }
+  const heading = markdown.headings.find((candidate) => {
+    const escapedAnchor = anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return candidate.text === anchor || new RegExp(`^${escapedAnchor}(?:\\s|[.、：:])`).test(candidate.text);
+  });
+  if (!heading) return null;
+  const next = markdown.headings.find((candidate) => candidate.start > heading.start && candidate.level <= heading.level);
+  return semanticFindingEvidence(reviewContent, heading, next?.start ?? reviewContent.length);
+}
+
+function taskFactDigest(taskDir: string, content: string): string {
+  const analysisNames = fs.readdirSync(taskDir).filter((name) => /^analysis(?:-r\d+)?\.md$/.test(name));
+  const latest = analysisNames.map((name) => ({ name, round: parseArtifactName(name)?.round ?? 0 })).sort((a, b) => b.round - a.round)[0];
+  const flow = latest ? parseLifecyclePathDecision(fs.readFileSync(path.join(taskDir, latest.name), 'utf8')) : null;
+  return semanticDigest(JSON.stringify({
+    taskInput: normalizedTaskFact(extractSection(content, ['任务输入', 'Task Input'])),
+    requirements: normalizedTaskFact(extractSection(content, ['需求', 'Requirements'])),
+    flow: flow?.status === 'valid' ? flow.decision.semanticDigest : flow?.status ?? 'missing'
+  }));
 }
 
 function nextFindingId(rows: readonly LedgerRow[], stage: ReviewStage): string {
@@ -123,11 +169,14 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   }
 
   if (intent.kind === 'rework-intent-upsert') {
-    if (!/^RI-[1-9]\d*$/.test(intent.intentId) || !/^(AN|PL|CD)-[1-9]\d*$/.test(intent.findingId) || !['analysis', 'plan', 'code'].includes(intent.target) || !/^[a-f0-9]{64}$/.test(intent.sourceSha256)) {
-      return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'rework intent identity, target, or source hash is invalid', resolved.taskId, intent.intentId);
+    if (!/^RI-[1-9]\d*$/.test(intent.intentId) || !/^(AN|PL|CD)-[1-9]\d*$/.test(intent.findingId) || !(intent.classification in CLASSIFICATION_TARGET) || !/^[a-f0-9]{64}$/.test(intent.sourceSha256)) {
+      return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'rework intent identity, classification, or source hash is invalid', resolved.taskId, intent.intentId);
     }
     const finding = rows.find((row) => row.id === intent.findingId);
     if (!finding || finding.severity === 'decision') return failed(intent, 'LEDGER_NOT_FOUND', `finding '${intent.findingId}' was not found`, resolved.taskId, intent.findingId);
+    if (intent.classification === 'human-decision' && finding.status !== 'needs-human-decision') {
+      return failed(intent, 'LEDGER_TRANSITION_INVALID', 'human-decision classification requires a needs-human-decision finding', resolved.taskId, intent.findingId);
+    }
     const sourceFromEvidence = finding.evidence.split('#')[0];
     if (sourceFromEvidence !== intent.sourceArtifact || parseArtifactName(intent.sourceArtifact)?.family !== `review-${finding.stage}`) {
       return failed(intent, 'LEDGER_IDENTITY_CONFLICT', 'rework intent source artifact does not match finding evidence', resolved.taskId, intent.intentId);
@@ -137,12 +186,34 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
       if (actualHash !== intent.sourceSha256) return failed(intent, 'LEDGER_IDENTITY_CONFLICT', 'rework intent source artifact hash does not match', resolved.taskId, intent.intentId);
       const parsed = parseReworkIntentDocument(content);
       if (!parsed.ok) return failed(intent, parsed.code, parsed.message, resolved.taskId, intent.intentId);
-      const nextIntent: ReworkIntent = {
+      const reviewContent = fs.readFileSync(path.join(resolved.taskDir, intent.sourceArtifact), 'utf8');
+      const evidenceBlock = findingEvidence(reviewContent, finding.evidence);
+      if (!evidenceBlock) return failed(intent, 'LEDGER_EVIDENCE_INVALID', `finding evidence anchor '${finding.evidence}' was not found`, resolved.taskId, intent.intentId);
+      const evidenceDigest = semanticDigest(evidenceBlock);
+      const factsDigest = taskFactDigest(resolved.taskDir, content);
+      const requestedIntent: ReworkIntent = {
         intentId: intent.intentId, findingId: intent.findingId, sourceArtifact: intent.sourceArtifact,
-        sourceSha256: intent.sourceSha256, target: intent.target, status: 'pending',
+        sourceSha256: intent.sourceSha256, target: CLASSIFICATION_TARGET[intent.classification], classification: intent.classification,
+        evidenceDigest, taskFactDigest: factsDigest, status: 'pending',
         declaredAt: new Date().toISOString(), consumedAt: ''
       };
-      const next = upsertReworkIntent(parsed.intents, nextIntent);
+      if (parsed.intents.some((candidate) => candidate.intentId === intent.intentId)) {
+        const replay = upsertReworkIntent(parsed.intents, requestedIntent);
+        if (!replay.changed) {
+          return { status: 'no-op', changed: false, intent: intent.kind, taskId: resolved.taskId, entityId: intent.intentId, before: null, after: null, operations: [], error: null };
+        }
+      }
+      const same = parsed.intents.find((candidate) => candidate.findingId === intent.findingId
+        && candidate.evidenceDigest === evidenceDigest && candidate.taskFactDigest === factsDigest
+        && candidate.classification === intent.classification && candidate.target === CLASSIFICATION_TARGET[intent.classification]);
+      const classification: ReworkClassification = same ? 'insufficient-evidence' : intent.classification;
+      const nextIntent: ReworkIntent = {
+        ...requestedIntent, target: CLASSIFICATION_TARGET[classification], classification
+      };
+      const now = nextIntent.declaredAt;
+      const superseded = parsed.intents.map((candidate) => candidate.status === 'pending'
+        ? { ...candidate, status: 'superseded' as const, consumedAt: now } : candidate);
+      const next = upsertReworkIntent(superseded, nextIntent);
       if (!next.changed) return { status: 'no-op', changed: false, intent: intent.kind, taskId: resolved.taskId, entityId: intent.intentId, before: null, after: null, operations: [], error: null };
       const result = writeTask({ taskRef: intent.taskRef, expectedState: 'active', dryRun: intent.dryRun, mutations: [reworkIntentMutation(content, next.intents)] }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
       if (result.status === 'failed') return failed(intent, result.error.code, result.error.message, result.taskId, intent.intentId);
@@ -152,6 +223,75 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
     }
   }
 
+  if (intent.kind === 'rework-intent-rebuild') {
+    const beforeSha256 = createHash('sha256').update(content).digest('hex');
+    const supplied = [intent.findingId, intent.sourceArtifact, intent.sourceSha256, intent.classification].filter((value) => value !== undefined).length;
+    if (supplied !== 0 && supplied !== 4) return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'rebuild binding options must be provided together', resolved.taskId);
+    const current = parseReworkIntentDocument(content);
+    if (current.ok && current.present) {
+      if (supplied !== 0) return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'current rework intent format does not accept rebuild binding options', resolved.taskId);
+      return {
+        status: 'no-op', changed: false, intent: intent.kind, taskId: resolved.taskId, entityId: null,
+        before: null, after: null, operations: [], error: null,
+        rebuild: { mode: 'format-only', beforeSha256, afterSha256: beforeSha256, converted: current.intents.length, newIntentId: null }
+      };
+    }
+    const legacy = parseLegacyReworkIntentDocument(content);
+    if (!legacy.ok) return failed(intent, legacy.code, legacy.message, resolved.taskId);
+    const pending = legacy.intents.filter((row) => row.status === 'pending');
+    if (pending.length === 0 && supplied !== 0) return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'format-only rebuild does not accept finding or classification options', resolved.taskId);
+    if (pending.length > 0 && supplied !== 4) return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'legacy pending intents require finding, review, hash, and classification', resolved.taskId);
+    const now = new Date().toISOString();
+    let next = legacy.intents.map((row) => row.status === 'pending' ? { ...row, status: 'superseded' as const, consumedAt: now } : row);
+    let entityId: string | null = null;
+    if (pending.length > 0) {
+      const finding = rows.find((row) => row.id === intent.findingId);
+      if (!finding || finding.severity === 'decision' || finding.evidence.split('#')[0] !== intent.sourceArtifact) return failed(intent, 'LEDGER_IDENTITY_CONFLICT', 'rebuild binding does not match a review finding', resolved.taskId);
+      if (intent.classification === 'human-decision' && finding.status !== 'needs-human-decision') {
+        return failed(intent, 'LEDGER_TRANSITION_INVALID', 'human-decision classification requires a needs-human-decision finding', resolved.taskId);
+      }
+      const sourceIdentity = parseArtifactName(intent.sourceArtifact!);
+      const expectedFamily = `review-${finding.stage}`;
+      const latestSource = fs.readdirSync(resolved.taskDir)
+        .map((name) => parseArtifactName(name))
+        .filter((identity) => identity?.family === expectedFamily)
+        .sort((left, right) => right!.round - left!.round || left!.name.localeCompare(right!.name))[0];
+      if (!sourceIdentity || sourceIdentity.family !== expectedFamily || latestSource?.name !== sourceIdentity.name) {
+        return failed(intent, 'LEDGER_IDENTITY_CONFLICT', 'rebuild source artifact is not the latest review for the finding stage', resolved.taskId);
+      }
+      const sourcePath = path.join(resolved.taskDir, intent.sourceArtifact!);
+      const actualHash = createHash('sha256').update(fs.readFileSync(sourcePath)).digest('hex');
+      if (actualHash !== intent.sourceSha256) return failed(intent, 'LEDGER_IDENTITY_CONFLICT', 'rebuild source artifact hash does not match', resolved.taskId);
+      const max = next.reduce((value, row) => Math.max(value, Number(row.intentId.slice(3))), 0);
+      entityId = `RI-${max + 1}`;
+      const reviewContent = fs.readFileSync(sourcePath, 'utf8');
+      const classification = intent.classification!;
+      if (!(classification in CLASSIFICATION_TARGET)) return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'rebuild classification is invalid', resolved.taskId);
+      const evidenceBlock = findingEvidence(reviewContent, finding.evidence);
+      if (!evidenceBlock) return failed(intent, 'LEDGER_EVIDENCE_INVALID', `finding evidence anchor '${finding.evidence}' was not found`, resolved.taskId);
+      next = [...next, {
+        intentId: entityId, findingId: intent.findingId!, sourceArtifact: intent.sourceArtifact!, sourceSha256: intent.sourceSha256!,
+        target: CLASSIFICATION_TARGET[classification], classification,
+        evidenceDigest: semanticDigest(evidenceBlock),
+        taskFactDigest: taskFactDigest(resolved.taskDir, content), status: 'pending', declaredAt: now, consumedAt: ''
+      }];
+    }
+    const result = writeTask({ taskRef: intent.taskRef, expectedState: 'active', dryRun: intent.dryRun, mutations: [reworkIntentMutation(content, next)] }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
+    if (result.status === 'failed') return failed(intent, result.error.code, result.error.message, result.taskId, entityId);
+    const afterContent = result.status === 'applied' || result.status === 'no-op' ? fs.readFileSync(resolved.taskMdPath, 'utf8') : content;
+    return {
+      status: result.status, changed: result.changed, intent: intent.kind, taskId: result.taskId, entityId,
+      before: null, after: null, operations: result.operations, error: null,
+      rebuild: {
+        mode: pending.length > 0 ? 'pending-reclassification' : 'format-only',
+        beforeSha256,
+        afterSha256: createHash('sha256').update(afterContent).digest('hex'),
+        converted: legacy.intents.length,
+        newIntentId: entityId
+      }
+    };
+  }
+
   let before: LedgerRow | null = null;
   let after: LedgerRow;
   if (intent.kind === 'finding-upsert') {
@@ -213,7 +353,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
             ? new Set(['confirmed', 'open', 'needs-human-decision'])
             : before.status === 'cannot-judge' ? new Set(['open', 'needs-human-decision']) : new Set<string>();
         const sameRoundMinorClose = before.status === 'open' && before.severity === 'minor' && intent.status === 'closed';
-        if (((!sameRoundMinorClose && !allowed.has(intent.status)) || (intent.status === 'open' && Number(before.round) >= maxHandshakeRounds(resolved.repoRoot)))
+        if ((!sameRoundMinorClose && !allowed.has(intent.status))
           && !allowsManualOverride(options.manualOverride, 'ledger-intent', 'LEDGER_TRANSITION_INVALID')) {
           return failed(intent, 'LEDGER_TRANSITION_INVALID', `finding '${intent.id}' cannot transition from ${before.status} to ${intent.status}`, resolved.taskId, intent.id);
         }

package/lib/task/lifecycle-path.ts

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto';
+
+import { extractSection } from './sections.ts';
+
+const PATH_STAGES = {
+  streamlined: ['analysis', 'code', 'review-code'],
+  standard: ['analysis', 'plan', 'code', 'review-code'],
+  full: ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code']
+} as const;
+
+type LifecyclePath = keyof typeof PATH_STAGES;
+type LifecycleStage = (typeof PATH_STAGES)[LifecyclePath][number];
+type LifecyclePathDecision = Readonly<{
+  path: LifecyclePath;
+  stages: readonly LifecycleStage[];
+  basis: string;
+  unmetHigherConditions: string;
+  upgradeTriggers: string;
+  semanticDigest: string;
+  sourceArtifact: string;
+  sourceSha256: string;
+}>;
+type LifecyclePathState =
+  | Readonly<{ status: 'missing'; decision: null; message: string }>
+  | Readonly<{ status: 'invalid'; decision: null; message: string }>
+  | Readonly<{ status: 'valid'; decision: LifecyclePathDecision; message: null }>;
+
+const FIELD_ALIASES = {
+  path: ['本任务路径', 'Path'],
+  basis: ['判定依据', 'Basis'],
+  unmetHigherConditions: ['未满足的更高路径条件', '未满足的较低路径条件', 'Unmet Higher-path Conditions'],
+  upgradeTriggers: ['升级触发条件', 'Upgrade Triggers']
+} as const;
+
+function normalizeText(value: string): string {
+  return value.normalize('NFKC').replace(/\s+/g, ' ').trim().replace(/[。.]$/, '');
+}
+
+function digest(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+function pathToken(value: string): LifecyclePath | null {
+  const normalized = normalizeText(value).toLowerCase().replace(/[`*_]/g, '');
+  if (/^(?:streamlined|精简路径|精简)$/.test(normalized)) return 'streamlined';
+  if (/^(?:standard|标准路径|标准)$/.test(normalized)) return 'standard';
+  if (/^(?:full|完整路径|完整)$/.test(normalized)) return 'full';
+  return null;
+}
+
+function fieldValues(body: string, aliases: readonly string[]): string[] {
+  const wanted = new Set(aliases);
+  const values: string[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    const match = /^\s*[-*]\s+\*\*([^*]+)\*\*[:：]\s*(.*?)\s*$/.exec(line);
+    if (match && wanted.has(match[1]!.trim())) values.push(match[2]!.trim());
+  }
+  return values;
+}
+
+function parseLifecyclePathDecision(
+  analysisContent: string,
+  sourceArtifact = '',
+  sourceSha256 = ''
+): LifecyclePathState {
+  const body = extractSection(analysisContent, ['流程裁定', 'Flow Decision']);
+  if (!body) return { status: 'missing', decision: null, message: 'analysis flow decision section is missing' };
+  const fields = Object.fromEntries(Object.entries(FIELD_ALIASES).map(([key, aliases]) => [key, fieldValues(body, aliases)])) as Record<keyof typeof FIELD_ALIASES, string[]>;
+  const invalid = Object.entries(fields).find(([, values]) => values.length !== 1);
+  if (invalid) return { status: 'invalid', decision: null, message: `flow decision field '${invalid[0]}' must appear exactly once` };
+  const path = pathToken(fields.path[0]!);
+  if (!path) return { status: 'invalid', decision: null, message: `unknown lifecycle path '${fields.path[0]}'` };
+  const basis = normalizeText(fields.basis[0]!);
+  const unmetHigherConditions = normalizeText(fields.unmetHigherConditions[0]!);
+  const upgradeTriggers = normalizeText(fields.upgradeTriggers[0]!);
+  if (!basis || !unmetHigherConditions || !upgradeTriggers) return { status: 'invalid', decision: null, message: 'flow decision fields must be non-empty' };
+  return {
+    status: 'valid',
+    message: null,
+    decision: {
+      path,
+      stages: PATH_STAGES[path],
+      basis,
+      unmetHigherConditions,
+      upgradeTriggers,
+      semanticDigest: digest({ path, basis, unmetHigherConditions, upgradeTriggers }),
+      sourceArtifact,
+      sourceSha256
+    }
+  };
+}
+
+function pathIncludes(state: LifecyclePathState | undefined, stage: LifecycleStage): boolean {
+  return state?.status === 'valid' && state.decision.stages.includes(stage);
+}
+
+export { PATH_STAGES, parseLifecyclePathDecision, pathIncludes };
+export type { LifecyclePath, LifecyclePathDecision, LifecyclePathState, LifecycleStage };

package/lib/task/lifecycle.ts

@@ -58,7 +58,7 @@ type TaskLifecycleRequest =
   | { taskRef: string; intent: 'close-codescan'; agent: string; alertNumber: number; reason: string; dryRun?: boolean }
   | { taskRef: string; intent: 'close-dependabot'; agent: string; alertNumber: number; reason: string; dryRun?: boolean }
   | { taskRef: string; intent: 'restore'; agent: string; stagingDir: string; issueNumber: number; dryRun?: boolean }
-  | { taskRef: string; intent: 'recover-started'; agent: string; stage: 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code'; round: number; artifact: string; reason: string; dryRun?: boolean };
+  | { taskRef: string; intent: 'recover-started'; agent: string; auto: true; dryRun?: boolean };
 
 type HotState = 'active' | 'blocked' | 'completed';
 type SourceState = HotState | 'staging';
@@ -108,6 +108,9 @@ type TaskLifecycleOptions = {
   taskFileSystem?: Partial<TaskFileSystem>;
   directoryRenameSync?: (source: string, target: string) => void;
   manualOverride?: Readonly<{ failureId: string; operator: string; reason: string }>;
+  /** Write the terminal task document and durable journal, but leave the move
+   * and short-id mutation for a separately authorized commit. */
+  prepareOnly?: boolean;
 };
 
 function allowsManualOverride(options: TaskLifecycleOptions, code: string): boolean {
@@ -209,7 +212,7 @@ function actionAndNote(request: TaskLifecycleRequest, restoredFiles = 0): { acti
   if (request.intent === 'complete') return { action: 'Complete Task', note: 'Task moved to completed/' };
   if (request.intent === 'close-codescan') return { action: 'Close Codescan', note: `Code Scanning alert #${request.alertNumber} dismissed: ${request.reason}` };
   if (request.intent === 'close-dependabot') return { action: 'Close Dependabot', note: `Dependabot alert #${request.alertNumber} dismissed: ${request.reason}` };
-  if (request.intent === 'recover-started') return { action: 'Recover Started', note: request.reason };
+  if (request.intent === 'recover-started') return { action: 'Recover Started', note: 'automatic recovery' };
   return { action: 'Restore Task', note: `Restored ${restoredFiles} files from Issue #${request.issueNumber}` };
 }
 
@@ -574,6 +577,16 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     try { writeJournal(journalPath, journal, io); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion }); }
   }
+  if (options.prepareOnly && !completed.has('directory-moved')) {
+    return {
+      ...failed(request, { code: '', message: '' }), status: 'applied', changed: true, error: null,
+      taskId, sourceState, targetState: spec.target, sourcePath, targetPath,
+      task: { operations: taskOperations }, directory: { effect: 'unchanged', changed: false },
+      shortId: { effect: 'unchanged', shortId: null, changed: false },
+      timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion,
+      journalPath, completedSteps: [...completed], pendingSteps: STEPS.filter((step) => !completed.has(step))
+    };
+  }
   if (fs.existsSync(targetPath) && !fs.existsSync(sourcePath)) completed.add('directory-moved');
   if (!completed.has('directory-moved')) {
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });

package/lib/task/local-artifact-finalization.ts

@@ -4,11 +4,7 @@ import path from 'node:path';
 import { inspectDecisionDetailDuplicates } from './decision-details.ts';
 import { scanVisibleMarkdown } from './markdown.ts';
 import { parseArtifactName } from './artifact-name.ts';
-import {
-  hasOpenArtifactRound,
-} from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
-import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 
@@ -28,8 +24,7 @@ type LocalArtifactDiagnosticCode =
   | 'LOCAL_DECISION_DETAIL_DUPLICATE'
   | 'LOCAL_REQUIRED_PATTERN_MISSING'
   | 'LOCAL_STRUCTURAL_INVALID'
-  | 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION'
-  | 'LOCAL_QUALIFICATION_AUDIT_INVALID';
+  | 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION';
 
 type LocalArtifactDiagnostic = {
   code: LocalArtifactDiagnosticCode;
@@ -40,8 +35,6 @@ type LocalArtifactDiagnostic = {
 type LocalArtifactValidationOptions = {
   family: LocalArtifactFamily;
   requiredSections?: readonly string[];
-  taskContent?: string;
-  artifact?: string;
 };
 
 type LocalArtifactValidationResult = {
@@ -128,20 +121,6 @@ function validateLocalArtifact(
   const decisionDetails = inspectDecisionDetailDuplicates(content);
   if (!decisionDetails.ok) diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
 
-  if (options.taskContent !== undefined) {
-    const identity = options.artifact ? parseArtifactName(options.artifact) : null;
-    const expected = identity?.family === options.family && hasOpenArtifactRound(options.taskContent, options.family, identity.round)
-      ? expectedQualificationRelations(options.taskContent, options.family)
-      : undefined;
-    if (expected && !expected.ok) diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, line: null });
-    const qualification = validateQualificationAudit(options.taskContent, content, {
-      family: options.family,
-      artifact: options.artifact,
-      expectedUpstreamRelations: expected?.ok ? expected.relations : undefined
-    });
-    if (!qualification.ok) diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, line: null });
-  }
-
   return {
     ok: diagnostics.length === 0,
     family: options.family,
@@ -182,10 +161,8 @@ function prepareLocalArtifact(
   if (!resolved.ok) return failed(resolved.code, resolved.message);
   const parsed = parseArtifactName(request.artifact);
   if (!parsed || parsed.family !== request.family) return failed('ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${request.family}`);
-  let taskContent: string;
   let content: string;
   try {
-    taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     const artifactPath = path.join(resolved.taskDir, request.artifact);
     if (!fs.statSync(artifactPath).isFile()) return failed('ARTIFACT_NOT_REGULAR', `artifact '${request.artifact}' is not a regular file`);
     content = candidate ?? fs.readFileSync(artifactPath, 'utf8');
@@ -195,7 +172,7 @@ function prepareLocalArtifact(
     return failed('ARTIFACT_IDENTITY_INVALID', 'artifact finalization requires an active task');
   }
   const validation = validateLocalArtifact(content, {
-    family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
+    family: request.family, requiredSections: request.requiredSections
   });
   const artifactSha256 = sha256Content(content);
   const result = failedFinalization(request, {

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

@@ -14,6 +14,7 @@ import {
 
 const MANUAL_VALIDATION_RECEIPT_SCHEMA = 'agent-infra/manual-validation-receipt';
 const MANUAL_VALIDATION_RECEIPT_VERSION = 1;
+const MANUAL_VALIDATION_RECEIPT_PLACEHOLDER = '[[manual-validation-receipt]]';
 
 type ManualValidationReceipt = Readonly<{
   schema: typeof MANUAL_VALIDATION_RECEIPT_SCHEMA;
@@ -73,13 +74,17 @@ function manualValidationFinalSummaryDigest(body: string): string {
   const projection = heading
     ? body.slice(heading.index, heading.index + heading[0].length + (nextSection?.index ?? afterHeading.length)).replace(/\s+$/u, '')
     : body;
-  const preimage = projection.replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
+  const preimage = projection
+    .replace(/\n*<!--\s*canonical-pr-change-report\s*-->\s*/gu, '')
+    .replace(/<!--\s*manual-validation-receipt:\s*[\s\S]*?-->/gu, MANUAL_VALIDATION_RECEIPT_PLACEHOLDER)
+    .replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
   return createHash('sha256').update(preimage, 'utf8').digest('hex');
 }
 
 function manualValidationFinalSummaryProjectionMatches(body: string, receipt: ManualValidationReceipt): boolean {
   const identity = `transaction=${receipt.transactionId}; receipt=${receipt.receiptDigest}; evidence=${receipt.evidenceDigest}; head=${receipt.prHeadSha}`;
-  return body.includes(identity) && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
+  return (body.includes(identity) || body.includes(MANUAL_VALIDATION_RECEIPT_PLACEHOLDER))
+    && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
 }
 
 function validateManualValidationReceipt(value: unknown, expected?: ManualValidationReceiptIdentity): ManualValidationReceiptResult {
@@ -137,6 +142,7 @@ function readManualValidationReceipt(taskDir: string, expected?: ManualValidatio
 export {
   MANUAL_VALIDATION_RECEIPT_SCHEMA,
   MANUAL_VALIDATION_RECEIPT_VERSION,
+  MANUAL_VALIDATION_RECEIPT_PLACEHOLDER,
   createManualValidationReceipt,
   manualValidationFinalSummaryDigest,
   manualValidationFinalSummaryProjectionMatches,

package/lib/task/orchestration.ts

@@ -59,6 +59,7 @@ import { hasOpenLifecycleExecution } from './activity-log.ts';
 import { reconcileTaskInvalidation } from './invalidation-command.ts';
 import type { LifecycleAction, LifecycleFacts } from './capabilities.ts';
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
+import { resolveArtifactContext } from './artifact-lifecycle.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
 type ModelPolicySource = Readonly<{
@@ -642,18 +643,14 @@ function validateSavedCurrentDiffBase(
   return null;
 }
 
-function routeFromFacts(facts: LifecycleFacts): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | { completion: true } | null {
+function routeFromFacts(facts: LifecycleFacts): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort' | 'round' | 'artifact'> | { completion: true } | null {
   const recommendation = recommendNext(facts);
-  if (!recommendation.action) return { completion: true };
+  if (!recommendation.action) return recommendation.reasonCode === 'LIFECYCLE_REVIEWED' ? { completion: true } : null;
   const action = recommendation.action;
   if (action === 'manual-validation' || action === 'validation-run') return null;
-  const family = action === 'analysis' ? 'analysis' : action;
-  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) };
+  return { action: command, role, stage: action };
 }
 
 function routeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
@@ -786,14 +783,35 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     return { status: 'completed', changed: true, taskId: resolved.taskId, run: completed, next: null, error: null };
   }
   const action = routed.stage as LifecycleAction;
+  const family = action === 'analysis' ? 'analysis' : action;
+  const artifactContext = resolveArtifactContext(taskRef, family, {
+    repoRoot: resolved.repoRoot
+  });
+  if (artifactContext.status !== 'ready' || !artifactContext.selection) {
+    return failed(
+      artifactContext.error?.code ?? 'ORCHESTRATION_ARTIFACT_SELECTION_FAILED',
+      artifactContext.error?.message ?? 'cannot determine artifact selection',
+      resolved.taskId
+    );
+  }
+  if (artifactContext.selection.disposition === 'reuse') {
+    return failed(
+      'ORCHESTRATION_REUSE_STALLED',
+      `lifecycle still routes to ${action} after reusing ${artifactContext.selection.artifact.name}`,
+      resolved.taskId
+    );
+  }
+  const selected = artifactContext.selection.artifact;
   const capability = canStart(action, facts.facts, {
-    initiator: 'orchestrator', requestId: `orchestration:${resolved.taskId}:${routed.stage}:${routed.round}`,
+    initiator: 'orchestrator', requestId: `orchestration:${resolved.taskId}:${routed.stage}:${selected.round}`,
     requestedAction: action, reasonCode: 'user-request', explicitRequest: true
   });
   if (!capability.allowed) return failed('ORCHESTRATION_CAPABILITY_DENIED', `${capability.reasonCode}: ${capability.evidence.join(', ')}`, resolved.taskId);
   const policy = run ? rolePolicy(run, routed.role) : null;
   const next: OrchestrationNext = {
     ...routed,
+    round: selected.round,
+    artifact: selected.name,
     requestedModel: policy?.model ?? null,
     requestedReasoningEffort: policy?.reasoningEffort ?? null
   };
@@ -1417,19 +1435,34 @@ function recoverPreparedOrchestrationDelegation(
   }
 }
 
+type ActivatedRecoveryEvent = Readonly<{
+  receiptId: string;
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  startedAgent: string;
+  childId: string;
+  stopRevision: number;
+  consumer: string;
+  consumedAt: string;
+}>;
+
+function recoveryReceiptMatches(
+  receipt: DelegationReceipt,
+  taskId: string,
+  event: ActivatedRecoveryEvent
+): boolean {
+  return receipt.taskId === taskId
+    && receipt.stage === event.stage
+    && receipt.round === event.round
+    && receipt.artifact === event.artifact
+    && receipt.childId === event.childId
+    && normalizeAgentToken(event.startedAgent) === normalizeAgentToken(receipt.client);
+}
+
 function recoverActivatedOrchestrationDelegationUnderLock(
   taskRef: string,
-  event: Readonly<{
-    receiptId: string;
-    stage: DelegationStage;
-    round: number;
-    artifact: string;
-    startedAgent: string;
-    childId: string;
-    stopRevision: number;
-    consumer: string;
-    consumedAt: string;
-  }>,
+  event: ActivatedRecoveryEvent,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
@@ -1442,14 +1475,7 @@ function recoverActivatedOrchestrationDelegationUnderLock(
   ];
   const receipt = matches.find((candidate) => candidate.id === event.receiptId);
   if (!receipt) return failed('ORCHESTRATION_DELEGATION_MISSING', 'recovery receipt does not exist', resolved.taskId);
-  if (
-    receipt.taskId !== resolved.taskId
-    || receipt.stage !== event.stage
-    || receipt.round !== event.round
-    || receipt.artifact !== event.artifact
-    || receipt.childId !== event.childId
-    || normalizeAgentToken(event.startedAgent) !== normalizeAgentToken(receipt.client)
-  ) {
+  if (!recoveryReceiptMatches(receipt, resolved.taskId, event)) {
     return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'recovery selector does not match the delegation receipt', resolved.taskId);
   }
   if (receipt.status === 'aborted' && run.pendingDelegation === null) {
@@ -1461,6 +1487,9 @@ function recoverActivatedOrchestrationDelegationUnderLock(
   if (run.receipts.some((candidate) => candidate.id === receipt.id)) {
     return failed('ORCHESTRATION_RECEIPT_DUPLICATE', 'recovery receipt already exists in the completed receipt history', resolved.taskId);
   }
+  if (run.status !== 'running' || run.pause !== null) {
+    return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'activated recovery cannot replace an unrelated orchestration pause', resolved.taskId);
+  }
   const aborted = abortActivatedDelegation(receipt, {
     childId: event.childId,
     stopRevision: event.stopRevision,