@tea-agent/loop-agent 0.9.0 → 0.10.0-alpha.0

package/dist/task/delegate.js

@@ -9,31 +9,24 @@ import { getTaskPaths, loadTaskConfig } from './runtime.js';
 import { copyDir } from '../records/harvest.js';
 import { saveWorkflowState } from './state.js';
 import { workflowStateSchema } from '../shared/types.js';
-import { assertCursorExecutorAvailable, resolveTaskExecutor, validateCursorTaskPreflight } from '../executors/config-core.js';
-import { resolveDelegateExecutionMode } from '../executors/cursor-execution-log.js';
 /**
  * Atomic delegation: validate source → check conflicts → create worktree →
  * sync source → optionally symlink node_modules.
  *
- * Execution runs in-process for Cursor SDK; Pi worktrees are prepared for manual DAG follow-up.
+ * Default is isolation only; callers may run Pi DAG via application use cases.
  */
 export async function delegateTask(repoRoot, manifest, taskId, opts = {}) {
     const symlinkEnabled = opts.symlinkNodeModules !== false;
     await validateSourceMaterials(repoRoot, taskId);
-    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    await loadTaskConfig(repoRoot, taskId);
     const effectiveManifest = manifest ?? (await loadHarnessManifest(repoRoot));
-    const executor = resolveTaskExecutor(taskConfig, opts.executor);
-    if (executor === 'cursor') {
-        assertCursorExecutorAvailable(effectiveManifest);
-        validateCursorTaskPreflight(taskConfig);
-    }
     await validateNoConflicts(repoRoot, taskId, opts.branch);
     const worktree = await createWorktree(repoRoot, effectiveManifest, {
         taskId,
         branch: opts.branch,
         base: opts.base,
     });
-    await syncSourceToWorktree(repoRoot, taskId, worktree.path, executor);
+    await syncSourceToWorktree(repoRoot, taskId, worktree.path);
     let symlinkedNodeModules = false;
     if (symlinkEnabled) {
         symlinkedNodeModules = await setupNodeModulesSymlink(repoRoot, worktree.path);
@@ -46,13 +39,9 @@ export async function delegateTask(repoRoot, manifest, taskId, opts = {}) {
         branch: worktree.branch,
         baseBranch: worktree.base,
         symlinkedNodeModules,
-        executor,
-        executionMode: resolveDelegateExecutionMode(executor),
+        executionMode: 'pi-worktree',
     };
 }
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
 async function validateSourceMaterials(repoRoot, taskId) {
     const { taskConfigPath, sourceDir } = getTaskPaths(repoRoot, taskId);
     try {
@@ -96,7 +85,7 @@ async function validateNoConflicts(repoRoot, taskId, branch) {
         console.error(`[delegate] warning: branch "${targetBranch}" already exists; will reuse it for the worktree.`);
     }
 }
-async function syncSourceToWorktree(repoRoot, taskId, worktreePath, executor) {
+async function syncSourceToWorktree(repoRoot, taskId, worktreePath) {
     const srcPaths = getTaskPaths(repoRoot, taskId);
     const destPaths = getTaskPaths(worktreePath, taskId);
     const destTaskDir = destPaths.taskDir;
@@ -106,16 +95,15 @@ async function syncSourceToWorktree(repoRoot, taskId, worktreePath, executor) {
     await copyDir(srcPaths.sourceDir, destSourceDir);
     const rawJson = await readFile(srcPaths.taskConfigPath, 'utf-8');
     const parsedTaskConfig = JSON.parse(rawJson);
-    parsedTaskConfig.executor = executor;
     await mkdir(path.dirname(destTaskConfigPath), { recursive: true });
     await writeTaskConfig(worktreePath, taskId, parsedTaskConfig);
     await mkdir(destPaths.logsDir, { recursive: true });
     await initializeArtifacts(destTaskDir);
     await initializeTaskLogStubs(worktreePath, taskId);
-    const state = await loadOrCreateWorkflowState(srcPaths.statePath, taskId, executor);
+    const state = await loadOrCreateWorkflowState(srcPaths.statePath, taskId);
     await saveWorkflowState(destPaths.statePath, state);
 }
-async function loadOrCreateWorkflowState(statePath, taskId, executor) {
+async function loadOrCreateWorkflowState(statePath, taskId) {
     try {
         const raw = await readFile(statePath, 'utf-8');
         return workflowStateSchema.parse(JSON.parse(raw));
@@ -129,8 +117,8 @@ async function loadOrCreateWorkflowState(statePath, taskId, executor) {
             completedSteps: [],
             lastUpdated: now,
             executor: {
-                name: executor,
-                mode: executor === 'cursor' ? 'sdk' : 'json',
+                name: 'pi',
+                mode: 'json',
             },
             artifacts: {
                 analysis: false,

package/dist/task/runtime.js

@@ -117,11 +117,10 @@ export async function createTask(repoRoot, taskId, title) {
             stopOnHardVerifyPass: true,
             pauseOnRegression: true,
         },
-        loopAutoWritePolicy: 'off',
+        loopAutoExecutionPolicy: 'off',
         verifyEnv: 'clean',
         maxGoalContinuationsPerRun: 5,
         piSubagentMode: 'off',
-        executor: 'pi',
         notes: '',
     };
     const state = {

package/dist/worker/cli.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { readPackageVersion } from "../shared/package-metadata.js";
 import YAML from "yaml";
 import { LoopAgentClient } from "./loop-agent/loop-agent-client.js";
 import { resolveLoopAgentProfile } from "./profile-mapping.js";
@@ -17,17 +18,158 @@ 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
         .name("agent-worker")
         .description("Local product-line worker utilities for TaskSpec validation")
+        .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
         .showHelpAfterError()
         .showSuggestionAfterError();
     const task = program.command("task").description("TaskSpec utilities");
     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")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
+        .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 expectedIdentity = buildIdentityExpectation(options);
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+            resolveIdentity: true,
+        });
+        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,
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: expectedIdentity,
+        });
+        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")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
+        .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()}`), resolveIdentity: true });
+        const result = await runFeatureFinalVerification({ featureDir: path.resolve(options.featureDir), repoRoot, taskId: options.taskId, client, controllerIdentity: client.getIdentity(), controllerExpectation: buildIdentityExpectation(options) });
+        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 +216,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")
@@ -85,13 +279,17 @@ export function buildAgentWorkerProgram() {
         .option("--check-repo-command <command...>", "Override the check-repo preflight command")
         .option("--quiet", "Suppress human-readable progress on stderr (JSON still goes to stdout)")
         .option("--pi-model <model>", "Smoke override: force every pi executor node to this model (drops --strict-models)")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
         .description("Run ready TaskSpec tasks serially")
         .action(async (options) => {
         const repoRoot = path.resolve(options.repo);
         const batchRunId = options.batchRunId ?? buildBatchRunId(new Date());
+        const expectedIdentity = buildIdentityExpectation(options);
         const client = new LoopAgentClient({
             loopAgentBin: options.loopAgentBin,
             artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+            resolveIdentity: true,
         });
         let progress;
         try {
@@ -117,6 +315,8 @@ export function buildAgentWorkerProgram() {
                 : {}),
             progress,
             ...(options.piModel ? { piModel: options.piModel } : {}),
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: expectedIdentity,
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         if (result.status !== "completed")
@@ -169,14 +369,57 @@ 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 function buildIdentityExpectation(options) {
+    if (options.expectedControllerVersion || options.expectedControllerFingerprint) {
+        const expectation = {};
+        if (options.expectedControllerVersion)
+            expectation.expectedVersion = options.expectedControllerVersion;
+        if (options.expectedControllerFingerprint)
+            expectation.expectedFingerprint = options.expectedControllerFingerprint;
+        return expectation;
+    }
+    return undefined;
+}
 export async function main(argv = process.argv) {
     await buildAgentWorkerProgram().parseAsync(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";
+}