@fitlab-ai/agent-infra 0.11.3 → 0.11.4

package/dist/lib/task/verification-engine.js

@@ -26,7 +26,6 @@ import { OrchestrationStateError, readRun } from "./orchestration.js";
 import { resolveDeliveryTarget } from "./delivery-target.js";
 import { readPrDeliveryFact } from "./pr-delivery-fact.js";
 import { validateLocalArtifact } from "./local-artifact-finalization.js";
-import { validateQualificationAudit } from "./qualification-audit.js";
 import { getArtifactSchema } from "./artifact-schema.js";
 import { inspectArtifactContract } from "./artifact-operations.js";
 import { normalizeVerificationRecord } from './gate-policy.js';
@@ -59,7 +58,6 @@ const ACTIVITY_LOG_STARTED_RE = /\s*\[started\]\s*$/;
 const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 // Review disagreement ledger (see .agents/rules/review-handshake.md).
 const LEDGER_SECTION_NAMES = ["审查分歧账本", "Review Disagreement Ledger"];
-const DEFAULT_MAX_HANDSHAKE_ROUNDS = 3;
 const POST_REVIEW_COMMIT_STAGE = "post-review-commit";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
 const scriptPath = fileURLToPath(import.meta.url);
@@ -441,21 +439,6 @@ function checkArtifact({ taskDir, config, artifactFile, skillName }) {
         return failResult("artifact", `Artifact is empty: ${path.basename(artifactPath)}`);
     }
     const content = fs.readFileSync(artifactPath, "utf8");
