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

package/dist/verification/maven/workspace-graph.js

@@ -0,0 +1,322 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import path from "node:path";
+import { readStaticPomFile, repoRelativePosix } from "./pom-static.js";
+import { MAVEN_CACHE_SCHEMA_VERSION, MAVEN_PLANNER_VERSION, MavenPlanError, } from "./types.js";
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    ".harness",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+    "coverage",
+    ".turbo",
+    ".next",
+]);
+const WRAPPER_BASENAMES = new Set([
+    "mvnw",
+    "mvnw.cmd",
+    "mvnw.bat",
+    "maven-wrapper.properties",
+    "maven-wrapper.jar",
+]);
+function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+/**
+ * Walk repository files using Dirent and do not follow directory/file symlinks.
+ * Captures every successfully scanned directory in the same pass so cache-hit
+ * checks can detect a POM or wrapper added below a previously empty directory.
+ */
+function walkFiles(root) {
+    const files = [];
+    const directories = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        directories.push({
+            path: current,
+            entryNames: entries
+                .filter((entry) => !entry.isSymbolicLink() && !SKIP_DIR_NAMES.has(entry.name))
+                .map((entry) => entry.name)
+                .sort(),
+        });
+        for (const entry of entries) {
+            if (SKIP_DIR_NAMES.has(entry.name))
+                continue;
+            // Never follow symlinks (dir or file).
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = path.join(current, entry.name);
+            // Double-check with lstat in case platform Dirent is incomplete.
+            try {
+                const lst = lstatSync(absolute);
+                if (lst.isSymbolicLink())
+                    continue;
+                if (lst.isDirectory()) {
+                    stack.push(absolute);
+                }
+                else if (lst.isFile()) {
+                    files.push(absolute);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return { files, directories };
+}
+function isPomFile(filePath) {
+    return path.basename(filePath).toLowerCase() === "pom.xml";
+}
+function isWrapperFile(filePath) {
+    const base = path.basename(filePath).toLowerCase();
+    if (WRAPPER_BASENAMES.has(base))
+        return true;
+    const posix = toPosix(filePath).toLowerCase();
+    return posix.endsWith("/.mvn/wrapper/maven-wrapper.properties");
+}
+function contentSha(absolutePath) {
+    const buf = readFileSync(absolutePath);
+    return createHash("sha256").update(buf).digest("hex");
+}
+function resolveModulePomPath(repoRoot, parentDir, moduleDecl) {
+    const absDir = path.resolve(repoRoot, parentDir, moduleDecl);
+    const candidates = [
+        path.join(absDir, "pom.xml"),
+        // moduleDecl may already point at a pom file
+        absDir.endsWith("pom.xml") ? absDir : null,
+    ].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+        try {
+            const lst = lstatSync(candidate);
+            if (lst.isSymbolicLink())
+                continue;
+            if (lst.isFile()) {
+                return repoRelativePosix(repoRoot, candidate);
+            }
+        }
+        catch {
+            // try next
+        }
+    }
+    return null;
+}
+/**
+ * Build reactor graphs with transitive nested aggregator membership.
+ * -pl coordinates are module paths relative to the reactor root, not bare artifactIds.
+ */
+function buildReactors(repoRoot, nodes) {
+    const byPom = new Map(nodes.map((node) => [node.pomPath, node]));
+    const reactors = [];
+    // Prefer outermost reactor root for each member when nested.
+    const reactorRootByPomPath = {};
+    const rootDepth = new Map();
+    for (const node of nodes) {
+        if (node.modules.length === 0)
+            continue;
+        const modulePomByArtifactId = {};
+        const artifactIdByPomPath = {
+            [node.pomPath]: node.artifactId,
+        };
+        const modulePathByPomPath = {};
+        const pomPaths = new Set([node.pomPath]);
+        const queue = node.modules.map((moduleDecl) => ({
+            parentNode: node,
+            moduleDecl,
+            pathFromRoot: toPosix(moduleDecl).replace(/\/+$/, ""),
+            stack: [node.pomPath],
+        }));
+        const seenEdges = new Set();
+        while (queue.length > 0) {
+            const item = queue.shift();
+            const edgeKey = `${item.parentNode.pomPath}=>${item.moduleDecl}`;
+            if (seenEdges.has(edgeKey))
+                continue;
+            seenEdges.add(edgeKey);
+            if (item.stack.includes(item.parentNode.pomPath) && item.stack.length > 1) {
+                // stack already contains parent from deeper cycle checks below
+            }
+            const modulePom = resolveModulePomPath(repoRoot, item.parentNode.dir, item.moduleDecl);
+            if (!modulePom) {
+                throw new MavenPlanError(`Reactor module path cannot be resolved statically from ${item.parentNode.pomPath}: ${item.moduleDecl}`, {
+                    code: "maven-reactor-module-missing",
+                    candidates: [item.parentNode.pomPath, item.moduleDecl],
+                });
+            }
+            if (item.stack.includes(modulePom)) {
+                throw new MavenPlanError(`Cyclic reactor module relationship detected involving ${modulePom}`, {
+                    code: "maven-reactor-cycle",
+                    candidates: [...item.stack, modulePom],
+                });
+            }
+            const moduleNode = byPom.get(modulePom);
+            if (!moduleNode) {
+                throw new MavenPlanError(`Reactor module POM was not discovered: ${modulePom}`, { code: "maven-reactor-module-missing", candidates: [modulePom] });
+            }
+            // module path relative to reactor root (for -pl)
+            const modulePath = item.pathFromRoot
+                .replace(/\/pom\.xml$/i, "")
+                .replace(/^\.\//, "");
+            if (modulePomByArtifactId[moduleNode.artifactId] &&
+                modulePomByArtifactId[moduleNode.artifactId] !== modulePom) {
+                throw new MavenPlanError(`Duplicate artifactId '${moduleNode.artifactId}' in reactor ${node.pomPath}`, {
+                    code: "maven-reactor-duplicate-artifactId",
+                    candidates: [
+                        modulePomByArtifactId[moduleNode.artifactId],
+                        modulePom,
+                    ],
+                });
+            }
+            modulePomByArtifactId[moduleNode.artifactId] = modulePom;
+            artifactIdByPomPath[modulePom] = moduleNode.artifactId;
+            modulePathByPomPath[modulePom] = modulePath;
+            pomPaths.add(modulePom);
+            // Recurse into nested aggregator modules.
+            for (const childDecl of moduleNode.modules) {
+                const childPath = toPosix(path.posix.join(modulePath, toPosix(childDecl))).replace(/\\/g, "/");
+                queue.push({
+                    parentNode: moduleNode,
+                    moduleDecl: childDecl,
+                    pathFromRoot: childPath,
+                    stack: [...item.stack, modulePom],
+                });
+            }
+        }
+        const reactor = {
+            rootPomPath: node.pomPath,
+            modulePomByArtifactId,
+            artifactIdByPomPath,
+            // Store module path coordinates for -pl via artifactIdByPomPath values when
+            // consumers need paths: expose via modulePathByPomPath on the side channel.
+            pomPaths: [...pomPaths].sort(),
+            // Extended field kept optional for schema compatibility via cast below.
+            ...(Object.keys(modulePathByPomPath).length > 0
+                ? { modulePathByPomPath }
+                : {}),
+        };
+        // Attach modulePathByPomPath for planners (types extended separately).
+        reactor
+            .modulePathByPomPath = modulePathByPomPath;
+        reactors.push(reactor);
+        // Register membership: prefer outermost (shallower path depth) reactor root.
+        const depth = node.pomPath.split("/").length;
+        for (const member of pomPaths) {
+            const existing = reactorRootByPomPath[member];
+            if (!existing) {
+                reactorRootByPomPath[member] = node.pomPath;
+                rootDepth.set(member, depth);
+                continue;
+            }
+            const existingDepth = rootDepth.get(member) ?? Number.MAX_SAFE_INTEGER;
+            if (depth < existingDepth) {
+                reactorRootByPomPath[member] = node.pomPath;
+                rootDepth.set(member, depth);
+            }
+        }
+    }
+    return { reactors, reactorRootByPomPath };
+}
+/**
+ * Statically discover all POMs and wrappers under the repository.
+ * Never executes Maven goals. Does not follow symlinks.
+ */
+/** Test/probe counter: increments only on full walk+parse builds. */
+let fullBuildCount = 0;
+export function getMavenFullBuildCount() {
+    return fullBuildCount;
+}
+export function resetMavenFullBuildCount() {
+    fullBuildCount = 0;
+}
+export function buildMavenWorkspaceGraph(repoRoot) {
+    if (!existsSync(repoRoot)) {
+        throw new MavenPlanError(`Repository root does not exist: ${repoRoot}`, {
+            code: "maven-repo-missing",
+        });
+    }
+    fullBuildCount += 1;
+    const walk = walkFiles(repoRoot);
+    const allFiles = walk.files;
+    const pomAbs = allFiles.filter(isPomFile).sort();
+    const wrapperAbs = allFiles.filter(isWrapperFile).sort();
+    const nodes = [];
+    const fingerprintParts = [];
+    const fileMeta = [];
+    const dirMeta = walk.directories.map((directory) => ({
+        path: directory.path === repoRoot
+            ? ""
+            : repoRelativePosix(repoRoot, directory.path),
+        entryNames: directory.entryNames,
+    }));
+    for (const abs of pomAbs) {
+        const pomPath = repoRelativePosix(repoRoot, abs);
+        const fields = readStaticPomFile(abs);
+        const st = statSync(abs);
+        const dir = toPosix(path.posix.dirname(pomPath));
+        nodes.push({
+            pomPath,
+            dir: dir === "." ? "" : dir,
+            artifactId: fields.artifactId,
+            groupId: fields.groupId,
+            packaging: fields.packaging,
+            modules: fields.modules,
+            parentRelativePath: fields.parentRelativePath,
+        });
+        const sha = contentSha(abs);
+        fingerprintParts.push(`pom:${pomPath}:${sha}`);
+        fileMeta.push({
+            path: pomPath,
+            size: st.size,
+            mtimeMs: st.mtimeMs,
+        });
+    }
+    const wrapperPaths = [];
+    for (const abs of wrapperAbs) {
+        const rel = repoRelativePosix(repoRoot, abs);
+        wrapperPaths.push(rel);
+        const st = statSync(abs);
+        const sha = contentSha(abs);
+        fingerprintParts.push(`wrapper:${rel}:${sha}`);
+        fileMeta.push({
+            path: rel,
+            size: st.size,
+            mtimeMs: st.mtimeMs,
+        });
+    }
+    fingerprintParts.sort();
+    const fingerprint = createHash("sha256")
+        .update(fingerprintParts.join("\n"))
+        .update(`\nplanner:${MAVEN_PLANNER_VERSION}`)
+        .update(`\nschema:${MAVEN_CACHE_SCHEMA_VERSION}`)
+        .digest("hex");
+    const { reactors, reactorRootByPomPath } = buildReactors(repoRoot, nodes);
+    return {
+        schemaVersion: MAVEN_CACHE_SCHEMA_VERSION,
+        plannerVersion: MAVEN_PLANNER_VERSION,
+        fingerprint,
+        pomPaths: nodes.map((n) => n.pomPath).sort(),
+        wrapperPaths: wrapperPaths.sort(),
+        nodes,
+        reactors,
+        reactorRootByPomPath,
+        manifest: {
+            files: fileMeta.sort((a, b) => a.path.localeCompare(b.path)),
+            directories: dirMeta.sort((a, b) => a.path.localeCompare(b.path)),
+        },
+    };
+}
+export function computeWorkspaceFingerprint(repoRoot) {
+    return buildMavenWorkspaceGraph(repoRoot).fingerprint;
+}

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();
@@ -41,7 +44,8 @@ export function buildAgentWorkerProgram() {
         .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();
+        .showSuggestionAfterError()
+        .enablePositionalOptions();
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program
         .command("batch")
@@ -244,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/")
@@ -283,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,
         });
@@ -593,18 +728,17 @@ export function buildAgentWorkerProgram() {
         process.stdout.write(`${JSON.stringify(snapshot)}\n`);
     });
     consoleCmd
-        .command("serve")
-        .requiredOption("--repo <repo-root>", "Target repo root")
+        .description("Loop Operator Console (local); bare `agent-worker console` starts it directly (repo defaults to current working directory, port defaults to 8790)")
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
         .option("--port <port>", "HTTP port", "8790")
         .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
         .option("--debug", "Log request source/method/path/status to stderr")
         .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
-        .description("Start Loop Operator Console HTTP server (Operate + Inspect; static SPA + Operator API)")
         .action(async (options) => {
-        const { createConsoleServer } = await import("./console/server.js");
-        const repoRoot = path.resolve(options.repo);
-        const server = await createConsoleServer({
-            repoRoot,
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
             host: options.host,
             port: Number.parseInt(options.port, 10),
             debug: options.debug === true,
@@ -612,13 +746,25 @@ export function buildAgentWorkerProgram() {
                 ? path.resolve(options.appData)
                 : undefined,
         });
-        process.stdout.write(`${server.url}\n`);
-        await new Promise((resolve) => {
-            const shutdown = () => resolve();
-            process.once("SIGINT", shutdown);
-            process.once("SIGTERM", shutdown);
+    });
+    consoleCmd
+        .command("serve")
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
+        .option("--port <port>", "HTTP port", "8790")
+        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
+        .option("--debug", "Log request source/method/path/status to stderr")
+        .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
+        .description("Start Loop Operator Console HTTP server (compat entry; equivalent to bare `agent-worker console`)")
+        .action(async (options) => {
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
+            appDataRoot: options.appData
+                ? path.resolve(options.appData)
+                : undefined,
         });
-        await server.close();
     });
     consoleCmd
         .command("doctor")
@@ -693,11 +839,80 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+/** Shared console serve entry used by both bare `console` and `console serve`. */
+async function runConsoleServe(options) {
+    const { createConsoleServer } = await import("./console/server.js");
+    try {
+        const server = await createConsoleServer({
+            repoRoot: options.repoRoot,
+            host: options.host,
+            port: options.port,
+            debug: options.debug === true,
+            appDataRoot: options.appDataRoot,
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error?.code;
+        const isPortInUse = code === "EADDRINUSE" ||
+            /listen EADDRINUSE/i.test(detail) ||
+            /address already in use/i.test(detail);
+        if (isPortInUse) {
+            process.stderr.write(`端口 ${options.port} 已被占用，请使用 --port <port> 指定其它端口后重试。\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`${detail}\n`);
+        process.exit(1);
+    }
+}
 function handlePoolRecoveryCliError(error) {
     const detail = error instanceof Error ? error.message : String(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,