@tea-agent/loop-agent 0.24.10 → 0.25.0

package/dist/worker/cli.js

@@ -31,8 +31,11 @@ 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 { advanceFeature, renderFeatureAdvance, } from "./feature/advance.js";
+import { diagnoseFeature, renderFeatureDoctor, } from "./feature/doctor.js";
+import { FEATURE_SCAFFOLD_TEMPLATES, ScaffoldError, scaffoldFeaturePacket, } from "./feature/scaffold.js";
 import { projectMonthlyMetrics } from "./metrics/projector.js";
-import { runFeatureFinalVerification } from "./delivery/final-verification.js";
+import { defaultFeatureEvidencePaths, runFeatureFinalVerification, } from "./delivery/final-verification.js";
 import { advanceGitCheckpoint } from "./delivery/git-transaction.js";
 export function buildAgentWorkerProgram() {
     const program = new Command();
@@ -245,6 +248,125 @@ export function buildAgentWorkerProgram() {
         if (result.status === "failed" || result.status === "needs-action")
             process.exitCode = 1;
     });
+    feature
+        .command("advance")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--task-id <id>", "Final verification TaskSpec id (default: resolve FINAL-VERIFY* from Feature review)")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--evidence-mode <mode>", "Evidence aggregate for verify-final: auto, qa-execute, or typed", "auto")
+        .option("--qa-evidence <path>", "Override QA pass evidence path")
+        .option("--final-verification <path>", "Override final verification evidence path")
+        .option("--waivers <path>", "Repo-local acceptance waiver decisions JSON")
+        .option("--dry-run", "Run verify-final + delivery dry-run + closeout preview without Delivery writes or closeout apply")
+        .option("--apply", "After ready closeout preview, apply Feature Closeout (requires --owner)")
+        .option("--owner <owner>", "Closeout owner when using --apply")
+        .option("--expected-controller-version <version>", "Exact expected controller version")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex>")
+        .option("--json", "Emit stable JSON")
+        .description("Orchestrate ADR 0007 delivery path: verify-final → delivery → closeout preview[/apply]")
+        .action(async (options) => {
+        if (options.evidenceMode !== "auto" &&
+            options.evidenceMode !== "qa-execute" &&
+            options.evidenceMode !== "typed") {
+            throw new Error("feature advance --evidence-mode must be auto, qa-execute, or typed");
+        }
+        const repoRoot = path.resolve(options.repo);
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `feature-advance-${Date.now()}`),
+            resolveIdentity: true,
+        });
+        const result = await advanceFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            ...(options.taskId ? { taskId: options.taskId } : {}),
+            client,
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: buildIdentityExpectation(options),
+            evidenceMode: options.evidenceMode,
+            ...(options.qaEvidence
+                ? { qaEvidencePath: options.qaEvidence }
+                : {}),
+            ...(options.finalVerification
+                ? { finalVerificationPath: options.finalVerification }
+                : {}),
+            ...(options.waivers ? { waiverPath: options.waivers } : {}),
+            dryRun: options.dryRun ?? false,
+            apply: options.apply ?? false,
+            ...(options.owner ? { owner: options.owner } : {}),
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureAdvance(result));
+        if (result.status === "failed" ||
+            result.status === "blocked") {
+            process.exitCode = 1;
+        }
+    });
+    feature
+        .command("doctor")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON")
+        .description("Read-only Feature delivery readiness diagnosis (evidence, pool states, dirty worktree)")
+        .action(async (options) => {
+        const result = await diagnoseFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureDoctor(result));
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
+    feature
+        .command("scaffold")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--template <id>", `Locked template: ${FEATURE_SCAFFOLD_TEMPLATES.join(" | ")}`)
+        .option("--feature-id <id>", "Feature id (F-YYYY-NNN)")
+        .option("--title <text>", "Human title")
+        .option("--description <text>", "Optional longer description")
+        .option("--be-path <pattern>", "Repo-relative backend allowed path (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--fe-path <pattern>", "Repo-relative frontend allowed path (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--contract-path <path>", "fe-with-api contract path (default docs/contracts/<feature-id>/api.md)")
+        .option("--verify-command <command>", "Explicit verify command for implementation tasks (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--batch <file>", "YAML/JSON batch list (mutually exclusive with single-feature flags)")
+        .option("--dry-run", "Parse/render/validate without writing features/")
+        .option("--json", "Emit stable JSON only")
+        .description("Deterministically scaffold a Feature Packet (no model, no Task Pool, no fullstack-v1 default)")
+        .action(async (options) => {
+        try {
+            const result = options.batch
+                ? await scaffoldFeaturePacket({
+                    repoRoot: path.resolve(options.repo),
+                    batchFile: path.resolve(options.batch),
+                    dryRun: options.dryRun ?? false,
+                })
+                : await scaffoldFeaturePacket({
+                    repoRoot: path.resolve(options.repo),
+                    dryRun: options.dryRun ?? false,
+                    feature: {
+                        featureId: options.featureId ?? "",
+                        title: options.title ?? "",
+                        template: (options.template ??
+                            ""),
+                        description: options.description,
+                        bePaths: options.bePath,
+                        fePaths: options.fePath,
+                        contractPath: options.contractPath,
+                        verifyCommands: options.verifyCommand,
+                    },
+                });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : renderFeatureScaffold(result));
+        }
+        catch (error) {
+            handleScaffoldCliError(error, options.json ?? false);
+        }
+    });
     feature
         .command("verify-final")
         .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
@@ -284,18 +406,30 @@ export function buildAgentWorkerProgram() {
         .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("--qa-evidence <path>", "Repo-local QA pass evidence (default: .harness/task-pool/evidence/<featureId>/qa-pass.json from verify-final)")
+        .option("--final-verification <path>", "Repo-local final verification evidence (default: .../final-verification.json from verify-final)")
         .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 featureDir = path.resolve(options.featureDir);
+        const repoRoot = path.resolve(options.repo);
+        // ADR 0007: default to verify-final evidence locations when omitted.
+        let qaEvidencePath = options.qaEvidence;
+        let finalVerificationPath = options.finalVerification;
+        if (!qaEvidencePath || !finalVerificationPath) {
+            const validation = await validateFeatureTaskGraph(featureDir);
+            const defaults = defaultFeatureEvidencePaths(validation.featureId);
+            qaEvidencePath = qaEvidencePath ?? defaults.qaEvidencePath;
+            finalVerificationPath =
+                finalVerificationPath ?? defaults.finalVerificationPath;
+        }
         const result = await prepareFeatureDelivery({
-            featureDir: path.resolve(options.featureDir),
-            repoRoot: path.resolve(options.repo),
-            qaEvidencePath: options.qaEvidence,
-            finalVerificationPath: options.finalVerification,
+            featureDir,
+            repoRoot,
+            qaEvidencePath,
+            finalVerificationPath,
             ...(options.waivers ? { waiverPath: options.waivers } : {}),
             dryRun: options.dryRun ?? false,
         });
@@ -743,6 +877,42 @@ function handlePoolRecoveryCliError(error) {
     process.stderr.write(`${detail}\n`);
     process.exitCode = 1;
 }
+function handleScaffoldCliError(error, json) {
+    const code = error instanceof ScaffoldError ? error.code : "write-failed";
+    const message = error instanceof Error ? error.message : String(error);
+    const details = error instanceof ScaffoldError ? error.details : undefined;
+    if (json) {
+        process.stdout.write(`${JSON.stringify({
+            schemaVersion: 1,
+            ok: false,
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+    process.exitCode = 1;
+}
+function renderFeatureScaffold(result) {
+    const lines = [
+        result.dryRun
+            ? `Feature scaffold dry-run: ${result.features.length} packet(s) validated`
+            : `Feature scaffold wrote ${result.features.length} packet(s)`,
+        "",
+    ];
+    for (const feature of result.features) {
+        lines.push(`- ${feature.featureId} [${feature.template}] → ${feature.featureDir}`);
+    }
+    if (!result.dryRun && result.writtenPaths.length > 0) {
+        lines.push("", "Written:");
+        for (const p of result.writtenPaths)
+            lines.push(`  ${p}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
 function handleFollowUpCliError(error, json, action) {
     const detail = error instanceof Error ? error.message : String(error);
     if (!json)

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

@@ -16,6 +16,18 @@ import { preflightTargetRepo } from "../preflight.js";
 import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
 import { buildFeatureVerificationBundle, writeFeatureVerificationBundle, } from "./verification-bundle.js";
 const execFileAsync = promisify(execFile);
+/**
+ * Canonical Delivery evidence locations written by `feature verify-final`
+ * (ADR 0007). Paths are repo-relative with forward slashes.
+ */
+export function defaultFeatureEvidencePaths(featureId) {
+    const base = `.harness/task-pool/evidence/${featureId}`;
+    return {
+        qaEvidencePath: `${base}/qa-pass.json`,
+        finalVerificationPath: `${base}/final-verification.json`,
+        bundleEvidencePath: `${base}/feature-verification-bundle.json`,
+    };
+}
 export async function runFeatureFinalVerification(input) {
     const dependencies = {
         preflight: preflightTargetRepo,

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 "○";
+    }
+}