-    let taskContent = "";
-    const taskPath = path.join(taskDir, "task.md");
-    if (fs.existsSync(taskPath)) {
-        try {
-            taskContent = fs.readFileSync(taskPath, "utf8");
-        }
-        catch (error) {
-            return failResult("artifact", `Cannot read task qualification contract: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    if (taskContent && /^review-(?:analysis|plan|code)$/.test(skillName)) {
-        const qualification = validateQualificationAudit(taskContent, content, { artifact: path.basename(artifactPath) });
-        if (!qualification.ok)
-            return failResult("artifact", `${path.basename(artifactPath)} has qualification audit errors: ${qualification.code}: ${qualification.message}`);
-    }
     const schemaFamily = skillName === "analyze-task"
         ? "analysis"
         : skillName === "review-analysis"
@@ -479,9 +462,7 @@ function checkArtifact({ taskDir, config, artifactFile, skillName }) {
     }
     if (localFamily) {
         const local = validateLocalArtifact(content, {
-            family: localFamily,
-            ...(taskContent ? { taskContent } : {}),
-            artifact: path.basename(artifactPath)
+            family: localFamily
         });
         if (!local.ok) {
             return failResult("artifact", `${path.basename(artifactPath)} has local structural errors: ${local.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')}`);
@@ -715,11 +696,10 @@ function checkReviewLedger({ taskDir, config, repositoryRoot }) {
         return passResult("review-ledger", "Disagreement ledger has no entries");
     }
     const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-    const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS, repositoryRoot));
     const problems = [];
     let inScopeCount = 0;
     for (const row of rows) {
-        const { id, stage, round: roundRaw, status, evidence } = row;
+        const { id, stage, status, evidence } = row;
         const stageScoped = stageScope ? stageScope.includes(stage) : true;
         // post-review-commit exemption rows are consumed by the post-review-commit
         // check, not enforced here.
@@ -738,13 +718,6 @@ function checkReviewLedger({ taskDir, config, repositoryRoot }) {
         if (status !== "open" && evidence === "") {
             problems.push(`${id}: status '${status}' requires evidence`);
         }
-        const round = Number.parseInt(roundRaw, 10);
-        if (Number.isFinite(round) &&
-            round >= maxRounds &&
-            !LEDGER_TERMINAL.has(status) &&
-            status !== "needs-human-decision") {
-            problems.push(`${id}: round ${round} reached limit ${maxRounds} without convergence; escalate to needs-human-decision`);
-        }
         if (!LEDGER_TERMINAL.has(status)) {
             problems.push(`${id}: unresolved (status '${status}')`);
         }
@@ -1051,7 +1024,8 @@ function checkReviewFact({ taskDir, artifactFile, repositoryRoot }) {
     let targetHead;
     let diffBase;
     try {
-        gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+        const taskRepositoryRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+        gitRoot = reviewWorktreeForTask(taskRepositoryRoot, String(task.metadata.branch || "").trim()) ?? taskRepositoryRoot;
         head = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
         const target = resolveDeliveryTarget(gitRoot, { remote: deliveryRemote, baseRef: deliveryBaseRef });
         if (!target.ok)
@@ -1101,6 +1075,22 @@ function checkReviewFact({ taskDir, artifactFile, repositoryRoot }) {
     }
     return passResult("review-fact", `Review fact valid for ${path.basename(resolvedArtifact.path)} at ${baseline.slice(0, 8)}`);
 }
+function reviewWorktreeForTask(repositoryRoot, branch) {
+    if (!branch)
+        return null;
+    const expectedRef = `refs/heads/${branch}`;
+    const records = execFileSync("git", ["-C", repositoryRoot, "worktree", "list", "--porcelain"], {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"]
+    }).trim().split(/\r?\n\r?\n/);
+    for (const record of records) {
+        const worktree = /^worktree (.+)$/m.exec(record)?.[1];
+        const branchRef = /^branch (.+)$/m.exec(record)?.[1];
+        if (worktree && branchRef === expectedRef)
+            return worktree;
+    }
+    throw new Error(`Task branch '${branch}' is not checked out in a registered worktree`);
+}
 function resolvePostReviewBaseline({ gitRoot, lastReviewedCommit, reviewArtifact }) {
     if (SHA_PATTERN.test(lastReviewedCommit) && gitCommitExists(gitRoot, lastReviewedCommit)) {
         return { ok: true, sha: lastReviewedCommit };

package/dist/lib/task/verification.js

@@ -23,6 +23,7 @@ const VERIFICATION_CATALOG = {
     'commit.completed': gate('commit', 'active'),
     'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
     'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
+    'complete-task.prepared': gate('complete-task', 'active'),
     'complete-task.completed': gate('complete-task', 'completed'),
     'create-pr.completed': gate('create-pr', 'active'),
     'create-task.completed': gate('create-task', 'active'),

package/dist/lib/task/workflow-warning-intents.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { resolveTaskRef } from './resolve-ref.js';
+import { parseTaskFrontmatter } from './frontmatter.js';
 import { WORKFLOW_WARNING_COLUMNS, WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_SEVERITIES, WORKFLOW_WARNING_STATUSES, parseWorkflowWarnings } from './workflow-warnings.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { allowsManualOverride } from './guard-override.js';
@@ -118,8 +119,18 @@ function projectFinalizationWarning(taskRef, warning, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return { status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } };
-    if (resolved.state !== 'completed')
-        return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected completed` } };
+    let prepared = resolved.state === 'completed';
+    if (!prepared && resolved.state === 'active') {
+        try {
+            prepared = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed';
+        }
+        catch {
+            prepared = false;
+        }
+    }
+    if (!prepared) {
+        return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected a prepared or completed task` } };
+    }
     let content;
     let rows;
     try {
@@ -139,23 +150,27 @@ function projectFinalizationWarning(taskRef, warning, options = {}) {
             message: warning.message,
             action: retryHintForWarning(warning),
             resolvedAt: warning.resolvedAt || (warning.status === 'resolved' ? metadata.timestamp : ''),
-            resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+            resolution: warning.status === 'resolved'
+                ? options.resolution === 'superseded' ? 'Superseded by a later verification observation' : 'Resolved by a successful finalization retry'
+                : ''
         }
         : {
             id: nextWarningId(rows), time: metadata.timestamp, step: warning.step,
             severity: warning.severity, code: warning.code, status: warning.status,
             target: warning.target, message: warning.message, action: retryHintForWarning(warning),
-            resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+            resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved'
+                ? options.resolution === 'superseded' ? 'Superseded by a later verification observation' : 'Resolved by a successful finalization retry'
+                : ''
         };
     if (existing && JSON.stringify(existing) === JSON.stringify(after))
         return { status: 'no-op', changed: false, error: null };
     const written = writeTask({
         taskRef: resolved.taskId,
-        expectedState: 'completed',
+        expectedState: resolved.state,
         mutations: [...sectionMutation(content), rowMutation(after)]
     }, {
         ...options,
-        taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: 'completed' },
+        taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },
         metadataProvider: () => metadata
     });
     if (written.status === 'failed')

package/dist/lib/task/workspace-snapshot.js

@@ -15,7 +15,12 @@ function captureWorktreeTree(repoRoot, forcedPath) {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
     const indexFile = path.join(tempDir, 'index');
     try {
-        git(repoRoot, indexFile, ['read-tree', 'HEAD']);
+        try {
+            git(repoRoot, indexFile, ['read-tree', 'HEAD']);
+        }
+        catch {
+            git(repoRoot, indexFile, ['read-tree', '--empty']);
+        }
         git(repoRoot, indexFile, ['add', '-A', '--', ':/']);
         if (forcedPath && fs.existsSync(path.join(repoRoot, forcedPath))) {
             git(repoRoot, indexFile, ['add', '-f', '--', forcedPath]);
@@ -111,5 +116,5 @@ function diffWorkspaceSnapshots(repoRoot, before, after) {
     }
     return [...changed].sort();
 }
-export { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots };
+export { captureRepositorySnapshot, captureWorkspaceSnapshot, captureWorktreeTree, diffWorkspaceSnapshots };
 //# sourceMappingURL=workspace-snapshot.js.map

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.3",
-  "sourceInputHash": "99efbc575d475879773bf1676cc2de5ea628b9c193f69a9812a723313ba5ae7f",
-  "internalExecutableBuildHash": "6912a66863d013c476699b88cc1d4154082971164cbae3f98ea79dda39a46e7a"
+  "packageVersion": "0.11.4",
+  "sourceInputHash": "46c0a39f354bff8c80fe19354cdda89a91a4acad060b1f134b6d599bc0ba6806",
+  "internalExecutableBuildHash": "1bc9e5755c857ee9f13a702452b2ce7c85da94444dc5a8d1305ae80d5899b001"
 }

package/lib/internal/cli-route-inventory.ts

@@ -53,7 +53,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'pr-review-grade': ['decide', 'resolve-host', 'verify-artifact'],
   'platform-checks': ['inspect', 'watch', 'resolve-run', 'logs'],
   'task-context': ['resolve'],
-  'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
+  'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert', 'rework-intent-rebuild'],
   'task-warning': ['list', 'add', 'set-status'],
   'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
   'task-artifact': ['inspect', 'init', 'preflight', 'finalize-local'],

package/lib/internal/task-artifact.ts

@@ -1,7 +1,7 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize a workflow artifact without changing task state.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family> [--source-finding <id> --source-artifact <name> --source-sha256 <digest>]\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize workflow artifact facts.\n`;
 
 
 function taskArtifact(args: string[] = []): void {

package/lib/internal/task-finalization.ts

@@ -3,8 +3,11 @@ import {
   dispatchTaskControlOperation,
   parseTaskControlOperation
 } from '../task/control-authority.ts';
-import { applyTaskFinalization } from '../task/finalization.ts';
+import { applyTaskFinalization, prepareTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
+import { verifyTaskEvent } from '../task/verification.ts';
+import { resolveSandboxControlTransport } from './task-operation-registry.ts';
+import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
@@ -73,10 +76,46 @@ async function taskFinalization(args: string[] = []): Promise<void> {
     ...operation,
     request: { ...operation.request, taskRef: resolved.taskId }
   };
+  const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
+  if (transport.kind === 'sandbox-local') {
+    const prepared = await prepareTaskFinalization(boundOperation.request, {
+      repoRoot,
+      preflight: (request, options) => verifyTaskEvent({ ...request, event: 'complete-task.hard-preflight' }, options)
+    });
+    if (prepared.status !== 'prepared') {
+      process.stdout.write(envelope(prepared.status, prepared.changed, true, prepared, prepared.error));
+      process.exitCode = exitCode(prepared.status);
+      return;
+    }
+    try {
+      const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
+      process.stdout.write(response.stdout);
+      process.stderr.write(response.stderr);
+      process.exitCode = response.exitCode ?? 1;
+      return;
+    } catch (error) {
+      const detail = error instanceof SandboxControlClientError
+        ? error.detail
+        : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
+      process.stdout.write(envelope(detail.retryable ? 'blocked' : 'failed', false, false, null, detail));
+      process.exitCode = detail.retryable ? 2 : 1;
+      return;
+    }
+  }
   const result = await dispatchTaskControlOperation(
     createDirectHostExecutionContext({ repoRoot }),
     boundOperation
   );
+  if (result.status === 'prepared') {
+    const detail = {
+      code: 'TASK_FINALIZATION_DIRECT_COMMIT_REQUIRED',
+      message: 'direct finalization prepared external work without committing the lifecycle transition',
+      retryable: false
+    };
+    process.stdout.write(envelope('failed', result.changed, true, result, detail));
+    process.exitCode = 1;
+    return;
+  }
   process.stdout.write(envelope(result.status, result.changed, true, result, result.error));
   process.exitCode = exitCode(result.status);
 }

package/lib/internal/task-ledger.ts

@@ -8,17 +8,18 @@ import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, rework-intent-upsert, stage-status\n`;
+const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, rework-intent-upsert, rework-intent-rebuild, stage-status\n`;
 const FLAGS: Record<string, string> = {
   '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
   '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
   '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation',
   '--intent-id': 'intentId', '--finding-id': 'findingId', '--source-artifact': 'sourceArtifact',
-  '--source-sha256': 'sourceSha256', '--target': 'target',
+  '--source-sha256': 'sourceSha256', '--classification': 'classification',
   '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['ordinal', 'round']);
 const BOOLEAN = new Set(['needsImplementation']);
+const REWORK_CLASSIFICATIONS = new Set(['scope-or-requirement', 'design', 'implementation', 'human-decision', 'insufficient-evidence']);
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
@@ -38,6 +39,7 @@ async function taskLedger(args: string[] = []): Promise<void> {
     internalHandlerRoute('task-ledger', 'decision-next-id', kind),
     internalHandlerRoute('task-ledger', 'decision-upsert', kind),
     internalHandlerRoute('task-ledger', 'rework-intent-upsert', kind),
+    internalHandlerRoute('task-ledger', 'rework-intent-rebuild', kind),
     internalHandlerRoute('task-ledger', 'stage-status', kind)
   ].some(Boolean)) {
     usageFailure(`unknown ledger intent '${kind}'`); return;
@@ -67,14 +69,16 @@ async function taskLedger(args: string[] = []): Promise<void> {
     'finding-review': ['id', 'status', 'evidence'],
     'decision-next-id': [],
     'decision-upsert': ['id', 'stage', 'artifact'],
-    'rework-intent-upsert': ['intentId', 'findingId', 'sourceArtifact', 'sourceSha256', 'target'],
+    'rework-intent-upsert': ['intentId', 'findingId', 'sourceArtifact', 'sourceSha256', 'classification'],
+    'rework-intent-rebuild': [],
     'stage-status': ['stage']
   };
   const optional: Record<string, string[]> = {
     'finding-review': ['needsImplementation'],
-    'decision-upsert': ['needsImplementation']
+    'decision-upsert': ['needsImplementation'],
+    'rework-intent-rebuild': ['findingId', 'sourceArtifact', 'sourceSha256', 'classification']
   };
-  const overrideFields = kind === 'stage-status' || kind === 'decision-next-id' || kind === 'rework-intent-upsert'
+  const overrideFields = kind === 'stage-status' || kind === 'decision-next-id' || kind === 'rework-intent-upsert' || kind === 'rework-intent-rebuild'
     ? []
     : ['overrideTicket', 'overrideTarget', 'overrideScope'];
   const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? []), ...overrideFields]);
@@ -84,6 +88,9 @@ async function taskLedger(args: string[] = []): Promise<void> {
   if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
   const dryRunConflict = overrideDryRunConflict(values);
   if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  if (values.classification !== undefined && !REWORK_CLASSIFICATIONS.has(String(values.classification))) {
+    usageFailure(`invalid rework classification '${values.classification}'`); return;
+  }
   if (kind === 'stage-status') {
     if (!isReviewStage(String(values.stage))) { usageFailure(`stage-status requires a valid review stage`); return; }
     const resolved = resolveTaskRef(taskRef);

package/lib/internal/task-operation-registry.ts

@@ -125,6 +125,7 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-ledger', 'finding-review', 'task-bound', 'progress'),
     descriptor('internal', 'task-ledger', 'decision-upsert', 'task-bound', 'progress'),
     descriptor('internal', 'task-ledger', 'rework-intent-upsert', 'task-bound', 'progress'),
+    descriptor('internal', 'task-ledger', 'rework-intent-rebuild', 'task-bound', 'progress'),
     descriptor('internal', 'task-warning', 'list', 'task-bound', 'diagnostic'),
     descriptor('internal', 'task-warning', 'add', 'task-bound', 'progress'),
     descriptor('internal', 'task-warning', 'set-status', 'task-bound', 'progress'),

package/lib/platform/completion-backfill.ts

@@ -19,6 +19,24 @@ type CompletionBackfillResult = PlatformResult & {
   artifacts: Array<{ artifact: string; status: PlatformResult['status'] }>;
   warnings: Array<{ id: string; status: string }>;
 };
+type CompletionBackfillEligibility = Readonly<{
+  status: 'ready' | 'failed';
+  eligible: boolean;
+  error: { code: string; message: string; retryable: boolean } | null;
+}>;
+type BackfillArtifactReference = Readonly<
+  | { status: 'ignored'; artifact: null; error: null }
+  | { status: 'ready'; artifact: string; error: null }
+  | { status: 'failed'; artifact: null; error: { code: string; message: string; retryable: false } }
+>;
+type BackfillWarningMatch = Readonly<{
+  warning: ReturnType<typeof getOpenWorkflowWarnings>[number];
+  artifact: string;
+}>;
+type BackfillWarningMatches = Readonly<
+  | { status: 'ready'; matches: BackfillWarningMatch[]; error: null }
+  | { status: 'failed'; matches: []; error: { code: string; message: string; retryable: false } }
+>;
 
 function result(
   base: PlatformResult,
@@ -28,18 +46,65 @@ function result(
   return { ...base, artifacts, warnings };
 }
 
-function excludedPrReview(taskDir: string, message: string): string | null {
-  const names = [...message.matchAll(/(?:^|[^A-Za-z0-9_-])(pr-review(?:-r[1-9]\d*)?\.md)(?=$|[^A-Za-z0-9_.-])/g)]
+function referencedBackfillArtifact(taskDir: string, message: string): BackfillArtifactReference {
+  const names = [...message.matchAll(/(?:^|[^A-Za-z0-9_-])([a-z][a-z-]*(?:-r[1-9]\d*)?\.md)(?=$|[^A-Za-z0-9_.-])/g)]
     .map((match) => match[1]!);
-  if (names.length !== 1) return null;
+  if (names.length !== 1) return { status: 'ignored', artifact: null, error: null };
   const parsed = parseArtifactName(names[0]!);
-  if (!parsed || parsed.family !== 'pr-review') return null;
+  if (!parsed || (parsed.family !== 'pr-review' && !COMPLETION_BACKFILL_FAMILIES.includes(parsed.family as typeof COMPLETION_BACKFILL_FAMILIES[number]))) {
+    return { status: 'ignored', artifact: null, error: null };
+  }
   const artifactPath = path.join(taskDir, parsed.name);
   try {
     const stat = fs.lstatSync(artifactPath);
-    return stat.isFile() && !stat.isSymbolicLink() ? parsed.name : null;
-  } catch {
-    return null;
+    if (stat.isSymbolicLink()) return {
+      status: 'failed', artifact: null,
+      error: { code: 'ARTIFACT_TOPOLOGY_CONFLICT', message: `SYMBOLIC_LINK: symbolic links are not workflow artifacts: ${parsed.name}`, retryable: false }
+    };
+    if (!stat.isFile()) return {
+      status: 'failed', artifact: null,
+      error: { code: 'ARTIFACT_TOPOLOGY_CONFLICT', message: `NON_REGULAR_FILE: artifact is not a regular file: ${parsed.name}`, retryable: false }
+    };
+    fs.accessSync(artifactPath, fs.constants.R_OK);
+    return { status: 'ready', artifact: parsed.name, error: null };
+  } catch (error) {
+    return {
+      status: 'failed', artifact: null,
+      error: { code: 'ARTIFACT_READ_FAILED', message: `Unable to inspect referenced artifact '${parsed.name}': ${error instanceof Error ? error.message : String(error)}`, retryable: false }
+    };
+  }
+}
+
+function matchingBackfillWarnings(taskDir: string, content: string): BackfillWarningMatches {
+  const matches: BackfillWarningMatch[] = [];
+  for (const warning of getOpenWorkflowWarnings(content)) {
+    if (warning.step !== 'complete-task' || warning.code !== 'COMMENT_SYNC_FAILED' || warning.target !== 'artifact') continue;
+    const reference = referencedBackfillArtifact(taskDir, warning.message);
+    if (reference.status === 'failed') return { status: 'failed', matches: [], error: reference.error };
+    if (reference.status === 'ready') matches.push({ warning, artifact: reference.artifact });
+  }
+  return { status: 'ready', matches, error: null };
+}
+
+function inspectCompletionBackfillEligibility(
+  taskRef: string,
+  options: Pick<CompletionBackfillOptions, 'cwd'> = {}
+): CompletionBackfillEligibility {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return {
+    status: 'failed', eligible: false,
+    error: { code: resolved.code, message: resolved.message, retryable: false }
+  };
+  try {
+    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const matching = matchingBackfillWarnings(resolved.taskDir, content);
+    if (matching.status === 'failed') return { status: 'failed', eligible: false, error: matching.error };
+    return { status: 'ready', eligible: matching.matches.length > 0, error: null };
+  } catch (error) {
+    return {
+      status: 'failed', eligible: false,
+      error: { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false }
+    };
   }
 }
 
@@ -60,6 +125,8 @@ async function backfillCompletionComments(
     }
   }), [], []);
   const initialContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const matching = matchingBackfillWarnings(resolved.taskDir, initialContent);
+  if (matching.status === 'failed') return result(platformResult('failed', { error: matching.error }), [], []);
   const issueIdentity = taskIssueIdentity(parseTaskFrontmatter(initialContent));
   if (!issueIdentity) return result(platformResult('no-op', {
     error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid platform issue identity', retryable: false }
@@ -92,17 +159,12 @@ async function backfillCompletionComments(
     }), artifacts, []);
   }
 
-  const matching = getOpenWorkflowWarnings(initialContent).flatMap((warning) => {
-    if (warning.step !== 'complete-task' || warning.code !== 'COMMENT_SYNC_FAILED' || warning.target !== 'artifact') return [];
-    const excluded = excludedPrReview(resolved.taskDir, warning.message);
-    return excluded ? [{ warning, excluded }] : [];
-  });
   const warnings: CompletionBackfillResult['warnings'] = [];
   let metadata: ReturnType<typeof captureTaskWriteMetadata> | null = null;
-  for (const { warning, excluded } of matching) {
+  for (const { warning, artifact } of matching.matches) {
     metadata ??= captureTaskWriteMetadata();
     const resolution = [
-      `excluded=${excluded}`,
+      `artifact=${artifact}`,
       `completionFamilies=${COMPLETION_BACKFILL_FAMILIES.join(',')}`,
       `synchronized=${inventory.artifacts.map((artifact) => artifact.name).join(',') || 'none'}`,
       `completedAt=${metadata.timestamp}`
@@ -131,5 +193,5 @@ async function backfillCompletionComments(
   }), artifacts, warnings);
 }
 
-export { backfillCompletionComments };
-export type { CompletionBackfillOptions, CompletionBackfillResult };
+export { backfillCompletionComments, inspectCompletionBackfillEligibility };
+export type { CompletionBackfillEligibility, CompletionBackfillOptions, CompletionBackfillResult };