@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.1

package/dist/worker/feature/advance.js

@@ -0,0 +1,301 @@
+import path from "node:path";
+import { defaultFeatureEvidencePaths, runFeatureFinalVerification, } from "../delivery/final-verification.js";
+import { prepareFeatureDelivery, } from "../delivery/package.js";
+import { applyFeatureCloseout, } from "../closeout/apply.js";
+import { previewFeatureCloseout, } from "../closeout/preview.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { reviewFeature } from "./review.js";
+const defaultDeps = {
+    validateFeature: validateFeatureTaskGraph,
+    review: reviewFeature,
+    verifyFinal: runFeatureFinalVerification,
+    delivery: prepareFeatureDelivery,
+    previewCloseout: previewFeatureCloseout,
+    applyCloseout: applyFeatureCloseout,
+};
+/**
+ * ADR 0007 orchestration: verify-final → delivery → closeout preview[/apply].
+ * Does not run implementation tasks (use `feature run` for Ready writers).
+ */
+export async function advanceFeature(input, deps = defaultDeps) {
+    const featureDir = path.resolve(input.featureDir);
+    const repoRoot = path.resolve(input.repoRoot);
+    const dryRun = input.dryRun ?? false;
+    const apply = Boolean(input.apply) && !dryRun;
+    const steps = [];
+    const blockers = [];
+    const started = Date.now();
+    const push = (id, status, message, from = started) => {
+        steps.push({
+            id,
+            status,
+            ...(message ? { message } : {}),
+            durationMs: Math.max(0, Date.now() - from),
+        });
+    };
+    const validateStarted = Date.now();
+    const validation = await deps.validateFeature(featureDir);
+    if (!validation.ok) {
+        push("validate", "failed", validation.errors.map((e) => e.code).join(", "), validateStarted);
+        return {
+            schemaVersion: 1,
+            featureId: validation.featureId || "unknown",
+            mode: dryRun ? "dry-run" : "executed",
+            status: "failed",
+            finalTaskId: null,
+            steps,
+            blockers: validation.errors.map((e) => e.message),
+            nextCommand: `agent-worker task validate-feature ${JSON.stringify(featureDir)}`,
+        };
+    }
+    push("validate", "completed", `featureId=${validation.featureId}`, validateStarted);
+    const featureId = validation.featureId;
+    const resolveStarted = Date.now();
+    let finalTaskId = input.taskId?.trim() || "";
+    if (!finalTaskId) {
+        const model = await deps.review({ featureDir, repoRoot });
+        finalTaskId = resolveFinalVerifyTaskId(model) ?? "";
+    }
+    if (!finalTaskId) {
+        push("resolve-final-task", "failed", "could not resolve FINAL-VERIFY task id", resolveStarted);
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "failed",
+            finalTaskId: null,
+            steps,
+            blockers: [
+                "missing --task-id and no FINAL-VERIFY* task found in Feature review",
+            ],
+            nextCommand: `agent-worker feature review --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)}`,
+        };
+    }
+    push("resolve-final-task", "completed", finalTaskId, resolveStarted);
+    if (!input.client) {
+        push("verify-final", "failed", "loop-agent client required for verify-final");
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "failed",
+            finalTaskId,
+            steps,
+            blockers: [
+                "feature advance requires --loop-agent-bin / client for verify-final",
+            ],
+        };
+    }
+    const verifyStarted = Date.now();
+    let verifyFinal;
+    try {
+        verifyFinal = await deps.verifyFinal({
+            featureDir,
+            repoRoot,
+            taskId: finalTaskId,
+            client: input.client,
+            controllerIdentity: input.controllerIdentity ?? input.client.getIdentity?.(),
+            ...(input.controllerExpectation
+                ? { controllerExpectation: input.controllerExpectation }
+                : {}),
+            evidenceMode: input.evidenceMode ?? "auto",
+            ...(input.now ? { now: input.now } : {}),
+        });
+        push("verify-final", "completed", `mode=${verifyFinal.evidenceMode ?? "qa-execute"}`, verifyStarted);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        push("verify-final", "failed", message, verifyStarted);
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "failed",
+            finalTaskId,
+            steps,
+            blockers: [message],
+            nextCommand: `agent-worker feature verify-final --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --task-id ${JSON.stringify(finalTaskId)} --json`,
+        };
+    }
+    const defaults = defaultFeatureEvidencePaths(featureId);
+    const qaEvidencePath = input.qaEvidencePath ??
+        verifyFinal.qaEvidencePath ??
+        defaults.qaEvidencePath;
+    const finalVerificationPath = input.finalVerificationPath ??
+        verifyFinal.finalVerificationPath ??
+        defaults.finalVerificationPath;
+    const deliveryStarted = Date.now();
+    const delivery = await deps.delivery({
+        featureDir,
+        repoRoot,
+        qaEvidencePath,
+        finalVerificationPath,
+        ...(input.waiverPath ? { waiverPath: input.waiverPath } : {}),
+        dryRun,
+        ...(input.now ? { now: input.now } : {}),
+    });
+    if (delivery.status === "blocked") {
+        push("delivery", "failed", delivery.blockers.join("; ") || "blocked", deliveryStarted);
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "blocked",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            blockers: delivery.blockers,
+            nextCommand: `agent-worker feature delivery --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --json`,
+        };
+    }
+    push("delivery", "completed", delivery.status, deliveryStarted);
+    const previewStarted = Date.now();
+    const closeoutPreview = await deps.previewCloseout({
+        featureDir,
+        repoRoot,
+        ...(input.now ? { now: input.now } : {}),
+    });
+    if (closeoutPreview.status !== "ready") {
+        const failedGates = closeoutPreview.gates
+            .filter((g) => !g.passed)
+            .map((g) => `${g.id}: ${g.message}`);
+        push("closeout-preview", "failed", failedGates.join("; ") || "blocked", previewStarted);
+        blockers.push(...failedGates);
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "blocked",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            closeoutPreview,
+            blockers,
+            nextCommand: `agent-worker feature closeout --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --json`,
+        };
+    }
+    push("closeout-preview", "completed", "ready", previewStarted);
+    if (!apply) {
+        push("closeout-apply", "skipped", dryRun
+            ? "dry-run: closeout apply skipped"
+            : "pass --apply --owner to apply closeout");
+        const reviewAfter = await deps.review({ featureDir, repoRoot });
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: dryRun ? "dry-run" : "executed",
+            status: "ready",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            closeoutPreview,
+            reviewAfter: {
+                status: reviewAfter.status,
+                statusLabel: reviewAfter.statusLabel,
+                nextAction: reviewAfter.nextAction,
+            },
+            blockers: [],
+            nextCommand: `agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --task-id ${JSON.stringify(finalTaskId)} --apply --owner <owner>`,
+        };
+    }
+    if (!input.owner?.trim()) {
+        push("closeout-apply", "failed", "owner required for --apply");
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: "executed",
+            status: "failed",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            closeoutPreview,
+            blockers: ["feature advance --apply requires non-empty --owner"],
+        };
+    }
+    const applyStarted = Date.now();
+    try {
+        const closeoutApply = await deps.applyCloseout({
+            featureDir,
+            repoRoot,
+            owner: input.owner.trim(),
+            ...(input.now ? { now: input.now } : {}),
+        });
+        push("closeout-apply", "completed", closeoutApply.status, applyStarted);
+        const reviewAfter = await deps.review({ featureDir, repoRoot });
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: "executed",
+            status: "applied",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            closeoutPreview,
+            closeoutApply,
+            reviewAfter: {
+                status: reviewAfter.status,
+                statusLabel: reviewAfter.statusLabel,
+                nextAction: reviewAfter.nextAction,
+            },
+            blockers: [],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        push("closeout-apply", "failed", message, applyStarted);
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: "executed",
+            status: "failed",
+            finalTaskId,
+            steps,
+            verifyFinal,
+            delivery,
+            closeoutPreview,
+            blockers: [message],
+            nextCommand: `agent-worker feature closeout --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --apply --owner ${JSON.stringify(input.owner)} --json`,
+        };
+    }
+}
+export function resolveFinalVerifyTaskId(model) {
+    const hint = /(final[-_]?(verify|verification))|closeout/i;
+    const byId = model.tasks.find((t) => hint.test(t.taskId));
+    if (byId)
+        return byId.taskId;
+    // Fallback: last Done-or-any task that depends on both test-ish types is not available here;
+    // review model lacks depends_on depth — require explicit task when id heuristic fails.
+    return null;
+}
+export function renderFeatureAdvance(result) {
+    const lines = [
+        `Feature: ${result.featureId}`,
+        `Advance: ${result.status} (${result.mode})`,
+        `Final task: ${result.finalTaskId ?? "none"}`,
+        ...result.steps.map((s) => `${statusMark(s.status)} ${s.id}${s.message ? `: ${s.message}` : ""}`),
+    ];
+    if (result.blockers.length) {
+        lines.push(`Blockers: ${result.blockers.join("; ")}`);
+    }
+    if (result.nextCommand) {
+        lines.push(`Next: ${result.nextCommand}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function statusMark(status) {
+    switch (status) {
+        case "completed":
+            return "✓";
+        case "failed":
+            return "✗";
+        case "skipped":
+            return "·";
+        default:
+            return "○";
+    }
+}

package/dist/worker/feature/doctor.js

@@ -0,0 +1,223 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { defaultFeatureEvidencePaths } from "../delivery/final-verification.js";
+import { transactionRecordPath } from "../delivery/git-transaction.js";
+import { readFeatureTaskPoolStates } from "../pool/run-store.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { reviewFeature } from "./review.js";
+import { resolveFinalVerifyTaskId } from "./advance.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Read-only Feature delivery readiness doctor (not pool migrate / not auto-repair).
+ */
+export async function diagnoseFeature(input) {
+    const featureDir = path.resolve(input.featureDir);
+    const repoRoot = path.resolve(input.repoRoot);
+    const findings = [];
+    const nextCommands = [];
+    const validation = await validateFeatureTaskGraph(featureDir);
+    const featureId = validation.featureId || "unknown";
+    if (!validation.ok) {
+        findings.push({
+            id: "feature-validation",
+            severity: "error",
+            message: `Feature Packet invalid: ${validation.errors.map((e) => e.code).join(", ")}`,
+            evidence: validation.errors.flatMap((e) => (e.path ? [e.path] : [])),
+            suggestedCommand: `agent-worker task validate-feature ${JSON.stringify(featureDir)}`,
+        });
+    }
+    let review;
+    try {
+        review = await reviewFeature({ featureDir, repoRoot });
+    }
+    catch (error) {
+        findings.push({
+            id: "feature-review",
+            severity: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const finalTaskId = review ? resolveFinalVerifyTaskId(review) : null;
+    const defaults = defaultFeatureEvidencePaths(featureId);
+    const deliveryManifestRel = `.harness/task-pool/artifacts/features/${featureId}/delivery/delivery-manifest.json`;
+    const gitTxAbs = transactionRecordPath(repoRoot, featureId);
+    const gitTxRel = path.relative(repoRoot, gitTxAbs).replace(/\\/g, "/");
+    const evidence = {
+        qaPass: {
+            path: defaults.qaEvidencePath,
+            present: await exists(path.join(repoRoot, defaults.qaEvidencePath)),
+        },
+        finalVerification: {
+            path: defaults.finalVerificationPath,
+            present: await exists(path.join(repoRoot, defaults.finalVerificationPath)),
+        },
+        bundle: {
+            path: defaults.bundleEvidencePath,
+            present: await exists(path.join(repoRoot, defaults.bundleEvidencePath)),
+        },
+        deliveryManifest: {
+            path: deliveryManifestRel,
+            present: await exists(path.join(repoRoot, deliveryManifestRel)),
+        },
+        gitTransaction: {
+            path: gitTxRel,
+            present: await exists(gitTxAbs),
+        },
+    };
+    const statesById = validation.ok
+        ? await readFeatureTaskPoolStates(repoRoot, featureId)
+        : {};
+    const states = Object.values(statesById);
+    const taskSummary = {
+        total: states.length,
+        done: states.filter((s) => s.status === "Done").length,
+        failed: states.filter((s) => s.status === "Failed").length,
+        running: states.filter((s) => s.status === "Running").length,
+        ready: states.filter((s) => s.status === "Ready").length,
+        other: states.filter((s) => !["Done", "Failed", "Running", "Ready"].includes(s.status)).length,
+    };
+    if (taskSummary.running > 0) {
+        const running = states.filter((s) => s.status === "Running");
+        findings.push({
+            id: "running-tasks",
+            severity: "warn",
+            message: `${taskSummary.running} task(s) still Running`,
+            evidence: running.map((s) => s.taskId),
+            suggestedCommand: `agent-worker task reconcile <task-id> --feature-id ${JSON.stringify(featureId)} --repo ${JSON.stringify(repoRoot)} --action abandon`,
+        });
+    }
+    if (taskSummary.failed > 0) {
+        const failed = states.filter((s) => s.status === "Failed");
+        findings.push({
+            id: "failed-tasks",
+            severity: "warn",
+            message: `${taskSummary.failed} task(s) Failed`,
+            evidence: failed.map((s) => s.taskId),
+            suggestedCommand: `agent-worker task retry <task-id> --feature-id ${JSON.stringify(featureId)} --repo ${JSON.stringify(repoRoot)} --reason <reason>`,
+        });
+    }
+    const dirty = await gitDirty(repoRoot);
+    if (dirty.dirty) {
+        findings.push({
+            id: "dirty-worktree",
+            severity: "warn",
+            message: "Target repo worktree is dirty (may block Delivery/closeout)",
+            evidence: dirty.lines.slice(0, 20),
+        });
+    }
+    if (!evidence.gitTransaction.present && taskSummary.done > 0) {
+        findings.push({
+            id: "missing-git-transaction",
+            severity: "info",
+            message: "No Feature git transaction record yet (expected before checkpointed Delivery)",
+            evidence: [evidence.gitTransaction.path],
+        });
+    }
+    const allTasksDone = review &&
+        review.tasks.length > 0 &&
+        review.tasks.every((t) => t.status === "Done");
+    if (allTasksDone) {
+        if (!evidence.qaPass.present || !evidence.finalVerification.present) {
+            findings.push({
+                id: "missing-final-evidence",
+                severity: "info",
+                message: "Implementation/QA tasks Done but verify-final evidence missing (ADR 0007)",
+                evidence: [
+                    evidence.qaPass.path,
+                    evidence.finalVerification.path,
+                ].filter((p, i) => i === 0 ? !evidence.qaPass.present : !evidence.finalVerification.present),
+                suggestedCommand: finalTaskId
+                    ? `agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --task-id ${JSON.stringify(finalTaskId)} --dry-run --json`
+                    : `agent-worker feature verify-final --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --task-id <FINAL-VERIFY-id> --json`,
+            });
+            if (finalTaskId) {
+                nextCommands.push(`agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --task-id ${JSON.stringify(finalTaskId)} --json`);
+            }
+        }
+        else if (!evidence.deliveryManifest.present) {
+            findings.push({
+                id: "missing-delivery",
+                severity: "info",
+                message: "Final evidence present but Delivery Package not written",
+                suggestedCommand: `agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)}${finalTaskId ? ` --task-id ${JSON.stringify(finalTaskId)}` : ""} --json`,
+            });
+            nextCommands.push(`agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)}${finalTaskId ? ` --task-id ${JSON.stringify(finalTaskId)}` : ""} --json`);
+        }
+        else if (review?.status === "deliverable") {
+            findings.push({
+                id: "ready-for-closeout",
+                severity: "info",
+                message: "Feature is deliverable; preview or apply closeout",
+                suggestedCommand: `agent-worker feature closeout --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --json`,
+            });
+            nextCommands.push(`agent-worker feature advance --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)}${finalTaskId ? ` --task-id ${JSON.stringify(finalTaskId)}` : ""} --apply --owner <owner> --json`);
+        }
+    }
+    else if (review?.status === "ready") {
+        nextCommands.push(`agent-worker feature run --feature-dir ${JSON.stringify(featureDir)} --repo ${JSON.stringify(repoRoot)} --limit 1 --json`);
+    }
+    const hasError = findings.some((f) => f.severity === "error");
+    const hasWarn = findings.some((f) => f.severity === "warn");
+    const status = hasError ? "blocked" : hasWarn ? "attention" : "healthy";
+    if (nextCommands.length === 0 && review?.nextAction?.command) {
+        nextCommands.push(review.nextAction.command);
+    }
+    return {
+        schemaVersion: 1,
+        featureId,
+        status,
+        ...(review ? { reviewStatus: review.status } : {}),
+        finalTaskId,
+        evidence,
+        taskSummary,
+        findings,
+        nextCommands,
+    };
+}
+export function renderFeatureDoctor(result) {
+    const lines = [
+        `Feature: ${result.featureId}`,
+        `Doctor: ${result.status}${result.reviewStatus ? ` (review=${result.reviewStatus})` : ""}`,
+        `Tasks: total=${result.taskSummary.total} done=${result.taskSummary.done} failed=${result.taskSummary.failed} running=${result.taskSummary.running} ready=${result.taskSummary.ready}`,
+        `Final task: ${result.finalTaskId ?? "none"}`,
+        `Evidence: qa=${result.evidence.qaPass.present ? "yes" : "no"} final=${result.evidence.finalVerification.present ? "yes" : "no"} bundle=${result.evidence.bundle.present ? "yes" : "no"} delivery=${result.evidence.deliveryManifest.present ? "yes" : "no"}`,
+        ...result.findings.map((f) => `${severityMark(f.severity)} ${f.id}: ${f.message}${f.suggestedCommand ? `\n  → ${f.suggestedCommand}` : ""}`),
+    ];
+    if (result.nextCommands.length) {
+        lines.push("Next commands:");
+        for (const cmd of result.nextCommands)
+            lines.push(`  - ${cmd}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function severityMark(severity) {
+    if (severity === "error")
+        return "✗";
+    if (severity === "warn")
+        return "!";
+    return "·";
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function gitDirty(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["status", "--short", "--branch"], { cwd: repoRoot, encoding: "utf8" });
+        const lines = stdout
+            .split(/\r?\n/)
+            .map((l) => l.trimEnd())
+            .filter((l) => l && !l.startsWith("##"));
+        return { dirty: lines.length > 0, lines };
+    }
+    catch {
+        return { dirty: false, lines: [] };
+    }
+}

package/dist/worker/feature/next-action.js

@@ -66,13 +66,21 @@ export function projectNextAction(input, status) {
         };
     }
     if (status === "awaiting_qa") {
+        const finalish = input.tasks.find((task) => /(final[-_]?(verify|verification))|closeout/i.test(task.taskId));
+        if (finalish && (finalish.status === "Done" || finalish.status === "Ready")) {
+            return {
+                kind: "advance_delivery",
+                label: "运行 feature advance（verify-final 权威路径）",
+                command: `agent-worker feature advance ${featureArgs} --task-id ${quote(finalish.taskId)}`,
+            };
+        }
         return { kind: "complete_qa", label: "补齐 QA verdict 与 required AC 证据" };
     }
     if (status === "deliverable") {
         return {
-            kind: "prepare_closeout",
-            label: "预览 Feature Closeout gates",
-            command: `agent-worker feature closeout ${featureArgs}`,
+            kind: "advance_delivery",
+            label: "编排 verify-final → delivery → closeout（ADR 0007）",
+            command: `agent-worker feature advance ${featureArgs}`,
         };
     }
     return null;