@tea-agent/loop-agent 0.8.0 → 0.10.0

package/dist/worker/cli.js

@@ -17,6 +17,15 @@ import { getTaskPoolRoot, prepareTaskPoolRetry } from "./pool/run-store.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 import { validateFeatureTaskGraph } from "./task-graph/validate.js";
+import { renderFeatureReview, reviewFeature } from "./feature/review.js";
+import { renderFeatureRun, runFeature } from "./feature/run.js";
+import { draftFollowUpDecision } from "./follow-up/factory.js";
+import { approveFollowUp } from "./follow-up/approve.js";
+import { prepareFeatureDelivery } from "./delivery/package.js";
+import { previewFeatureCloseout, renderCloseoutPreview } from "./closeout/preview.js";
+import { applyFeatureCloseout } from "./closeout/apply.js";
+import { projectMonthlyMetrics } from "./metrics/projector.js";
+import { runFeatureFinalVerification } from "./delivery/final-verification.js";
 export function buildAgentWorkerProgram() {
     const program = new Command();
     program
@@ -28,6 +37,129 @@ export function buildAgentWorkerProgram() {
     const batch = program.command("batch").description("Task Pool batch utilities");
     const report = program.command("report").description("Task Pool reporting utilities");
     const observe = program.command("observe").description("Observe UI server and snapshot utilities");
+    const feature = program.command("feature").description("Feature-level review and delivery workflow");
+    feature
+        .command("review")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .description("Derive Feature status, blockers, acceptance coverage, and next action")
+        .action(async (options) => {
+        const result = await reviewFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureReview(result));
+    });
+    feature
+        .command("run")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--dry-run", "Show validation, Ready tasks, steps, and expected artifacts without writes")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .option("--limit <count>", "Maximum Ready tasks (without checkpoint mode capped at 1)", "1")
+        .option("--git-mode <mode>", "Git mode: none or checkpoint", "none")
+        .option("--keep-failed-diff", "Keep a failed task diff and stop instead of restoring")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--batch-run-id <id>", "Batch run id")
+        .option("--check-repo", "Run bash scripts/check-repo.sh during target repo preflight")
+        .option("--check-repo-command <command...>", "Override the check-repo preflight command")
+        .option("--quiet", "Suppress human-readable progress on stderr")
+        .option("--pi-model <model>", "Smoke override for pi executor nodes")
+        .description("Validate and advance one Ready Feature task through the existing Worker pipeline")
+        .action(async (options) => {
+        if (options.gitMode !== "none" && options.gitMode !== "checkpoint")
+            throw new Error("feature run --git-mode must be none or checkpoint");
+        if (options.keepFailedDiff && options.gitMode !== "checkpoint")
+            throw new Error("--keep-failed-diff requires --git-mode checkpoint");
+        const repoRoot = path.resolve(options.repo);
+        const batchRunId = options.batchRunId ?? buildBatchRunId(new Date());
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+        });
+        let progress;
+        try {
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? options.dryRun ?? false,
+                eventStore: createRoutedWorkerEventStore(repoRoot),
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? options.dryRun ?? false });
+        }
+        const result = await runFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            client,
+            dryRun: options.dryRun ?? false,
+            limit: Number.parseInt(options.limit, 10),
+            batchRunId,
+            runCheckRepo: options.checkRepo ?? false,
+            ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+            progress,
+            ...(options.piModel ? { piModel: options.piModel } : {}),
+            gitMode: options.gitMode === "checkpoint" ? "checkpoint" : "none",
+            keepFailedDiff: options.keepFailedDiff ?? false,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureRun(result));
+        if (result.status === "failed" || result.status === "needs-action")
+            process.exitCode = 1;
+    });
+    feature
+        .command("verify-final")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--task-id <id>", "Completed qa-execute TaskSpec to rerun as dedicated final verification")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--json", "Emit stable JSON")
+        .description("Run an independent HEAD-bound final QA verification and project Delivery evidence")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const client = new LoopAgentClient({ loopAgentBin: options.loopAgentBin, artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `final-verification-${Date.now()}`) });
+        const result = await runFeatureFinalVerification({ featureDir: path.resolve(options.featureDir), repoRoot, taskId: options.taskId, client });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}\n`);
+    });
+    feature
+        .command("delivery")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--qa-evidence <path>", "Repo-local QA pass evidence")
+        .requiredOption("--final-verification <path>", "Repo-local fresh final verification evidence")
+        .option("--waivers <path>", "Repo-local acceptance waiver decisions JSON")
+        .option("--dry-run", "Validate and show the Delivery Package plan without writes")
+        .option("--json", "Emit stable JSON")
+        .description("Validate checkpointed Feature evidence and prepare a local Delivery Package")
+        .action(async (options) => {
+        const result = await prepareFeatureDelivery({
+            featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo),
+            qaEvidencePath: options.qaEvidence, finalVerificationPath: options.finalVerification,
+            ...(options.waivers ? { waiverPath: options.waivers } : {}), dryRun: options.dryRun ?? false,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nDelivery: ${result.status}\nArtifacts: ${Object.values(result.artifacts).join(", ")}\nBlockers: ${result.blockers.join("; ") || "none"}\n`);
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
+    feature
+        .command("closeout")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--apply", "Apply Feature Closeout (reserved for M2-08)")
+        .option("--owner <owner>", "Closeout owner for apply")
+        .option("--json", "Emit stable JSON")
+        .description("Preview Feature Closeout gates without modifying the Feature Packet")
+        .action(async (options) => {
+        if (options.apply) {
+            const result = await applyFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo), owner: options.owner ?? "" });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        const result = await previewFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo) });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderCloseoutPreview(result));
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
     task
         .command("validate")
         .argument("<task-yaml>", "TaskSpec YAML file")
@@ -74,6 +206,58 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     });
+    task
+        .command("draft-followup")
+        .argument("<task-id>", "Failed parent Task id")
+        .requiredOption("--worker-run-id <id>", "Failed Worker run id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Create or reuse a classified Follow-up Task draft or human action card")
+        .action(async (taskId, options) => {
+        try {
+            const result = await draftFollowUpDecision({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                taskId,
+                workerRunId: options.workerRunId,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : result.kind === "TaskDraft"
+                    ? `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成任务草稿" : "复用现有任务草稿"}\n下一步: agent-worker feature approve-followup --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --followup-id ${result.followUpId} --repo ${JSON.stringify(path.resolve(options.repo))} --owner <owner>\n证据: ${result.draftPath}\n`
+                    : `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成人工行动卡" : "复用现有行动卡"}\n下一步: ${result.actionCard.command ?? result.actionCard.label}\n证据: ${result.draftPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "draft-followup");
+        }
+    });
+    feature
+        .command("approve-followup")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .requiredOption("--followup-id <id>", "Follow-up approval id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--owner <name>", "Human owner approving the Follow-up")
+        .option("--dry-run", "Validate baseline and show the transaction plan without writes")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Approve a Follow-up and atomically add its TaskSpec to the Feature")
+        .action(async (options) => {
+        try {
+            const result = await approveFollowUp({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                followUpId: options.followupId,
+                owner: options.owner,
+                dryRun: options.dryRun ?? false,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : `Follow-up: ${result.followUpId}\n结果: ${result.status === "planned" ? "批准事务预览通过" : result.idempotent ? "已批准（幂等复用）" : "已批准并进入 Ready"}\n下一步: agent-worker feature review --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --repo ${JSON.stringify(path.resolve(options.repo))}\n证据: ${result.approvalPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "approve-followup");
+        }
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
@@ -169,6 +353,16 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify({ ok: true, outputPath }, null, 2)}\n`);
     });
+    report
+        .command("metrics")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--month <yyyy-mm>", "UTC reporting month")
+        .option("--json", "Emit the metrics JSON on stdout")
+        .description("Project monthly Feature delivery metrics to JSON and Markdown")
+        .action(async (options) => {
+        const result = await projectMonthlyMetrics({ repoRoot: path.resolve(options.repo), month: options.month });
+        process.stdout.write(options.json ? `${JSON.stringify(result.metrics, null, 2)}\n` : `${JSON.stringify({ ok: true, jsonPath: result.jsonPath, markdownPath: result.markdownPath }, null, 2)}\n`);
+    });
     return program;
 }
 export async function main(argv = process.argv) {
@@ -177,6 +371,28 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+function handleFollowUpCliError(error, json, action) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (!json)
+        throw error;
+    const code = detail.includes("only supports ProductBug")
+        ? "unsupported-failure-category"
+        : detail.includes("baseline changed")
+            ? "stale-feature-baseline"
+            : detail.includes("already exists") || detail.includes("collision")
+                ? "follow-up-conflict"
+                : detail.includes("evidence") || detail.includes("draft hash")
+                    ? "follow-up-evidence-invalid"
+                    : "follow-up-failed";
+    process.stdout.write(`${JSON.stringify({
+        schemaVersion: 1,
+        status: "failed",
+        action,
+        error: { code, message: detail },
+        nextAction: action === "draft-followup" ? "Inspect the failed Worker run and failure category." : "Regenerate and review the Follow-up draft before approving.",
+    }, null, 2)}\n`);
+    process.exitCode = 1;
+}
 function isDirectRun() {
     const entry = process.argv[1];
     if (!entry)

package/dist/worker/closeout/apply.js

@@ -0,0 +1,73 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { validateDeliveryPackage } from "../delivery/package.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { previewFeatureCloseout } from "./preview.js";
+export const appliedFeatureCloseoutSchema = z.object({
+    schema_version: z.literal(1), feature_id: z.string().min(1), 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), decided_at: z.string().datetime(), appliedAt: z.string().datetime(), input_facts_hash: z.string().regex(/^[a-f0-9]{64}$/), summary: z.string().min(1),
+}).strict();
+export async function applyFeatureCloseout(input) {
+    if (!input.owner.trim())
+        throw new Error("feature closeout --apply requires a non-empty owner");
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    const featureDir = await realpath(path.resolve(input.featureDir));
+    const relative = path.relative(repoRoot, featureDir);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("Feature Packet must be inside the target repo");
+    const beforeValidation = await validateFeatureTaskGraph(featureDir);
+    if (!beforeValidation.ok)
+        throw new Error(`Feature Packet is invalid before closeout apply: ${beforeValidation.errors.map((error) => error.code).join(", ")}`);
+    const closeoutPath = path.join(featureDir, "closeout.yaml");
+    const deliveryPath = path.join(repoRoot, ".harness", "task-pool", "artifacts", "features", beforeValidation.featureId, "delivery", "delivery-manifest.json");
+    let previous;
+    let reusable;
+    try {
+        previous = await readFile(closeoutPath);
+        const existing = appliedFeatureCloseoutSchema.safeParse(YAML.parse(previous.toString("utf-8")));
+        if (existing.success)
+            reusable = existing.data;
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    if (reusable && reusable.feature_id !== beforeValidation.featureId)
+        throw new Error(`existing Feature Closeout ownership mismatch: expected ${beforeValidation.featureId}, got ${reusable.feature_id}`);
+    const allowedDirtyPaths = reusable ? [path.relative(repoRoot, closeoutPath).replace(/\\/g, "/")] : undefined;
+    const preview = await previewFeatureCloseout({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(allowedDirtyPaths ? { allowedDirtyPaths } : {}) });
+    if (preview.status !== "ready")
+        throw new Error(`Feature Closeout gates are blocked: ${preview.gates.filter((gate) => !gate.passed).map((gate) => `${gate.id} (${gate.message})`).join(", ")}`);
+    const delivery = await validateDeliveryPackage({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(allowedDirtyPaths ? { allowedDirtyPaths } : {}) });
+    if (!delivery.valid || !delivery.manifest)
+        throw new Error(`Delivery Package is invalid: ${delivery.blockers.join("; ")}`);
+    const inputFactsHash = createHash("sha256").update(await readFile(deliveryPath)).digest("hex");
+    const appliedAt = (input.now ?? new Date()).toISOString();
+    if (reusable?.input_facts_hash === inputFactsHash)
+        return { schemaVersion: 1, featureId: beforeValidation.featureId, status: "reused", closeoutPath, owner: reusable.owner, appliedAt: reusable.appliedAt, inputFactsHash };
+    const record = appliedFeatureCloseoutSchema.parse({ schema_version: 1, feature_id: preview.featureId, status: "success", qa_verdict: "pass", qa_evidence: [delivery.manifest.qa.evidence.path, delivery.manifest.finalVerification.path], delivery_manifest_ref: path.relative(repoRoot, deliveryPath).replace(/\\/g, "/"), owner: input.owner.trim(), decided_at: appliedAt, appliedAt, input_facts_hash: inputFactsHash, summary: `Feature ${preview.featureId} passed tasks, QA, required AC, risk, final verification, and Delivery gates.` });
+    const temp = path.join(featureDir, `.closeout.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, YAML.stringify(record), "utf-8");
+        await rename(temp, closeoutPath);
+        const after = await (input.validateAfterWrite ?? validateFeatureTaskGraph)(featureDir);
+        if (!after.ok)
+            throw new Error(`Feature Packet is invalid after closeout apply: ${after.errors.map((error) => error.code).join(", ")}`);
+        return { schemaVersion: 1, featureId: preview.featureId, status: "applied", closeoutPath, owner: record.owner, appliedAt, inputFactsHash };
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        if (previous) {
+            const rollback = path.join(featureDir, `.closeout.${randomUUID()}.rollback`);
+            await writeFile(rollback, previous);
+            await rename(rollback, closeoutPath);
+        }
+        else
+            await rm(closeoutPath, { force: true });
+        throw error;
+    }
+}
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }

package/dist/worker/closeout/preview.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { validateDeliveryPackage } from "../delivery/package.js";
+import { reviewFeature } from "../feature/review.js";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+export async function previewFeatureCloseout(input) {
+    const featureDir = path.resolve(input.featureDir);
+    const repoRoot = path.resolve(input.repoRoot);
+    const validation = await validateFeatureTaskGraph(featureDir);
+    const model = await reviewFeature({ featureDir, repoRoot });
+    const manifestPath = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", validation.featureId, "delivery", "delivery-manifest.json");
+    const delivery = await validateDeliveryPackage({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(input.allowedDirtyPaths ? { allowedDirtyPaths: input.allowedDirtyPaths } : {}) });
+    const manifest = delivery.manifest;
+    const requiredIncomplete = model.acceptanceCoverage.filter((item) => item.required && !["covered", "waived"].includes(item.status));
+    const allTasksDone = model.tasks.length > 0 && model.tasks.every((task) => task.status === "Done");
+    const gates = [
+        { id: "feature-validation", passed: validation.ok, message: validation.ok ? "Feature Packet is valid" : "Feature Packet validation failed", evidence: validation.errors.flatMap((error) => error.path ? [error.path] : []) },
+        { id: "tasks-complete", passed: allTasksDone, message: allTasksDone ? "All development and QA tasks are Done" : "One or more required tasks are not Done", evidence: model.tasks.filter((task) => task.status !== "Done").map((task) => task.taskId) },
+        { id: "qa-pass", passed: manifest?.qa.verdict === "passed", message: manifest?.qa.verdict === "passed" ? "QA verdict passed" : "QA pass evidence is missing", evidence: manifest ? [manifest.qa.evidence.path] : [] },
+        { id: "required-ac", passed: requiredIncomplete.length === 0, message: requiredIncomplete.length === 0 ? "Required AC are covered or waived" : "Required AC coverage is incomplete", evidence: requiredIncomplete.map((item) => item.acId) },
+        { id: "risk", passed: model.riskSummary.high === 0, message: model.riskSummary.high === 0 ? "No unresolved high risk" : "Unresolved high risk remains", evidence: model.blockingItems.filter((item) => item.failureCategory && ["RiskyChange", "ContractMismatch", "SpecUnclear", "NeedsHuman"].includes(item.failureCategory)).flatMap((item) => item.evidence) },
+        { id: "final-verification", passed: Boolean(manifest?.finalVerification), message: manifest?.finalVerification ? "Final verification evidence is present" : "Final verification evidence is missing", evidence: manifest ? [manifest.finalVerification.path] : [] },
+        { id: "delivery", passed: delivery.valid && model.evidence.delivery === manifestPath, message: delivery.valid && model.evidence.delivery === manifestPath ? "Delivery manifest and Git facts are valid" : `Delivery is invalid: ${delivery.blockers[0] ?? "missing manifest"}`, evidence: manifest ? [manifestPath] : [] },
+    ];
+    const ready = gates.every((gate) => gate.passed);
+    return { schemaVersion: 1, featureId: validation.featureId, status: ready ? "ready" : "blocked", gates, nextAction: ready ? "Closeout gates are ready; retain this preview for human review until atomic --apply is implemented in M2-08" : "Resolve the first failed closeout gate and preview again" };
+}
+export function renderCloseoutPreview(preview) {
+    return [`Feature: ${preview.featureId}`, `Closeout: ${preview.status === "ready" ? "可应用" : "被阻止"}`, ...preview.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.id}: ${gate.message}`), `下一步: ${preview.nextAction}`].join("\n") + "\n";
+}

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

@@ -0,0 +1,158 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import YAML from "yaml";
+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, readJsonlFile, recordTaskPoolRun } from "../pool/run-store.js";
+import { buildWorkerRunId, runTaskSpec } from "../run-task/run-task.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
+const execFileAsync = promisify(execFile);
+export async function runFeatureFinalVerification(input) {
+    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 record = gitTransactionRecordSchema.parse(JSON.parse(await readFile(transactionRecordPath(repoRoot, featureId), "utf-8")));
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    const headSha = await git(repoRoot, ["rev-parse", "HEAD"]);
+    const status = await 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);
+    if (!finalRun) {
+        const workerRunId = buildWorkerRunId(`${input.taskId}-final`, now);
+        const result = await runTaskSpec({ repoRoot, taskSpec: verificationTaskSpec, taskSpecPath, client: input.client, now, workerRunId, skipSuccessFinalization: true });
+        if (result.status !== "succeeded")
+            throw new Error(`dedicated final verification failed: ${workerRunId}`);
+        const afterHead = await git(repoRoot, ["rev-parse", "HEAD"]);
+        const afterStatus = await 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: new Date().toISOString() };
+        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 qaRuns = latestSuccessfulQaRuns(runs, allSpecs, taskSpec.id, featureId);
+    if (qaRuns.length === 0)
+        throw new Error("no prior successful qa-execute runs are available for the QA aggregate");
+    const coveredAcIds = [...new Set(qaRuns.flatMap((run) => allSpecs.get(run.taskId)?.acceptance_refs ?? []))];
+    const requiredAcIds = acceptance.acceptance.filter((item) => item.priority === "must").map((item) => item.id);
+    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) },
+        final: { schemaVersion: 1, featureId, kind: "final-verification", status: "passed", headSha, run: runRef(finalRun), shellSummary: { path: summaryRelative, sha256: createHash("sha256").update(summary).digest("hex") } },
+    });
+    return { schemaVersion: 1, featureId, taskId: taskSpec.id, workerRunId: finalRun.workerRunId, headSha, qaEvidencePath: repoRef(repoRoot, qaEvidencePath), finalVerificationPath: repoRef(repoRoot, finalVerificationPath), qaRunCount: qaRuns.length };
+}
+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));
+}
+async function reusableFinalRun(repoRoot, runs, taskId, featureId, record, now) {
+    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;
+        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 }; }
+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`);
+    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) { return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout.trim(); }
+async function gitRaw(repoRoot, args) { return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout; }
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }