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

package/dist/worker/delivery/package.js

@@ -0,0 +1,537 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isResilientGitCommandError, runResilientGitCommand } from "../../shared/resilient-git.js";
+import YAML from "yaml";
+import { z } from "zod";
+import { controllerIdentitiesMatch, LOOP_AGENT_PACKAGE_NAME, } from "../loop-agent/loop-agent-client.js";
+import { getRunsJsonlPath, getTaskPoolRoot, readFeatureTaskPoolStates, readJsonlFile } from "../pool/run-store.js";
+import { acceptanceSpecSchema } from "../task-graph/acceptance-schema.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
+import { readVerifiedBundle, verifyBundleCurrentStateBindings, verifyBundleOutcomes, verifyBundleTaskSpecBindings } from "./verification-bundle.js";
+const hashedRefSchema = z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const acceptanceCoverageArtifactSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    waiverSource: hashedRefSchema.optional(),
+    items: z.array(z.object({
+        acId: z.string().min(1), required: z.boolean(),
+        status: z.enum(["covered", "partial", "blocked", "waived", "missing"]),
+        evidence: z.array(hashedRefSchema), blockedBy: z.array(z.string()),
+        decision: z.object({ owner: z.string().min(1), reason: z.string().min(1), decidedAt: z.string().datetime() }).optional(),
+    }).strict()),
+}).strict();
+export 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().regex(/^[a-f0-9]{40}$/), headSha: z.string().regex(/^[a-f0-9]{40}$/), createdAt: z.string().datetime(),
+    tasks: z.array(z.object({ taskId: z.string(), workerRunId: z.string(), dagRunId: z.string(), commit: z.string().regex(/^[a-f0-9]{40}$/), acceptanceRefs: z.array(z.string()), verificationEvidence: z.array(hashedRefSchema).min(1), changedFiles: z.array(z.string()) }).strict()),
+    qa: z.object({ verdict: z.literal("passed"), evidence: hashedRefSchema }).strict(),
+    finalVerification: hashedRefSchema,
+    acceptanceCoverage: z.object({ requiredTotal: z.number().int().nonnegative(), covered: z.number().int().nonnegative(), blocked: z.number().int().nonnegative(), waived: z.number().int().nonnegative() }).strict(),
+    riskSummary: z.object({ high: z.number().int().nonnegative(), medium: z.number().int().nonnegative(), low: z.number().int().nonnegative() }).strict(),
+}).strict();
+const waiverSchema = z.object({ schemaVersion: z.literal(1), featureId: z.string(), items: z.array(z.object({ acId: z.string(), owner: z.string().min(1), reason: z.string().min(1), decidedAt: z.string().datetime() }).strict()) }).strict();
+const controllerIdentityEvidenceSchema = z.object({
+    schemaVersion: z.literal(1),
+    packageName: z.literal(LOOP_AGENT_PACKAGE_NAME),
+    binName: z.string().min(1),
+    requested: z.string().min(1),
+    entry: z.string().min(1),
+    realEntry: z.string().min(1),
+    launch: z.object({ command: z.string().min(1), argsPrefix: z.array(z.string()) }).strict(),
+    binarySha256: z.string().regex(/^[a-f0-9]{64}$/),
+    packageRoot: z.string().min(1),
+    packageVersion: z.string().min(1),
+    reportedVersion: z.string().min(1).optional(),
+    packageFingerprint: z.object({
+        algorithm: z.literal("sha256"),
+        scopeVersion: z.literal(1),
+        scope: z.tuple([
+            z.literal("package.json"),
+            z.literal("bin/**"),
+            z.literal("dist/**"),
+            z.literal("skills/**"),
+        ]),
+        value: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+        fileCount: z.number().int().positive(),
+    }).strict(),
+    resolvedAt: z.string().datetime(),
+}).strict().superRefine((identity, ctx) => {
+    if (identity.reportedVersion !== undefined
+        && identity.reportedVersion !== identity.packageVersion) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["reportedVersion"],
+            message: "reportedVersion must match packageVersion",
+        });
+    }
+});
+const evidenceRunSchema = z.object({
+    taskId: z.string(),
+    workerRunId: z.string(),
+    recordedAt: z.string().datetime(),
+    controllerIdentity: controllerIdentityEvidenceSchema.optional(),
+}).strict();
+const qaEvidenceSchema = z.object({ schemaVersion: z.literal(1), featureId: z.string(), verdict: z.literal("passed"), acIds: z.array(z.string()).min(1), runs: z.array(evidenceRunSchema).min(1), bundle: hashedRefSchema.optional() }).strict();
+const finalVerificationSchema = z.object({ schemaVersion: z.literal(1), featureId: z.string(), kind: z.literal("final-verification"), status: z.literal("passed"), headSha: z.string().regex(/^[a-f0-9]{40}$/), run: evidenceRunSchema, shellSummary: hashedRefSchema, bundle: hashedRefSchema.optional() }).strict();
+const workerRunEvidenceSchema = z.object({ schemaVersion: z.literal(1), status: z.literal("succeeded"), workerRunId: z.string(), businessId: z.string(), featureId: z.string(), reportDecision: z.object({ succeeded: z.literal(true) }).passthrough(), commands: z.array(z.object({ name: z.string(), result: z.object({ ok: z.literal(true) }).passthrough() }).passthrough()).min(1), controllerIdentity: controllerIdentityEvidenceSchema.optional() }).passthrough();
+export async function prepareFeatureDelivery(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const featureDir = path.resolve(input.featureDir);
+    const validation = await validateFeatureTaskGraph(featureDir);
+    const featureId = validation.featureId;
+    const deliveryDir = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "delivery");
+    const artifacts = { manifest: path.join(deliveryDir, "delivery-manifest.json"), coverage: path.join(deliveryDir, "acceptance-coverage.json"), prDraft: path.join(deliveryDir, "PR.md") };
+    const blockers = validation.ok ? [] : validation.errors.map((error) => `${error.code}: ${error.message}`);
+    const now = input.now ?? new Date();
+    const record = await readTransaction(repoRoot, featureId, blockers);
+    if (record) {
+        const branch = await git(repoRoot, ["branch", "--show-current"]).catch(rethrowInfrastructureOr(""));
+        const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(rethrowInfrastructureOr(""));
+        const status = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(rethrowInfrastructureOr("git-error"));
+        if (branch !== record.branch)
+            blockers.push(`current branch must be ${record.branch}`);
+        if (head !== record.lastCheckpoint)
+            blockers.push("HEAD does not match the last Feature checkpoint");
+        if (status.trim())
+            blockers.push("Git worktree must be clean before Delivery");
+        if (!await gitOk(repoRoot, ["merge-base", "--is-ancestor", record.baseCommit, record.lastCheckpoint]))
+            blockers.push("Feature checkpoint history does not descend from the recorded base");
+    }
+    const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+    const states = await readFeatureTaskPoolStates(repoRoot, featureId);
+    const runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    const taskSpecs = new Map();
+    for (const node of graph.nodes)
+        taskSpecs.set(node.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", node.task), "utf-8"))));
+    const qaFact = await canonicalQaEvidence(repoRoot, input.qaEvidencePath, featureId, runs, taskSpecs, now, blockers);
+    const finalFact = record ? await canonicalFinalEvidence(repoRoot, input.finalVerificationPath, featureId, runs, taskSpecs, record, now, blockers) : undefined;
+    if (qaFact?.data.bundle || finalFact?.data.bundle) {
+        if (!qaFact?.data.bundle || !finalFact?.data.bundle || qaFact.data.bundle.path !== finalFact.data.bundle.path || qaFact.data.bundle.sha256 !== finalFact.data.bundle.sha256)
+            blockers.push("QA and final verification do not bind the same Feature Verification Bundle");
+    }
+    if (qaFact && finalFact && qaFact.data.runs.some((entry) => entry.workerRunId === finalFact.data.run.workerRunId))
+        blockers.push("final verification must use a dedicated run not included in the QA aggregate");
+    const qaEvidence = qaFact?.ref;
+    const finalVerification = finalFact?.ref;
+    const waivers = await readWaivers(input.waiverPath, repoRoot, featureId, blockers);
+    const taskRunEvidence = new Map();
+    for (const taskId of new Set(acceptance.acceptance.flatMap((item) => item.verification.expected_task_refs))) {
+        const evidence = await canonicalTaskRunEvidence(repoRoot, featureId, taskId, runs, blockers);
+        if (evidence)
+            taskRunEvidence.set(taskId, evidence);
+    }
+    const coverageItems = acceptance.acceptance.map((ac) => {
+        const blockedBy = ac.verification.expected_task_refs.filter((taskId) => ["Failed", "Blocked"].includes(states[taskId]?.status ?? ""));
+        const allDone = ac.verification.expected_task_refs.every((taskId) => states[taskId]?.status === "Done");
+        const waiver = waivers.items.get(ac.id);
+        const taskEvidence = allDone ? ac.verification.expected_task_refs.map((taskId) => taskRunEvidence.get(taskId)).filter((item) => Boolean(item)) : [];
+        const evidence = qaEvidence && qaFact?.data.acIds.includes(ac.id) && allDone && taskEvidence.length === ac.verification.expected_task_refs.length ? [qaEvidence, ...taskEvidence] : [];
+        return { acId: ac.id, required: ac.priority === "must", status: waiver ? "waived" : blockedBy.length ? "blocked" : allDone && evidence.length ? "covered" : allDone ? "partial" : "missing", evidence, blockedBy, ...(waiver ? { decision: waiver } : {}) };
+    });
+    const coverage = acceptanceCoverageArtifactSchema.parse({ schemaVersion: 1, featureId, ...(waivers.ref ? { waiverSource: waivers.ref } : {}), items: coverageItems });
+    const deliveryTasks = [];
+    if (record)
+        for (const checkpoint of record.checkpoints) {
+            const spec = taskSpecs.get(checkpoint.taskId);
+            if (!spec || !isDevelopmentTask(spec.type))
+                continue;
+            if (!await checkpointMatches(repoRoot, record.lastCheckpoint, checkpoint, spec)) {
+                blockers.push(`checkpoint ${checkpoint.taskId} does not match Git history, trailers, or changed files`);
+                continue;
+            }
+            const run = runs.find((candidate) => candidate.workerRunId === checkpoint.workerRunId && candidate.status === "succeeded" && candidate.taskId === checkpoint.taskId);
+            if (!run?.runRecordPath) {
+                blockers.push(`successful checkpoint ${checkpoint.taskId} is missing canonical run evidence`);
+                continue;
+            }
+            const evidence = await canonicalTaskRunEvidence(repoRoot, featureId, checkpoint.taskId, runs, blockers, checkpoint.workerRunId);
+            if (!evidence)
+                continue;
+            deliveryTasks.push({ taskId: checkpoint.taskId, workerRunId: checkpoint.workerRunId, dagRunId: run.harnessTaskId ?? run.workerRunId, commit: checkpoint.commit, acceptanceRefs: spec.acceptance_refs, verificationEvidence: [evidence], changedFiles: checkpoint.changedFiles });
+        }
+    for (const [taskId, spec] of taskSpecs)
+        if (isDevelopmentTask(spec.type) && states[taskId]?.status === "Done" && !deliveryTasks.some((task) => task.taskId === taskId))
+            blockers.push(`completed development task ${taskId} has no checkpointed Delivery evidence`);
+    const required = coverage.items.filter((item) => item.required);
+    const covered = required.filter((item) => item.status === "covered").length;
+    const waived = required.filter((item) => item.status === "waived").length;
+    const blocked = required.filter((item) => item.status === "blocked").length;
+    if (required.some((item) => !["covered", "waived"].includes(item.status)))
+        blockers.push("required acceptance coverage is incomplete");
+    let manifest;
+    if (record && qaEvidence && finalVerification)
+        manifest = deliveryManifestSchema.parse({ schemaVersion: 1, featureId, branch: record.branch, baseBranch: record.baseBranch, baseSha: record.baseCommit, headSha: record.lastCheckpoint, createdAt: now.toISOString(), tasks: deliveryTasks, qa: { verdict: "passed", evidence: qaEvidence }, finalVerification, acceptanceCoverage: { requiredTotal: required.length, covered, blocked, waived }, riskSummary: { high: 0, medium: waived, low: 0 } });
+    const result = { schemaVersion: 1, status: blockers.length ? "blocked" : input.dryRun ? "ready" : "written", featureId, dryRun: input.dryRun ?? false, blockers, artifacts, ...(manifest ? { manifest } : {}) };
+    if (!input.dryRun && blockers.length === 0 && manifest)
+        await writeDeliveryArtifacts(artifacts, coverage, manifest);
+    return result;
+}
+export async function validateDeliveryPackage(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const featureDir = path.resolve(input.featureDir);
+    const now = input.now ?? new Date();
+    const blockers = [];
+    const validation = await validateFeatureTaskGraph(featureDir);
+    const featureId = validation.featureId;
+    const deliveryDir = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "delivery");
+    let manifest;
+    let coverage;
+    try {
+        manifest = deliveryManifestSchema.parse(JSON.parse(await readFile(path.join(deliveryDir, "delivery-manifest.json"), "utf-8")));
+    }
+    catch (error) {
+        blockers.push(`delivery manifest is invalid: ${message(error)}`);
+    }
+    try {
+        coverage = acceptanceCoverageArtifactSchema.parse(JSON.parse(await readFile(path.join(deliveryDir, "acceptance-coverage.json"), "utf-8")));
+    }
+    catch (error) {
+        blockers.push(`acceptance coverage is invalid: ${message(error)}`);
+    }
+    const record = await readTransaction(repoRoot, featureId, blockers);
+    if (!manifest || !coverage || !record)
+        return { valid: false, blockers };
+    if (manifest.featureId !== featureId || coverage.featureId !== featureId)
+        blockers.push("Delivery Feature ownership mismatch");
+    if (manifest.branch !== record.branch || manifest.baseBranch !== record.baseBranch || manifest.baseSha !== record.baseCommit || manifest.headSha !== record.lastCheckpoint)
+        blockers.push("Delivery manifest does not match the Git transaction");
+    const branch = await git(repoRoot, ["branch", "--show-current"]).catch(rethrowInfrastructureOr(""));
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(rethrowInfrastructureOr(""));
+    if (branch !== record.branch || head !== record.lastCheckpoint)
+        blockers.push("current Git position does not match Delivery");
+    const rawCloseoutStatus = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(rethrowInfrastructureOr("git-error"));
+    const allowedDirtyPaths = new Set((input.allowedDirtyPaths ?? []).map((item) => item.replace(/\\/g, "/")));
+    const closeoutStatus = rawCloseoutStatus.split("\n").filter(Boolean).filter((line) => !allowedDirtyPaths.has(line.slice(3).replace(/\\/g, "/"))).join("\n").trim();
+    if (closeoutStatus)
+        blockers.push(`Git worktree is not clean for Closeout: ${closeoutStatus}`);
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+    const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
+    const states = await readFeatureTaskPoolStates(repoRoot, featureId);
+    const specs = new Map();
+    for (const node of graph.nodes)
+        specs.set(node.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", node.task), "utf-8"))));
+    const runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    for (const task of manifest.tasks) {
+        const checkpoint = record.checkpoints.find((entry) => entry.taskId === task.taskId && entry.workerRunId === task.workerRunId && entry.commit === task.commit);
+        const spec = specs.get(task.taskId);
+        if (!checkpoint || !spec || JSON.stringify([...task.acceptanceRefs].sort()) !== JSON.stringify([...(spec?.acceptance_refs ?? [])].sort()) || JSON.stringify([...task.changedFiles].sort()) !== JSON.stringify([...checkpoint.changedFiles].sort()) || !await checkpointMatches(repoRoot, record.lastCheckpoint, checkpoint, spec))
+            blockers.push(`Delivery task ${task.taskId} does not match its checkpoint`);
+        const canonical = await canonicalTaskRunEvidence(repoRoot, featureId, task.taskId, runs, blockers, task.workerRunId);
+        if (!canonical || !task.verificationEvidence.some((ref) => ref.path === canonical.path && ref.sha256 === canonical.sha256))
+            blockers.push(`Delivery task evidence is not canonical: ${task.taskId}`);
+    }
+    const expectedDevTasks = [...specs.values()].filter((spec) => isDevelopmentTask(spec.type) && states[spec.id]?.status === "Done").map((spec) => spec.id).sort();
+    if (JSON.stringify(expectedDevTasks) !== JSON.stringify(manifest.tasks.map((task) => task.taskId).sort()))
+        blockers.push("Delivery manifest does not contain exactly the completed development tasks");
+    const qa = await canonicalQaEvidence(repoRoot, manifest.qa.evidence.path, featureId, runs, specs, now, blockers);
+    if (!qa || qa.ref.sha256 !== manifest.qa.evidence.sha256)
+        blockers.push("QA evidence hash or semantics changed");
+    const final = await canonicalFinalEvidence(repoRoot, manifest.finalVerification.path, featureId, runs, specs, record, now, blockers);
+    if (!final || final.ref.sha256 !== manifest.finalVerification.sha256)
+        blockers.push("final verification hash or semantics changed");
+    if (qa && final && qa.data.runs.some((entry) => entry.workerRunId === final.data.run.workerRunId))
+        blockers.push("final verification run is not dedicated");
+    const required = coverage.items.filter((item) => item.required);
+    const counts = { requiredTotal: required.length, covered: required.filter((item) => item.status === "covered").length, blocked: required.filter((item) => item.status === "blocked").length, waived: required.filter((item) => item.status === "waived").length };
+    if (JSON.stringify(counts) !== JSON.stringify(manifest.acceptanceCoverage) || required.some((item) => !["covered", "waived"].includes(item.status)))
+        blockers.push("Delivery acceptance coverage no longer matches the manifest");
+    const coverageById = new Map(coverage.items.map((item) => [item.acId, item]));
+    if (coverageById.size !== coverage.items.length || coverage.items.length !== acceptance.acceptance.length)
+        blockers.push("Acceptance coverage item set does not match AcceptanceSpec");
+    const canonicalWaivers = new Map();
+    if (coverage.waiverSource) {
+        if (!await hashedRefValid(repoRoot, coverage.waiverSource))
+            blockers.push("waiver source hash changed");
+        else
+            try {
+                const raw = waiverSchema.parse(JSON.parse(await readFile(await safeRepoPath(repoRoot, coverage.waiverSource.path), "utf-8")));
+                if (raw.featureId !== featureId)
+                    throw new Error("Feature mismatch");
+                for (const item of raw.items)
+                    canonicalWaivers.set(item.acId, { owner: item.owner, reason: item.reason, decidedAt: item.decidedAt });
+            }
+            catch (error) {
+                blockers.push(`waiver source is invalid: ${message(error)}`);
+            }
+    }
+    for (const ac of acceptance.acceptance) {
+        const item = coverageById.get(ac.id);
+        if (!item) {
+            blockers.push(`Acceptance coverage is missing ${ac.id}`);
+            continue;
+        }
+        if (item.required !== (ac.priority === "must"))
+            blockers.push(`Acceptance required flag changed: ${ac.id}`);
+        const blockedBy = ac.verification.expected_task_refs.filter((taskId) => ["Failed", "Blocked"].includes(states[taskId]?.status ?? ""));
+        const allDone = ac.verification.expected_task_refs.every((taskId) => states[taskId]?.status === "Done");
+        const expectedRefs = [];
+        for (const taskId of ac.verification.expected_task_refs) {
+            const ref = await canonicalTaskRunEvidence(repoRoot, featureId, taskId, runs, blockers);
+            if (ref)
+                expectedRefs.push(ref);
+        }
+        const waiver = canonicalWaivers.get(ac.id);
+        const waiverMatches = Boolean(waiver && item.decision && JSON.stringify(waiver) === JSON.stringify(item.decision));
+        const expectedStatus = waiverMatches ? "waived" : blockedBy.length ? "blocked" : allDone && expectedRefs.length === ac.verification.expected_task_refs.length && qa?.data.acIds.includes(ac.id) ? "covered" : allDone ? "partial" : "missing";
+        if (item.status !== expectedStatus)
+            blockers.push(`Acceptance coverage status is not derivable: ${ac.id}`);
+        if (JSON.stringify([...item.blockedBy].sort()) !== JSON.stringify([...blockedBy].sort()))
+            blockers.push(`Acceptance blockers changed: ${ac.id}`);
+        // partial / missing / blocked should-ACs intentionally omit full evidence lists
+        // (only must ACs covered by QA require run+QA hash binding).
+        if (expectedStatus === "covered") {
+            for (const ref of expectedRefs)
+                if (!item.evidence.some((candidate) => candidate.path === ref.path && candidate.sha256 === ref.sha256))
+                    blockers.push(`Acceptance run evidence is missing: ${ac.id}`);
+            if (qa?.data.acIds.includes(ac.id) && !item.evidence.some((candidate) => candidate.path === qa.ref.path && candidate.sha256 === qa.ref.sha256))
+                blockers.push(`Acceptance QA evidence is missing: ${ac.id}`);
+        }
+        for (const ref of item.evidence)
+            if (!await hashedRefValid(repoRoot, ref))
+                blockers.push(`Acceptance evidence changed: ${item.acId}`);
+    }
+    const age = now.getTime() - new Date(manifest.createdAt).getTime();
+    if (age < 0 || age > 24 * 60 * 60 * 1000)
+        blockers.push("Delivery manifest is not fresh within 24 hours");
+    return { valid: blockers.length === 0, blockers, manifest };
+}
+function isDevelopmentTask(type) { return !type.startsWith("qa-") && !["architecture", "review"].includes(type); }
+async function readTransaction(repoRoot, featureId, blockers) { try {
+    return gitTransactionRecordSchema.parse(JSON.parse(await readFile(transactionRecordPath(repoRoot, featureId), "utf-8")));
+}
+catch {
+    blockers.push("Feature Git transaction record is missing or invalid");
+    return undefined;
+} }
+async function readWaivers(filePath, repoRoot, featureId, blockers) {
+    const items = new Map();
+    if (!filePath)
+        return { items };
+    const ref = await hashedRepoRef(repoRoot, filePath, blockers, "waiver artifact");
+    if (!ref)
+        return { items };
+    try {
+        const parsed = waiverSchema.parse(JSON.parse(await readFile(await safeRepoPath(repoRoot, filePath), "utf-8")));
+        if (parsed.featureId !== featureId)
+            throw new Error("Feature mismatch");
+        for (const item of parsed.items)
+            items.set(item.acId, { owner: item.owner, reason: item.reason, decidedAt: item.decidedAt });
+        return { items, ref };
+    }
+    catch (error) {
+        blockers.push(`waiver artifact is invalid: ${message(error)}`);
+        return { items };
+    }
+}
+async function hashedRepoRef(repoRoot, ref, blockers, label) { try {
+    const absolute = await safeRepoPath(repoRoot, ref);
+    const content = await readFile(absolute);
+    return { path: path.relative(await realpath(repoRoot), absolute).replace(/\\/g, "/"), sha256: createHash("sha256").update(content).digest("hex") };
+}
+catch (error) {
+    blockers.push(`${label} is missing or unsafe: ${message(error)}`);
+    return undefined;
+} }
+async function safeRepoPath(repoRoot, ref) { const canonicalRepo = await realpath(repoRoot); const lexical = path.isAbsolute(ref) ? path.resolve(ref) : path.resolve(repoRoot, ref); const absolute = await realpath(lexical); const relative = path.relative(canonicalRepo, absolute); if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+    throw new Error("path escapes repo"); return absolute; }
+async function canonicalQaEvidence(repoRoot, ref, featureId, runs, specs, now, blockers) {
+    const hashed = await hashedRepoRef(repoRoot, ref, blockers, "QA evidence");
+    if (!hashed)
+        return undefined;
+    try {
+        const data = qaEvidenceSchema.parse(JSON.parse(await readFile(await safeRepoPath(repoRoot, ref), "utf-8")));
+        if (data.featureId !== featureId)
+            throw new Error("Feature ownership mismatch");
+        const bundle = data.bundle ? await readVerifiedBundle({ repoRoot, ref: data.bundle }) : undefined;
+        if (data.bundle && (!bundle || bundle.featureId !== featureId || !await verifyBundleOutcomes(repoRoot, bundle) || !verifyBundleTaskSpecBindings(bundle, specs) || !await verifyBundleCurrentStateBindings(repoRoot, bundle)))
+            throw new Error("Feature Verification Bundle is missing, changed, has invalid typed outcomes, no longer matches TaskSpecs, or no longer matches current Task Pool state");
+        const typedByRun = new Map((bundle ? [...bundle.backendTests, ...bundle.frontendTests] : []).map((entry) => [entry.workerRunId, entry]));
+        for (const entry of data.runs) {
+            const run = assertEvidenceRun(entry, featureId, runs, specs, now, !bundle);
+            if (bundle) {
+                const typed = typedByRun.get(entry.workerRunId);
+                if (!typed || typed.taskId !== entry.taskId || run.workflow !== typed.workflow)
+                    throw new Error(`QA bundle run is not a declared typed outcome: ${entry.workerRunId}`);
+            }
+            await readCanonicalWorkerRun(repoRoot, run);
+        }
+        const allowedAcIds = bundle ? new Set(bundle.acceptance.filter((item) => item.status === "covered").map((item) => item.acId)) : new Set(data.runs.flatMap((entry) => specs.get(entry.taskId)?.acceptance_refs ?? []));
+        for (const acId of data.acIds)
+            if (!allowedAcIds.has(acId))
+                throw new Error(`QA run scope does not cover ${acId}`);
+        return { data, ref: hashed };
+    }
+    catch (error) {
+        blockers.push(`QA evidence is not canonical: ${message(error)}`);
+        return undefined;
+    }
+}
+async function canonicalFinalEvidence(repoRoot, ref, featureId, runs, specs, record, now, blockers) {
+    const hashed = await hashedRepoRef(repoRoot, ref, blockers, "final verification");
+    if (!hashed)
+        return undefined;
+    try {
+        const data = finalVerificationSchema.parse(JSON.parse(await readFile(await safeRepoPath(repoRoot, ref), "utf-8")));
+        if (data.featureId !== featureId)
+            throw new Error("Feature ownership mismatch");
+        if (data.bundle) {
+            const bundle = await readVerifiedBundle({ repoRoot, ref: data.bundle });
+            if (!bundle || bundle.featureId !== featureId || bundle.headSha !== record.lastCheckpoint || !await verifyBundleOutcomes(repoRoot, bundle) || !verifyBundleTaskSpecBindings(bundle, specs) || !await verifyBundleCurrentStateBindings(repoRoot, bundle))
+                throw new Error("Feature Verification Bundle is missing, changed, does not bind the Delivery HEAD, no longer matches TaskSpecs, or no longer matches current Task Pool state");
+        }
+        const taskPoolRun = assertEvidenceRun(data.run, featureId, runs, specs, now, true);
+        if (data.headSha !== record.lastCheckpoint)
+            throw new Error("final verification is not bound to Delivery HEAD");
+        const latestCheckpointAt = Math.max(...record.checkpoints.map((entry) => new Date(entry.createdAt).getTime()));
+        if (new Date(data.run.recordedAt).getTime() < latestCheckpointAt)
+            throw new Error("final verification predates the last checkpoint");
+        const runRecord = await readCanonicalWorkerRun(repoRoot, taskPoolRun);
+        if (!runRecord.commands.some((command) => command.name === "run-dag"))
+            throw new Error("final verification run is missing a successful run-dag command");
+        const spec = specs.get(data.run.taskId);
+        const requiredCommands = spec.verify.commands.filter((command) => command.required);
+        if (requiredCommands.length === 0)
+            throw new Error("final verification TaskSpec has no required commands");
+        const expectedSummaryPath = path.join(".harness", "dag-runs", "completed", data.run.workerRunId, "verify-shell", "result.summary.md").replace(/\\/g, "/");
+        if (data.shellSummary.path !== expectedSummaryPath || !await hashedRefValid(repoRoot, data.shellSummary))
+            throw new Error("final verification shell summary is missing or changed");
+        const summary = await readFile(await safeRepoPath(repoRoot, data.shellSummary.path), "utf-8");
+        for (const required of requiredCommands) {
+            const escaped = required.command.replace(/\|/g, "\\|");
+            if (!summary.split(/\r?\n/).some((line) => line.includes("| true | 0 | success |") && (line.endsWith(`| ${escaped} |`) || line.endsWith(`'${escaped}' |`))))
+                throw new Error(`final verification command evidence is missing: ${required.id}`);
+        }
+        return { data, ref: hashed };
+    }
+    catch (error) {
+        blockers.push(`final verification is not canonical: ${message(error)}`);
+        return undefined;
+    }
+}
+function assertEvidenceRun(entry, featureId, runs, specs, now, requireQa) {
+    const run = runs.find((candidate) => candidate.featureId === featureId && candidate.taskId === entry.taskId && candidate.workerRunId === entry.workerRunId && candidate.status === "succeeded");
+    if (!run || run.recordedAt !== entry.recordedAt)
+        throw new Error(`successful run ownership/time mismatch: ${entry.workerRunId}`);
+    if (requireQa && specs.get(entry.taskId)?.type !== "qa-execute")
+        throw new Error(`run is not a qa-execute task: ${entry.taskId}`);
+    const age = now.getTime() - new Date(run.recordedAt).getTime();
+    if (age < 0 || age > 24 * 60 * 60 * 1000)
+        throw new Error(`run is not fresh within 24 hours: ${entry.workerRunId}`);
+    assertControllerIdentityPair(entry.controllerIdentity, run.controllerIdentity, "evidence and Task Pool run");
+    return run;
+}
+async function canonicalTaskRunEvidence(repoRoot, featureId, taskId, runs, blockers, workerRunId) {
+    const run = [...runs].reverse().find((candidate) => candidate.featureId === featureId && candidate.taskId === taskId && candidate.status === "succeeded" && candidate.runRecordPath && (!workerRunId || candidate.workerRunId === workerRunId));
+    if (!run?.runRecordPath)
+        return undefined;
+    const hashed = await hashedRepoRef(repoRoot, run.runRecordPath, blockers, `${taskId} run evidence`);
+    if (!hashed)
+        return undefined;
+    try {
+        await readCanonicalWorkerRun(repoRoot, run);
+        return hashed;
+    }
+    catch (error) {
+        blockers.push(`${taskId} run evidence is not canonical: ${message(error)}`);
+        return undefined;
+    }
+}
+async function readCanonicalWorkerRun(repoRoot, run) {
+    if (!run?.runRecordPath)
+        throw new Error("Task Pool run record path is missing");
+    const record = workerRunEvidenceSchema.parse(JSON.parse(await readFile(await safeRepoPath(repoRoot, run.runRecordPath), "utf-8")));
+    if (record.featureId !== run.featureId || record.businessId !== run.taskId || record.workerRunId !== run.workerRunId)
+        throw new Error("run record ownership mismatch");
+    assertControllerIdentityPair(run.controllerIdentity, record.controllerIdentity, "Task Pool run and worker run record");
+    return record;
+}
+function assertControllerIdentityPair(left, right, label) {
+    if (left === undefined && right === undefined)
+        return;
+    if (left === undefined || right === undefined)
+        throw new Error(`controller identity presence mismatch between ${label}`);
+    const parsedLeft = controllerIdentityEvidenceSchema.parse(left);
+    const parsedRight = controllerIdentityEvidenceSchema.parse(right);
+    if (!controllerIdentitiesMatch(parsedLeft, parsedRight))
+        throw new Error(`controller identity mismatch between ${label}`);
+}
+async function writeDeliveryArtifacts(artifacts, coverage, manifest) {
+    const deliveryDir = path.dirname(artifacts.manifest);
+    const parent = path.dirname(deliveryDir);
+    const staging = path.join(parent, `.delivery.${randomUUID()}.staging`);
+    const backup = path.join(parent, `.delivery.${randomUUID()}.backup`);
+    await mkdir(staging, { recursive: true });
+    await writeFile(path.join(staging, "acceptance-coverage.json"), `${JSON.stringify(coverage, null, 2)}\n`);
+    await writeFile(path.join(staging, "delivery-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    await writeFile(path.join(staging, "PR.md"), renderPr(manifest));
+    let backedUp = false;
+    try {
+        try {
+            await rename(deliveryDir, backup);
+            backedUp = true;
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+        }
+        await rename(staging, deliveryDir);
+        if (backedUp)
+            await rm(backup, { recursive: true, force: true });
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        if (backedUp) {
+            await rm(deliveryDir, { recursive: true, force: true });
+            await rename(backup, deliveryDir);
+        }
+        throw error;
+    }
+}
+function renderPr(manifest) { return `# Summary\n\nFeature ${manifest.featureId} local Delivery Package.\n\n## Feature/base/head\n\n- Branch: ${manifest.branch}\n- Base: ${manifest.baseBranch} @ ${manifest.baseSha}\n- Head: ${manifest.headSha}\n\n## Completed Tasks\n\n${manifest.tasks.map((task) => `- ${task.taskId}: ${task.commit} (${task.changedFiles.join(", ")})`).join("\n")}\n\n## Acceptance Coverage\n\n- Required: ${manifest.acceptanceCoverage.requiredTotal}\n- Covered: ${manifest.acceptanceCoverage.covered}\n- Waived: ${manifest.acceptanceCoverage.waived}\n- Blocked: ${manifest.acceptanceCoverage.blocked}\n\n## Verification\n\n- QA: ${manifest.qa.evidence.path}\n- Final: ${manifest.finalVerification.path}\n\n## Changed Files\n\n${[...new Set(manifest.tasks.flatMap((task) => task.changedFiles))].map((file) => `- ${file}`).join("\n")}\n\n## Risks\n\n- high=${manifest.riskSummary.high}, medium=${manifest.riskSummary.medium}, low=${manifest.riskSummary.low}\n\n## Human Review Checklist\n\n- [ ] Review diff and commits\n- [ ] Confirm required AC coverage and waivers\n- [ ] Confirm QA and final verification evidence\n- [ ] Review risks\n- [ ] Decide whether to push or create a remote PR manually\n`; }
+async function git(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    if (result.code !== 0)
+        throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result.stdout.trim();
+}
+async function gitRaw(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    if (result.code !== 0)
+        throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result.stdout;
+}
+async function gitOk(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    return result.code === 0;
+}
+function rethrowInfrastructureOr(fallback) {
+    return (error) => {
+        if (isResilientGitCommandError(error))
+            throw error;
+        return fallback;
+    };
+}
+async function checkpointMatches(repoRoot, head, checkpoint, spec) {
+    if (!await gitOk(repoRoot, ["merge-base", "--is-ancestor", checkpoint.commit, head]))
+        return false;
+    const messageText = await gitRaw(repoRoot, ["show", "-s", "--format=%B", checkpoint.commit]).catch(rethrowInfrastructureOr(""));
+    for (const trailer of [`Feature: ${spec.feature_id}`, `Task: ${spec.id}`, `Acceptance: ${spec.acceptance_refs.join(", ")}`, `Worker-Run: ${checkpoint.workerRunId}`])
+        if (!messageText.split(/\r?\n/).includes(trailer))
+            return false;
+    const actual = (await gitRaw(repoRoot, ["diff-tree", "--no-commit-id", "--name-only", "-r", checkpoint.commit]).catch(rethrowInfrastructureOr(""))).split(/\r?\n/).filter(Boolean).sort();
+    return JSON.stringify(actual) === JSON.stringify([...checkpoint.changedFiles].sort());
+}
+async function hashedRefValid(repoRoot, ref) { try {
+    const content = await readFile(await safeRepoPath(repoRoot, ref.path));
+    return createHash("sha256").update(content).digest("hex") === ref.sha256;
+}
+catch {
+    return false;
+} }
+function message(error) { return error instanceof Error ? error.message : String(error); }
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }