agentplane 0.3.10 → 0.3.12

package/dist/commands/branch/work-start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-start.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAiInC,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqJlB"}
+{"version":3,"file":"work-start.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.ts"],"names":[],"mappings":"AA0BA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAsRnC,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+JlB"}

package/dist/commands/branch/work-start.js

@@ -1,4 +1,4 @@
-import { copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { chmod, copyFile, cp, mkdir, readFile, readdir, rm, symlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
 import { resolveBaseBranch } from "@agentplaneorg/core";
 import { LocalBackend } from "../../backends/task-backend.js";
@@ -11,9 +11,40 @@ import { execFileAsync, gitEnv } from "../shared/git.js";
 import { gitAheadBehind } from "../shared/git-diff.js";
 import { gitBranchExists, gitBranchUpstream, gitCurrentBranch } from "../shared/git-ops.js";
 import { isPathWithin } from "../shared/path.js";
+import { resolveRuntimeSourceInfo } from "../../shared/runtime-source.js";
 import { loadBackendTask, loadCommandContext, } from "../shared/task-backend.js";
+function isPresentString(value) {
+    return value !== null;
+}
 import { ensurePlanApprovedIfRequired } from "../task/shared.js";
 import { validateWorkAgent, validateWorkSlug } from "./internal/work-validate.js";
+const HOOK_SHIM_MARKER = "agentplane-hook-shim";
+function repoLocalHookShimText() {
+    return [
+        "#!/usr/bin/env sh",
+        `# ${HOOK_SHIM_MARKER} (do not edit)`,
+        "set -e",
+        'SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"',
+        'REPO_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"',
+        'LOCAL_BIN="$REPO_ROOT/packages/agentplane/bin/agentplane.js"',
+        'if command -v node >/dev/null 2>&1 && [ -f "$LOCAL_BIN" ]; then',
+        '  exec node "$LOCAL_BIN" "$@"',
+        "fi",
+        'ENV_BIN="${AGENTPLANE_HOOK_RUNNER:-}"',
+        'if [ -n "$ENV_BIN" ] && command -v node >/dev/null 2>&1 && [ -f "$ENV_BIN" ]; then',
+        '  exec node "$ENV_BIN" "$@"',
+        "fi",
+        "if command -v agentplane >/dev/null 2>&1; then",
+        '  exec agentplane "$@"',
+        "fi",
+        "if command -v npx >/dev/null 2>&1; then",
+        '  exec npx --yes agentplane "$@"',
+        "fi",
+        'echo "agentplane shim: runner not found (need env runner, repo-local source, agentplane in PATH, or node+npx)." >&2',
+        "  exit 127",
+        "",
+    ].join("\n");
+}
 function directWorkLockPath(agentplaneDir) {
     // Intentionally under cache/ so it stays out of git by default.
     return path.join(agentplaneDir, "cache", "direct-work.json");
@@ -54,13 +85,108 @@ async function materializeLocalBackendReadmesForWorktree(opts) {
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        const sourceTaskRoot = path.join(sourceRoot, entry.name);
         const sourceReadme = path.join(sourceRoot, entry.name, "README.md");
         if (!(await fileExists(sourceReadme)))
             continue;
         const targetReadme = path.join(targetRoot, entry.name, "README.md");
         await mkdir(path.dirname(targetReadme), { recursive: true });
         await copyFile(sourceReadme, targetReadme);
+        if (entry.name !== opts.taskId)
+            continue;
+        // Hand off ownership of the active task README to the task worktree so
+        // later merges cannot collide with a stale untracked copy on the base checkout.
+        await rm(sourceReadme, { force: true });
+        const remainingEntries = await readdir(sourceTaskRoot).catch(() => []);
+        if (remainingEntries.length === 0) {
+            await rm(sourceTaskRoot, { recursive: true, force: true });
+        }
+    }
+}
+async function materializeRepoLocalDistForWorktree(opts) {
+    const runtimeSource = resolveRuntimeSourceInfo({ cwd: process.cwd() });
+    const sourceRoots = [
+        ...new Set([
+            path.resolve(opts.repoRoot),
+            path.resolve(process.cwd()),
+            runtimeSource.agentplane.packageRoot
+                ? path.resolve(runtimeSource.agentplane.packageRoot, "..", "..")
+                : null,
+        ].filter((value) => isPresentString(value))),
+    ];
+    const copyTargets = [
+        ["packages/core/dist", "packages/core/dist"],
+        ["packages/agentplane/dist", "packages/agentplane/dist"],
+        ["packages/agentplane/bin", "packages/agentplane/bin"],
+    ];
+    for (const [sourceRelativePath, targetRelativePath] of copyTargets) {
+        let sourcePath = "";
+        for (const sourceRoot of sourceRoots) {
+            const candidate = path.join(sourceRoot, sourceRelativePath);
+            if (await fileExists(candidate)) {
+                sourcePath = candidate;
+                break;
+            }
+        }
+        if (!sourcePath)
+            continue;
+        const targetPath = path.join(opts.worktreePath, targetRelativePath);
+        if (await fileExists(targetPath))
+            continue;
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await cp(sourcePath, targetPath, { recursive: true });
+    }
+}
+async function linkDirectoryIntoWorktree(opts) {
+    let sourcePath = "";
+    for (const sourceRoot of opts.sourceRoots) {
+        const candidate = path.join(sourceRoot, opts.relativePath);
+        if (await fileExists(candidate)) {
+            sourcePath = candidate;
+            break;
+        }
     }
+    if (!sourcePath)
+        return false;
+    const targetPath = path.join(opts.worktreePath, opts.relativePath);
+    if (await fileExists(targetPath))
+        return false;
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await symlink(sourcePath, targetPath, process.platform === "win32" ? "junction" : "dir");
+    return true;
+}
+async function materializeRepoLocalInstallLayoutForWorktree(opts) {
+    const runtimeSource = resolveRuntimeSourceInfo({ cwd: process.cwd() });
+    const sourceRoots = [
+        ...new Set([
+            path.resolve(opts.repoRoot),
+            path.resolve(process.cwd()),
+            runtimeSource.agentplane.packageRoot
+                ? path.resolve(runtimeSource.agentplane.packageRoot, "..", "..")
+                : null,
+        ].filter((value) => isPresentString(value))),
+    ];
+    const linkTargets = [
+        "node_modules",
+        path.join("packages", "core", "node_modules"),
+        path.join("packages", "agentplane", "node_modules"),
+        "agentplane-recipes",
+    ];
+    for (const relativePath of linkTargets) {
+        await linkDirectoryIntoWorktree({
+            sourceRoots,
+            worktreePath: opts.worktreePath,
+            relativePath,
+        });
+    }
+}
+async function materializeHookShimForWorktree(worktreePath) {
+    const shimPath = path.join(worktreePath, ".agentplane", "bin", "agentplane");
+    if (await fileExists(shimPath))
+        return;
+    await mkdir(path.dirname(shimPath), { recursive: true });
+    await writeFile(shimPath, repoLocalHookShimText(), "utf8");
+    await chmod(shimPath, 0o755);
 }
 async function ensureGitClean(gitRoot) {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain"], {
@@ -227,7 +353,17 @@ export async function cmdWorkStart(opts) {
                 backend: ctx.taskBackend,
                 repoRoot: resolved.gitRoot,
                 worktreePath,
+                taskId: opts.taskId,
+            });
+            await materializeRepoLocalDistForWorktree({
+                repoRoot: resolved.gitRoot,
+                worktreePath,
+            });
+            await materializeRepoLocalInstallLayoutForWorktree({
+                repoRoot: resolved.gitRoot,
+                worktreePath,
             });
+            await materializeHookShimForWorktree(worktreePath);
         }
         else {
             if (branchExists) {

package/dist/commands/cleanup/merged.command.d.ts

@@ -7,6 +7,8 @@ export type CleanupMergedParsed = {
     base: string | null;
     yes: boolean;
     archive: boolean;
+    deleteRemoteBranches: boolean;
+    fetch: boolean;
     quiet: boolean;
 };
 export declare const cleanupMergedSpec: CommandSpec<CleanupMergedParsed>;

package/dist/commands/cleanup/merged.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merged.command.d.ts","sourceRoot":"","sources":["../../../src/commands/cleanup/merged.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,KAAK,kBAAkB,GAAG,kBAAkB,CAAC;AAE7C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAUvD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAkC9D,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAQzD,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC5E,KAAK,UAAU,EAAE,GAAG,mBAAmB,KAAG,OAAO,CAAC,MAAM,CAAC,CAWxE"}
+{"version":3,"file":"merged.command.d.ts","sourceRoot":"","sources":["../../../src/commands/cleanup/merged.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,KAAK,kBAAkB,GAAG,kBAAkB,CAAC;AAE7C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAUvD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAwD9D,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAQzD,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC5E,KAAK,UAAU,EAAE,GAAG,mBAAmB,KAAG,OAAO,CAAC,MAAM,CAAC,CAaxE"}

package/dist/commands/cleanup/merged.command.js

@@ -25,6 +25,18 @@ export const cleanupMergedSpec = {
             default: false,
             description: "Archive PR artifacts before deletion.",
         },
+        {
+            kind: "boolean",
+            name: "delete-remote-branches",
+            default: false,
+            description: "Also delete matching remote task branches on origin.",
+        },
+        {
+            kind: "boolean",
+            name: "fetch",
+            default: false,
+            description: "Fetch and prune origin before candidate resolution.",
+        },
         { kind: "boolean", name: "quiet", default: false, description: "Reduce output noise." },
     ],
     examples: [
@@ -33,6 +45,14 @@ export const cleanupMergedSpec = {
             cmd: "agentplane cleanup merged --yes --archive",
             why: "Delete candidates and archive PR artifacts.",
         },
+        {
+            cmd: "agentplane cleanup merged --yes --delete-remote-branches",
+            why: "Delete candidates and matching remote task branches on origin.",
+        },
+        {
+            cmd: "agentplane cleanup merged --fetch",
+            why: "Refresh origin before evaluating cleanup candidates.",
+        },
     ],
     validateRaw: (raw) => {
         const base = typeof raw.opts.base === "string" ? raw.opts.base.trim() : "";
@@ -44,6 +64,8 @@ export const cleanupMergedSpec = {
         base: typeof raw.opts.base === "string" ? raw.opts.base : null,
         yes: raw.opts.yes === true,
         archive: raw.opts.archive === true,
+        deleteRemoteBranches: raw.opts["delete-remote-branches"] === true,
+        fetch: raw.opts.fetch === true,
         quiet: raw.opts.quiet === true,
     }),
 };
@@ -65,6 +87,8 @@ export function makeRunCleanupMergedHandler(getCtx) {
             base: p.base ?? undefined,
             yes: p.yes,
             archive: p.archive,
+            deleteRemoteBranches: p.deleteRemoteBranches,
+            fetch: p.fetch,
             quiet: p.quiet,
         });
     };

package/dist/commands/doctor/branch-pr.d.ts

@@ -0,0 +1,4 @@
+import type { CommandContext } from "../shared/task-backend.js";
+export declare function checkBranchPrShippedTaskDrift(ctx?: CommandContext): Promise<string[]>;
+export declare function checkBranchPrDoneTaskOpenPrDrift(ctx?: CommandContext): Promise<string[]>;
+//# sourceMappingURL=branch-pr.d.ts.map

package/dist/commands/doctor/branch-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-pr.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/branch-pr.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,wBAAsB,6BAA6B,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuC3F;AAED,wBAAsB,gCAAgC,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkC9F"}

package/dist/commands/doctor/branch-pr.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { renderDiagnosticFinding } from "../../shared/diagnostics.js";
+import { findDoneBranchPrTasksWithOpenPrArtifacts, findLocallyShippedBranchPrTasks, } from "../task/hosted-merge-sync.js";
+export async function checkBranchPrShippedTaskDrift(ctx) {
+    if (ctx?.backendId !== "local" || ctx.config.workflow_mode !== "branch_pr")
+        return [];
+    let tasks = [];
+    try {
+        tasks = await ctx.taskBackend.listTasks();
+    }
+    catch {
+        return [];
+    }
+    if (tasks.length === 0)
+        return [];
+    const matches = await findLocallyShippedBranchPrTasks({ ctx, tasks });
+    if (matches.length === 0)
+        return [];
+    const examples = matches
+        .slice(0, 5)
+        .map((entry) => `${entry.taskId}@${entry.base}:${entry.commitHash.slice(0, 12)} verified_via=${entry.verificationSource}`)
+        .join(", ");
+    return [
+        renderDiagnosticFinding({
+            severity: "WARN",
+            state: "branch_pr tasks appear shipped on the base branch but remain open",
+            likelyCause: "the verified task commit already landed on the base branch, but canonical task closure artifacts were never reconciled",
+            nextAction: {
+                command: "agentplane task normalize --sync-branch-pr-state",
+                reason: "mark locally shipped branch_pr tasks as DONE in the task projection before committing the reconciled task artifacts on the base branch",
+            },
+            details: [
+                `Affected tasks: ${matches.length}`,
+                examples ? `Examples: ${examples}` : "Examples unavailable.",
+            ],
+        }),
+    ];
+}
+export async function checkBranchPrDoneTaskOpenPrDrift(ctx) {
+    if (ctx?.backendId !== "local" || ctx.config.workflow_mode !== "branch_pr")
+        return [];
+    const tasks = await readDoneTaskSnapshot(ctx);
+    if (tasks.length === 0)
+        return [];
+    const matches = await findDoneBranchPrTasksWithOpenPrArtifacts({ ctx, tasks });
+    if (matches.length === 0)
+        return [];
+    const examples = matches
+        .slice(0, 5)
+        .map((entry) => `${entry.taskId}@${entry.base}:${entry.commitHash.slice(0, 12)} branch=${entry.branch}`)
+        .join(", ");
+    return [
+        renderDiagnosticFinding({
+            severity: "WARN",
+            state: "DONE branch_pr tasks still have open or unmerged PR artifacts",
+            likelyCause: "the task was marked DONE, but its branch_pr PR artifacts were never reconciled to MERGED and the task branch still exists",
+            nextAction: {
+                command: "agentplane task normalize --sync-branch-pr-state --task-id <task-id>",
+                reason: "reconcile the shipped task's local branch_pr state and PR artifacts to MERGED without scanning unrelated task history",
+            },
+            details: [
+                `Affected tasks: ${matches.length}`,
+                examples ? `Examples: ${examples}` : "Examples unavailable.",
+            ],
+        }),
+    ];
+}
+async function readDoneTaskSnapshot(ctx) {
+    try {
+        const tasks = await ctx.taskBackend.listTasks();
+        if (tasks.length > 0) {
+            return tasks;
+        }
+    }
+    catch {
+        // Fall back to the legacy export snapshot when the live backend read is unavailable.
+    }
+    const tasksJsonPath = path.join(ctx.resolvedProject.agentplaneDir, "tasks.json");
+    try {
+        const raw = await readFile(tasksJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.tasks))
+            return [];
+        return parsed.tasks.filter((task) => isTaskDataLike(task));
+    }
+    catch {
+        return [];
+    }
+}
+function isTaskDataLike(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.id === "string" && typeof record.status === "string";
+}

