@fitlab-ai/agent-infra 0.10.0 → 0.11.1

package/lib/task/events.ts

@@ -1,12 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
   buildArtifactLinkSection,
   inspectArtifactDirectory,
-  parseReviewedInputReference,
-  parseCodePlanInputReference,
   resolveArtifactContext,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
@@ -24,6 +23,7 @@ import {
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { ReviewStage } from './ledger.ts';
 import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
+import { extractReviewBaseline, extractReviewedHead, extractReviewedSnapshotTree } from './review-fingerprint.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
@@ -46,6 +46,7 @@ import { buildLifecycleFacts, canStart } from './capabilities.ts';
 import type { ExplicitTrigger, LifecycleAction, TriggerInitiator, TriggerReason } from './capabilities.ts';
 import { createInvalidationOperation, invalidationMutation, parseInvalidationDocument, targetIdFor, upsertInvalidation } from './invalidation.ts';
 import type { InvalidationTargetKind } from './invalidation.ts';
+import { reconcileTaskInvalidation } from './invalidation-command.ts';
 import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.ts';
 import { ARTIFACT_FAMILIES, expectedQualificationRelations, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest, validateQualificationAudit } from './qualification-audit.ts';
 import type { QualificationAudit, UpstreamRelation } from './qualification-audit.ts';
@@ -113,6 +114,23 @@ type TaskEventResult = {
   operations: readonly TaskOperationSummary[]; error: TaskEventError | null;
 };
 
+function approvedCleanReviewedCommit(reviewContent: string, verdict: Verdict | undefined, repoRoot: string): string | null {
+  if (verdict !== 'approved') return null;
+  const reviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
+  const reviewedTree = extractReviewedSnapshotTree(reviewContent);
+  if (!/^[a-f0-9]{40}$/.test(reviewedHead) || !/^[a-f0-9]{40}$/.test(reviewedTree)) return null;
+  try {
+    const currentHead = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+    if (currentHead !== reviewedHead) return null;
+    const currentTree = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD^{tree}'], { encoding: 'utf8' }).trim();
+    if (currentTree !== reviewedTree) return null;
+    execFileSync('git', ['-C', repoRoot, 'diff-index', '--quiet', 'HEAD', '--']);
+    return reviewedHead;
+  } catch {
+    return null;
+  }
+}
+
 const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
@@ -402,7 +420,7 @@ function reconcileReviewCompletionReplay(
       }
       intent = reconciled.intent;
     }
-    if (!['passed', 'consumed'].includes(intent.state)) {
+    if (!['passed', 'consumption-started', 'consumed'].includes(intent.state)) {
       return {
         code: 'EVENT_ARTIFACT_CONFLICT',
         message: `review finalizer provenance is incomplete for ${artifact}`
@@ -413,9 +431,7 @@ function reconcileReviewCompletionReplay(
       return { code: 'EVENT_ARTIFACT_CONFLICT', message: validated.error.message };
     }
     const content = fs.readFileSync(validated.artifact.path, 'utf8');
-    const expectedRequestId = `review-finalize:${taskId}:${stage}:${round}`;
     if (intent.round !== round
-      || intent.requestId !== expectedRequestId
       || intent.finalArtifactSha256 !== sha256Content(content)
       || intent.finalSemanticDigest !== canonicalSemanticDigest(content)) {
       return {
@@ -423,7 +439,7 @@ function reconcileReviewCompletionReplay(
         message: `review finalizer provenance does not match ${artifact}`
       };
     }
-    if (intent.state === 'passed') {
+    if (intent.state === 'passed' || intent.state === 'consumption-started') {
       const consumed = { ...intent, state: 'consumed' as const, updatedAt: Date.now() };
       writeArtifactRecoveryIntent(repoRoot, consumed, { expected: intent });
     }
@@ -652,26 +668,20 @@ function buildCompletionReceipt(
   frontmatter: Record<string, unknown>
 ): { ok: true; receipt: ArtifactReceipt } | { ok: false; message: string } | null {
   if (family === 'code') {
-    let content: string;
-    try { content = fs.readFileSync(artifact.path, 'utf8'); }
-    catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
-    const input = parseCodePlanInputReference(content);
-    if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical plan artifact` };
     const startedInput = typeof frontmatter.code_input_artifact === 'string' ? frontmatter.code_input_artifact : '';
     const startedSha256 = typeof frontmatter.code_input_sha256 === 'string' ? frontmatter.code_input_sha256 : '';
     if (!startedInput || !startedSha256) return { ok: false, message: 'code.started plan input context is missing' };
-    if (input.name !== startedInput) return { ok: false, message: `${artifact.name} plan input '${input.name}' does not match code.started input '${startedInput}'` };
     const plan = inspectArtifactDirectory(taskDir, 'plan');
-    if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== input.name) {
-      return { ok: false, message: `code input '${input.name}' is not the latest plan artifact` };
+    if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== startedInput) {
+      return { ok: false, message: `code input '${startedInput}' is not the latest plan artifact` };
     }
     try {
       const inputSha256 = sha256File(plan.latest.path);
-      if (inputSha256 !== startedSha256) return { ok: false, message: `code input ${input.name} changed after code.started` };
+      if (inputSha256 !== startedSha256) return { ok: false, message: `code input ${startedInput} changed after code.started` };
       return {
         ok: true,
         receipt: {
-          event: 'code.completed', output: artifact.name, input: input.name,
+          event: 'code.completed', output: artifact.name, input: startedInput,
           inputSha256, completedAt
         }
       };
@@ -681,18 +691,12 @@ function buildCompletionReceipt(
   }
   if (!family.startsWith('review-')) return null;
   const expectedFamily = reviewInputFamily(family);
-  let content: string;
-  try { content = fs.readFileSync(artifact.path, 'utf8'); }
-  catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
-  const input = parseReviewedInputReference(content, expectedFamily);
-  if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical ${expectedFamily} artifact` };
   const startedInput = typeof frontmatter.review_input_artifact === 'string' ? frontmatter.review_input_artifact : '';
   const startedSha256 = typeof frontmatter.review_input_sha256 === 'string' ? frontmatter.review_input_sha256 : '';
   if (!startedInput || !startedSha256) return { ok: false, message: 'review started input context is missing' };
-  if (input.name !== startedInput) return { ok: false, message: `${artifact.name} input '${input.name}' does not match review.started input '${startedInput}'` };
   const current = inspectArtifactDirectory(taskDir, expectedFamily);
-  if (current.status !== 'ready' || !current.latest || current.latest.name !== input.name) {
-    return { ok: false, message: `review input '${input.name}' is not the latest ${expectedFamily} artifact` };
+  if (current.status !== 'ready' || !current.latest || current.latest.name !== startedInput) {
+    return { ok: false, message: `review input '${startedInput}' is not the latest ${expectedFamily} artifact` };
   }
   const event = family === 'review-analysis'
     ? 'review-analysis.completed' as const
@@ -701,16 +705,16 @@ function buildCompletionReceipt(
     const stat = fs.lstatSync(current.latest.path);
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('review input is not a regular file');
     const inputSha256 = sha256File(current.latest.path);
-    if (inputSha256 !== startedSha256) return { ok: false, message: `review input ${input.name} changed after review.started` };
+    if (inputSha256 !== startedSha256) return { ok: false, message: `review input ${startedInput} changed after review.started` };
     return {
       ok: true,
       receipt: {
-        event, output: artifact.name, input: input.name,
+        event, output: artifact.name, input: startedInput,
         inputSha256, completedAt
       }
     };
   } catch (error) {
-    return { ok: false, message: `cannot hash review input ${input.name}: ${error instanceof Error ? error.message : String(error)}` };
+    return { ok: false, message: `cannot hash review input ${startedInput}: ${error instanceof Error ? error.message : String(error)}` };
   }
 }
 
@@ -724,6 +728,20 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   let content: string;
   try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
   catch (error) { return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
+  const initialParts = eventParts(request.event);
+  if (initialParts.phase === 'started' && !request.dryRun) {
+    const reconciled = reconcileTaskInvalidation(request.taskRef, { repoRoot: resolved.repoRoot });
+    if (reconciled.status === 'failed') {
+      return failed(request, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: `INVALIDATION_RECONCILE_FAILED: ${reconciled.error?.code ?? 'UNKNOWN'}: ${reconciled.error?.message ?? ''}`
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+    if (reconciled.changed) {
+      try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+      catch (error) { return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
+    }
+  }
   let frontmatter;
   try { frontmatter = parseTypedTaskFrontmatter(content); }
   catch (error) { return failed(request, { code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
@@ -732,7 +750,6 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   const rows = startedBackedRows(pairEntries(section.entries));
   let normalized = request;
   let artifactContext: ArtifactContextResult | null = null;
-  const initialParts = eventParts(request.event);
   if (initialParts.phase === 'started') {
     const openIdentity = openStartedIdentity(rows, initialParts.family);
     if (openIdentity && 'conflict' in openIdentity) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'artifact family has more than one open started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
@@ -963,20 +980,15 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
         );
         if (reconciled.status === 'passed' || reconciled.status === 'consumed') reviewFinalizationIntent = reconciled.intent;
       }
-      if (!reviewFinalizationIntent || !['passed', 'consumed'].includes(reviewFinalizationIntent.state)) {
+      if (!reviewFinalizationIntent || !['passed', 'consumption-started', 'consumed'].includes(reviewFinalizationIntent.state)) {
         return failed(normalized, {
           code: 'EVENT_ARTIFACT_CONFLICT',
           message: `review finalizer provenance is missing or incomplete for ${completedArtifact.name}`
         }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
       }
-      const reviewStage = eventIdentity.family === 'review-analysis'
-        ? 'analysis'
-        : eventIdentity.family === 'review-plan' ? 'plan' : 'code';
       const actualSha256 = sha256File(completedArtifact.path);
       const actualSemanticDigest = canonicalSemanticDigest(reviewContent);
-      const expectedRequestId = `review-finalize:${resolved.taskId}:${reviewStage}:${normalized.round}`;
       if (reviewFinalizationIntent.round !== normalized.round
-        || reviewFinalizationIntent.requestId !== expectedRequestId
         || reviewFinalizationIntent.finalArtifactSha256 !== actualSha256
         || reviewFinalizationIntent.finalSemanticDigest !== actualSemanticDigest) {
         return failed(normalized, {
@@ -1072,6 +1084,11 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   } else if (eventIdentity.phase === 'completed' && eventIdentity.family.startsWith('review-')) {
     frontmatterRemove = ['review_input_artifact', 'review_input_sha256'];
   }
+  if (eventIdentity.phase === 'completed' && eventIdentity.family === 'review-code' && reviewContent !== null) {
+    const reviewedCommit = approvedCleanReviewedCommit(reviewContent, normalized.verdict, resolved.repoRoot);
+    if (reviewedCommit) frontmatterSet.last_reviewed_commit = reviewedCommit;
+    else if (normalized.verdict === 'approved') frontmatterSet.last_reviewed_commit = '';
+  }
   if (eventIdentity.phase === 'completed') frontmatterRemove = [...(frontmatterRemove ?? []), 'qualification_input_relations'];
   if (eventIdentity.phase === 'started' && normalized.implementationInput) frontmatterSet.last_reviewed_commit = '';
   const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
@@ -1116,7 +1133,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
         const expectedIntent = localFinalizationIntent;
         localFinalizationIntent = {
           ...localFinalizationIntent,
-          state: 'commit-started',
+          state: 'consumption-started',
           phase: 'task-event.completed',
           authorityDigest: lifecycleRecoveryAttestationDigest(lifecycleAuthority),
           requestId: lifecycleAuthority.lifecycleRequestId,
@@ -1146,7 +1163,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
       const expectedIntent = reviewFinalizationIntent;
       reviewFinalizationIntent = {
         ...reviewFinalizationIntent,
-        state: 'commit-started',
+        state: 'consumption-started',
         phase: 'task-event.completed',
         updatedAt: Date.now()
       };
@@ -1183,7 +1200,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   }
   if (!normalized.dryRun && reviewFinalizationIntent && completedArtifact) {
     try {
-      if (reviewFinalizationIntent.state === 'commit-started') {
+      if (reviewFinalizationIntent.state === 'consumption-started') {
         const consumed = { ...reviewFinalizationIntent, state: 'consumed' as const, updatedAt: Date.now() };
         writeArtifactRecoveryIntent(resolved.repoRoot, consumed, { expected: reviewFinalizationIntent });
       }
@@ -1231,7 +1248,7 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskEventOptions = {
   if (invalid) return failed(request, invalid);
   const parts = eventParts(request.event);
   if (options.lockAlreadyHeld) return applyTaskEventUnlocked(request, options);
-  if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
+  if (request.dryRun || !['started', 'completed'].includes(parts.phase)) {
     return applyTaskEventUnlocked(request, options);
   }
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });

package/lib/task/gate-policy.ts

@@ -0,0 +1,133 @@
+import type { VerificationStatus } from './verification-types.ts';
+
+export type GateClassification = 'hard' | 'soft' | 'info';
+export type PlatformAuditId =
+  | 'closed-status-labels' | 'status-label' | 'comment-marker' | 'pr-comment-marker'
+  | 'pr-comment-last-commit' | 'pr-comment-content' | 'comment-content' | 'task-comment-content'
+  | 'in-labels-computed' | 'pr-type-label' | 'in-labels-match-pr' | 'pr-assignee'
+  | 'requirements' | 'issue-type' | 'issue-fields' | 'milestone';
+
+export type PlatformAuditPolicy = {
+  classification: GateClassification;
+  enabled: boolean;
+  expectedStatusLabel?: string;
+  expectedCommentMarkerKey?: 'artifact' | 'summary';
+  expectedPrCommentMarkerKey?: 'prSummary';
+  requireSpecificMilestone?: boolean;
+};
+
+export type VerificationRecord = {
+  type: string;
+  status: VerificationStatus;
+  message: string;
+  fail_type?: string;
+  checkId?: string;
+  classification?: GateClassification;
+  effectiveStatus?: VerificationStatus;
+  reason?: string;
+  action?: string;
+  dependsOn?: string;
+  warnings?: string[];
+  subchecks?: VerificationRecord[];
+};
+
+const OPTIONAL_PLATFORM_AUDITS = new Set<PlatformAuditId>([
+  'closed-status-labels', 'status-label', 'comment-marker', 'pr-comment-marker',
+  'pr-comment-last-commit', 'pr-comment-content', 'comment-content', 'task-comment-content',
+  'in-labels-computed', 'pr-type-label', 'in-labels-match-pr', 'pr-assignee',
+  'requirements', 'issue-type', 'issue-fields', 'milestone'
+]);
+
+const STATUS_LABELS: Record<string, string> = {
+  'create-task': 'status: waiting-for-triage',
+  'analyze-task': 'status: pending-design-work',
+  'review-analysis': 'status: pending-design-work',
+  'plan-task': 'status: pending-design-work',
+  'review-plan': 'status: pending-design-work',
+  'code-task': 'status: in-progress',
+  'review-code': 'status: in-progress'
+};
+
+const ARTIFACT_COMMENT_SKILLS = new Set([
+  'analyze-task', 'plan-task', 'review-analysis', 'review-plan', 'code-task',
+  'review-code', 'review-pr', 'run-manual-validation'
+]);
+const PR_AUDIT_SKILLS = new Set(['create-pr']);
+const IN_LABEL_AUDIT_SKILLS = new Set(['code-task', 'commit', 'create-pr']);
+
+export function platformAuditPolicy(checkId: PlatformAuditId, context: { skillName?: string; artifactFile?: string | null }): PlatformAuditPolicy {
+  const skillName = context.skillName || '';
+  const artifactComment = Boolean(context.artifactFile) && ARTIFACT_COMMENT_SKILLS.has(skillName);
+  const prAudit = PR_AUDIT_SKILLS.has(skillName);
+  const inLabelAudit = IN_LABEL_AUDIT_SKILLS.has(skillName);
+
+  switch (checkId) {
+    case 'status-label':
+      return { classification: 'soft', enabled: Boolean(STATUS_LABELS[skillName]), expectedStatusLabel: STATUS_LABELS[skillName] };
+    case 'comment-marker':
+      return {
+        classification: 'soft',
+        enabled: artifactComment || skillName === 'complete-task',
+        ...(artifactComment ? { expectedCommentMarkerKey: 'artifact' } : skillName === 'complete-task' ? { expectedCommentMarkerKey: 'summary' } : {})
+      };
+    case 'pr-comment-marker':
+      return {
+        classification: 'soft',
+        enabled: skillName === 'commit' || prAudit,
+        ...(skillName === 'commit' || prAudit ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+      };
+    case 'pr-comment-last-commit':
+      return {
+        classification: 'soft',
+        enabled: skillName === 'commit',
+        ...(skillName === 'commit' ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+      };
+    case 'pr-comment-content':
+      return {
+        classification: 'soft',
+        enabled: skillName === 'complete-manual-validation',
+        ...(skillName === 'complete-manual-validation' ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+      };
+    case 'comment-content':
+      return { classification: 'soft', enabled: artifactComment, expectedCommentMarkerKey: 'artifact' };
+    case 'task-comment-content':
+      return { classification: 'soft', enabled: true };
+    case 'in-labels-computed':
+      return { classification: 'soft', enabled: inLabelAudit };
+    case 'pr-type-label':
+    case 'in-labels-match-pr':
+    case 'pr-assignee':
+      return { classification: 'soft', enabled: prAudit };
+    case 'requirements':
+      return { classification: 'soft', enabled: skillName === 'complete-task' };
+    case 'milestone':
+      return { classification: 'soft', enabled: true, requireSpecificMilestone: skillName === 'code-task' };
+    case 'closed-status-labels':
+    case 'issue-type':
+    case 'issue-fields':
+      return { classification: 'soft', enabled: true };
+  }
+}
+
+export function classificationForCheck(checkId: string): GateClassification {
+  return checkId.startsWith('platform.') && OPTIONAL_PLATFORM_AUDITS.has(checkId.slice('platform.'.length) as PlatformAuditId)
+    ? 'soft'
+    : 'hard';
+}
+
+export function effectiveStatus(status: VerificationStatus, classification: GateClassification): VerificationStatus {
+  return classification === 'hard' ? status : 'pass';
+}
+
+export function normalizeVerificationRecord(record: VerificationRecord): VerificationRecord {
+  const checkId = record.checkId ?? record.type;
+  const classification = record.classification ?? classificationForCheck(checkId);
+  return {
+    ...record,
+    checkId,
+    classification,
+    effectiveStatus: record.effectiveStatus ?? effectiveStatus(record.status, classification),
+    reason: record.reason ?? record.fail_type ?? (classification === 'info' ? 'NOT_APPLICABLE' : record.status === 'pass' ? 'OK' : 'CHECK_FAILED'),
+    action: record.action ?? (classification === 'info' || record.status === 'pass' ? 'No action required' : 'Review the check evidence and retry after correction')
+  };
+}

package/lib/task/intermediate-cleanup.ts

@@ -327,10 +327,26 @@ function cleanupConsumedRecoveryFiles(repoRoot: string, task: TaskRecord | undef
   let entries: fs.Dirent[];
   try { entries = fs.readdirSync(recovery, { withFileTypes: true }); } catch { return false; }
   for (const entry of entries) {
-    if (entry.isSymbolicLink() || !entry.isFile() || !['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name)) return false;
+    if (entry.isSymbolicLink()) return false;
+    if (entry.isFile()) {
+      if (!['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name)) return false;
+      continue;
+    }
+    if (!entry.isDirectory() || entry.name !== 'generations') return false;
+    let generations: fs.Dirent[];
+    try { generations = fs.readdirSync(path.join(recovery, entry.name), { withFileTypes: true }); } catch { return false; }
+    if (generations.some((generation) => generation.isSymbolicLink()
+      || !generation.isFile() || !/^[a-f0-9]{64}\.md$/u.test(generation.name))) return false;
   }
   try {
-    for (const entry of entries) fs.unlinkSync(path.join(recovery, entry.name));
+    for (const entry of entries) {
+      const target = path.join(recovery, entry.name);
+      if (entry.isFile()) fs.unlinkSync(target);
+      else {
+        for (const generation of fs.readdirSync(target, { withFileTypes: true })) fs.unlinkSync(path.join(target, generation.name));
+        fs.rmdirSync(target);
+      }
+    }
     fs.rmdirSync(recovery);
     const recoveryRoot = path.dirname(recovery);
     if (fs.readdirSync(recoveryRoot).length === 0) fs.rmdirSync(recoveryRoot);

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

@@ -5,7 +5,6 @@ import { scanVisibleMarkdown } from './markdown.ts';
 import { parseArtifactName } from './artifact-name.ts';
 import {
   hasOpenArtifactRound,
-  parseCodePlanInputReference,
   validateArtifactPublication,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
@@ -19,8 +18,10 @@ import {
   beginArtifactRecovery,
   commitArtifactRecovery,
   consumeArtifactRecovery,
+  prepareArtifactRecoveryFinal,
   prepareArtifactRecoveryCommit,
   recordArtifactRecoveryPassed,
+  reconcileArtifactRecovery,
   recoveryContextFromIntent,
   stageArtifactCandidate
 } from './artifact-recovery.ts';
@@ -204,12 +205,15 @@ function validateLocalArtifact(
   if (!decisionDetails.ok) diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
 
   if (options.taskContent !== undefined) {
-    const expected = expectedQualificationRelations(options.taskContent, options.family);
-    if (!expected.ok) diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, line: null });
+    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
+      expectedUpstreamRelations: expected?.ok ? expected.relations : undefined
     });
     if (!qualification.ok) diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, line: null });
   }
@@ -265,7 +269,8 @@ function tupleFor(
 function prepareLocalArtifact(
   request: LocalArtifactFinalizationRequest,
   candidate?: string,
-  authority?: LifecycleRecoveryAttestationV1
+  authority?: LifecycleRecoveryAttestationV1,
+  preflightOnly = false
 ): LocalArtifactPreparation {
   const failed = (code: string, message: string, extra: Partial<LocalArtifactFinalizationResult> = {}): LocalArtifactPreparation => ({
     result: failedFinalization(request, { code, message }, extra), content: candidate ?? ''
@@ -281,12 +286,14 @@ function prepareLocalArtifact(
   let taskContent: string;
   let content: string;
   let recovery: ArtifactRecoveryContext | undefined;
+  let recoveryState: ArtifactRecoveryIntent['state'] | undefined;
   try {
     taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     if (request.recoveryId) {
       const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
       if (!intent || intent.recoveryOperationId !== request.recoveryId) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'recovery id does not match the artifact journal');
-      if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state)) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+      if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state)) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+      recoveryState = intent.state;
       recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
       content = fs.existsSync(recovery.stagingPath)
         ? fs.readFileSync(recovery.stagingPath, 'utf8')
@@ -315,26 +322,66 @@ function prepareLocalArtifact(
 
   if (request.recoveryId) {
     if (!validation.ok) return { result, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    if (preflightOnly && recovery && recoveryState === 'awaiting-preflight-recovery') {
+      const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+      prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+    }
     return {
-      result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(recovery!) },
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(recovery!) },
       content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
     };
   }
 
   const existing = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
   if (existing?.state === 'passed' || existing?.state === 'consumed') {
-    if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+    if (existing.state === 'consumed' && (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest)) {
       return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match its completed recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
+    if (existing.finalArtifactSha256 === artifactSha256 && existing.finalSemanticDigest === validation.semanticDigest) {
+      const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+      return {
+        result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+        content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+      };
+    }
+  }
+
+  if (existing && ['preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready'].includes(existing.state)) {
     const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
     return {
-      result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
+      content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+    };
+  }
+  if (existing?.state === 'commit-started') {
+    if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+      return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match the interrupted recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    }
+    const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+    const reconciled = reconcileArtifactRecovery(context, {
+      lockAlreadyHeld: request.lockAlreadyHeld,
+      validateFinal: () => validation.semanticDigest === existing.finalSemanticDigest
+    });
+    if (reconciled.status !== 'passed') {
+      return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `interrupted recovery could not be reconciled: ${reconciled.status}`), content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    }
+    return {
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
       content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
     };
   }
 
   try {
     if (validation.ok) {
+      if (preflightOnly) {
+        const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+          repoRoot: resolved.repoRoot, taskDir: resolved.taskDir,
+          ...(authority ? { recoveryId: authority.operationId } : {}), lockAlreadyHeld: request.lockAlreadyHeld
+        });
+        const staged = stageArtifactCandidate(context, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+        prepareArtifactRecoveryCommit(context, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+        return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+      }
       const context = recordArtifactRecoveryPassed(tupleFor(request, resolved.taskId, authority), {
         repoRoot: resolved.repoRoot,
         taskDir: resolved.taskDir,
@@ -344,7 +391,7 @@ function prepareLocalArtifact(
         lockAlreadyHeld: request.lockAlreadyHeld
       });
       recovery = context;
-      return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+      return { result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
     const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
       repoRoot: resolved.repoRoot,
@@ -362,7 +409,10 @@ function prepareLocalArtifact(
   }
 }
 
-function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): LocalArtifactFinalizationResult {
+function commitLocalArtifactProvenance(
+  prepared: LocalArtifactPreparation,
+  options: Readonly<{ afterPublish?: () => void }> = {}
+): LocalArtifactFinalizationResult {
   if (!prepared.recovery || !prepared.repoRoot || prepared.result.status === 'failed' && !prepared.result.recovery) return prepared.result;
   if (prepared.result.status === 'failed') return prepared.result;
   try {
@@ -372,26 +422,42 @@ function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): Loca
     if (intent.state === 'passed' || intent.state === 'consumed') {
       return {
         ...prepared.result,
+        changed: false,
         artifactSha256: intent.finalArtifactSha256,
         semanticDigest: intent.finalSemanticDigest,
         error: null
       };
-    } else if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-    } else {
+    } else if (intent.state === 'commit-started') {
+      const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+        lockAlreadyHeld: prepared.lockAlreadyHeld,
+        afterPublish: options.afterPublish
+      });
+      committed = reconciled.intent;
+    } else if (intent.state === 'awaiting-preflight-recovery') {
       const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
       prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
       committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
     }
-    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    }
+    if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+      prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+    } else if (intent.state === 'full-finalizer-ready') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+    }
+    if (!committed || committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
     return {
       ...prepared.result,
       status: 'passed',
+      changed: false,
       artifactSha256: committed.finalArtifactSha256,
       semanticDigest: committed.finalSemanticDigest,
       error: null
     };
   } catch (error) {
+    if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:')) throw error;
     return { ...prepared.result, status: 'failed', error: {
       code: 'LOCAL_RECOVERY_COMMIT_FAILED', message: String(error)
     } };
@@ -417,10 +483,20 @@ function finalizeLocalArtifact(
   return result;
 }
 
+/** Validate and seal an immutable preflight generation without publishing the formal artifact. */
+function preflightLocalArtifact(
+  request: LocalArtifactFinalizationRequest,
+  authority?: LifecycleRecoveryAttestationV1
+): LocalArtifactFinalizationResult {
+  const prepared = prepareLocalArtifact(request, undefined, authority, true);
+  return prepared.result;
+}
+
 export {
   LOCAL_ARTIFACT_REQUIRED_SECTIONS,
   consumeLocalArtifactFinalizationIntent,
   finalizeLocalArtifact,
+  preflightLocalArtifact,
   prepareLocalArtifact,
   commitLocalArtifactProvenance,
   readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent,