agentplane 0.3.12 → 0.3.13

package/dist/cli/run-cli.test-helpers.js

@@ -308,7 +308,7 @@ export async function writeConfig(root, config) {
 export async function resetAgentplaneHomeRecipes() {
     if (!agentplaneHome)
         return;
-    await rm(path.join(agentplaneHome, "recipes"), { recursive: true, force: true });
+    await rm(path.join(agentplaneHome, "recipes-store"), { recursive: true, force: true });
     await rm(path.join(agentplaneHome, "recipes.json"), { force: true });
     await rm(path.join(agentplaneHome, "recipes-index.json"), { force: true });
 }
@@ -349,8 +349,7 @@ export async function createRecipeArchive(opts) {
             {
                 id: "RECIPE_SKILL",
                 summary: "Recipe analysis skill",
-                kind: "agent-skill",
-                file: "skills/analysis.json",
+                file: "skills/analysis.md",
             },
         ],
         agents: [
@@ -361,7 +360,7 @@ export async function createRecipeArchive(opts) {
                 summary: "Recipe agent",
                 skills: ["RECIPE_SKILL"],
                 tools: ["RECIPE_TOOL"],
-                file: "agents/recipe.json",
+                file: "agents/recipe.md",
             },
         ],
         tools: [
@@ -395,18 +394,23 @@ export async function createRecipeArchive(opts) {
     await writeFile(path.join(recipeDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
     const agentsDir = path.join(recipeDir, "agents");
     await mkdir(agentsDir, { recursive: true });
-    await writeFile(path.join(agentsDir, "recipe.json"), JSON.stringify({
-        id: "RECIPE_AGENT",
-        role: "Recipe agent",
-        description: "Example agent installed from a recipe.",
-    }, null, 2), "utf8");
+    await writeFile(path.join(agentsDir, "recipe.md"), [
+        "# Recipe Agent",
+        "",
+        "Role: executor",
+        "",
+        "Instructions:",
+        "- Use recipe local policy.",
+        "- Materialize the declared scenario artifacts.",
+    ].join("\n"), "utf8");
     const skillsDir = path.join(recipeDir, "skills");
     await mkdir(skillsDir, { recursive: true });
-    await writeFile(path.join(skillsDir, "analysis.json"), JSON.stringify({
-        id: "RECIPE_SKILL",
-        summary: "Recipe analysis skill",
-        kind: "agent-skill",
-    }, null, 2), "utf8");
+    await writeFile(path.join(skillsDir, "analysis.md"), [
+        "# Recipe Skill",
+        "",
+        "- Inspect the generated bundle before acting.",
+        "- Keep recipe-owned artifacts inside the declared output paths.",
+    ].join("\n"), "utf8");
     const toolsDir = path.join(recipeDir, "tools");
     await mkdir(toolsDir, { recursive: true });
     await writeFile(path.join(toolsDir, "run.js"), [
@@ -496,8 +500,7 @@ export async function createUnsafeRecipeArchive(opts) {
             {
                 id: "RECIPE_SKILL",
                 summary: "Recipe skill",
-                kind: "agent-skill",
-                file: "skills/recipe.json",
+                file: "skills/recipe.md",
             },
         ],
         agents: [
@@ -508,7 +511,7 @@ export async function createUnsafeRecipeArchive(opts) {
                 summary: "Recipe agent",
                 skills: ["RECIPE_SKILL"],
                 tools: ["RECIPE_TOOL"],
-                file: "agents/recipe.json",
+                file: "agents/recipe.md",
             },
         ],
         tools: [
@@ -535,10 +538,10 @@ export async function createUnsafeRecipeArchive(opts) {
     await writeFile(path.join(recipeDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
     const agentsDir = path.join(recipeDir, "agents");
     await mkdir(agentsDir, { recursive: true });
-    await writeFile(path.join(agentsDir, "recipe.json"), JSON.stringify({ id: "RECIPE_AGENT", role: "Recipe agent" }, null, 2), "utf8");
+    await writeFile(path.join(agentsDir, "recipe.md"), "# Recipe Agent\n\nFollow the unsafe archive validation path.\n", "utf8");
     const skillsDir = path.join(recipeDir, "skills");
     await mkdir(skillsDir, { recursive: true });
-    await writeFile(path.join(skillsDir, "recipe.json"), JSON.stringify({ id: "RECIPE_SKILL" }), "utf8");
+    await writeFile(path.join(skillsDir, "recipe.md"), "# Recipe Skill\n\nInspect archive contents before materialization.\n", "utf8");
     const toolsDir = path.join(recipeDir, "tools");
     await mkdir(toolsDir, { recursive: true });
     await writeFile(path.join(toolsDir, "run.sh"), "#!/usr/bin/env bash\n", "utf8");

package/dist/commands/codex/plugin-install.d.ts

@@ -0,0 +1,26 @@
+export declare const AGENTPLANE_CODEX_HOME_ENV = "AGENTPLANE_CODEX_HOME";
+export type CodexPluginInstallScope = "user" | "repo";
+export type CodexPluginInstallResult = {
+    scope: CodexPluginInstallScope;
+    installRoot: string;
+    pluginRoot: string;
+    manifestPath: string;
+    marketplacePath: string;
+    copiedAssets: string[];
+};
+type JsonObject = Record<string, unknown>;
+export declare function buildCodexPluginManifest(version?: string): JsonObject;
+export declare function resolveCodexInstallRoot(opts: {
+    scope: CodexPluginInstallScope;
+    repoRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function resolveCodexPluginRoot(installRoot: string): string;
+export declare function resolveCodexMarketplacePath(installRoot: string): string;
+export declare function installBundledCodexPlugin(opts: {
+    scope: CodexPluginInstallScope;
+    installRoot: string;
+    version?: string;
+}): Promise<CodexPluginInstallResult>;
+export {};
+//# sourceMappingURL=plugin-install.d.ts.map

package/dist/commands/codex/plugin-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-install.d.ts","sourceRoot":"","sources":["../../../src/commands/codex/plugin-install.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwG1C,wBAAgB,wBAAwB,CAAC,OAAO,SAAe,GAAG,UAAU,CA8B3E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,MAAM,CAiBT;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAyCpC"}

package/dist/commands/codex/plugin-install.js

@@ -0,0 +1,209 @@
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "../../shared/errors.js";
+import { getVersion } from "../../meta/version.js";
+import { writeJsonStableIfChanged, writeTextIfChanged } from "../../shared/write-if-changed.js";
+const PLUGIN_NAME = "agentplane";
+const DEFAULT_MARKETPLACE_NAME = "agentplane-local-marketplace";
+const DEFAULT_MARKETPLACE_DISPLAY_NAME = "AgentPlane Local Plugins";
+const ASSET_ROOT_URL = new URL("../../../assets/codex-plugin/", import.meta.url);
+const TEXT_ASSETS = [
+    {
+        source: new URL("skills/agentplane/SKILL.md", ASSET_ROOT_URL),
+        relativePath: "skills/agentplane/SKILL.md",
+    },
+];
+const BINARY_ASSETS = [
+    {
+        source: new URL("assets/icon.svg", ASSET_ROOT_URL),
+        relativePath: "assets/icon.svg",
+    },
+    {
+        source: new URL("assets/logo.svg", ASSET_ROOT_URL),
+        relativePath: "assets/logo.svg",
+    },
+    {
+        source: new URL("assets/header.png", ASSET_ROOT_URL),
+        relativePath: "assets/header.png",
+    },
+];
+export const AGENTPLANE_CODEX_HOME_ENV = "AGENTPLANE_CODEX_HOME";
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidMarketplaceError(message) {
+    return new CliError({
+        exitCode: 3,
+        code: "E_VALIDATION",
+        message,
+    });
+}
+async function readTextIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function defaultMarketplaceDocument() {
+    return {
+        name: DEFAULT_MARKETPLACE_NAME,
+        interface: {
+            displayName: DEFAULT_MARKETPLACE_DISPLAY_NAME,
+        },
+        plugins: [],
+    };
+}
+function parseMarketplaceDocument(text) {
+    if (text === null)
+        return defaultMarketplaceDocument();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw invalidMarketplaceError(`Invalid Codex marketplace JSON: ${err instanceof Error ? err.message : "unknown parse error"}`);
+    }
+    if (!isJsonObject(parsed)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: expected a top-level object.");
+    }
+    if ("plugins" in parsed && !Array.isArray(parsed.plugins)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: `plugins` must be an array.");
+    }
+    if ("interface" in parsed && parsed.interface !== undefined && !isJsonObject(parsed.interface)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: `interface` must be an object when present.");
+    }
+    return parsed;
+}
+function marketplaceEntry() {
+    return {
+        name: PLUGIN_NAME,
+        source: {
+            source: "local",
+            path: `./plugins/${PLUGIN_NAME}`,
+        },
+        policy: {
+            installation: "AVAILABLE",
+            authentication: "ON_INSTALL",
+        },
+        category: "Productivity",
+    };
+}
+function upsertMarketplaceDocument(text) {
+    const document = parseMarketplaceDocument(text);
+    const interfaceObject = isJsonObject(document.interface) ? { ...document.interface } : {};
+    if (typeof document.name !== "string" || document.name.trim().length === 0) {
+        document.name = DEFAULT_MARKETPLACE_NAME;
+    }
+    if (typeof interfaceObject.displayName !== "string" ||
+        interfaceObject.displayName.trim().length === 0) {
+        interfaceObject.displayName = DEFAULT_MARKETPLACE_DISPLAY_NAME;
+    }
+    const plugins = Array.isArray(document.plugins) ? document.plugins : [];
+    const nextEntry = marketplaceEntry();
+    const existingIndex = plugins.findIndex((entry) => isJsonObject(entry) && entry.name === PLUGIN_NAME);
+    if (existingIndex === -1) {
+        plugins.push(nextEntry);
+    }
+    else {
+        plugins.splice(existingIndex, 1, nextEntry);
+    }
+    return {
+        ...document,
+        interface: interfaceObject,
+        plugins,
+    };
+}
+export function buildCodexPluginManifest(version = getVersion()) {
+    return {
+        name: PLUGIN_NAME,
+        version,
+        description: "Bundle AgentPlane workflow guidance for the Codex plugins UI.",
+        homepage: "https://github.com/basilisk-labs/agentplane",
+        repository: "https://github.com/basilisk-labs/agentplane",
+        license: "MIT",
+        keywords: ["agentplane", "codex", "workflow", "tasks", "git"],
+        skills: "./skills/",
+        interface: {
+            displayName: "AgentPlane",
+            shortDescription: "Governed git-native workflow guidance for Codex",
+            longDescription: "Install AgentPlane into Codex through a local marketplace and give Codex explicit task, planning, verification, and branch_pr workflow guidance.",
+            developerName: "basilisk-labs",
+            category: "Productivity",
+            capabilities: ["Read", "Write"],
+            websiteURL: "https://github.com/basilisk-labs/agentplane",
+            defaultPrompt: [
+                "Use AgentPlane to initialize a governed workflow in this repository.",
+                "Use AgentPlane to create a task, approve the plan, and start work in branch_pr mode.",
+                "Use AgentPlane to verify the active task and record evidence before finish.",
+            ],
+            brandColor: "#111827",
+            composerIcon: "./assets/icon.svg",
+            logo: "./assets/logo.svg",
+            screenshots: ["./assets/header.png"],
+        },
+    };
+}
+export function resolveCodexInstallRoot(opts) {
+    if (opts.scope === "repo") {
+        const repoRoot = opts.repoRoot?.trim();
+        if (!repoRoot) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Repo scope requires a resolved repository root.",
+            });
+        }
+        return path.resolve(repoRoot);
+    }
+    const env = opts.env ?? process.env;
+    const overridden = env[AGENTPLANE_CODEX_HOME_ENV]?.trim();
+    if (overridden)
+        return path.resolve(overridden);
+    return os.homedir();
+}
+export function resolveCodexPluginRoot(installRoot) {
+    return path.join(installRoot, "plugins", PLUGIN_NAME);
+}
+export function resolveCodexMarketplacePath(installRoot) {
+    return path.join(installRoot, ".agents", "plugins", "marketplace.json");
+}
+export async function installBundledCodexPlugin(opts) {
+    const installRoot = path.resolve(opts.installRoot);
+    const pluginRoot = resolveCodexPluginRoot(installRoot);
+    const manifestPath = path.join(pluginRoot, ".codex-plugin", "plugin.json");
+    const marketplacePath = resolveCodexMarketplacePath(installRoot);
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    await mkdir(path.dirname(marketplacePath), { recursive: true });
+    await writeJsonStableIfChanged(manifestPath, buildCodexPluginManifest(opts.version ?? getVersion()));
+    const copiedAssets = [];
+    for (const asset of TEXT_ASSETS) {
+        const targetPath = path.join(pluginRoot, asset.relativePath);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        const contents = await readFile(asset.source, "utf8");
+        await writeTextIfChanged(targetPath, contents);
+        copiedAssets.push(targetPath);
+    }
+    for (const asset of BINARY_ASSETS) {
+        const targetPath = path.join(pluginRoot, asset.relativePath);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await copyFile(fileURLToPath(asset.source), targetPath);
+        copiedAssets.push(targetPath);
+    }
+    const nextMarketplace = upsertMarketplaceDocument(await readTextIfExists(marketplacePath));
+    await writeJsonStableIfChanged(marketplacePath, nextMarketplace);
+    return {
+        scope: opts.scope,
+        installRoot,
+        pluginRoot,
+        manifestPath,
+        marketplacePath,
+        copiedAssets,
+    };
+}

package/dist/commands/pr/integrate/cmd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cmd.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/cmd.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAUnE,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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+OlB"}
+{"version":3,"file":"cmd.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/cmd.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA0EnE,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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6QlB"}

package/dist/commands/pr/integrate/cmd.js

@@ -2,11 +2,13 @@ import path from "node:path";
 import { mapBackendError } from "../../../cli/error-map.js";
 import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { createCliEmitter } from "../../../cli/output.js";
+import { withDiagnosticContext } from "../../../shared/diagnostics.js";
 import { CliError } from "../../../shared/errors.js";
 import { cleanupIntegratedBranch } from "./internal/cleanup.js";
 import { renderPostIntegrateBootstrapFailureGuidance, renderPostIntegrateBootstrapGuidance, shouldRecommendPostIntegrateBootstrap, } from "./internal/bootstrap-guidance.js";
 import { execFileAsync, gitEnv } from "../../shared/git.js";
 import { gitRevParse } from "../../shared/git-ops.js";
+import { buildTaskHandoffArtifact, resolveTaskHandoffPaths, writeTaskHandoff, } from "../../shared/task-handoff.js";
 import { finalizeIntegrate } from "./internal/finalize.js";
 import { runMergeCommit, runRebaseFastForward, runSquashMerge } from "./internal/merge.js";
 import { maybeRunPreIntegrateBootstrap } from "./internal/pre-integrate-bootstrap.js";
@@ -14,6 +16,54 @@ import { maybeRunPostIntegrateBootstrap } from "./internal/post-integrate-bootst
 import { prepareIntegrate } from "./internal/prepare.js";
 import { resolveWorktreeForIntegrate } from "./internal/worktree.js";
 import { runVerifyCommands } from "./verify.js";
+async function recordProtectedBaseIntegrateHandoff(opts) {
+    const paths = resolveTaskHandoffPaths({
+        git_root: opts.ctx.resolvedProject.gitRoot,
+        workflow_dir: opts.ctx.config.paths.workflow_dir,
+        task_id: opts.taskId,
+    });
+    const handoffShowCommand = `agentplane task handoff show ${opts.taskId}`;
+    const prLabel = typeof opts.prNumber === "number" && opts.prNumber > 0
+        ? `GitHub PR #${opts.prNumber}`
+        : `the GitHub PR for branch ${opts.branch}`;
+    const prUrl = opts.prUrl?.trim() ?? "";
+    const prMetaPath = path.join(opts.ctx.config.paths.workflow_dir, opts.taskId, "pr", "meta.json");
+    const taskReadmePath = path.join(opts.ctx.config.paths.workflow_dir, opts.taskId, "README.md");
+    await writeTaskHandoff({
+        paths,
+        handoff: buildTaskHandoffArtifact({
+            task_id: opts.taskId,
+            created_at: new Date().toISOString(),
+            from_role: "INTEGRATOR",
+            reason: `Protected base ${opts.base} requires GitHub pull-request merges.`,
+            note: prUrl.length > 0
+                ? `Merge ${prLabel}: ${prUrl}. After GitHub merge, wait for Task Hosted Close, then pull ${opts.base}.`
+                : `Merge ${prLabel} on GitHub. After GitHub merge, wait for Task Hosted Close, then pull ${opts.base}.`,
+            branch: opts.branch,
+            base_branch: opts.base,
+            head_sha: opts.branchHeadSha,
+            workspace_root: opts.ctx.resolvedProject.gitRoot,
+            pr_branch: opts.branch,
+            route: {
+                kind: "protected_base_integrate",
+                status: "awaiting_github_merge",
+                local_mutation: "not_performed",
+                finalize_via: "github_pr_merge_then_hosted_close",
+                pr_number: opts.prNumber,
+                pr_url: prUrl.length > 0 ? prUrl : null,
+                handoff_show_command: handoffShowCommand,
+                base_pull_command: "git pull --ff-only",
+            },
+            next_actions: [
+                handoffShowCommand,
+                prUrl.length > 0 ? `Merge ${prLabel}: ${prUrl}` : `Merge ${prLabel} on GitHub`,
+                `Wait for Task Hosted Close to finish`,
+                `git pull --ff-only`,
+            ],
+            evidence_paths: [taskReadmePath, prMetaPath],
+        }),
+    });
+}
 export async function cmdIntegrate(opts) {
     let tempWorktreePath = null;
     let createdTempWorktree = false;
@@ -41,14 +91,40 @@ export async function cmdIntegrate(opts) {
             return 0;
         }
         if (protectedBaseRequiresPrMerge) {
-            const prHint = typeof metaSource.pr_number === "number" && metaSource.pr_number > 0
-                ? `GitHub PR #${metaSource.pr_number}`
-                : `the GitHub PR for branch ${branch}`;
+            const prNumber = typeof metaSource.pr_number === "number" && metaSource.pr_number > 0
+                ? metaSource.pr_number
+                : null;
+            const prUrl = typeof metaSource.pr_url === "string" ? metaSource.pr_url : null;
+            const prHint = prNumber === null ? `the GitHub PR for branch ${branch}` : `GitHub PR #${prNumber}`;
+            await recordProtectedBaseIntegrateHandoff({
+                ctx: prepared.ctx,
+                taskId: task.id,
+                branch,
+                base,
+                branchHeadSha,
+                prNumber,
+                prUrl,
+            });
             throw new CliError({
-                exitCode: exitCodeForError("E_GIT"),
-                code: "E_GIT",
+                exitCode: exitCodeForError("E_HANDOFF"),
+                code: "E_HANDOFF",
                 message: `Base branch ${base} requires GitHub pull-request merges; integrate will not mutate it locally. ` +
                     `Merge ${prHint} on GitHub, let Task Hosted Close finish the closure tail, then pull ${base}.`,
+                context: withDiagnosticContext({
+                    task_id: task.id,
+                    branch,
+                    base_branch: base,
+                    reason_code: "protected_base_integrate_handoff",
+                }, {
+                    state: `protected-base integrate routed to GitHub merge handoff for ${task.id}`,
+                    likelyCause: `base branch ${base} is protected by a GitHub pull-request merge policy, so local integrate must stop before mutating ${base}`,
+                    hint: "Inspect the persisted handoff artifact for the canonical finalize route, then merge the PR on GitHub and let Task Hosted Close finish the close tail.",
+                    nextAction: {
+                        command: `agentplane task handoff show ${task.id}`,
+                        reason: "inspect the persisted protected-base finalize route before continuing",
+                        reasonCode: "protected_base_integrate_handoff",
+                    },
+                }),
             });
         }
         const wt = await resolveWorktreeForIntegrate({

package/dist/commands/pr/integrate/internal/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/prepare.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAUrE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAC;AAWzC,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,YAAY,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,EAAE,QAAQ,CAAC;IAEf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B,EAAE,OAAO,CAAC;IAEtC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAEtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgP7B"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/prepare.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAWrE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAC;AAWzC,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,YAAY,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,EAAE,QAAQ,CAAC;IAEf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B,EAAE,OAAO,CAAC;IAEtC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAEtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqR7B"}

package/dist/commands/pr/integrate/internal/prepare.js

@@ -4,6 +4,7 @@ import { resolveBaseBranch } from "@agentplaneorg/core";
 import { fileExists } from "../../../../cli/fs-utils.js";
 import { exitCodeForError } from "../../../../cli/exit-codes.js";
 import { unknownEntityMessage, workflowModeMessage } from "../../../../cli/output.js";
+import { withDiagnosticContext } from "../../../../shared/diagnostics.js";
 import { CliError } from "../../../../shared/errors.js";
 import { ensureGitClean } from "../../../guard/index.js";
 import { gitDiffNames } from "../../../shared/git-diff.js";
@@ -52,13 +53,6 @@ export async function prepareIntegrate(opts) {
         });
     }
     const currentBranch = await gitCurrentBranch(resolved.gitRoot);
-    if (currentBranch !== baseBranch) {
-        throw new CliError({
-            exitCode: exitCodeForError("E_GIT"),
-            code: "E_GIT",
-            message: `integrate must run on base branch ${baseBranch} (current: ${currentBranch})`,
-        });
-    }
     const { prDir, metaPath, diffstatPath, verifyLogPath } = await resolvePrPaths({
         ctx,
         cwd: opts.cwd,
@@ -92,6 +86,43 @@ export async function prepareIntegrate(opts) {
             message: unknownEntityMessage("branch", branch),
         });
     }
+    if (currentBranch !== baseBranch) {
+        if (currentBranch === branch) {
+            const baseWorktreePath = await findWorktreeForBranch(resolved.gitRoot, baseBranch);
+            const rerunCommand = baseWorktreePath && baseWorktreePath.trim().length > 0
+                ? `agentplane integrate ${opts.taskId} --branch ${branch} --root ${baseWorktreePath}`
+                : `git checkout ${baseBranch} && agentplane integrate ${opts.taskId} --branch ${branch}`;
+            throw new CliError({
+                exitCode: exitCodeForError("E_GIT"),
+                code: "E_GIT",
+                message: `integrate must run from the ${baseBranch} base checkout, not from task branch ${branch}. ` +
+                    `Rerun it against the base checkout after leaving this task worktree.`,
+                context: withDiagnosticContext({
+                    command: "integrate",
+                    task_id: opts.taskId,
+                    branch,
+                    base_branch: baseBranch,
+                    current_branch: currentBranch,
+                    ...(baseWorktreePath ? { base_worktree_path: baseWorktreePath } : {}),
+                    reason_code: "integrate_base_checkout_required",
+                }, {
+                    state: `integrate was invoked from task branch ${branch} instead of base branch ${baseBranch}`,
+                    likelyCause: "the operator is inside the task worktree, but branch_pr integrate is only valid from the registered base checkout",
+                    hint: "Use the base checkout/worktree for the resolved base branch, not the task branch worktree, when running integrate.",
+                    nextAction: {
+                        command: rerunCommand,
+                        reason: "rerun integrate against the base checkout route",
+                        reasonCode: "integrate_base_checkout_required",
+                    },
+                }),
+            });
+        }
+        throw new CliError({
+            exitCode: exitCodeForError("E_GIT"),
+            code: "E_GIT",
+            message: `integrate must run on base branch ${baseBranch} (current: ${currentBranch})`,
+        });
+    }
     await ensureCommittedPrArtifactsOnBranch({
         resolved,
         prDir,

package/dist/commands/pr/internal/auto-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/auto-commit.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA6BnE,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACzD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CA8CnB"}
+{"version":3,"file":"auto-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/auto-commit.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAiCnE,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACzD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CA8CnB"}

package/dist/commands/pr/internal/auto-commit.js

@@ -7,8 +7,13 @@ import { gitCurrentBranch } from "../../shared/git-ops.js";
 function taskPrDirPrefix(workflowDir, taskId) {
     return `${toGitPath(path.join(workflowDir, taskId, "pr"))}/`;
 }
-function isTaskPrArtifactPath(opts) {
-    return toGitPath(opts.relPath).startsWith(taskPrDirPrefix(opts.workflowDir, opts.taskId));
+function taskReadmePath(workflowDir, taskId) {
+    return toGitPath(path.join(workflowDir, taskId, "README.md"));
+}
+function isTaskPacketPath(opts) {
+    const normalized = toGitPath(opts.relPath);
+    return (normalized === taskReadmePath(opts.workflowDir, opts.taskId) ||
+        normalized.startsWith(taskPrDirPrefix(opts.workflowDir, opts.taskId)));
 }
 async function readCachedPaths(gitRoot) {
     const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "--relative"], {
@@ -31,22 +36,22 @@ export async function maybeAutoCommitTaskPrArtifacts(opts) {
     if (!currentBranch || currentBranch !== opts.branch.trim())
         return false;
     const changedPaths = await opts.ctx.git.statusChangedPaths();
-    const prArtifactPaths = changedPaths.filter((relPath) => isTaskPrArtifactPath({
+    const taskPacketPaths = changedPaths.filter((relPath) => isTaskPacketPath({
         workflowDir: opts.ctx.config.paths.workflow_dir,
         taskId: opts.taskId,
         relPath,
     }));
-    if (prArtifactPaths.length === 0)
+    if (taskPacketPaths.length === 0)
         return false;
     const cachedPaths = await readCachedPaths(opts.ctx.resolvedProject.gitRoot);
-    if (cachedPaths.some((relPath) => !isTaskPrArtifactPath({
+    if (cachedPaths.some((relPath) => !isTaskPacketPath({
         workflowDir: opts.ctx.config.paths.workflow_dir,
         taskId: opts.taskId,
         relPath,
     }))) {
         return false;
     }
-    await opts.ctx.git.stage(prArtifactPaths);
+    await opts.ctx.git.stage(taskPacketPaths);
     await opts.ctx.git.commit({
         message: taskPrArtifactRefreshMessage(opts.taskId),
         env: buildGitCommitEnv({

package/dist/commands/pr/internal/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAoFtC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAySF,KAAK,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAmCpC,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B,GAAG,IAAI,CAAC,CAmDR;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC,CA4TD"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAoFtC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA6SF,KAAK,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAmCpC,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B,GAAG,IAAI,CAAC,CAmDR;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC,CA4TD"}

package/dist/commands/pr/internal/sync.js

@@ -282,9 +282,13 @@ async function computePrDiffstat(opts) {
         gitRoot: opts.gitRoot,
         baseBranch: opts.baseBranch,
     });
+    const taskDir = path.dirname(opts.prDir);
     try {
         return await gitDiffStat(opts.gitRoot, diffBaseRef, opts.branch, {
-            excludePaths: [path.relative(opts.gitRoot, opts.prDir)],
+            excludePaths: [
+                path.relative(opts.gitRoot, opts.prDir),
+                path.relative(opts.gitRoot, path.join(taskDir, "README.md")),
+            ],
         });
     }
     catch (err) {

package/dist/commands/pr/open.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/open.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAkBpF,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ClB"}
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/open.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAuCpF,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgElB"}