package/dist/commands/doctor/fixes.d.ts

@@ -1,3 +1,4 @@
+import type { CommandContext } from "../shared/task-backend.js";
 export declare function safeFixGitignore(repoRoot: string): Promise<{
     changed: boolean;
     note: string;
@@ -6,4 +7,8 @@ export declare function safeFixTaskIndex(repoRoot: string): Promise<{
     changed: boolean;
     note: string;
 }>;
+export declare function safeFixLegacyUntrackedTaskReadmes(repoRoot: string, ctx?: CommandContext): Promise<{
+    changed: boolean;
+    note: string;
+}>;
 //# sourceMappingURL=fixes.d.ts.map

package/dist/commands/doctor/fixes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixes.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/fixes.ts"],"names":[],"mappings":"AAMA,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB7C;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ7C"}
+{"version":3,"file":"fixes.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/fixes.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB7C;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ7C;AAED,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA8E7C"}

package/dist/commands/doctor/fixes.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { parseTaskReadme } from "@agentplaneorg/core";
 import { RUNTIME_GITIGNORE_LINES } from "../../shared/runtime-artifacts.js";
+import { GitContext } from "../shared/git-context.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 export async function safeFixGitignore(repoRoot) {
     const gitignorePath = path.join(repoRoot, ".gitignore");
@@ -38,3 +40,71 @@ export async function safeFixTaskIndex(repoRoot) {
         return { changed: false, note: "Skip: could not rebuild tasks index cache." };
     }
 }
