@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/task/worktree.js

@@ -0,0 +1,388 @@
+import { createHash, randomBytes } from "node:crypto";
+import { access, appendFile, mkdir, readFile, realpath, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+const OWNERSHIP_FILENAME = ".loop-agent-worktree-ownership.json";
+/**
+ * Resolve the worktree root directory from a harness manifest.
+ * Falls back to `<repoRoot>/.worktrees` when not configured.
+ */
+export function resolveWorktreeRoot(repoRoot, manifest) {
+    const relativePath = manifest?.worktree?.rootRelativePath ?? ".worktrees";
+    return path.resolve(repoRoot, relativePath);
+}
+/**
+ * Resolve the worktree directory path for a given taskId.
+ */
+export function resolveWorktreePath(repoRoot, manifest, taskId) {
+    const root = resolveWorktreeRoot(repoRoot, manifest);
+    return path.join(root, taskId);
+}
+/**
+ * Resolve repoRoot to its real path (resolving symlinks) so that paths match
+ * what `git worktree list --porcelain` returns (e.g. /tmp → /private/tmp on macOS).
+ */
+async function resolveRepoRoot(repoRoot) {
+    try {
+        return await realpath(repoRoot);
+    }
+    catch {
+        return repoRoot;
+    }
+}
+/**
+ * Create a new git worktree for a task.
+ *
+ * @returns The created worktree path, branch name, and base ref.
+ */
+export async function createWorktree(repoRoot, manifest, opts) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const worktreePath = resolveWorktreePath(resolvedRoot, manifest, opts.taskId);
+    const branch = opts.branch ?? `task/${opts.taskId}`;
+    const base = opts.base ?? "HEAD";
+    // Check if worktree path already exists
+    try {
+        await access(worktreePath);
+        throw new Error(`worktree path already exists: ${worktreePath}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    // Ensure parent directory exists
+    await mkdir(path.dirname(worktreePath), { recursive: true });
+    // Build git worktree add arguments
+    const addArgs = ["worktree", "add", worktreePath];
+    // Check if branch already exists; if so, don't pass -b
+    const branchExists = await gitBranchExists(resolvedRoot, branch);
+    if (!branchExists) {
+        addArgs.push("-b", branch);
+    }
+    addArgs.push(base);
+    await runGit(resolvedRoot, addArgs);
+    return { path: worktreePath, branch, base };
+}
+/**
+ * Idempotent ensure for a schedule-owned worktree.
+ * Validates path ↔ branch ↔ baseCommit and ownership token; never reuses an
+ * unowned path/branch with the same names.
+ */
+export async function ensureOwnedWorktree(repoRoot, options) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const worktreePath = resolveAgainstCanonicalRepoRoot(repoRoot, resolvedRoot, options.worktreePath);
+    assertOwnedWorktreePath(resolvedRoot, worktreePath);
+    const ownershipPath = path.join(worktreePath, OWNERSHIP_FILENAME);
+    const now = options.now ?? new Date();
+    let pathExists = false;
+    try {
+        await access(worktreePath);
+        pathExists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (pathExists) {
+        const ownership = await readOwnershipRecord(ownershipPath);
+        if (!ownership) {
+            throw new Error(`worktree path exists without ownership record: ${worktreePath}`);
+        }
+        if (ownership.scheduleId !== options.scheduleId) {
+            throw new Error(`worktree ownership schedule mismatch: expected ${options.scheduleId}, found ${ownership.scheduleId}`);
+        }
+        if (options.ownershipToken &&
+            ownership.ownershipToken !== options.ownershipToken) {
+            throw new Error(`worktree ownership token mismatch at ${worktreePath}`);
+        }
+        if (ownership.branch !== options.branch ||
+            ownership.baseCommit !== options.baseCommit ||
+            ownership.baseBranch !== options.baseBranch) {
+            throw new Error(`worktree ownership triple mismatch at ${worktreePath}: expected branch=${options.branch} base=${options.baseBranch}@${options.baseCommit}`);
+        }
+        const entries = await listWorktrees(resolvedRoot);
+        const registered = entries.find((entry) => path.normalize(entry.path) === path.normalize(worktreePath));
+        if (!registered) {
+            throw new Error(`worktree path exists but is not registered in git worktree list: ${worktreePath}`);
+        }
+        if (registered.branch && registered.branch !== options.branch) {
+            throw new Error(`worktree registry branch mismatch: expected ${options.branch}, found ${registered.branch}`);
+        }
+        const head = (await runGit(worktreePath, ["rev-parse", "HEAD"])).trim();
+        if (head !== options.baseCommit) {
+            throw new Error(`worktree HEAD drift at ${worktreePath}: expected ${options.baseCommit}, found ${head}`);
+        }
+        await ensureOwnershipFileIgnored(worktreePath);
+        return {
+            path: worktreePath,
+            branch: options.branch,
+            baseBranch: options.baseBranch,
+            baseCommit: options.baseCommit,
+            ownershipToken: ownership.ownershipToken,
+            created: false,
+            reused: true,
+            head,
+        };
+    }
+    // Create path: branch must not already exist without our ownership.
+    const branchExists = await gitBranchExists(resolvedRoot, options.branch);
+    if (branchExists) {
+        throw new Error(`branch already exists without owned worktree: ${options.branch}`);
+    }
+    await mkdir(path.dirname(worktreePath), { recursive: true });
+    await runGit(resolvedRoot, [
+        "worktree",
+        "add",
+        worktreePath,
+        "-b",
+        options.branch,
+        options.baseCommit,
+    ]);
+    const ownershipToken = options.ownershipToken ??
+        `sha256:${createHash("sha256")
+            .update(`${options.scheduleId}\0${options.branch}\0${options.baseCommit}\0${randomBytes(8).toString("hex")}`)
+            .digest("hex")}`;
+    const ownership = {
+        schemaVersion: 1,
+        scheduleId: options.scheduleId,
+        branch: options.branch,
+        baseBranch: options.baseBranch,
+        baseCommit: options.baseCommit,
+        ownershipToken,
+        createdAt: now.toISOString(),
+        worktreePath,
+    };
+    await writeFile(ownershipPath, `${JSON.stringify(ownership, null, 2)}\n`, "utf-8");
+    await ensureOwnershipFileIgnored(worktreePath);
+    const head = (await runGit(worktreePath, ["rev-parse", "HEAD"])).trim();
+    return {
+        path: worktreePath,
+        branch: options.branch,
+        baseBranch: options.baseBranch,
+        baseCommit: options.baseCommit,
+        ownershipToken,
+        created: true,
+        reused: false,
+        head,
+    };
+}
+export async function readWorktreeOwnership(worktreePath) {
+    return readOwnershipRecord(path.join(worktreePath, OWNERSHIP_FILENAME));
+}
+export async function verifyOwnedWorktree(input) {
+    const resolvedRoot = await resolveRepoRoot(input.repoRoot);
+    const worktreePath = resolveAgainstCanonicalRepoRoot(input.repoRoot, resolvedRoot, input.worktreePath);
+    assertOwnedWorktreePath(resolvedRoot, worktreePath);
+    const ownership = await readWorktreeOwnership(worktreePath);
+    if (!ownership) {
+        throw new Error(`missing worktree ownership at ${worktreePath}`);
+    }
+    if (ownership.scheduleId !== input.scheduleId) {
+        throw new Error(`worktree ownership schedule mismatch: expected ${input.scheduleId}, found ${ownership.scheduleId}`);
+    }
+    if (ownership.ownershipToken !== input.ownershipToken) {
+        throw new Error(`worktree ownership token mismatch at ${worktreePath}`);
+    }
+    if (ownership.branch !== input.branch ||
+        ownership.baseCommit !== input.baseCommit) {
+        throw new Error(`worktree ownership branch/base mismatch at ${worktreePath}`);
+    }
+    const entries = await listWorktrees(resolvedRoot);
+    const registered = entries.find((entry) => path.normalize(entry.path) === path.normalize(worktreePath));
+    if (!registered) {
+        throw new Error(`worktree not registered: ${worktreePath}`);
+    }
+    if (registered.branch && registered.branch !== input.branch) {
+        throw new Error(`worktree registry branch mismatch: expected ${input.branch}, found ${registered.branch}`);
+    }
+    const head = (await runGit(worktreePath, ["rev-parse", "HEAD"])).trim();
+    if (head !== input.baseCommit) {
+        throw new Error(`worktree HEAD drift at ${worktreePath}: expected ${input.baseCommit}, found ${head}`);
+    }
+    await ensureOwnershipFileIgnored(worktreePath);
+    return { head, ownership };
+}
+/**
+ * List git worktrees by parsing `git worktree list --porcelain`.
+ */
+export async function listWorktrees(repoRoot) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const stdout = await runGit(resolvedRoot, [
+        "worktree",
+        "list",
+        "--porcelain",
+    ]);
+    const entries = [];
+    const blocks = stdout.split("\n\n").filter((b) => b.trim().length > 0);
+    for (const block of blocks) {
+        const lines = block.trim().split("\n");
+        let entryPath = "";
+        let branch;
+        let head = "";
+        let bare = false;
+        let locked = false;
+        for (const line of lines) {
+            if (line.startsWith("worktree ")) {
+                entryPath = line.slice("worktree ".length);
+            }
+            else if (line.startsWith("branch ")) {
+                const ref = line.slice("branch ".length);
+                // Convert refs/heads/<name> to <name>
+                branch = ref.replace(/^refs\/heads\//, "");
+            }
+            else if (line.startsWith("HEAD ")) {
+                head = line.slice("HEAD ".length);
+            }
+            else if (line === "bare") {
+                bare = true;
+            }
+            else if (line === "locked") {
+                locked = true;
+            }
+        }
+        if (entryPath) {
+            entries.push({
+                path: path.normalize(entryPath),
+                branch,
+                head,
+                bare,
+                locked,
+            });
+        }
+    }
+    return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Remove a git worktree.
+ * Either `taskId` or `path` must be provided.
+ */
+export async function removeWorktree(repoRoot, manifest, opts) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const worktreePath = opts.path ??
+        (opts.taskId
+            ? resolveWorktreePath(resolvedRoot, manifest, opts.taskId)
+            : undefined);
+    if (!worktreePath) {
+        throw new Error("removeWorktree requires either taskId or path");
+    }
+    const removeArgs = ["worktree", "remove"];
+    if (opts.force) {
+        removeArgs.push("--force");
+    }
+    removeArgs.push(worktreePath);
+    await runGit(resolvedRoot, removeArgs);
+    // Optionally delete the branch
+    if (opts.deleteBranch && opts.taskId) {
+        const branch = `task/${opts.taskId}`;
+        try {
+            await runGit(resolvedRoot, ["branch", "-d", branch]);
+        }
+        catch {
+            // Branch may already be deleted or not exist; ignore
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run a git command and return stdout. Throws on non-zero exit.
+ */
+async function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", (err) => {
+            reject(new Error(`git ${args.join(" ")} spawn error: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+            const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+            if (code !== 0) {
+                reject(new Error(`git ${args.join(" ")} failed (exit ${code}): ${stderr.trim()}`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/**
+ * Check if a branch exists in the local git repository.
+ */
+async function gitBranchExists(cwd, branchName) {
+    try {
+        const stdout = await runGit(cwd, ["branch", "--list", branchName]);
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveAgainstCanonicalRepoRoot(providedRepoRoot, resolvedRepoRoot, candidatePath) {
+    if (!path.isAbsolute(candidatePath)) {
+        return path.resolve(resolvedRepoRoot, candidatePath);
+    }
+    const relativeToProvided = path.relative(path.resolve(providedRepoRoot), path.resolve(candidatePath));
+    if (!relativeToProvided.startsWith("..") &&
+        !path.isAbsolute(relativeToProvided)) {
+        return path.resolve(resolvedRepoRoot, relativeToProvided);
+    }
+    return path.resolve(candidatePath);
+}
+function assertOwnedWorktreePath(resolvedRepoRoot, worktreePath) {
+    const worktreeRoot = path.resolve(resolvedRepoRoot, ".worktrees");
+    const relative = path.relative(worktreeRoot, path.resolve(worktreePath));
+    if (relative.length === 0 ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new Error(`owned worktree path must be a child of ${worktreeRoot}: ${worktreePath}`);
+    }
+}
+async function ensureOwnershipFileIgnored(worktreePath) {
+    const excludeRef = (await runGit(worktreePath, ["rev-parse", "--git-path", "info/exclude"])).trim();
+    const excludePath = path.isAbsolute(excludeRef)
+        ? excludeRef
+        : path.resolve(worktreePath, excludeRef);
+    const ignoreLine = `/${OWNERSHIP_FILENAME}`;
+    let existing = "";
+    try {
+        existing = await readFile(excludePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .includes(ignoreLine)) {
+        return;
+    }
+    await mkdir(path.dirname(excludePath), { recursive: true });
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await appendFile(excludePath, `${separator}${ignoreLine}\n`, "utf-8");
+}
+async function readOwnershipRecord(ownershipPath) {
+    try {
+        const raw = await readFile(ownershipPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.schemaVersion !== 1 ||
+            typeof parsed.scheduleId !== "string" ||
+            typeof parsed.ownershipToken !== "string" ||
+            typeof parsed.branch !== "string" ||
+            typeof parsed.baseCommit !== "string") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}

package/dist/verification/maven/cache.js

@@ -0,0 +1,142 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { MAVEN_CACHE_SCHEMA_VERSION, MAVEN_PLANNER_VERSION, } from "./types.js";
+import { buildMavenWorkspaceGraph } from "./workspace-graph.js";
+const CACHE_FILE_NAME = "maven-workspace-graph.json";
+/** Directory names ignored during discovery and lightweight entry-list checks. */
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    ".harness",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+    "coverage",
+    ".turbo",
+    ".next",
+]);
+export function defaultMavenCacheDir(repoRoot) {
+    return path.join(repoRoot, ".harness", "cache");
+}
+export function mavenGraphCachePath(cacheDir) {
+    return path.join(cacheDir, CACHE_FILE_NAME);
+}
+function isValidCachedGraph(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const graph = value;
+    return (graph.schemaVersion === MAVEN_CACHE_SCHEMA_VERSION &&
+        graph.plannerVersion === MAVEN_PLANNER_VERSION &&
+        typeof graph.fingerprint === "string" &&
+        Array.isArray(graph.pomPaths) &&
+        Array.isArray(graph.nodes));
+}
+/**
+ * Lightweight freshness probe: only stat previously recorded directories and
+ * file metadata. Does NOT re-walk the whole tree or re-parse POMs.
+ * Returns true when the cached graph can be reused as-is.
+ */
+export function isCachedGraphStillFresh(repoRoot, graph) {
+    if (graph.schemaVersion !== MAVEN_CACHE_SCHEMA_VERSION ||
+        graph.plannerVersion !== MAVEN_PLANNER_VERSION) {
+        return false;
+    }
+    const manifest = graph.manifest;
+    if (!manifest) {
+        // Old cache shape without manifest cannot prove lightweight freshness.
+        return false;
+    }
+    // Directory entry lists: any add/remove invalidates.
+    for (const dir of manifest.directories) {
+        const absDir = dir.path === "" ? repoRoot : path.join(repoRoot, ...dir.path.split("/"));
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true })
+                .filter((e) => {
+                if (SKIP_DIR_NAMES.has(e.name))
+                    return false;
+                try {
+                    return !e.isSymbolicLink();
+                }
+                catch {
+                    return true;
+                }
+            })
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            return false;
+        }
+        if (entries.length !== dir.entryNames.length)
+            return false;
+        for (let i = 0; i < entries.length; i += 1) {
+            if (entries[i] !== dir.entryNames[i])
+                return false;
+        }
+    }
+    // File metadata: size/mtime change triggers rebuild (content re-hash on rebuild).
+    for (const file of manifest.files) {
+        const abs = path.join(repoRoot, ...file.path.split("/"));
+        try {
+            const lst = lstatSync(abs);
+            if (lst.isSymbolicLink())
+                return false;
+            const st = statSync(abs);
+            if (st.size !== file.size)
+                return false;
+            if (st.mtimeMs !== file.mtimeMs)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Load cached graph when schema/planner versions match and lightweight
+ * directory/file metadata is unchanged. Full parse only on miss/stale.
+ */
+export function loadOrBuildMavenWorkspaceGraph(input) {
+    const cacheDir = input.cacheDir ?? defaultMavenCacheDir(input.repoRoot);
+    const cachePath = mavenGraphCachePath(cacheDir);
+    if (existsSync(cachePath)) {
+        try {
+            const raw = JSON.parse(readFileSync(cachePath, "utf8"));
+            if (isValidCachedGraph(raw) && isCachedGraphStillFresh(input.repoRoot, raw)) {
+                return raw;
+            }
+        }
+        catch {
+            // Fall through to rebuild.
+        }
+    }
+    const graph = buildMavenWorkspaceGraph(input.repoRoot);
+    writeGraphCache(cacheDir, graph);
+    return graph;
+}
+export function writeGraphCache(cacheDir, graph) {
+    mkdirSync(cacheDir, { recursive: true });
+    const payload = `${JSON.stringify(graph, null, 2)}\n`;
+    // Guard: never persist absolute host paths.
+    if (/[A-Za-z]:[\\/]/.test(payload) || payload.includes("\\\\")) {
+        // Absolute Windows paths are forbidden; re-check using graph fields only.
+        const serialized = JSON.stringify({
+            schemaVersion: graph.schemaVersion,
+            plannerVersion: graph.plannerVersion,
+            fingerprint: graph.fingerprint,
+            pomPaths: graph.pomPaths,
+            wrapperPaths: graph.wrapperPaths,
+            nodes: graph.nodes,
+            reactors: graph.reactors,
+            reactorRootByPomPath: graph.reactorRootByPomPath,
+            manifest: graph.manifest,
+        });
+        writeFileSync(mavenGraphCachePath(cacheDir), `${serialized}\n`, "utf8");
+        return;
+    }
+    writeFileSync(mavenGraphCachePath(cacheDir), payload, "utf8");
+}

package/dist/verification/maven/index.js

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { loadOrBuildMavenWorkspaceGraph } from "./cache.js";
+import { commandContainsMaven, extractExplicitMavenFile, parseMavenInvocation, planMavenCommands, } from "./plan-commands.js";
+import { resolveMavenTargets } from "./scope-resolve.js";
+import { assertMavenPlanFresh } from "./stale.js";
+import { MAVEN_CACHE_SCHEMA_VERSION, MAVEN_PLANNER_VERSION, MavenPlanError, MavenPlanStaleError, } from "./types.js";
+export { MAVEN_CACHE_SCHEMA_VERSION, MAVEN_PLANNER_VERSION, MavenPlanError, MavenPlanStaleError, assertMavenPlanFresh, };
+function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+function allMavenCommandsHaveExplicitFile(commands) {
+    const mavenCommands = commands.filter(commandContainsMaven);
+    if (mavenCommands.length === 0)
+        return false;
+    return mavenCommands.every((command) => {
+        const parsed = parseMavenInvocation(command);
+        if (!parsed)
+            return false;
+        return extractExplicitMavenFile(parsed.mavenArgs) !== undefined;
+    });
+}
+function targetsFromExplicitFiles(input) {
+    const byPom = new Map();
+    for (const command of input.commands) {
+        const parsed = parseMavenInvocation(command);
+        if (!parsed)
+            continue;
+        const explicit = extractExplicitMavenFile(parsed.mavenArgs);
+        if (!explicit)
+            continue;
+        // Resolve relative -f against the original command cwd.
+        const baseCwd = command.cwd ?? input.repoRoot;
+        const absolute = path.isAbsolute(explicit)
+            ? path.normalize(explicit)
+            : path.resolve(baseCwd, explicit);
+        const rel = toPosix(path.relative(input.repoRoot, absolute));
+        if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+            // Keep unresolved path for planMavenCommands validation/fail-fast.
+            byPom.set(toPosix(explicit), {
+                pomPath: toPosix(explicit),
+                artifactId: path.posix.basename(toPosix(explicit).replace(/\/pom\.xml$/i, "")) || "unknown",
+            });
+            continue;
+        }
+        const node = input.graph.nodes.find((n) => n.pomPath === rel);
+        if (node) {
+            const reactorRoot = input.graph.reactorRootByPomPath[node.pomPath];
+            if (reactorRoot && reactorRoot !== node.pomPath) {
+                const reactor = input.graph.reactors.find((r) => r.rootPomPath === reactorRoot);
+                byPom.set(node.pomPath, {
+                    pomPath: node.pomPath,
+                    artifactId: node.artifactId,
+                    reactorRootPomPath: reactorRoot,
+                    moduleCoordinate: reactor?.modulePathByPomPath?.[node.pomPath] ??
+                        reactor?.artifactIdByPomPath[node.pomPath] ??
+                        node.artifactId,
+                });
+            }
+            else {
+                byPom.set(node.pomPath, {
+                    pomPath: node.pomPath,
+                    artifactId: node.artifactId,
+                    reactorRootPomPath: reactorRoot === node.pomPath ? reactorRoot : undefined,
+                });
+            }
+        }
+        else {
+            const base = rel.replace(/\/pom\.xml$/i, "");
+            const artifactId = base.split("/").filter(Boolean).pop() ?? rel;
+            byPom.set(rel, { pomPath: rel, artifactId });
+        }
+    }
+    return [...byPom.values()];
+}
+/**
+ * Plan Maven verification commands from task scope + static workspace graph.
+ * Non-Maven commands are returned unchanged. Returns plan=null when no Maven
+ * commands are present (REQ-MVN-007).
+ */
+export function planMavenVerification(input) {
+    const mavenCommands = input.commands.filter(commandContainsMaven);
+    if (mavenCommands.length === 0) {
+        return { commands: input.commands, plan: null };
+    }
+    const graph = loadOrBuildMavenWorkspaceGraph({
+        repoRoot: input.repoRoot,
+        cacheDir: input.cacheDir,
+    });
+    if (graph.pomPaths.length === 0) {
+        throw new MavenPlanError("Maven verification is requested but no pom.xml was found in the repository.", { code: "maven-no-pom" });
+    }
+    // When every Maven command already carries a resolvable -f, skip automatic
+    // scope target resolution (wide/empty scope must not block explicit targets).
+    const targets = allMavenCommandsHaveExplicitFile(input.commands)
+        ? targetsFromExplicitFiles({
+            repoRoot: input.repoRoot,
+            commands: input.commands,
+            graph,
+        })
+        : resolveMavenTargets({
+            graph,
+            scope: input.scope,
+        });
+    const planned = planMavenCommands({
+        repoRoot: input.repoRoot,
+        commands: input.commands,
+        targets,
+        graph,
+        scope: input.scope,
+    });
+    // Ensure planned commands keep original repoRoot cwd (explicit -f, not module cd).
+    const commands = planned.commands.map((command) => ({
+        ...command,
+        cwd: input.repoRoot,
+    }));
+    return {
+        commands,
+        plan: planned.plan,
+    };
+}