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

package/dist/worker/delivery/final-verification.js

@@ -0,0 +1,302 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runResilientGitCommand } from "../../shared/resilient-git.js";
+import YAML from "yaml";
+import { controllerIdentitiesMatch, controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.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 { getRunsJsonlPath, getTaskPoolRoot, readFeatureTaskPoolStates, readJsonlFile, recordTaskPoolRun } from "../pool/run-store.js";
+import { readVerifiedOutcome } from "../outcomes/store.js";
+import { buildWorkerRunId, runTaskSpec } from "../run-task/run-task.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { preflightTargetRepo } from "../preflight.js";
+import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
+import { buildFeatureVerificationBundle, writeFeatureVerificationBundle, } from "./verification-bundle.js";
+/**
+ * Canonical Delivery evidence locations written by `feature verify-final`
+ * (ADR 0007). Paths are repo-relative with forward slashes.
+ */
+export function defaultFeatureEvidencePaths(featureId) {
+    const base = `.harness/task-pool/evidence/${featureId}`;
+    return {
+        qaEvidencePath: `${base}/qa-pass.json`,
+        finalVerificationPath: `${base}/final-verification.json`,
+        bundleEvidencePath: `${base}/feature-verification-bundle.json`,
+    };
+}
+export async function runFeatureFinalVerification(input) {
+    const dependencies = {
+        preflight: preflightTargetRepo,
+        runTask: runTaskSpec,
+        git,
+        gitRaw,
+        ...input.dependencies,
+    };
+    let controllerIdentity = resolveControllerIdentity(input.client, input.controllerIdentity);
+    const identityFailure = controllerIdentityExpectationFailure(controllerIdentity, input.controllerExpectation);
+    if (identityFailure) {
+        throw new Error(`${identityFailure.code}: ${identityFailure.message}`);
+    }
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    const featureDir = await realpath(path.resolve(input.featureDir));
+    const relativeFeature = path.relative(repoRoot, featureDir);
+    if (!relativeFeature || relativeFeature.startsWith("..") || path.isAbsolute(relativeFeature))
+        throw new Error("Feature Packet must be inside the target repo");
+    const validation = await validateFeatureTaskGraph(featureDir);
+    if (!validation.ok)
+        throw new Error(`Feature Packet is invalid: ${validation.errors.map((error) => error.code).join(", ")}`);
+    const featureId = validation.featureId;
+    const preflight = await dependencies.preflight({
+        repoRoot,
+        client: input.client,
+        ...(input.controllerExpectation ? { expectation: input.controllerExpectation } : {}),
+    });
+    if (!preflight.ok) {
+        throw new Error(`target repo preflight failed: ${preflight.code}: ${preflight.message}`);
+    }
+    controllerIdentity = preflight.controllerIdentity ?? controllerIdentity;
+    const record = gitTransactionRecordSchema.parse(JSON.parse(await readFile(transactionRecordPath(repoRoot, featureId), "utf-8")));
+    const branch = await dependencies.git(repoRoot, ["branch", "--show-current"]);
+    const headSha = await dependencies.git(repoRoot, ["rev-parse", "HEAD"]);
+    const status = await dependencies.gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (branch !== record.branch || headSha !== record.lastCheckpoint)
+        throw new Error("final verification requires the recorded Feature branch at lastCheckpoint");
+    if (status.trim())
+        throw new Error(`final verification requires a clean worktree:\n${status.trim()}`);
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+    const node = graph.nodes.find((candidate) => candidate.id === input.taskId);
+    if (!node)
+        throw new Error(`final verification task is not in the Feature graph: ${input.taskId}`);
+    const taskSpecPath = path.join(featureDir, "tasks", node.task);
+    const taskSpec = taskSpecSchema.parse(YAML.parse(await readFile(taskSpecPath, "utf-8")));
+    if (taskSpec.type !== "qa-execute")
+        throw new Error(`final verification requires a qa-execute TaskSpec: ${input.taskId}`);
+    if (taskSpec.verify.commands.filter((command) => command.required).length === 0)
+        throw new Error("final verification TaskSpec has no required commands");
+    const verificationTaskSpec = {
+        ...taskSpec,
+        constraints: {
+            ...taskSpec.constraints,
+            allowed_paths: [],
+            hard_constraints: [...taskSpec.constraints.hard_constraints, "Dedicated final verification is read-only; do not modify repository files"],
+        },
+    };
+    const now = input.now ?? new Date();
+    let runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    let finalRun = await reusableFinalRun(repoRoot, runs, taskSpec.id, featureId, record, now, controllerIdentity);
+    if (!finalRun) {
+        const workerRunId = buildWorkerRunId(`${input.taskId}-final`, now);
+        const result = await dependencies.runTask({
+            repoRoot,
+            taskSpec: verificationTaskSpec,
+            taskSpecPath,
+            client: input.client,
+            now,
+            workerRunId,
+            skipSuccessFinalization: true,
+            preflight: false,
+            ...(controllerIdentity ? { controllerIdentity } : {}),
+            ...(input.controllerExpectation ? { controllerExpectation: input.controllerExpectation } : {}),
+        });
+        if (result.status !== "succeeded")
+            throw new Error(`dedicated final verification failed: ${workerRunId}`);
+        const afterHead = await dependencies.git(repoRoot, ["rev-parse", "HEAD"]);
+        const afterStatus = await dependencies.gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (afterHead !== headSha || afterStatus.trim())
+            throw new Error("dedicated final verification changed the Delivery HEAD or worktree");
+        finalRun = { schemaVersion: 1, batchRunId: `final-verification-${workerRunId}`, workerRunId, taskId: taskSpec.id, featureId, status: "succeeded", harnessTaskId: result.harnessTaskId, runRecordPath: result.runRecordPath, dagPath: result.dagPath, recordedAt: now.toISOString(), ...(controllerIdentity ? { controllerIdentity } : {}) };
+        await recordTaskPoolRun({ repoRoot, run: finalRun });
+        runs = [...runs, finalRun];
+    }
+    const allSpecs = new Map();
+    for (const graphNode of graph.nodes) {
+        allSpecs.set(graphNode.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", graphNode.task), "utf-8"))));
+    }
+    const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
+    const requiredAcIds = acceptance.acceptance.filter((item) => item.priority === "must").map((item) => item.id);
+    const states = await readFeatureTaskPoolStates(repoRoot, featureId);
+    for (const [taskId, spec] of allSpecs) {
+        if ((spec.execution?.workflow === "backend-test" || spec.execution?.workflow === "frontend-test") && ["Failed", "Blocked"].includes(states[taskId]?.status ?? "")) {
+            throw new Error(`final verification has an unresolved typed test task: ${taskId}`);
+        }
+    }
+    const evidenceMode = input.evidenceMode ?? "auto";
+    let bundleRef;
+    let bundlePayload;
+    let qaRuns = latestSuccessfulQaRuns(runs, allSpecs, taskSpec.id, featureId);
+    let coveredAcIds = [...new Set(qaRuns.flatMap((run) => allSpecs.get(run.taskId)?.acceptance_refs ?? []))];
+    const typedCapable = requiredAcIds.length > 0 && requiredAcIds.every((acId) => {
+        const item = acceptance.acceptance.find((candidate) => candidate.id === acId);
+        const refs = item?.verification.verification_task_refs ?? [];
+        return refs.length > 0 && refs.every((taskId) => {
+            const workflow = allSpecs.get(taskId)?.execution?.workflow;
+            return workflow === "backend-test" || workflow === "frontend-test";
+        });
+    });
+    if (evidenceMode === "qa-execute" && !qaRuns.length) {
+        throw new Error("evidence-mode qa-execute requires at least one successful qa-execute run");
+    }
+    if ((evidenceMode === "auto" && typedCapable) || evidenceMode === "typed") {
+        const typedRuns = selectCurrentTypedVerificationRuns({
+            featureId,
+            acceptance: acceptance.acceptance,
+            specs: allSpecs,
+            states,
+            runs,
+        });
+        const outcomes = new Map();
+        for (const run of typedRuns) {
+            const outcome = await readVerifiedOutcome({ repoRoot, workerRunId: run.workerRunId, outcomePath: run.outcomePath, outcomeSha256: run.outcomeSha256 });
+            if (outcome)
+                outcomes.set(run.workerRunId, outcome);
+        }
+        const bundle = buildFeatureVerificationBundle({
+            featureId,
+            headSha,
+            runs: typedRuns,
+            specs: allSpecs,
+            outcomes,
+            acceptance: acceptance.acceptance,
+            implementationTaskIds: new Set(acceptance.acceptance.flatMap((item) => item.verification.implementation_task_refs ?? []).filter((taskId) => states[taskId]?.status === "Done")),
+            controllerIdentity,
+        });
+        bundleRef = await writeFeatureVerificationBundle(repoRoot, bundle);
+        bundlePayload = bundle;
+        qaRuns = typedRuns;
+        coveredAcIds = bundle.acceptance.filter((item) => item.status === "covered").map((item) => item.acId);
+    }
+    if (qaRuns.length === 0)
+        throw new Error("no prior successful typed test or qa-execute runs are available for the QA aggregate");
+    for (const acId of requiredAcIds)
+        if (!coveredAcIds.includes(acId))
+            throw new Error(`QA aggregate does not cover required acceptance: ${acId}`);
+    const summaryRelative = path.join(".harness", "dag-runs", "completed", finalRun.workerRunId, "verify-shell", "result.summary.md").replace(/\\/g, "/");
+    const summaryAbsolute = path.join(repoRoot, ...summaryRelative.split("/"));
+    const summary = await readFile(summaryAbsolute);
+    const evidenceDir = path.join(getTaskPoolRoot(repoRoot), "evidence", featureId);
+    const qaEvidencePath = path.join(evidenceDir, "qa-pass.json");
+    const finalVerificationPath = path.join(evidenceDir, "final-verification.json");
+    await writeEvidencePairAtomic(evidenceDir, {
+        qa: { schemaVersion: 1, featureId, verdict: "passed", acIds: requiredAcIds, runs: qaRuns.map(runRef), ...(bundleRef ? { bundle: bundleRef } : {}) },
+        final: { schemaVersion: 1, featureId, kind: "final-verification", status: "passed", headSha, run: runRef(finalRun), shellSummary: { path: summaryRelative, sha256: createHash("sha256").update(summary).digest("hex") }, ...(bundleRef ? { bundle: bundleRef } : {}) },
+        ...(bundlePayload ? { bundle: bundlePayload } : {}),
+    });
+    return { schemaVersion: 1, featureId, taskId: taskSpec.id, workerRunId: finalRun.workerRunId, headSha, qaEvidencePath: repoRef(repoRoot, qaEvidencePath), finalVerificationPath: repoRef(repoRoot, finalVerificationPath), qaRunCount: qaRuns.length, ...(bundleRef ? { bundleEvidencePath: bundleRef.path, bundleSha256: bundleRef.sha256, evidenceMode: "typed" } : { evidenceMode: "qa-execute" }), ...(controllerIdentity ? { controllerIdentity } : {}) };
+}
+export function latestSuccessfulQaRuns(runs, specs, excludedTaskId, featureId) {
+    const byTask = new Map();
+    for (const run of runs)
+        if (run.featureId === featureId && run.status === "succeeded" && run.taskId !== excludedTaskId && specs.get(run.taskId)?.type === "qa-execute")
+            byTask.set(run.taskId, run);
+    return [...byTask.values()].sort((a, b) => a.taskId.localeCompare(b.taskId));
+}
+/**
+ * Typed verification is bound to the canonical Feature-scoped Task Pool state,
+ * never to an arbitrary historical success in runs.jsonl. Each required AC
+ * verification task must be Done and identify exactly one succeeded run.
+ */
+function selectCurrentTypedVerificationRuns(input) {
+    const requiredTaskIds = [
+        ...new Set(input.acceptance.flatMap((item) => item.verification.verification_task_refs ?? [])),
+    ];
+    const selected = [];
+    for (const taskId of requiredTaskIds) {
+        const spec = input.specs.get(taskId);
+        const workflow = spec?.execution?.workflow;
+        if (workflow !== "backend-test" && workflow !== "frontend-test") {
+            throw new Error(`typed verification TaskSpec is not a typed test: ${taskId}`);
+        }
+        const state = input.states[taskId];
+        if (state?.status !== "Done" || !state.workerRunId) {
+            throw new Error(`required typed verification task is not Done: ${taskId}`);
+        }
+        const matches = input.runs.filter((run) => run.featureId === input.featureId &&
+            run.taskId === taskId &&
+            run.workerRunId === state.workerRunId);
+        if (matches.length !== 1) {
+            throw new Error(`current Task Pool run is missing or ambiguous: ${taskId}`);
+        }
+        const run = matches[0];
+        if (run.status !== "succeeded" || run.workflow !== workflow) {
+            throw new Error(`current Task Pool run is not a succeeded typed test: ${taskId}`);
+        }
+        selected.push(run);
+    }
+    return selected;
+}
+async function reusableFinalRun(repoRoot, runs, taskId, featureId, record, now, controllerIdentity) {
+    const latestCheckpointAt = Math.max(...record.checkpoints.map((entry) => new Date(entry.createdAt).getTime()));
+    for (const run of [...runs].reverse()) {
+        if (run.taskId !== taskId || run.featureId !== featureId || run.status !== "succeeded" || !run.workerRunId.includes("-final-") || !run.runRecordPath)
+            continue;
+        if (controllerIdentity && !controllerIdentitiesMatch(run.controllerIdentity, controllerIdentity))
+            continue;
+        const recordedAt = new Date(run.recordedAt).getTime();
+        if (recordedAt < latestCheckpointAt || now.getTime() - recordedAt > 24 * 60 * 60 * 1000)
+            continue;
+        try {
+            const canonical = JSON.parse(await readFile(run.runRecordPath, "utf-8"));
+            if (canonical.workerRunId !== run.workerRunId || canonical.businessId !== taskId || canonical.featureId !== featureId || canonical.status !== "succeeded")
+                continue;
+            await readFile(path.join(repoRoot, ".harness", "dag-runs", "completed", run.workerRunId, "verify-shell", "result.summary.md"));
+            return run;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+function runRef(run) { return { taskId: run.taskId, workerRunId: run.workerRunId, recordedAt: run.recordedAt, ...(run.controllerIdentity ? { controllerIdentity: run.controllerIdentity } : {}) }; }
+function repoRef(repoRoot, absolute) { return path.relative(repoRoot, absolute).replace(/\\/g, "/"); }
+export async function writeEvidencePairAtomic(evidenceDir, value, fs = { rm }) {
+    const parent = path.dirname(evidenceDir);
+    const staging = path.join(parent, `.evidence.${randomUUID()}.staging`);
+    const backup = path.join(parent, `.evidence.${randomUUID()}.backup`);
+    await mkdir(staging, { recursive: true });
+    await writeFile(path.join(staging, "qa-pass.json"), `${JSON.stringify(value.qa, null, 2)}\n`);
+    await writeFile(path.join(staging, "final-verification.json"), `${JSON.stringify(value.final, null, 2)}\n`);
+    if (value.bundle)
+        await writeFile(path.join(staging, "feature-verification-bundle.json"), `${JSON.stringify(value.bundle, null, 2)}\n`);
+    let backedUp = false;
+    try {
+        await rename(evidenceDir, backup);
+        backedUp = true;
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    let installed = false;
+    try {
+        await rename(staging, evidenceDir);
+        installed = true;
+    }
+    catch (error) {
+        if (installed)
+            await fs.rm(evidenceDir, { recursive: true, force: true }).catch(() => { });
+        if (backedUp)
+            await rename(backup, evidenceDir).catch(() => { });
+        throw error;
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true }).catch(() => { });
+    }
+    if (backedUp)
+        await fs.rm(backup, { recursive: true, force: true }).catch(() => { });
+}
+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;
+}
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }