@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/feature/review.js

@@ -0,0 +1,678 @@
+import { createHash } from "node:crypto";
+import { access, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { getRunsJsonlPath, getTaskPoolRoot, readFeatureTaskPoolStates, readJsonlFile } from "../pool/run-store.js";
+import { readRunOwner } from "../pool/run-owner-store.js";
+import { artifactMatchesEvidenceToken, isShellVerificationToken, } from "../outcomes/evidence-tokens.js";
+import { readVerifiedOutcome } from "../outcomes/store.js";
+import { acceptanceSpecSchema } from "../task-graph/acceptance-schema.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { followUpActionCardSchema, followUpApprovalSchema, followUpDraftSchema, followUpEvidenceSchema } from "../follow-up/schema.js";
+import { readFollowUpIndex, resolveRepoFile, sha256File as sha256FollowUpFile } from "../follow-up/store.js";
+import { projectReadyPlan } from "./ready-plan-projection.js";
+import { reduceFeature } from "./reducer.js";
+import { buildAcceptanceGaps, indexRawAcceptanceItems, parseAcceptancePolicy, } from "./acceptance-policy.js";
+export async function reviewFeature(input) {
+    const projection = await loadFeatureProjection(input);
+    return reduceFeature(projection);
+}
+export function renderFeatureReview(model) {
+    const reason = model.blockingItems[0]?.message ??
+        `${model.summary.tasksSucceeded}/${model.summary.tasksTotal} tasks completed; ${model.summary.requiredAcCovered}/${model.summary.requiredAcTotal} required AC covered.`;
+    const evidence = [model.evidence.morningReport, model.evidence.observeSnapshot, model.evidence.delivery, model.evidence.closeout, ...model.blockingItems.flatMap((item) => item.evidence)]
+        .filter((item) => Boolean(item));
+    const workflows = model.tasks.map((task) => task.workflow).filter((value) => Boolean(value));
+    const distinctWorkflows = [...new Set(workflows)];
+    const outcomes = model.tasks.filter((task) => task.outcome).length;
+    return [
+        `Feature: ${model.featureId}`,
+        `结果: ${model.statusLabel}`,
+        `原因: ${reason}`,
+        `任务: ${model.summary.tasksSucceeded}/${model.summary.tasksTotal} 完成，${model.summary.tasksReady} Ready，${model.summary.tasksFailed} 失败，${model.summary.tasksBlocked} 阻塞`,
+        `工作流: ${distinctWorkflows.length > 0 ? distinctWorkflows.join(", ") : "-"}`,
+        `Outcome: ${outcomes}/${model.tasks.length} 已投影`,
+        `required AC: ${model.summary.requiredAcCovered}/${model.summary.requiredAcTotal} 已覆盖；缺口 ${model.acceptanceCoverage.filter((item) => item.required && item.status !== "covered" && item.status !== "waived").map((item) => item.acId).join(", ") || "无"}`,
+        `风险: high=${model.riskSummary.high}, medium=${model.riskSummary.medium}, low=${model.riskSummary.low}`,
+        `交付/Closeout: ${model.status === "deliverable" || model.status === "closed" ? "交付证据齐备" : "尚未就绪"}`,
+        `下一步: ${model.nextAction?.command ?? model.nextAction?.label ?? "当前无行动"}`,
+        `证据: ${evidence[0] ?? "暂无"}`,
+    ].join("\n") + "\n";
+}
+async function loadFeatureProjection(input) {
+    const featureDir = path.resolve(input.featureDir);
+    const repoRoot = path.resolve(input.repoRoot);
+    const projectionWarnings = [];
+    let validation = {
+        ok: false,
+        featureId: path.basename(featureDir),
+        summary: { acceptanceCount: 0, nodeCount: 0, readyWithoutState: [] },
+        errors: [],
+    };
+    try {
+        validation = await validateFeatureTaskGraph(featureDir);
+    }
+    catch (error) {
+        validation.errors.push({
+            code: "feature-packet-unreadable",
+            message: message(error),
+            path: featureDir,
+        });
+    }
+    let acceptance = acceptanceSpecSchema.safeParse({});
+    let acceptanceRaw = {};
+    let graph = taskGraphSpecSchema.safeParse({});
+    let featurePacketRaw = {};
+    try {
+        acceptanceRaw = YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8"));
+        acceptance = acceptanceSpecSchema.safeParse(acceptanceRaw);
+        graph = taskGraphSpecSchema.safeParse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+    }
+    catch (error) {
+        projectionWarnings.push(`cannot read Feature Packet: ${message(error)}`);
+    }
+    try {
+        const featureYamlPath = path.join(featureDir, "feature.yaml");
+        if (await exists(featureYamlPath)) {
+            featurePacketRaw = YAML.parse(await readFile(featureYamlPath, "utf-8"));
+        }
+    }
+    catch (error) {
+        projectionWarnings.push(`cannot read feature.yaml: ${message(error)}`);
+    }
+    const acceptancePolicy = parseAcceptancePolicy(featurePacketRaw);
+    if (!acceptance.success)
+        projectionWarnings.push("acceptance.yaml is invalid");
+    if (!graph.success)
+        projectionWarnings.push("tasks/task-graph.yaml is invalid");
+    let states = {};
+    let runs = [];
+    try {
+        states = await readFeatureTaskPoolStates(repoRoot, validation.featureId);
+        runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    }
+    catch (error) {
+        projectionWarnings.push(`Task Pool facts are corrupt: ${message(error)}`);
+    }
+    for (const [taskId, state] of Object.entries(states)) {
+        if (!taskPoolStateSchema.safeParse(state).success || state.taskId !== taskId) {
+            projectionWarnings.push(`Task Pool state is semantically invalid: ${taskId}`);
+            delete states[taskId];
+        }
+    }
+    runs = runs.filter((run) => {
+        const valid = taskPoolRunSchema.safeParse(run).success;
+        if (!valid)
+            projectionWarnings.push("Task Pool run record is semantically invalid");
+        return valid;
+    });
+    const outcomes = new Map();
+    for (const run of runs) {
+        const outcome = await readVerifiedOutcome({
+            repoRoot,
+            workerRunId: run.workerRunId,
+            outcomePath: run.outcomePath,
+            outcomeSha256: run.outcomeSha256,
+        });
+        if (outcome)
+            outcomes.set(run.workerRunId, outcome);
+    }
+    const graphNodes = graph.success ? graph.data.nodes : [];
+    let planning;
+    if (graph.success) {
+        try {
+            const taskSpecs = new Map();
+            for (const node of graph.data.nodes) {
+                const value = YAML.parse(await readFile(path.join(featureDir, "tasks", node.task), "utf-8"));
+                taskSpecs.set(node.id, taskSpecSchema.parse(value));
+            }
+            planning = projectReadyPlan({ featureId: validation.featureId, graph: graph.data, taskSpecs, states, outcomes, selectionLimit: Math.max(graph.data.nodes.length, 1) });
+        }
+        catch (error) {
+            projectionWarnings.push(`Ready Planner projection is unavailable: ${message(error)}`);
+        }
+    }
+    let pendingFollowUps = [];
+    let actionCards = [];
+    let resolvedFailureTaskIds = [];
+    const approvedReplacements = new Map();
+    try {
+        const followUps = await readFollowUpIndex(repoRoot, validation.featureId);
+        pendingFollowUps = followUps.entries.filter((entry) => entry.kind === "TaskDraft" && entry.status === "Draft" && Boolean(entry.proposedTaskId)).map((entry) => ({
+            followUpId: entry.followUpId,
+            proposedTaskId: entry.proposedTaskId,
+            parentTaskId: entry.parentTaskId,
+            draftPath: entry.draftPath,
+        }));
+        for (const entry of followUps.entries.filter((candidate) => candidate.kind === "ActionCard" && candidate.status === "ActionRequired")) {
+            try {
+                const cardPath = await resolveRepoFile(repoRoot, entry.draftPath);
+                if (await sha256FollowUpFile(cardPath) !== entry.draftHash)
+                    throw new Error("action card hash changed");
+                const card = followUpActionCardSchema.parse(YAML.parse(await readFile(cardPath, "utf-8")));
+                const evidencePath = await resolveRepoFile(repoRoot, path.join(path.dirname(entry.draftPath), "evidence.json"));
+                if (await sha256FollowUpFile(evidencePath) !== entry.evidenceHash)
+                    throw new Error("action card evidence manifest changed");
+                const evidence = followUpEvidenceSchema.parse(JSON.parse(await readFile(evidencePath, "utf-8")));
+                if (evidence.followUpId !== entry.followUpId || evidence.evidence.map((item) => item.ref).join("\0") !== card.evidence_refs.join("\0"))
+                    throw new Error("action card evidence lineage changed");
+                for (const item of evidence.evidence) {
+                    if (await sha256FollowUpFile(await resolveRepoFile(repoRoot, item.ref)) !== item.sha256)
+                        throw new Error(`action card evidence changed: ${item.ref}`);
+                }
+                actionCards.push({ followUpId: entry.followUpId, parentTaskId: entry.parentTaskId, draftPath: entry.draftPath, action: card.action, label: card.label, ...(card.command ? { command: card.command } : {}) });
+            }
+            catch (error) {
+                projectionWarnings.push(`action card ${entry.followUpId} is inconsistent: ${message(error)}`);
+            }
+        }
+        for (const entry of followUps.entries.filter((candidate) => candidate.status === "Approved")) {
+            try {
+                if (!entry.approvalPath)
+                    throw new Error("approval path is missing");
+                const approval = followUpApprovalSchema.parse(JSON.parse(await readFile(await resolveRepoFile(repoRoot, entry.approvalPath), "utf-8")));
+                const draftPath = await resolveRepoFile(repoRoot, entry.draftPath);
+                const draft = followUpDraftSchema.parse(YAML.parse(await readFile(draftPath, "utf-8")));
+                if (await sha256FollowUpFile(draftPath) !== entry.draftHash || approval.draftHash !== entry.draftHash)
+                    throw new Error("draft hash does not match approval");
+                if (approval.followUpId !== entry.followUpId || approval.proposedTaskId !== entry.proposedTaskId)
+                    throw new Error("approval lineage does not match index");
+                const replacementNode = graphNodes.find((node) => node.id === entry.proposedTaskId && node.type === draft.proposed_graph_patch.add_node.type);
+                if (!replacementNode || draft.proposed_graph_patch.add_node.id !== entry.proposedTaskId)
+                    throw new Error("approved Follow-up node is missing");
+                for (const rewire of draft.proposed_graph_patch.rewire_dependents) {
+                    const dependent = graphNodes.find((node) => node.id === rewire.task_id);
+                    if (!dependent?.depends_on.includes(entry.proposedTaskId) || dependent.depends_on.includes(entry.parentTaskId))
+                        throw new Error(`approved dependency rewire is missing for ${rewire.task_id}`);
+                }
+                if (!states[entry.proposedTaskId])
+                    throw new Error("approved FIX state is missing");
+                resolvedFailureTaskIds.push(entry.parentTaskId);
+                approvedReplacements.set(entry.parentTaskId, entry.proposedTaskId);
+            }
+            catch (error) {
+                projectionWarnings.push(`approved follow-up ${entry.followUpId} is inconsistent: ${message(error)}`);
+            }
+        }
+    }
+    catch (error) {
+        projectionWarnings.push(`follow-up index is corrupt: ${message(error)}`);
+    }
+    const ownerByWorkerRunId = new Map();
+    await Promise.all(Object.values(states).map(async (state) => {
+        if (!state.workerRunId)
+            return;
+        const owner = await readRunOwner(repoRoot, state.workerRunId).catch(() => undefined);
+        if (owner)
+            ownerByWorkerRunId.set(state.workerRunId, owner);
+    }));
+    const tasks = graphNodes.map((node) => {
+        const rawState = states[node.id];
+        const stateRun = rawState?.workerRunId
+            ? runs.find((run) => run.workerRunId === rawState.workerRunId)
+            : undefined;
+        const live = rawState?.status === "Running" ||
+            rawState?.status === "Queued" ||
+            rawState?.status === "AgentCompleted" ||
+            rawState?.status === "VerificationRunning" ||
+            rawState?.status === "HumanReview";
+        const owner = rawState?.workerRunId
+            ? ownerByWorkerRunId.get(rawState.workerRunId)
+            : undefined;
+        let state = rawState;
+        if (rawState?.workerRunId) {
+            if (stateRun && stateRun.featureId !== validation.featureId) {
+                state = undefined;
+            }
+            else if (owner && owner.featureId !== validation.featureId) {
+                state = undefined;
+            }
+            else if (!stateRun && !live) {
+                state = undefined;
+            }
+            else if (!stateRun && live) {
+                const stateFeatureOk = !rawState.featureId || rawState.featureId === validation.featureId;
+                const ownerOk = !owner || owner.featureId === validation.featureId;
+                state = stateFeatureOk && ownerOk ? rawState : undefined;
+            }
+            else {
+                state = rawState;
+            }
+            if (rawState && !state) {
+                projectionWarnings.push(`Task Pool state for ${node.id} has missing or cross-Feature run ownership`);
+            }
+        }
+        const latest = [...runs].reverse().find((run) => run.featureId === validation.featureId && run.taskId === node.id);
+        return {
+            taskId: node.id,
+            type: node.type,
+            dependsOn: node.depends_on,
+            ...(state?.status ? { status: state.status } : {}),
+            ...(state?.workerRunId ? { workerRunId: state.workerRunId } : {}),
+            ...(state?.failure?.category ? { failureCategory: state.failure.category } : {}),
+            ...(latest?.workflow ? { workflow: latest.workflow } : {}),
+            ...(latest?.outcomePath && latest.outcomeSha256 ? { outcome: { path: latest.outcomePath, sha256: latest.outcomeSha256 } } : {}),
+            failureEvidence: Object.values(latest?.failureArtifacts ?? {}).filter((value) => typeof value === "string"),
+        };
+    });
+    const deliveryRoot = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", validation.featureId, "delivery");
+    const coveragePath = path.join(deliveryRoot, "acceptance-coverage.json");
+    const explicitCoverage = await readExplicitCoverage(coveragePath, repoRoot, validation.featureId, projectionWarnings);
+    const coverage = acceptance.success
+        ? acceptance.data.acceptance.map((item) => {
+            const effectiveRefs = item.verification.expected_task_refs.map((taskId) => approvedReplacements.get(taskId) ?? taskId);
+            const referenced = effectiveRefs.map((taskId) => states[taskId]);
+            const failed = effectiveRefs.filter((taskId) => ["Failed", "Blocked"].includes(states[taskId]?.status ?? ""));
+            const done = effectiveRefs.filter((taskId) => states[taskId]?.status === "Done");
+            const explicit = explicitCoverage.get(item.id);
+            return {
+                acId: item.id,
+                required: item.priority === "must",
+                expectedTaskRefs: item.verification.expected_task_refs,
+                status: resolveAcceptanceCoverageStatus({
+                    item,
+                    states,
+                    outcomes,
+                    failed,
+                    done,
+                    referencedCount: referenced.length,
+                    explicit,
+                    expectedFeatureId: validation.featureId,
+                }),
+                evidence: explicit?.evidence ?? [],
+                blockedBy: failed,
+            };
+        })
+        : [];
+    const acceptanceGaps = acceptance.success
+        ? buildAcceptanceGaps({
+            policy: acceptancePolicy,
+            acceptanceItems: acceptance.data.acceptance,
+            rawByAcId: indexRawAcceptanceItems(acceptanceRaw),
+            coverage,
+            tasks,
+            featureDir,
+            repoRoot,
+        })
+        : [];
+    const deliveryPath = path.join(deliveryRoot, "delivery-manifest.json");
+    const morningReportPath = path.join(getTaskPoolRoot(repoRoot), "reports", "morning-report.md");
+    const observeSnapshotPath = path.join(getTaskPoolRoot(repoRoot), "observability", "snapshot.json");
+    const closeoutPath = path.join(featureDir, "closeout.yaml");
+    let delivery;
+    let deliveryQaEvidencePath;
+    if (await exists(deliveryPath)) {
+        try {
+            const raw = deliveryManifestSchema.safeParse(JSON.parse(await readFile(deliveryPath, "utf-8")));
+            const hashedRefs = raw.success
+                ? [raw.data.qa.evidence, ...(raw.data.finalVerification ? [raw.data.finalVerification] : []), ...raw.data.tasks.flatMap((task) => task.verificationEvidence)]
+                : [];
+            const graphTaskIds = new Set(graphNodes.map((node) => node.id));
+            const acceptanceIds = new Set(coverage.map((item) => item.acId));
+            const requiredDeliveryTaskIds = tasks
+                .filter((task) => task.status === "Done" && isDevelopmentTask(task.type))
+                .map((task) => task.taskId);
+            const manifestTaskIds = raw.success ? new Set(raw.data.tasks.map((task) => task.taskId)) : new Set();
+            const tasksComplete = raw.success &&
+                requiredDeliveryTaskIds.every((taskId) => manifestTaskIds.has(taskId)) &&
+                raw.data.tasks.every((task) => graphTaskIds.has(task.taskId) && task.acceptanceRefs.every((acId) => acceptanceIds.has(acId)));
+            const requiredCoverage = coverage.filter((item) => item.required);
+            const coveredCount = requiredCoverage.filter((item) => item.status === "covered").length;
+            const waivedCount = requiredCoverage.filter((item) => item.status === "waived").length;
+            const blockedCount = requiredCoverage.filter((item) => item.status === "blocked").length;
+            const coverageCountsMatch = raw.success &&
+                raw.data.acceptanceCoverage.requiredTotal === requiredCoverage.length &&
+                raw.data.acceptanceCoverage.covered === coveredCount &&
+                raw.data.acceptanceCoverage.waived === waivedCount &&
+                raw.data.acceptanceCoverage.blocked === blockedCount &&
+                coveredCount + waivedCount === requiredCoverage.length;
+            if (raw.success && raw.data.featureId === validation.featureId && tasksComplete && coverageCountsMatch && raw.data.riskSummary.high === 0 && await allHashedRefsValid(hashedRefs, repoRoot)) {
+                delivery = {
+                    valid: true,
+                    path: deliveryPath,
+                    riskSummary: raw.data.riskSummary,
+                };
+                deliveryQaEvidencePath = raw.data.qa.evidence.path;
+            }
+            else {
+                projectionWarnings.push("delivery manifest does not match the Feature");
+            }
+        }
+        catch (error) {
+            projectionWarnings.push(`delivery manifest is corrupt: ${message(error)}`);
+        }
+    }
+    let closeout;
+    if (await exists(closeoutPath)) {
+        try {
+            const closeoutRaw = YAML.parse(await readFile(closeoutPath, "utf-8"));
+            const attemptedSuccess = Boolean(closeoutRaw && typeof closeoutRaw === "object" && closeoutRaw.status === "success");
+            const raw = closeoutSchema.safeParse(closeoutRaw);
+            const deliveryRef = raw.success
+                ? resolveReference(raw.data.delivery_manifest_ref, repoRoot, featureDir)
+                : undefined;
+            const qaEvidenceValid = raw.success && await allRefsExist(raw.data.qa_evidence, repoRoot) &&
+                raw.data.qa_evidence.some((ref) => normalizeRepoRef(ref, repoRoot) === normalizeRepoRef(deliveryQaEvidencePath ?? "", repoRoot));
+            const deliveryHash = delivery?.valid ? await sha256File(deliveryPath) : undefined;
+            closeout = {
+                applied: attemptedSuccess,
+                valid: raw.success && qaEvidenceValid && delivery?.valid === true && deliveryRef === deliveryPath && raw.data.input_facts_hash === deliveryHash,
+                path: closeoutPath,
+            };
+            if (attemptedSuccess && !closeout.valid) {
+                projectionWarnings.push("applied closeout has invalid schema, evidence, delivery reference, or facts hash");
+            }
+        }
+        catch (error) {
+            projectionWarnings.push(`closeout.yaml is corrupt: ${message(error)}`);
+        }
+    }
+    return {
+        featureId: validation.featureId,
+        featureDir,
+        repoRoot,
+        validationOk: validation.ok,
+        validationErrors: validation.errors.map((error) => `${error.code}: ${error.message}`),
+        tasks,
+        acceptance: coverage,
+        acceptanceGaps,
+        acceptancePolicy: {
+            authority: acceptancePolicy.authority ?? "feature-verify-final",
+            coverageWriter: acceptancePolicy.coverage_writer ?? "feature-verify-final",
+            verifyFinalCommand: acceptancePolicy.final_verification?.command ??
+                "agent-worker feature verify-final",
+        },
+        ...(closeout ? { closeout } : {}),
+        ...(delivery ? { delivery } : {}),
+        pendingFollowUps,
+        actionCards,
+        resolvedFailureTaskIds,
+        ...((await exists(morningReportPath)) ? { morningReport: morningReportPath } : {}),
+        ...((await exists(observeSnapshotPath)) ? { observeSnapshot: observeSnapshotPath } : {}),
+        projectionWarnings,
+        ...(planning ? { planning } : {}),
+    };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const deliveryManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    branch: z.string().min(1),
+    baseBranch: z.string().min(1),
+    baseSha: z.string().min(1),
+    headSha: z.string().min(1),
+    createdAt: z.string().datetime(),
+    tasks: z.array(z.object({
+        taskId: z.string().min(1),
+        workerRunId: z.string().min(1),
+        dagRunId: z.string().min(1),
+        commit: z.string().min(1),
+        acceptanceRefs: z.array(z.string().min(1)),
+        verificationEvidence: z.array(z.object({
+            path: z.string().min(1),
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        })).min(1),
+    })).min(1),
+    qa: z.object({
+        verdict: z.literal("passed"),
+        evidence: z.object({
+            path: z.string().min(1),
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        }),
+    }),
+    finalVerification: z.object({
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    }).optional(),
+    acceptanceCoverage: z.object({
+        requiredTotal: z.number().int().nonnegative(),
+        covered: z.number().int().nonnegative(),
+        blocked: z.number().int().nonnegative(),
+        waived: z.number().int().nonnegative(),
+    }),
+    riskSummary: z.object({
+        high: z.number().int().nonnegative(),
+        medium: z.number().int().nonnegative(),
+        low: z.number().int().nonnegative(),
+    }),
+});
+const explicitCoverageSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    items: z.array(z.object({
+        acId: z.string().min(1),
+        status: z.enum(["covered", "partial", "blocked", "waived", "missing", "awaiting-verification"]),
+        evidence: z.array(z.object({
+            path: z.string().min(1),
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        })).default([]),
+        decision: z.object({
+            owner: z.string().min(1),
+            reason: z.string().min(1),
+            decidedAt: z.string().datetime(),
+        }).optional(),
+    })),
+});
+const failureRouteSchema = z.object({
+    category: z.enum(["SpecUnclear", "ContractMismatch", "ProductBug", "TestBug", "EnvFailure", "FlakyTest", "RiskyChange", "DependencyFailure", "NeedsHuman", "Unknown"]),
+    recommendedFollowUpKind: z.string(),
+    derivedFollowUpTaskId: z.string(),
+    source: z.enum(["report-primary-failure", "report-decision", "runner-error", "fallback"]),
+});
+const taskPoolStateSchema = z.object({
+    taskId: z.string().min(1),
+    status: z.enum(["Draft", "Ready", "Queued", "Running", "AgentCompleted", "VerificationRunning", "HumanReview", "Done", "Failed", "Blocked", "Abandoned"]),
+    updatedAt: z.string().datetime(),
+    workerRunId: z.string().min(1).optional(),
+    failure: failureRouteSchema.optional(),
+}).passthrough();
+const taskPoolRunSchema = z.object({
+    schemaVersion: z.literal(1),
+    batchRunId: z.string().min(1),
+    workerRunId: z.string().min(1),
+    taskId: z.string().min(1),
+    featureId: z.string().min(1),
+    status: z.enum(["succeeded", "failed", "run-error"]),
+    recordedAt: z.string().datetime(),
+    failure: failureRouteSchema.optional(),
+}).passthrough();
+const closeoutSchema = z.object({
+    status: z.literal("success"),
+    qa_verdict: z.literal("pass"),
+    qa_evidence: z.array(z.string().min(1)).min(1),
+    delivery_manifest_ref: z.string().min(1),
+    owner: z.string().min(1),
+    appliedAt: z.string().datetime(),
+    input_facts_hash: z.string().regex(/^[a-f0-9]{64}$/),
+});
+async function readExplicitCoverage(coveragePath, repoRoot, featureId, warnings) {
+    const result = new Map();
+    if (!(await exists(coveragePath)))
+        return result;
+    try {
+        const parsed = explicitCoverageSchema.safeParse(JSON.parse(await readFile(coveragePath, "utf-8")));
+        if (!parsed.success || parsed.data.featureId !== featureId) {
+            warnings.push("acceptance coverage artifact is invalid");
+            return result;
+        }
+        for (const item of parsed.data.items) {
+            if (item.status !== "covered" && item.status !== "waived")
+                continue;
+            if (item.status === "waived" && !item.decision) {
+                warnings.push(`acceptance waiver is missing owner/reason/time for ${item.acId}`);
+                continue;
+            }
+            if (item.status === "covered" && item.evidence.length === 0) {
+                warnings.push(`acceptance evidence is missing for ${item.acId}`);
+                continue;
+            }
+            if (!(await allHashedRefsValid(item.evidence, repoRoot))) {
+                warnings.push(`acceptance evidence is missing for ${item.acId}`);
+                continue;
+            }
+            result.set(item.acId, {
+                status: item.status,
+                evidence: item.evidence.map((entry) => entry.path),
+            });
+        }
+    }
+    catch (error) {
+        warnings.push(`acceptance coverage artifact is corrupt: ${message(error)}`);
+    }
+    return result;
+}
+async function allRefsExist(refs, repoRoot) {
+    for (const ref of refs) {
+        const resolved = await resolveSafeRepoRef(ref, repoRoot);
+        if (!resolved)
+            return false;
+        if (!(await exists(resolved)))
+            return false;
+    }
+    return true;
+}
+async function allHashedRefsValid(refs, repoRoot) {
+    for (const ref of refs) {
+        const resolved = await resolveSafeRepoRef(ref.path, repoRoot);
+        if (!resolved)
+            return false;
+        if (!(await exists(resolved)) || await sha256File(resolved) !== ref.sha256)
+            return false;
+    }
+    return true;
+}
+async function resolveSafeRepoRef(ref, repoRoot) {
+    if (!ref || path.isAbsolute(ref))
+        return undefined;
+    try {
+        const canonicalRepo = await realpath(repoRoot);
+        const resolved = await realpath(path.resolve(repoRoot, ref));
+        const relative = path.relative(canonicalRepo, resolved);
+        return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function sha256File(filePath) {
+    try {
+        return createHash("sha256").update(await readFile(filePath)).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveReference(ref, repoRoot, featureDir) {
+    if (path.isAbsolute(ref))
+        return "";
+    const repoRelative = path.resolve(repoRoot, ref);
+    const featureRelative = path.resolve(featureDir, ref);
+    for (const candidate of [repoRelative, featureRelative]) {
+        const relative = path.relative(repoRoot, candidate);
+        if (!relative.startsWith("..") && !path.isAbsolute(relative) && candidate.endsWith(path.join("delivery", "delivery-manifest.json"))) {
+            return candidate;
+        }
+    }
+    return "";
+}
+function isSafeRelativeRef(ref, repoRoot) {
+    if (!ref || path.isAbsolute(ref))
+        return false;
+    const resolved = path.resolve(repoRoot, ref);
+    const relative = path.relative(repoRoot, resolved);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function normalizeRepoRef(ref, repoRoot) {
+    return isSafeRelativeRef(ref, repoRoot) ? path.resolve(repoRoot, ref) : "";
+}
+function isDevelopmentTask(type) {
+    return !type.startsWith("qa-") && !["architecture", "review"].includes(type);
+}
+export function resolveAcceptanceCoverageStatus(input) {
+    const dualCoverage = projectDualCoverage(input.item, input.states, input.outcomes, input.failed, input.done, input.expectedFeatureId);
+    if (input.failed.length > 0)
+        return "blocked";
+    if (input.explicit?.status === "covered" &&
+        input.explicit.evidence.length > 0 &&
+        (dualCoverage === undefined || dualCoverage === "covered")) {
+        return "covered";
+    }
+    if (input.explicit?.status === "waived")
+        return "waived";
+    if (dualCoverage === "covered")
+        return "awaiting-verification";
+    return dualCoverage ??
+        (input.done.length === input.referencedCount && input.done.length > 0
+            ? "partial"
+            : "missing");
+}
+export function projectDualCoverage(item, states, outcomes, failed, done, expectedFeatureId) {
+    const implRefs = item.verification.implementation_task_refs ?? [];
+    const verRefs = item.verification.verification_task_refs ?? [];
+    const integration = item.verification.integration;
+    const dualMode = implRefs.length > 0 || verRefs.length > 0 || integration !== undefined;
+    if (!dualMode)
+        return undefined;
+    const envByWorkerRunId = (workerRunId) => workerRunId ? outcomes.get(workerRunId) : undefined;
+    // 1. implementation refs must all be Done.
+    const implDone = implRefs.length > 0
+        ? implRefs.every((id) => states[id]?.status === "Done")
+        : done.length > 0;
+    // 2. verification refs must each have a succeeded outcome envelope.
+    let verSucceeded = false;
+    let verEnvelopes = [];
+    if (verRefs.length > 0) {
+        verEnvelopes = verRefs
+            .map((taskId) => ({ taskId, envelope: envByWorkerRunId(states[taskId]?.workerRunId) }))
+            .filter((value) => Boolean(value.envelope));
+        verSucceeded =
+            verEnvelopes.length === verRefs.length &&
+                verEnvelopes.every(({ envelope }) => envelope.outcomeStatus === "succeeded");
+    }
+    if (failed.length > 0)
+        return "blocked";
+    if (!implDone) {
+        return done.length > 0 ? "partial" : "missing";
+    }
+    if (verRefs.length === 0 || !verSucceeded)
+        return "awaiting-verification";
+    if (expectedFeatureId && verEnvelopes.some(({ taskId, envelope }) => envelope.identity?.featureId !== expectedFeatureId ||
+        envelope.identity?.taskId !== taskId ||
+        (envelope.identity?.workflow !== "backend-test" && envelope.identity?.workflow !== "frontend-test"))) {
+        return "awaiting-verification";
+    }
+    const requiredEvidence = item.verification.required_evidence ?? [];
+    if (requiredEvidence.some((token) => !verEnvelopes.some(({ envelope }) => isShellVerificationToken(token)
+        ? envelope.shellVerification?.exitZero === true
+        : envelope.artifacts?.some((artifact) => artifactMatchesEvidenceToken(artifact, token))))) {
+        return "awaiting-verification";
+    }
+    // 3. integration policy: real-required demands real evidence on every
+    //    verification envelope. mock-only / locally-validated (real:false) cannot
+    //    satisfy real-required.
+    if (integration === "real-required") {
+        if (verRefs.length === 0)
+            return "awaiting-verification";
+        const realOk = verEnvelopes.every(({ envelope }) => envelope.integrationStatus?.real === true);
+        if (!realOk)
+            return "awaiting-verification";
+    }
+    // 4. All dual-coverage prerequisites are satisfied. The caller still requires
+    //    an explicit, hash-validated coverage artifact before publishing `covered`;
+    //    without it, the read model remains awaiting-verification.
+    return "covered";
+}