+export async function safeFixLegacyUntrackedTaskReadmes(repoRoot, ctx) {
+    const commandCtx = ctx ??
+        (await loadCommandContext({
+            cwd: repoRoot,
+            rootOverride: null,
+        }));
+    const workflowDir = (commandCtx.config.paths.workflow_dir ?? ".agentplane/tasks").replaceAll("\\", "/");
+    const git = commandCtx.git ?? new GitContext({ gitRoot: repoRoot });
+    let untracked = [];
+    try {
+        untracked = await git.statusUntrackedPaths();
+    }
+    catch {
+        return { changed: false, note: "Skip: could not inspect untracked task README collisions." };
+    }
+    const candidates = untracked.filter((relPath) => relPath.startsWith(`${workflowDir}/`) && relPath.endsWith("/README.md"));
+    if (candidates.length === 0) {
+        return { changed: false, note: "OK: no legacy untracked task README collisions." };
+    }
+    const removed = [];
+    for (const relPath of candidates) {
+        const absPath = path.join(repoRoot, relPath);
+        let text = "";
+        try {
+            text = await fs.readFile(absPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseTaskReadme(text);
+        }
+        catch {
+            continue;
+        }
+        const taskId = path.basename(path.dirname(absPath));
+        const parsedId = typeof parsed.frontmatter.id === "string" && parsed.frontmatter.id.trim().length > 0
+            ? parsed.frontmatter.id.trim()
+            : taskId;
+        const status = typeof parsed.frontmatter.status === "string"
+            ? parsed.frontmatter.status.trim().toUpperCase()
+            : "";
+        if (parsedId !== taskId || status !== "DONE")
+            continue;
+        await fs.rm(absPath, { force: true });
+        try {
+            const remaining = await fs.readdir(path.dirname(absPath));
+            if (remaining.length === 0) {
+                await fs.rmdir(path.dirname(absPath));
+            }
+        }
+        catch {
+            // Ignore cleanup failures for parent directories; the file removal is the actual fix.
+        }
+        removed.push(taskId);
+    }
+    if (removed.length === 0) {
+        return {
+            changed: false,
+            note: "OK: no safe-to-remove legacy untracked DONE task README collisions.",
+        };
+    }
+    return {
+        changed: true,
+        note: `Fixed: removed legacy untracked DONE task README collisions (${removed.join(", ")}).`,
+    };
+}

package/dist/commands/doctor.run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.run.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.run.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAarD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CA6DlD,CAAC"}
+{"version":3,"file":"doctor.run.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.run.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAqBrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAiElD,CAAC"}

package/dist/commands/doctor.run.js

@@ -2,7 +2,8 @@ import { loadConfig, resolveProject } from "@agentplaneorg/core";
 import { warnMessage, successMessage } from "../cli/output.js";
 import { loadCommandContext } from "./shared/task-backend.js";
 import { checkDoneTaskCommitInvariants } from "./doctor/archive.js";
-import { safeFixGitignore, safeFixTaskIndex } from "./doctor/fixes.js";
+import { checkBranchPrDoneTaskOpenPrDrift, checkBranchPrShippedTaskDrift, } from "./doctor/branch-pr.js";
+import { safeFixGitignore, safeFixLegacyUntrackedTaskReadmes, safeFixTaskIndex, } from "./doctor/fixes.js";
 import { checkLayering } from "./doctor/layering.js";
 import { checkRuntimeSourceFacts, findingSeverity } from "./doctor/runtime.js";
 import { checkWorkspace } from "./doctor/workspace.js";
@@ -21,6 +22,8 @@ export const runDoctor = async (ctx, p) => {
     const runChecks = async () => {
         let checks = [
             ...(await checkWorkspace(repoRoot, { ctx: commandCtx })),
+            ...(await checkBranchPrShippedTaskDrift(commandCtx)),
+            ...(await checkBranchPrDoneTaskOpenPrDrift(commandCtx)),
             ...checkRuntimeSourceFacts(ctx.cwd, loadedConfig.config),
             ...(await checkDoneTaskCommitInvariants(repoRoot, { fullArchive: p.archiveFull })),
         ];
@@ -38,6 +41,8 @@ export const runDoctor = async (ctx, p) => {
     if (p.fix) {
         const fix = await safeFixGitignore(repoRoot);
         console.log(successMessage("doctor fix", undefined, fix.note));
+        const legacyTaskReadmes = await safeFixLegacyUntrackedTaskReadmes(repoRoot, commandCtx);
+        console.log(successMessage("doctor fix", undefined, legacyTaskReadmes.note));
         const idx = await safeFixTaskIndex(repoRoot);
         console.log(successMessage("doctor fix", undefined, idx.note));
         const workflowFix = await safeFixWorkflow(repoRoot);

package/dist/commands/finish.run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finish.run.d.ts","sourceRoot":"","sources":["../../src/commands/finish.run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEjE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACrE,KAAK,UAAU,EAAE,GAAG,YAAY,KAAG,OAAO,CAAC,MAAM,CAAC,CAuCjE"}
+{"version":3,"file":"finish.run.d.ts","sourceRoot":"","sources":["../../src/commands/finish.run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEjE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACrE,KAAK,UAAU,EAAE,GAAG,YAAY,KAAG,OAAO,CAAC,MAAM,CAAC,CAkDjE"}

package/dist/commands/finish.run.js

@@ -38,6 +38,17 @@ export function makeRunFinishHandler(getCtx) {
             closeCommit: p.closeCommit,
             noCloseCommit: p.noCloseCommit,
             closeUnstageOthers: p.closeUnstageOthers,
+            baseBranchOverride: p.baseBranchOverride,
+            observation: p.observation,
+            impact: p.impact,
+            resolution: p.resolution,
+            localOnly: p.localOnly,
+            repoFixable: p.repoFixable,
+            incidentScope: p.incidentScope,
+            incidentTags: p.incidentTags,
+            incidentMatch: p.incidentMatch,
+            incidentAdvice: p.incidentAdvice,
+            incidentRule: p.incidentRule,
             quiet: p.quiet,
         });
     };

package/dist/commands/finish.spec.d.ts

@@ -24,6 +24,17 @@ export type FinishParsed = {
     closeCommit: boolean;
     noCloseCommit: boolean;
     closeUnstageOthers: boolean;
+    baseBranchOverride?: string;
+    observation?: string;
+    impact?: string;
+    resolution?: string;
+    localOnly: boolean;
+    repoFixable: boolean;
+    incidentScope?: string;
+    incidentTags: string[];
+    incidentMatch: string[];
+    incidentAdvice?: string;
+    incidentRule?: string;
     quiet: boolean;
 };
 export declare const finishSpec: CommandSpec<FinishParsed>;

package/dist/commands/finish.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finish.spec.d.ts","sourceRoot":"","sources":["../../src/commands/finish.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AASvD,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,wBAAwB,EAAE,OAAO,CAAC;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAqUhD,CAAC"}
+{"version":3,"file":"finish.spec.d.ts","sourceRoot":"","sources":["../../src/commands/finish.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAUvD,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,wBAAwB,EAAE,OAAO,CAAC;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CA4XhD,CAAC"}

package/dist/commands/finish.spec.js

@@ -1,4 +1,5 @@
 import { usageError } from "../cli/spec/errors.js";
+import { verifyFindingOptions, validateVerifyFindingSource } from "./task/verify-command-shared.js";
 import { toStringList } from "../cli/spec/parse-utils.js";
 import { findRepoWideAllowPrefixes, repoWideAllowPrefixMessage, } from "../shared/allow-prefix-policy.js";
 export const finishSpec = {
@@ -157,6 +158,13 @@ export const finishSpec = {
             default: false,
             description: "With --close-commit: unstage any currently staged paths before staging the task README.",
         },
+        {
+            kind: "string",
+            name: "base",
+            valueHint: "<branch>",
+            description: "Optional explicit base branch override for branch_pr finish validation and close-commit reconciliation.",
+        },
+        ...verifyFindingOptions,
         { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
     ],
     examples: [
@@ -168,6 +176,10 @@ export const finishSpec = {
             cmd: 'agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: all checks passed" --commit-from-comment --commit-allow packages/agentplane/src',
             why: "Finish and create a commit from the comment (single-task only).",
         },
+        {
+            cmd: 'agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: all checks passed" --commit abcdef123456 --observation "Recurring manual recovery remained easy to miss." --impact "incidents.md stayed stale until a second command." --resolution "Capture the closeout finding during finish itself."',
+            why: "Finish a task while appending a structured finding that can promote into incidents.md.",
+        },
     ],
     validateRaw: (raw) => {
         const ids = raw.args["task-id"];
@@ -270,9 +282,29 @@ export const finishSpec = {
                 message: "--close-unstage-others requires --close-commit",
             });
         }
+        if (typeof raw.opts.base === "string" && raw.opts.base.trim().length === 0) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "Invalid value for --base: empty.",
+            });
+        }
         const hasMeta = typeof raw.opts.result === "string" ||
             typeof raw.opts.risk === "string" ||
             raw.opts.breaking === true;
+        const hasFindingInput = [
+            raw.opts.observation,
+            raw.opts.impact,
+            raw.opts.resolution,
+            raw.opts["incident-scope"],
+            raw.opts["incident-advice"],
+            raw.opts["incident-rule"],
+        ].some((value) => typeof value === "string" && value.trim().length > 0)
+            ? true
+            : (Array.isArray(raw.opts["incident-tag"]) && raw.opts["incident-tag"].length > 0) ||
+                (Array.isArray(raw.opts["incident-match"]) && raw.opts["incident-match"].length > 0) ||
+                raw.opts["local-only"] === true ||
+                raw.opts["repo-fixable"] === true;
         if (hasMeta && taskIds.length !== 1) {
             throw usageError({
                 spec: finishSpec,
@@ -280,6 +312,14 @@ export const finishSpec = {
                 message: "--result/--risk/--breaking requires exactly one task id",
             });
         }
+        if (hasFindingInput && taskIds.length !== 1) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "--observation/--impact/--resolution and incident finding options require exactly one task id",
+            });
+        }
+        validateVerifyFindingSource(raw, finishSpec, { command: "finish" });
     },
     parse: (raw) => ({
         taskIds: Array.isArray(raw.args["task-id"])
@@ -308,6 +348,17 @@ export const finishSpec = {
         closeCommit: raw.opts["close-commit"] === true,
         noCloseCommit: raw.opts["no-close-commit"] === true,
         closeUnstageOthers: raw.opts["close-unstage-others"] === true,
+        baseBranchOverride: typeof raw.opts.base === "string" ? raw.opts.base : undefined,
+        observation: typeof raw.opts.observation === "string" ? raw.opts.observation : undefined,
+        impact: typeof raw.opts.impact === "string" ? raw.opts.impact : undefined,
+        resolution: typeof raw.opts.resolution === "string" ? raw.opts.resolution : undefined,
+        localOnly: raw.opts["local-only"] === true,
+        repoFixable: raw.opts["repo-fixable"] === true,
+        incidentScope: typeof raw.opts["incident-scope"] === "string" ? raw.opts["incident-scope"] : undefined,
+        incidentTags: toStringList(raw.opts["incident-tag"]),
+        incidentMatch: toStringList(raw.opts["incident-match"]),
+        incidentAdvice: typeof raw.opts["incident-advice"] === "string" ? raw.opts["incident-advice"] : undefined,
+        incidentRule: typeof raw.opts["incident-rule"] === "string" ? raw.opts["incident-rule"] : undefined,
         quiet: raw.opts.quiet === true,
     }),
 };

package/dist/commands/guard/impl/close-message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-message.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/close-message.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAsHlE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsD9B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAET"}
+{"version":3,"file":"close-message.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/close-message.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAyIlE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsD9B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAET"}