agentplane 0.3.10 → 0.3.12

package/dist/commands/incidents/shared.js

@@ -5,6 +5,8 @@ import { writeTextIfChanged } from "../../shared/write-if-changed.js";
 import { appendIncidentRegistryEntries, buildIncidentAdviceQueryFromTask, createIncidentRegistrySkeleton, parseIncidentRegistry, planIncidentCollection, resolveIncidentAdviceMatches, } from "../../runtime/incidents/index.js";
 import { extractDocSection, extractTaskObservationSection, normalizeTaskDocVersion, } from "../task/shared.js";
 export const INCIDENTS_POLICY_PATH = ".agentplane/policy/incidents.md";
+export const INCIDENTS_POLICY_ASSET_PATH = "packages/agentplane/assets/policy/incidents.md";
+const INCIDENTS_POLICY_LINE_BUDGET = 100;
 async function readTextIfExists(filePath) {
     try {
         return await readFile(filePath, "utf8");
@@ -19,6 +21,41 @@ async function readTextIfExists(filePath) {
 export function incidentRegistryPath(ctx) {
     return path.join(ctx.resolvedProject.gitRoot, INCIDENTS_POLICY_PATH);
 }
+export function incidentRegistryAssetPath(ctx) {
+    return path.join(ctx.resolvedProject.gitRoot, INCIDENTS_POLICY_ASSET_PATH);
+}
+function normalizeIncidentRegistryDocument(text) {
+    const normalized = text.replaceAll("\r\n", "\n").trimEnd();
+    return normalized.length > 0 ? `${normalized}\n` : createIncidentRegistrySkeleton();
+}
+async function writeIncidentRegistryMirrors(ctx, content) {
+    const registryPath = incidentRegistryPath(ctx);
+    const assetPath = incidentRegistryAssetPath(ctx);
+    const assetExists = (await readTextIfExists(assetPath)) !== null;
+    const normalizedContent = normalizeIncidentRegistryDocument(content);
+    let wroteRegistry = await writeTextIfChanged(registryPath, normalizedContent);
+    let wroteAsset = false;
+    if (assetExists) {
+        const canonicalText = (await readTextIfExists(registryPath)) ?? normalizedContent;
+        wroteAsset = await writeTextIfChanged(assetPath, canonicalText);
+        const registryText = await readTextIfExists(registryPath);
+        if (registryText !== canonicalText) {
+            wroteRegistry = (await writeTextIfChanged(registryPath, canonicalText)) || wroteRegistry;
+        }
+    }
+    return wroteRegistry || wroteAsset;
+}
+async function resolveIncidentRegistryMirrorPaths(ctx) {
+    const paths = [INCIDENTS_POLICY_PATH];
+    const assetPath = incidentRegistryAssetPath(ctx);
+    if ((await readTextIfExists(assetPath)) !== null) {
+        paths.push(INCIDENTS_POLICY_ASSET_PATH);
+    }
+    return paths;
+}
+function countTextLines(text) {
+    return text.replaceAll("\r\n", "\n").split("\n").length;
+}
 export async function loadIncidentRegistry(ctx) {
     const registryPath = incidentRegistryPath(ctx);
     const registryText = (await readTextIfExists(registryPath)) ?? createIncidentRegistrySkeleton();
@@ -60,19 +97,48 @@ export function formatIncidentCollectionIssues(taskId, plan) {
         return `line ${issue.candidate.line}: ${scope} -> missing ${issue.missingFields.join(", ")}`;
     });
     return [
-        `${taskId}: incident-candidate entries require explicit external incident metadata before promotion.`,
+        `${taskId}: reusable external findings need explicit external marking and enough recovery detail before promotion.`,
         "Required fields:",
         ...issueLines.map((line) => `- ${line}`),
     ].join("\n");
 }
 export async function collectTaskIncidents(opts) {
+    const inspected = await inspectTaskIncidents(opts);
+    const { loaded, registryPath, registryPaths, registryText, registry, plan } = inspected;
+    if (plan.issues.length > 0) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: formatIncidentCollectionIssues(opts.taskId, plan),
+        });
+    }
+    const nextText = appendIncidentRegistryEntries(registryText, plan.promotable.map((item) => item.entry));
+    if (plan.promotable.length > 0) {
+        const nextLineCount = countTextLines(nextText);
+        if (nextLineCount > INCIDENTS_POLICY_LINE_BUDGET) {
+            throw new CliError({
+                exitCode: 3,
+                code: "E_VALIDATION",
+                message: `Incident registry write would exceed policy budget: ${nextLineCount} lines ` +
+                    `(limit ${INCIDENTS_POLICY_LINE_BUDGET}). Compact or promote fewer entries before writing.`,
+            });
+        }
+    }
+    const wrote = opts.write && plan.promotable.length > 0
+        ? await writeIncidentRegistryMirrors(opts.ctx, nextText)
+        : false;
+    return { loaded, registryPath, registryPaths, registryText, registry, plan, wrote };
+}
+export async function inspectTaskIncidents(opts) {
     const loaded = await loadTaskIncidents(opts.ctx, opts.taskId, opts.task ?? null);
     const { registryPath, registryText, registry } = await loadIncidentRegistry(opts.ctx);
+    const registryPaths = await resolveIncidentRegistryMirrorPaths(opts.ctx);
     const plan = planIncidentCollection({
         task: {
             id: loaded.task.id,
             title: loaded.task.title,
             description: loaded.task.description,
+            scope: loaded.scope,
             tags: loaded.task.tags ?? [],
             commitHash: loaded.task.commit?.hash ?? null,
         },
@@ -80,18 +146,106 @@ export async function collectTaskIncidents(opts) {
         registry,
         now: opts.now,
     });
-    if (plan.issues.length > 0) {
-        throw new CliError({
-            exitCode: 3,
-            code: "E_VALIDATION",
-            message: formatIncidentCollectionIssues(opts.taskId, plan),
-        });
+    return { loaded, registryPath, registryPaths, registryText, registry, plan };
+}
+export function renderIncidentCollectionOutcome(promotedCount) {
+    return promotedCount > 0
+        ? `incident registry updated (${promotedCount} promoted)`
+        : "incident registry unchanged (no promotable external findings)";
+}
+function summarizeDetailList(values, maxItems = 3) {
+    const filtered = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    if (filtered.length === 0)
+        return null;
+    if (filtered.length <= maxItems)
+        return filtered.join(", ");
+    return `${filtered.slice(0, maxItems).join(", ")}, +${filtered.length - maxItems} more`;
+}
+export function renderIncidentCollectionPlanOutcome(plan, opts) {
+    const candidates = Array.isArray(plan.candidates) ? plan.candidates.length : 0;
+    const skipped = Array.isArray(plan.skipped) ? plan.skipped.length : 0;
+    const promoted = Array.isArray(plan.promotable) ? plan.promotable.length : 0;
+    const duplicates = Array.isArray(plan.duplicates) ? plan.duplicates.length : 0;
+    const issues = Array.isArray(plan.issues) ? plan.issues.length : 0;
+    const findingsTextPresent = plan.findingsTextPresent === true;
+    const structuredFindingCount = typeof plan.structuredFindingCount === "number" ? plan.structuredFindingCount : 0;
+    const wrote = opts?.wrote === true;
+    const context = opts?.context ?? "generic";
+    const taskId = typeof opts?.taskId === "string" && opts.taskId.trim().length > 0 ? opts.taskId.trim() : null;
+    const findingsNextStep = taskId
+        ? ` next: agentplane task findings add ${taskId} --observation "<observation>" --impact "<impact>" --resolution "<resolution>"`
+        : "";
+    if (promoted > 0 && wrote) {
+        const suffix = [];
+        if (duplicates > 0)
+            suffix.push(`${duplicates} duplicate${duplicates === 1 ? "" : "s"}`);
+        if (skipped > 0)
+            suffix.push(`${skipped} skipped structured finding${skipped === 1 ? "" : "s"}`);
+        const base = suffix.length > 0
+            ? `incident registry updated (${promoted} promoted; ${suffix.join("; ")})`
+            : renderIncidentCollectionOutcome(promoted);
+        const details = [];
+        const promotedIds = Array.isArray(opts?.promotedIds)
+            ? opts.promotedIds.filter((id) => typeof id === "string" && id.trim().length > 0)
+            : [];
+        const registryPaths = Array.isArray(opts?.registryPaths)
+            ? opts.registryPaths.filter((filePath) => typeof filePath === "string" && filePath.trim().length > 0)
+            : [];
+        const idsSummary = summarizeDetailList(promotedIds);
+        const pathsSummary = summarizeDetailList(registryPaths);
+        if (idsSummary)
+            details.push(`ids=${idsSummary}`);
+        if (pathsSummary)
+            details.push(`files=${pathsSummary}`);
+        return details.length > 0 ? `${base} ${details.join(" ")}` : base;
     }
-    const nextText = appendIncidentRegistryEntries(registryText, plan.promotable.map((item) => item.entry));
-    const wrote = opts.write && plan.promotable.length > 0
-        ? await writeTextIfChanged(registryPath, nextText)
-        : false;
-    return { loaded, registryPath, registryText, registry, plan, wrote };
+    if (promoted > 0 && !wrote) {
+        if (context === "collect") {
+            return `incident registry unchanged (${promoted} promotable external finding${promoted === 1 ? "" : "s"} validated; rerun without --check to update incidents.md)`;
+        }
+        if (context === "verify") {
+            return `incident registry unchanged (${promoted} promotable external finding${promoted === 1 ? "" : "s"} stayed task-local in the current task worktree; run verify --collect-incidents, agentplane incidents collect <task-id>, or finish on the base branch to update incidents.md)`;
+        }
+        return `incident registry unchanged (${promoted} promotable external finding${promoted === 1 ? "" : "s"} pending promotion)`;
+    }
+    if (issues > 0) {
+        const issueEntries = Array.isArray(plan.issues)
+            ? plan.issues
+            : [];
+        const firstIssue = issueEntries[0];
+        const rawMissingFields = firstIssue?.missingFields;
+        const missingFields = Array.isArray(rawMissingFields)
+            ? rawMissingFields.filter((field) => typeof field === "string" && field.trim().length > 0)
+            : [];
+        const detail = missingFields.length > 0
+            ? ` missing required fields: ${missingFields.join(", ")}`
+            : " missing required promotion fields";
+        const suffix = issues > 1 ? `; +${issues - 1} more candidate${issues - 1 === 1 ? "" : "s"}` : "";
+        return `incident registry unchanged (${issues} structured finding candidate${issues === 1 ? "" : "s"} still invalid;${detail}${suffix})`;
+    }
+    if (skipped > 0) {
+        return `incident registry unchanged (${skipped} structured finding${skipped === 1 ? "" : "s"} stayed task-local in the current checkout: mark reusable external findings with Promotion: incident-candidate plus Fixability: external, or use task findings add without --local-only)`;
+    }
+    if (candidates === 0 && structuredFindingCount === 0 && findingsTextPresent) {
+        return "incident registry unchanged (plain Findings text stays task-local in the current checkout and does not update incidents.md: add a structured Observation/Impact/Resolution block for reusable external incidents, or use task findings add without --local-only)";
+    }
+    if (candidates === 0) {
+        if (context === "verify") {
+            return ("incident registry unchanged (plain verify note stayed task-local and did not update " +
+                "incidents.md: add --observation, --impact, and --resolution for a reusable incident, " +
+                `then rerun with --collect-incidents or collect later on the base branch.${findingsNextStep})`);
+        }
+        if (context === "finish") {
+            return ("incident registry unchanged (plain finish body/result stayed task-local and did not " +
+                "update incidents.md: add --observation, --impact, and --resolution for a reusable " +
+                `incident before closeout.${findingsNextStep})`);
+        }
+        return "incident registry unchanged (no structured incident findings)";
+    }
+    if (duplicates > 0 && duplicates === candidates) {
+        return `incident registry unchanged (${duplicates} duplicate incident${duplicates === 1 ? "" : "s"} already recorded)`;
+    }
+    return "incident registry unchanged (no promotable external findings)";
 }
 export async function adviseTaskIncidents(opts) {
     const loaded = await loadTaskIncidents(opts.ctx, opts.taskId, opts.task ?? null);

package/dist/commands/pr/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/check.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AA8DnC,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiMlB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/check.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAkLnC,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6NlB"}

package/dist/commands/pr/check.js

@@ -6,12 +6,12 @@ import { fileExists } from "../../cli/fs-utils.js";
 import { createCliEmitter, workflowModeMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { parsePrMeta } from "../shared/pr-meta.js";
-import { gitListTaskBranches, parseTaskIdFromBranch } from "../shared/git-worktree.js";
+import { findWorktreeForBranch, gitListTaskBranches, parseTaskIdFromBranch, } from "../shared/git-worktree.js";
 import { gitRevParse } from "../shared/git-ops.js";
-import { isTaskLocalOnlyAdvance } from "../shared/task-local-freshness.js";
 import { loadBackendTask, loadCommandContext, } from "../shared/task-backend.js";
-import { readPrArtifact, resolvePrPaths } from "./internal/pr-paths.js";
+import { readPrArtifactFromBranch, resolvePrPaths } from "./internal/pr-paths.js";
 import { validateGithubPrBodyContents, validateReviewContents, } from "./internal/review-template.js";
+import { assessPrArtifactFreshness } from "./internal/freshness.js";
 function isUnknownRevisionError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return /unknown revision or path not in the working tree/i.test(message);
@@ -31,26 +31,102 @@ async function resolveArtifactBranch(opts) {
     }
     return null;
 }
-async function readPrArtifactWithOptionalBranch(opts) {
-    const localPath = path.join(opts.prDir, opts.fileName);
-    if (await fileExists(localPath)) {
-        return await readFile(localPath, "utf8");
+async function readLocalPrArtifactText(prDir, fileName) {
+    const localPath = path.join(prDir, fileName);
+    if (!(await fileExists(localPath)))
+        return null;
+    return await readFile(localPath, "utf8");
+}
+function validateSnapshotContents(opts) {
+    const errors = [];
+    let meta = null;
+    if (opts.texts.metaText) {
+        try {
+            meta = parsePrMeta(opts.texts.metaText, opts.taskId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push(message);
+        }
     }
-    if (opts.branchCache.value === undefined) {
-        opts.branchCache.value = await resolveArtifactBranch({
-            ctx: opts.ctx,
-            resolved: opts.resolved,
-            taskId: opts.taskId,
-        });
+    else {
+        errors.push(`Missing PR directory: ${opts.relPrDir}`, `Missing ${opts.relMetaPath}`);
     }
-    if (!opts.branchCache.value)
-        return null;
-    return await readPrArtifact({
-        resolved: opts.resolved,
-        prDir: opts.prDir,
-        fileName: opts.fileName,
-        branch: opts.branchCache.value,
+    if (opts.texts.diffstatText === null)
+        errors.push(`Missing ${opts.relDiffstatPath}`);
+    if (opts.texts.verifyLogText === null)
+        errors.push(`Missing ${opts.relVerifyLogPath}`);
+    if (opts.texts.reviewText) {
+        validateReviewContents(opts.texts.reviewText, errors);
+    }
+    else {
+        errors.push(`Missing ${opts.relReviewPath}`);
+    }
+    if (!opts.texts.githubTitleText?.trim()) {
+        errors.push(`Missing ${opts.relGithubTitlePath}`);
+    }
+    if (opts.texts.githubBodyText) {
+        validateGithubPrBodyContents(opts.texts.githubBodyText, errors);
+    }
+    else {
+        errors.push(`Missing ${opts.relGithubBodyPath}`);
+    }
+    return { meta, errors };
+}
+async function evaluateSnapshotFreshness(opts) {
+    if (!opts.snapshot.meta || !opts.branchHeadSha)
+        return;
+    const freshness = await assessPrArtifactFreshness({
+        gitRoot: opts.gitRoot,
+        workflowDir: opts.workflowDir,
+        tasksPath: opts.tasksPath,
+        taskId: opts.taskId,
+        branchHeadSha: opts.branchHeadSha,
+        metaHeadSha: opts.snapshot.meta.head_sha ?? null,
+        metaLastVerifiedSha: opts.snapshot.meta.last_verified_sha ?? null,
+        metaVerifyStatus: opts.snapshot.meta.verify?.status ?? null,
+        taskVerificationState: opts.taskVerificationState,
+        verifyLogText: opts.snapshot.texts.verifyLogText,
+        requiresVerify: opts.requiresVerify,
     });
+    opts.snapshot.freshnessEvaluated = true;
+    opts.snapshot.freshnessReviewFresh = freshness.reviewFresh;
+    opts.snapshot.freshnessVerifySatisfied = freshness.verifySatisfied;
+    opts.snapshot.freshnessVerifyFresh = freshness.verifyFresh;
+    opts.snapshot.freshnessVerifyLogSha = freshness.verifyLogSha;
+}
+function finalizeSnapshotErrors(opts) {
+    const errors = [...opts.snapshot.errors];
+    const meta = opts.snapshot.meta;
+    if (!meta)
+        return errors;
+    if (opts.branchHeadSha && opts.snapshot.freshnessEvaluated) {
+        if (!opts.snapshot.freshnessReviewFresh) {
+            errors.push(`PR artifacts stale: head_sha=${meta.head_sha ?? "<missing>"} current_head=${opts.branchHeadSha}`);
+        }
+        if (opts.requiresVerify && !opts.snapshot.freshnessVerifySatisfied) {
+            if (meta.verify?.status !== "pass") {
+                errors.push("Verify requirements not satisfied (meta.verify.status != pass)");
+            }
+            if ((!meta.last_verified_sha || !meta.last_verified_at) &&
+                !opts.snapshot.freshnessVerifyLogSha) {
+                errors.push("Verify metadata missing (last_verified_sha/last_verified_at)");
+            }
+        }
+        if (opts.requiresVerify && meta.last_verified_sha && !opts.snapshot.freshnessVerifyFresh) {
+            errors.push(`Verify state stale: last_verified_sha=${meta.last_verified_sha} current_head=${opts.branchHeadSha}`);
+        }
+        return errors;
+    }
+    if (opts.requiresVerify) {
+        if (meta.verify?.status !== "pass") {
+            errors.push("Verify requirements not satisfied (meta.verify.status != pass)");
+        }
+        if (!meta.last_verified_sha || !meta.last_verified_at) {
+            errors.push("Verify metadata missing (last_verified_sha/last_verified_at)");
+        }
+    }
+    return errors;
 }
 export async function cmdPrCheck(opts) {
     try {
@@ -80,99 +156,51 @@ export async function cmdPrCheck(opts) {
         const relGithubTitlePath = path.relative(resolved.gitRoot, githubTitlePath);
         const relGithubBodyPath = path.relative(resolved.gitRoot, githubBodyPath);
         const branchCache = {};
-        let meta = null;
-        const metaText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "meta.json",
+        const requiresVerify = Boolean(task.verify && task.verify.length > 0);
+        const localTexts = {
+            metaText: await readLocalPrArtifactText(prDir, "meta.json"),
+            diffstatText: await readLocalPrArtifactText(prDir, "diffstat.txt"),
+            verifyLogText: await readLocalPrArtifactText(prDir, "verify.log"),
+            reviewText: await readLocalPrArtifactText(prDir, "review.md"),
+            githubTitleText: await readLocalPrArtifactText(prDir, "github-title.txt"),
+            githubBodyText: await readLocalPrArtifactText(prDir, "github-body.md"),
+        };
+        const localParsed = validateSnapshotContents({
+            texts: localTexts,
+            relPrDir,
+            relMetaPath,
+            relDiffstatPath,
+            relVerifyLogPath,
+            relReviewPath,
+            relGithubTitlePath,
+            relGithubBodyPath,
             taskId: task.id,
-            branchCache,
         });
-        if (metaText) {
-            try {
-                meta = parsePrMeta(metaText, task.id);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                errors.push(message);
-            }
+        const localSnapshot = {
+            source: "local",
+            texts: localTexts,
+            meta: localParsed.meta,
+            errors: localParsed.errors,
+            freshnessEvaluated: false,
+            freshnessReviewFresh: false,
+            freshnessVerifySatisfied: false,
+            freshnessVerifyFresh: false,
+            freshnessVerifyLogSha: null,
+        };
+        const localBranch = localSnapshot.meta?.branch?.trim() ?? "";
+        if (localBranch) {
+            branchCache.value = localBranch;
         }
-        else {
-            errors.push(`Missing PR directory: ${relPrDir}`, `Missing ${relMetaPath}`);
-        }
-        const diffstatText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "diffstat.txt",
-            taskId: task.id,
-            branchCache,
-        });
-        if (diffstatText === null) {
-            errors.push(`Missing ${relDiffstatPath}`);
-        }
-        const verifyLogText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "verify.log",
-            taskId: task.id,
-            branchCache,
-        });
-        if (verifyLogText === null) {
-            errors.push(`Missing ${relVerifyLogPath}`);
-        }
-        const reviewText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "review.md",
-            taskId: task.id,
-            branchCache,
-        });
-        if (reviewText) {
-            validateReviewContents(reviewText, errors);
-        }
-        else {
-            errors.push(`Missing ${relReviewPath}`);
-        }
-        const githubTitleText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "github-title.txt",
-            taskId: task.id,
-            branchCache,
-        });
-        if (!githubTitleText?.trim()) {
-            errors.push(`Missing ${relGithubTitlePath}`);
-        }
-        const githubBodyText = await readPrArtifactWithOptionalBranch({
-            ctx,
-            resolved,
-            prDir,
-            fileName: "github-body.md",
-            taskId: task.id,
-            branchCache,
-        });
-        if (githubBodyText) {
-            validateGithubPrBodyContents(githubBodyText, errors);
-        }
-        else {
-            errors.push(`Missing ${relGithubBodyPath}`);
-        }
-        if (task.verify && task.verify.length > 0) {
-            if (meta?.verify?.status !== "pass") {
-                errors.push("Verify requirements not satisfied (meta.verify.status != pass)");
-            }
-            if (!meta?.last_verified_sha || !meta.last_verified_at) {
-                errors.push("Verify metadata missing (last_verified_sha/last_verified_at)");
-            }
+        else if (branchCache.value === undefined) {
+            branchCache.value = await resolveArtifactBranch({
+                ctx,
+                resolved,
+                taskId: task.id,
+            });
         }
-        const branchForFreshness = branchCache.value ?? (typeof meta?.branch === "string" ? meta.branch.trim() : null);
-        if (meta && branchForFreshness) {
-            let branchHeadSha = null;
+        const branchForFreshness = branchCache.value ?? null;
+        let branchHeadSha = null;
+        if (branchForFreshness) {
             try {
                 branchHeadSha = await gitRevParse(resolved.gitRoot, [branchForFreshness]);
             }
@@ -180,34 +208,112 @@ export async function cmdPrCheck(opts) {
                 if (!isUnknownRevisionError(err))
                     throw err;
             }
-            if (branchHeadSha) {
-                const reviewFresh = (meta.head_sha ?? null) === branchHeadSha ||
-                    (await isTaskLocalOnlyAdvance({
-                        gitRoot: resolved.gitRoot,
-                        workflowDir: config.paths.workflow_dir,
-                        taskId: task.id,
-                        fromRef: meta.head_sha ?? null,
-                        toRef: branchHeadSha,
-                    }));
-                if (!reviewFresh) {
-                    errors.push(`PR artifacts stale: head_sha=${meta.head_sha ?? "<missing>"} current_head=${branchHeadSha}`);
-                }
-                const verifyFresh = !task.verify ||
-                    task.verify.length === 0 ||
-                    !meta.last_verified_sha ||
-                    meta.last_verified_sha === branchHeadSha ||
-                    (await isTaskLocalOnlyAdvance({
-                        gitRoot: resolved.gitRoot,
-                        workflowDir: config.paths.workflow_dir,
-                        taskId: task.id,
-                        fromRef: meta.last_verified_sha,
-                        toRef: branchHeadSha,
-                    }));
-                if (task.verify && task.verify.length > 0 && meta.last_verified_sha && !verifyFresh) {
-                    errors.push(`Verify state stale: last_verified_sha=${meta.last_verified_sha} current_head=${branchHeadSha}`);
-                }
+        }
+        await evaluateSnapshotFreshness({
+            snapshot: localSnapshot,
+            gitRoot: resolved.gitRoot,
+            workflowDir: config.paths.workflow_dir,
+            tasksPath: config.paths.tasks_path,
+            taskId: task.id,
+            branchHeadSha,
+            taskVerificationState: task.verification?.state ?? null,
+            requiresVerify,
+        });
+        let selectedSnapshot = localSnapshot;
+        if (branchForFreshness &&
+            branchHeadSha &&
+            (!localSnapshot.meta ||
+                !localSnapshot.freshnessReviewFresh ||
+                (requiresVerify && !localSnapshot.freshnessVerifySatisfied))) {
+            const worktreePath = await findWorktreeForBranch(resolved.gitRoot, branchForFreshness);
+            const branchTexts = {
+                metaText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "meta.json",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+                diffstatText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "diffstat.txt",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+                verifyLogText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "verify.log",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+                reviewText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "review.md",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+                githubTitleText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "github-title.txt",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+                githubBodyText: await readPrArtifactFromBranch({
+                    resolved,
+                    prDir,
+                    fileName: "github-body.md",
+                    branch: branchForFreshness,
+                    worktreePath,
+                }),
+            };
+            const branchParsed = validateSnapshotContents({
+                texts: branchTexts,
+                relPrDir,
+                relMetaPath,
+                relDiffstatPath,
+                relVerifyLogPath,
+                relReviewPath,
+                relGithubTitlePath,
+                relGithubBodyPath,
+                taskId: task.id,
+            });
+            const branchSnapshot = {
+                source: "branch",
+                texts: branchTexts,
+                meta: branchParsed.meta,
+                errors: branchParsed.errors,
+                freshnessEvaluated: false,
+                freshnessReviewFresh: false,
+                freshnessVerifySatisfied: false,
+                freshnessVerifyFresh: false,
+                freshnessVerifyLogSha: null,
+            };
+            await evaluateSnapshotFreshness({
+                snapshot: branchSnapshot,
+                gitRoot: resolved.gitRoot,
+                workflowDir: config.paths.workflow_dir,
+                tasksPath: config.paths.tasks_path,
+                taskId: task.id,
+                branchHeadSha,
+                taskVerificationState: task.verification?.state ?? null,
+                requiresVerify,
+            });
+            if (branchSnapshot.errors.length === 0 &&
+                branchSnapshot.meta &&
+                branchSnapshot.freshnessReviewFresh &&
+                (!requiresVerify || branchSnapshot.freshnessVerifySatisfied)) {
+                selectedSnapshot = branchSnapshot;
             }
         }
+        errors.push(...finalizeSnapshotErrors({
+            snapshot: selectedSnapshot,
+            branchHeadSha,
+            requiresVerify,
+        }));
         if (errors.length > 0) {
             throw new CliError({
                 exitCode: exitCodeForError("E_VALIDATION"),

package/dist/commands/pr/close-superseded.d.ts

@@ -0,0 +1,9 @@
+import { type CommandContext } from "../shared/task-backend.js";
+export declare function cmdPrCloseSuperseded(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    taskId: string;
+    deleteRemoteBranch: boolean;
+}): Promise<number>;
+//# sourceMappingURL=close-superseded.d.ts.map

package/dist/commands/pr/close-superseded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-superseded.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/close-superseded.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAiCnC,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAsHlB"}