agentplane 0.3.1 → 0.3.2

package/assets/AGENTS.md

@@ -17,7 +17,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then apply `## LOAD RULES` before any mutation.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then read `docs/user/agent-bootstrap.generated.mdx`, then apply `## LOAD RULES` before any mutation.
 
 ---
 
@@ -28,7 +28,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/config.json`.
+4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `docs/user/agent-bootstrap.generated.mdx`, `.agentplane/config.json`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -66,7 +66,7 @@ agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
 agentplane task plan approve <task-id> --by ORCHESTRATOR
 agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
 agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
-agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
 ### Verification
@@ -83,6 +83,7 @@ node .agentplane/policy/check-routing.mjs
 ## TOOLING
 
 - Use `## COMMANDS` as the canonical command source.
+- Use `docs/user/agent-bootstrap.generated.mdx` as the canonical startup path for agent onboarding.
 - For policy changes, routing validation MUST pass via `node .agentplane/policy/check-routing.mjs`.
 
 ---

package/assets/policy/workflow.direct.md

@@ -23,7 +23,7 @@ agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
 agentplane task plan approve <task-id> --by ORCHESTRATOR
 agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
 agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
-agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
 ## ERROR RECOVERY
@@ -41,6 +41,7 @@ If any step fails:
 - MUST NOT perform mutating actions before explicit user approval.
 - Task documentation updates MAY be batched within one turn before approval.
 - MUST run `task plan approve` then `task start-ready` as `Step 1 -> wait -> Step 2` (never parallel).
+- In direct mode, `finish` auto-creates the deterministic close commit by default; use `--no-close-commit` only for explicit manual handling.
 - MUST stop and request re-approval on material drift.
 - Do not use worktrees in direct mode.
 - Do not perform `branch_pr`-only operations.

package/bin/agentplane.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
+import { resolveFrameworkBinaryContext } from "./runtime-context.js";
 
 async function exists(p) {
   try {
@@ -14,15 +16,12 @@ async function exists(p) {
 }
 
 async function maybeWarnGlobalBinaryInRepoCheckout() {
-  const cwd = process.cwd();
-  const repoCli = path.join(cwd, "packages", "agentplane", "src", "cli.ts");
-  const repoBin = path.join(cwd, "packages", "agentplane", "bin", "agentplane.js");
-  if (!(await exists(repoCli)) || !(await exists(repoBin))) return;
-
   const thisBin = fileURLToPath(import.meta.url);
+  const context = resolveFrameworkBinaryContext({ cwd: process.cwd(), thisBin });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return;
+
   const normalizedThis = path.resolve(thisBin);
-  const normalizedRepo = path.resolve(repoBin);
-  if (normalizedThis === normalizedRepo) return;
+  const normalizedRepo = path.resolve(context.checkout.repoBin);
 
   process.stderr.write(
     "warning: running global agentplane binary inside repository checkout.\n" +
@@ -36,6 +35,53 @@ async function maybeWarnGlobalBinaryInRepoCheckout() {
   );
 }
 
+function shouldUseGlobalBinaryInFramework() {
+  return (process.env.AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK ?? "").trim() === "1";
+}
+
+function isRepoLocalHandoffInvocation() {
+  return (process.env.AGENTPLANE_REPO_LOCAL_HANDOFF ?? "").trim() === "1";
+}
+
+function handoffToRepoLocalBinary(context) {
+  const repoBin = context.checkout?.repoBin;
+  if (!repoBin) return false;
+
+  process.stderr.write(
+    `info: detected framework checkout; delegating to repo-local binary: ${repoBin}\n`,
+  );
+
+  const result = spawnSync(process.execPath, [repoBin, ...process.argv.slice(2)], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      AGENTPLANE_REPO_LOCAL_HANDOFF: "1",
+    },
+  });
+
+  if (result.error) {
+    process.stderr.write(`error: failed to launch repo-local binary: ${result.error.message}\n`);
+    process.exitCode = 2;
+    return true;
+  }
+
+  process.exitCode = result.status ?? (result.signal ? 1 : 0);
+  return true;
+}
+
+function maybeHandoffToRepoLocalBinary() {
+  if (shouldUseGlobalBinaryInFramework() || isRepoLocalHandoffInvocation()) return false;
+
+  const context = resolveFrameworkBinaryContext({
+    cwd: process.cwd(),
+    thisBin: fileURLToPath(import.meta.url),
+  });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return false;
+
+  return handoffToRepoLocalBinary(context);
+}
+
 function isHooksRunCommitMsgInvocation(argv) {
   const args = argv.slice(2).map((value) => String(value ?? "").trim());
   for (let i = 0; i < args.length; i += 1) {
@@ -119,6 +165,8 @@ async function assertDistUpToDate() {
   return true;
 }
 
-await maybeWarnGlobalBinaryInRepoCheckout();
-const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
-if (ok) await import("../dist/cli.js");
+if (!maybeHandoffToRepoLocalBinary()) {
+  await maybeWarnGlobalBinaryInRepoCheckout();
+  const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
+  if (ok) await import("../dist/cli.js");
+}

package/bin/runtime-context.d.ts

@@ -0,0 +1,20 @@
+export type FrameworkCheckout = {
+  repoRoot: string;
+  packageRoot: string;
+  repoBin: string;
+  repoCli: string;
+};
+
+export type FrameworkBinaryContext = {
+  inFrameworkCheckout: boolean;
+  isRepoLocalBinary: boolean;
+  checkout: FrameworkCheckout | null;
+  thisBin: string;
+};
+
+export function findFrameworkCheckout(startDir: string): FrameworkCheckout | null;
+
+export function resolveFrameworkBinaryContext(options: {
+  cwd: string;
+  thisBin: string;
+}): FrameworkBinaryContext;

package/bin/runtime-context.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {{
+ *   repoRoot: string;
+ *   packageRoot: string;
+ *   repoBin: string;
+ *   repoCli: string;
+ * }} FrameworkCheckout
+ */
+
+/**
+ * @typedef {{
+ *   cwd: string;
+ *   thisBin: string;
+ * }} FrameworkBinaryContextOptions
+ */
+
+/**
+ * @typedef {{
+ *   inFrameworkCheckout: boolean;
+ *   isRepoLocalBinary: boolean;
+ *   checkout: FrameworkCheckout | null;
+ *   thisBin: string;
+ * }} FrameworkBinaryContext
+ */
+
+function fileExists(p) {
+  return existsSync(p);
+}
+
+/**
+ * @param {string} startDir
+ * @returns {FrameworkCheckout | null}
+ */
+export function findFrameworkCheckout(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const packageRoot = path.join(dir, "packages", "agentplane");
+    const repoBin = path.join(packageRoot, "bin", "agentplane.js");
+    const repoCli = path.join(packageRoot, "src", "cli.ts");
+    if (fileExists(repoBin) && fileExists(repoCli)) {
+      return {
+        repoRoot: dir,
+        packageRoot,
+        repoBin,
+        repoCli,
+      };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * @param {FrameworkBinaryContextOptions} options
+ * @returns {FrameworkBinaryContext}
+ */
+export function resolveFrameworkBinaryContext(options) {
+  const cwd = path.resolve(options.cwd);
+  const thisBin = path.resolve(options.thisBin);
+  const checkout = findFrameworkCheckout(cwd);
+  if (!checkout) {
+    return {
+      inFrameworkCheckout: false,
+      isRepoLocalBinary: false,
+      checkout: null,
+      thisBin,
+    };
+  }
+
+  return {
+    inFrameworkCheckout: true,
+    isRepoLocalBinary: path.resolve(checkout.repoBin) === thisBin,
+    checkout,
+    thisBin,
+  };
+}

package/dist/.build-manifest.json

@@ -1,11 +1,11 @@
 {
   "schema_version": 1,
   "package_dir": "/home/runner/work/agentplane/agentplane/packages/agentplane",
-  "generated_at": "2026-03-06T15:25:37.651Z",
-  "git_head": "1be96fc47916b76925f9bc59ce7d24176216a87f",
-  "src_cli_mtime_ms": 1772810682734.0005,
+  "generated_at": "2026-03-07T17:34:46.688Z",
+  "git_head": "8ffbebd27d5fa6dcf906b1781f8fe2d0030c6c98",
+  "src_cli_mtime_ms": 1772904835121.3193,
   "src_index_mtime_ms": null,
-  "dist_cli_mtime_ms": 1772810737168.81,
+  "dist_cli_mtime_ms": 1772904886214.584,
   "dist_index_mtime_ms": null,
-  "tsbuildinfo_mtime_ms": 1772810737234.8098
+  "tsbuildinfo_mtime_ms": 1772904886278.5845
 }

package/dist/cli/bootstrap-guide.d.ts

@@ -0,0 +1,18 @@
+export declare const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
+export type BootstrapSection = {
+    heading: string;
+    summary: string;
+    commands: readonly string[];
+    notes?: readonly string[];
+};
+export declare const BOOTSTRAP_PREFLIGHT_COMMANDS: readonly ["agentplane config show", "agentplane quickstart", "agentplane task list", "git status --short --untracked-files=no", "git rev-parse --abbrev-ref HEAD"];
+export declare const BOOTSTRAP_TASK_PREP_COMMANDS: string[];
+export declare const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS: readonly [...string[], "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
+export declare const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
+export declare const BOOTSTRAP_VERIFICATION_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane doctor", "node .agentplane/policy/check-routing.mjs"];
+export declare const BOOTSTRAP_RECOVERY_COMMANDS: readonly ["agentplane doctor", "agentplane upgrade --dry-run", "agentplane upgrade"];
+export declare const BOOTSTRAP_SECTIONS: readonly BootstrapSection[];
+export declare function renderBootstrapReferenceLine(): string;
+export declare function renderBootstrapSectionLines(sections: readonly BootstrapSection[]): string[];
+export declare function renderBootstrapDoc(): string;
+//# sourceMappingURL=bootstrap-guide.d.ts.map

package/dist/cli/bootstrap-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,oKAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,iCAAiC,2RAKpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,wOAIvC,CAAC;AAEX,eAAO,MAAM,+BAA+B,8LAKlC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EA+ChD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA0B3C"}

package/dist/cli/bootstrap-guide.js

@@ -0,0 +1,132 @@
+import { COMMAND_SNIPPETS } from "./command-snippets.js";
+export const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
+export const BOOTSTRAP_PREFLIGHT_COMMANDS = [
+    "agentplane config show",
+    "agentplane quickstart",
+    "agentplane task list",
+    "git status --short --untracked-files=no",
+    "git rev-parse --abbrev-ref HEAD",
+];
+export const BOOTSTRAP_TASK_PREP_COMMANDS = [
+    COMMAND_SNIPPETS.core.taskNew,
+    'agentplane task plan set <task-id> --text "..." --updated-by <ROLE>',
+    "agentplane task plan approve <task-id> --by ORCHESTRATOR",
+];
+export const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS = [
+    ...BOOTSTRAP_TASK_PREP_COMMANDS,
+    COMMAND_SNIPPETS.core.startTask,
+    COMMAND_SNIPPETS.core.verifyTask,
+    'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
+];
+export const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS = [
+    "agentplane task verify-show <task-id>",
+    COMMAND_SNIPPETS.core.verifyTask,
+    'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
+];
+export const BOOTSTRAP_VERIFICATION_COMMANDS = [
+    "agentplane task verify-show <task-id>",
+    COMMAND_SNIPPETS.core.verifyTask,
+    "agentplane doctor",
+    "node .agentplane/policy/check-routing.mjs",
+];
+export const BOOTSTRAP_RECOVERY_COMMANDS = [
+    "agentplane doctor",
+    "agentplane upgrade --dry-run",
+    "agentplane upgrade",
+];
+export const BOOTSTRAP_SECTIONS = [
+    {
+        heading: "1. Preflight",
+        summary: "Establish workflow mode, current branch, current task state, and tracked working-tree state.",
+        commands: BOOTSTRAP_PREFLIGHT_COMMANDS,
+        notes: [
+            "Run this before any mutation.",
+            "If the project is not initialized, stop and use `agentplane init` first.",
+        ],
+    },
+    {
+        heading: "2. Prepare executable task scope",
+        summary: "Work only through executable task ids. Create the task, fill plan/docs, then approve the plan.",
+        commands: BOOTSTRAP_TASK_PREP_COMMANDS,
+        notes: [
+            "Use `task doc set` to fill required README sections before approval.",
+            "For dependent tasks, wait until upstream tasks are DONE before `task start-ready`.",
+        ],
+    },
+    {
+        heading: "3. Start work deterministically",
+        summary: "Move the task to DOING only after plan approval succeeds.",
+        commands: [COMMAND_SNIPPETS.core.startTask],
+        notes: ["`task plan approve` and `task start-ready` must run sequentially, never in parallel."],
+    },
+    {
+        heading: "4. Verify and finish",
+        summary: "Treat Verify Steps as the contract, then record verification and close with traceable metadata.",
+        commands: BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS,
+        notes: [
+            "In `direct`, `finish` creates the deterministic close commit by default.",
+            "Use `--no-close-commit` only for explicit manual close handling.",
+        ],
+    },
+    {
+        heading: "5. Recover mixed or broken state",
+        summary: "Use diagnostics before manual repair, especially after framework upgrades or partial edits.",
+        commands: BOOTSTRAP_RECOVERY_COMMANDS,
+        notes: [
+            "Run `doctor` before touching managed policy files by hand.",
+            "`upgrade` applies the managed framework files from the installed CLI bundle.",
+        ],
+    },
+];
+export function renderBootstrapReferenceLine() {
+    return `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`;
+}
+export function renderBootstrapSectionLines(sections) {
+    const lines = [];
+    for (const section of sections) {
+        lines.push(`## ${section.heading}`, "", section.summary, "");
+        for (const command of section.commands) {
+            lines.push(`- \`${command}\``);
+        }
+        if (section.notes && section.notes.length > 0) {
+            lines.push("");
+            for (const note of section.notes) {
+                lines.push(`- ${note}`);
+            }
+        }
+        lines.push("");
+    }
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+function renderCommandBlock(commands) {
+    return ["```bash", ...commands, "```"];
+}
+export function renderBootstrapDoc() {
+    const lines = [
+        "---",
+        'title: "Agent bootstrap"',
+        'description: "The shortest canonical startup path for agent work in an Agent Plane repository."',
+        "---",
+        "",
+        "This page is generated from `packages/agentplane/src/cli/bootstrap-guide.ts`.",
+        "",
+        "Use it as the single startup path for agents. `AGENTS.md`, `agentplane quickstart`, and `agentplane role <ROLE>` should point here instead of restating lifecycle prose.",
+        "",
+        "## Copy-paste start block",
+        "",
+        ...renderCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
+        "",
+        "After preflight, continue with the smallest task flow that matches your mode and role.",
+        "",
+        ...renderBootstrapSectionLines(BOOTSTRAP_SECTIONS),
+        "",
+        "## Direct vs branch_pr",
+        "",
+        "- `direct`: work in the current checkout and finish the task yourself.",
+        "- `branch_pr`: start a task branch/worktree, maintain PR artifacts, and let INTEGRATOR close on base.",
+        "",
+    ];
+    return `${lines.join("\n")}\n`;
+}

package/dist/cli/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA0MA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA6FzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA+GA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAsCzC"}

package/dist/cli/command-guide.js

@@ -1,183 +1,103 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-const CHEAT_SHEET_ROWS = [
-    {
-        operation: "PLANNER: list/show tasks",
-        command: "`agentplane task list` / `agentplane task show <task-id>`",
-    },
-    {
-        operation: "PLANNER: set/approve/reject plan",
-        command: '`agentplane task plan set <task-id> --text "..." --updated-by <id>` / `agentplane task plan approve <task-id> --by <id> --note "OK"`',
-    },
-    {
-        operation: "PLANNER: create task (auto ID)",
-        command: '`agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag> [--depends-on <task-id|json>]`',
-    },
-    {
-        operation: "PLANNER: add/update task",
-        command: "`agentplane task add <task-id> ...` / `agentplane task update <task-id> ...`",
-    },
-    {
-        operation: "PLANNER: backfill/repair scaffold",
-        command: "`agentplane task scaffold <task-id>` (backfill/import/manual repair only)",
-    },
-    {
-        operation: "PLANNER: derive implementation from spike",
-        command: '`agentplane task derive <spike-id> --title "..." --description "..." --priority med --owner CODER --tag code`',
-    },
-    {
-        operation: "Config: show/set",
-        command: "`agentplane config show` / `agentplane config set <key> <value>`",
-    },
-    {
-        operation: "CODER/TESTER/DOCS: start checkout (branch_pr)",
-        command: "`agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-    },
-    {
-        operation: "CODER/TESTER: start task deterministically",
-        command: '`agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (run after successful `task plan approve`; do not run in parallel)',
-    },
-    {
-        operation: "CODER/TESTER/DOCS: update PR artifacts",
-        command: "`agentplane pr update <task-id>`",
-    },
-    {
-        operation: "CODER/TESTER/DOCS/REVIEWER: add handoff note",
-        command: '`agentplane pr note <task-id> --author <ROLE> --body "..."`',
-    },
-    {
-        operation: "CODER/TESTER: verify task",
-        command: '`agentplane verify <task-id> --ok|--rework --by <id> --note "..."` (record-only; appends to README)',
-    },
-    {
-        operation: "CODER/TESTER: print Verify Steps",
-        command: "`agentplane task verify-show <task-id>`",
-    },
-    {
-        operation: "REVIEWER: check PR artifacts",
-        command: "`agentplane pr check <task-id>`",
-    },
-    {
-        operation: "INTEGRATOR: integrate task",
-        command: "`agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify`",
-    },
-    {
-        operation: "INTEGRATOR: finish task(s)",
-        command: '`agentplane finish <task-id> [<task-id> ...] --commit <git-rev> --author INTEGRATOR --body "Verified: ..." [--result "<one line>"] [--close-commit] [--close-unstage-others]`',
-    },
-    {
-        operation: "INTEGRATOR: commit closure",
-        command: "Preferred: `agentplane finish <task-id> --close-commit` (single command). Legacy/manual: `agentplane commit <task-id> --close [--check-only] [--unstage-others]` / duplicate no-op close: `agentplane task close-duplicate <task-id> --of <canonical-task-id> --author <ROLE>`",
-    },
-];
+import { AGENT_BOOTSTRAP_DOC_PATH, BOOTSTRAP_SECTIONS, renderBootstrapReferenceLine, } from "./bootstrap-guide.js";
+function renderBootstrapOverview() {
+    const lines = [];
+    for (const section of BOOTSTRAP_SECTIONS) {
+        lines.push(`## ${section.heading}`, "", section.summary, "");
+        for (const command of section.commands) {
+            lines.push(`- \`${command}\``);
+        }
+        lines.push("");
+    }
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
 const ROLE_GUIDES = [
     {
         role: "ORCHESTRATOR",
         lines: [
-            "- Plan intake: `agentplane task list` / `agentplane task show <task-id>`",
-            "- After plan approval: ask PLANNER to create executable tasks directly from the approved task graph.",
-            "- If task graph has exactly one work item, create exactly one executable task.",
-            "- Two-stage verification: `## Verify Steps` is the ex-ante contract; `agentplane verify ...` appends an ex-post entry into `## Verification`.",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Owns preflight, plan summaries, approvals, and scope checkpoints.",
+            "- Does not create non-executable tasks or bypass lifecycle guardrails.",
         ],
     },
     {
         role: "PLANNER",
         lines: [
-            '- TODO scan: `agentplane task list` / `agentplane task search "..."` / `agentplane task next`',
-            '- Create tasks: `agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --depends-on "[]" --tag <tag>` (tags are required; use `task add` only for imported IDs)',
-            '- Update tasks: `agentplane task update <task-id> --title "..." --description "..." --priority med --owner <ROLE> --depends-on <task-id>`',
-            "- `task new` auto-seeds README sections; use `task scaffold` only for backfill/import/manual repair.",
-            '- Plan lifecycle: `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>` -> `agentplane task plan approve <task-id> --by <id>`',
-            "- Verify Steps discipline: if a task primary tag is verify-required (default: code/data/ops), fill `## Verify Steps` before plan approval.",
-            "- Doc quality gate: `task plan approve` and `finish` fail when required agent-filled sections (`Summary/Scope/Plan/Risks/Rollback Plan`, per config) are empty/TODO placeholders.",
-            '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`; if `--text`/`--file` contains multiple known headings, the command applies it as one batched full-doc update.',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- Create executable tasks with `agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>`.',
+            '- Fill docs with `agentplane task doc set <task-id> --section <name> --text "..."` and set plan text with `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>`.',
+            "- Approve plan only after required sections and Verify Steps are ready.",
         ],
     },
     {
         role: "CODER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
-            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
-            "- Verify Steps: `agentplane task verify-show <task-id>` (use as the verification contract before recording results).",
-            '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
-            '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- direct: stay in the current checkout; branch_pr: start a task branch/worktree first.",
+            `- Start deterministically with \`${COMMAND_SNIPPETS.core.startTask}\` after plan approval.`,
+            '- Treat `agentplane task verify-show <task-id>` as the verification contract, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
+            `- Preferred direct close path: \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`; add \`--no-close-commit\` only for explicit manual close handling.`,
         ],
     },
     {
         role: "TESTER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
-            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
-            "- Verify Steps: `agentplane task verify-show <task-id>` (treat as the verification contract).",
-            '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
-            '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Start only after plan approval and explicit Verify Steps exist.",
+            '- Use `agentplane task verify-show <task-id>` before running checks, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
+            `- In direct mode, close with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \` when you own final verification.`,
         ],
     },
     {
         role: "DOCS",
         lines: [
-            '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section, or send one multi-heading full-doc payload via `--text`/`--file`)',
-            '- PR notes: `agentplane pr note <task-id> --author DOCS --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- Keep task docs and user docs aligned with runtime behavior via `agentplane task doc set <task-id> --section <name> --text "..."`.',
+            "- For implementation tasks, verify generated/help surfaces after changing CLI-facing text.",
         ],
     },
     {
         role: "REVIEWER",
         lines: [
-            "- Review artifacts: `agentplane pr check <task-id>` / `agentplane task show <task-id>`",
-            '- Handoff notes: `agentplane pr note <task-id> --author REVIEWER --body "..."`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Review artifacts with `agentplane task show <task-id>` and `agentplane pr check <task-id>` when relevant.",
+            "- Focus on regressions, lifecycle drift, and missing verification evidence.",
         ],
     },
     {
         role: "INTEGRATOR",
         lines: [
-            '- branch_pr: `agentplane pr check <task-id>` -> `agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify` -> `agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --close-commit`',
-            '- direct: task owner uses `agentplane finish <task-id> --commit <git-rev> --author <OWNER> --body "Verified: ..." --close-commit` after the implementation commit',
-            "- Optional cleanup: `agentplane cleanup merged --yes`",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- branch_pr: `agentplane pr check <task-id>` -> `agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify` -> `agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --result "..." --close-commit`.',
+            `- direct: the task owner normally closes with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \`.`,
         ],
     },
     {
         role: "CREATOR",
         lines: [
-            '- Task bookkeeping: `agentplane task update <task-id> ...` / `agentplane task start-ready <task-id> --author CREATOR --body "Start: ..."`',
-            '- Commits: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            `- Use \`${COMMAND_SNIPPETS.core.startTask}\` only when the new-agent creation task is approved and ready.`,
+            "- Keep commits scoped to the created agent artifacts and task docs.",
         ],
     },
     {
         role: "REDMINE",
         lines: [
-            `- Sync before/after updates: \`${COMMAND_SNIPPETS.sync.pullRedmineExplicit}\` / \`${COMMAND_SNIPPETS.sync.pushRedmineExplicitWithYes}\``,
-            "- Then use normal task/doc commands (`agentplane task list` / `agentplane task show` / `agentplane task update` / `agentplane task doc set`) as needed.",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            `- Sync explicitly with \`${COMMAND_SNIPPETS.sync.pullRedmineExplicit}\` / \`${COMMAND_SNIPPETS.sync.pushRedmineExplicitWithYes}\`.`,
+            "- After sync, follow the same task/bootstrap lifecycle as local backends.",
         ],
     },
     {
         role: "UPDATER",
         lines: [
-            '- Read-only audit: `agentplane task list` / `agentplane task show` / `agentplane task search "..."` / `agentplane task next` (no write commands).',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Read-only role: inspect state, do not mutate task or workflow artifacts.",
         ],
     },
 ];
-function renderCheatSheet(rows) {
-    const lines = ["Operation | Command", "--- | ---"];
-    for (const row of rows) {
-        lines.push(`${row.operation} | ${row.command}`);
-    }
-    return lines;
-}
-function renderRoleSection() {
-    const lines = [];
-    for (const guide of ROLE_GUIDES) {
-        lines.push(`### ${guide.role}`, ...guide.lines, "");
-    }
-    if (lines.at(-1) === "")
-        lines.pop();
-    return lines;
-}
 export function listRoles() {
     return ROLE_GUIDES.map((guide) => guide.role);
 }
@@ -195,84 +115,30 @@ export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy; quickstart and role output are the source of truth for CLI syntax and artifacts.",
+        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy. CLI syntax lives in quickstart and `agentplane role <ROLE>`.",
         "Do not edit `.agentplane/tasks.json` by hand.",
+        "If the repository is not initialized yet, stop and run `agentplane init` first.",
         "",
-        "- See your policy gateway file (AGENTS.md or CLAUDE.md) for canonical workflow policy and approval gates.",
-        "",
-        "## Project setup",
+        renderBootstrapReferenceLine(),
         "",
-        "- `agentplane init` (bootstrap `.agentplane/`)",
-        "- `agentplane config show` / `agentplane config set <key> <value>`",
-        "- `agentplane mode get` / `agentplane mode set <direct|branch_pr>`",
-        "- `agentplane ide sync` (regenerate IDE entrypoints)",
+        ...renderBootstrapOverview(),
         "",
-        "## Daily task workflow",
+        "## Role-specific deltas",
         "",
-        `- \`${COMMAND_SNIPPETS.core.taskList}\` / \`${COMMAND_SNIPPETS.core.taskShow}\``,
-        `- \`${COMMAND_SNIPPETS.core.taskNew}\``,
-        `- \`${COMMAND_SNIPPETS.core.startTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.verifyTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.finishTask}\``,
+        `- Use \`${COMMAND_SNIPPETS.core.role}\` for role-specific constraints after you understand the shared bootstrap path.`,
+        "- Role output should add deltas, not replace the canonical bootstrap flow.",
         "",
-        "## Harness engeneering loop",
-        "",
-        "- Constrain: policy + workflow contract first.",
-        "- Execute: small explicit transitions.",
-        "- Observe: structured artifacts and diagnostics.",
-        "- Recover: deterministic fallback before manual repair.",
-        "",
-        "## Branch workflow (branch_pr)",
+        "## Branch workflow extras",
         "",
         "- `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
         "- `agentplane pr open <task-id>` / `agentplane pr update <task-id>` / `agentplane pr check <task-id>`",
         "- `agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify`",
         "",
-        "## Workflow operations (core)",
-        "- `agentplane workflow debug`",
-        "- `agentplane workflow sync`",
-        "- `agentplane workflow land`",
-        "",
-        "## Recipes and scenarios (extensions)",
-        "",
-        "- `agentplane recipes list`",
-        "- `agentplane recipes list --tag <tag>`",
-        "- `agentplane recipes explain <id>`",
-        "- `agentplane scenario list`",
-        "- `agentplane scenario run <recipe:scenario>`",
-        "",
         "## More guidance",
         "",
-        `- \`${COMMAND_SNIPPETS.core.quickstart}\` and \`${COMMAND_SNIPPETS.core.role}\` show command guidance.`,
-        "",
-        "## Agent cheat sheet",
-        "",
-        ...renderCheatSheet(CHEAT_SHEET_ROWS),
-        "",
-        "## Config management",
-        "",
-        "- Show the current config: `agentplane config show`",
-        "- Set a value by dotted key: `agentplane config set workflow_mode branch_pr`",
-        '- Set JSON values (lists/objects): `agentplane config set tasks.verify.require_steps_for_primary \'["code","data","ops"]\'`',
-        "",
-        "## Role/phase command guide (when to use what)",
-        "",
-        "Use `agentplane role <ROLE>` to print a single block from this section.",
-        "",
-        ...renderRoleSection(),
-        "",
-        "## Global flags",
-        "",
-        "- `--root <path>`: treat <path> as project root",
-        "- `--output <text|json>`: force global CLI output mode (`json` is agent-oriented envelope mode)",
-        "- `--json-errors`: emit JSON-formatted errors",
-        "- `--help` / `-h`: show help",
-        "- `--version`: show version",
-        "- `--no-update-check`: skip checking npm for a newer CLI version",
-        "",
-        "Notes:",
-        "- `AGENTPLANE_OUTPUT=json` enables global JSON output mode for agent runtimes.",
-        "- `.env` at the repo root is loaded automatically (without overwriting existing environment variables).",
+        "- `agentplane help <command>` for command-level flags and examples.",
+        `- \`${COMMAND_SNIPPETS.core.role}\` for role-specific deltas.`,
+        `- \`${AGENT_BOOTSTRAP_DOC_PATH}\` for the canonical startup path in repository docs.`,
         "",
         "## Commit message format",
         "",

package/dist/cli/command-snippets.d.ts

@@ -2,10 +2,10 @@ export declare const COMMAND_SNIPPETS: {
     readonly core: {
         readonly taskList: "agentplane task list";
         readonly taskShow: "agentplane task show <task-id>";
-        readonly taskNew: "agentplane task new --title \"...\" --description \"...\" --priority med --owner CODER --tag <tag>";
+        readonly taskNew: "agentplane task new --title \"...\" --description \"...\" --priority med --owner <ROLE> --tag <tag>";
         readonly startTask: "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"";
         readonly verifyTask: "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"";
-        readonly finishTask: "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --commit <git-rev> --close-commit";
+        readonly finishTask: "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --commit <git-rev>";
         readonly quickstart: "agentplane quickstart";
         readonly role: "agentplane role <ROLE>";
     };

package/dist/cli/command-snippets.js

@@ -2,10 +2,10 @@ export const COMMAND_SNIPPETS = {
     core: {
         taskList: "agentplane task list",
         taskShow: "agentplane task show <task-id>",
-        taskNew: 'agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag>',
+        taskNew: 'agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>',
         startTask: 'agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."',
         verifyTask: 'agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."',
-        finishTask: 'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev> --close-commit',
+        finishTask: 'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev>',
         quickstart: "agentplane quickstart",
         role: "agentplane role <ROLE>",
     },

package/dist/cli/run-cli/commands/core.js

@@ -15,7 +15,7 @@ import { wrapCommand } from "./wrap-command.js";
 export const quickstartSpec = {
     id: ["quickstart"],
     group: "Core",
-    summary: "Print CLI quickstart and command cheat sheet.",
+    summary: "Print the canonical agent bootstrap path and startup guidance.",
     options: [
         {
             kind: "boolean",

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":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAyUrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAmDlD,CAAC"}
+{"version":3,"file":"doctor.run.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.run.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAoXrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAmDlD,CAAC"}

package/dist/commands/doctor.run.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveProject } from "@agentplaneorg/core";
 import { warnMessage, successMessage } from "../cli/output.js";
 import { RUNTIME_GITIGNORE_LINES } from "../shared/runtime-artifacts.js";
@@ -57,6 +58,29 @@ async function isDirectory(absPath) {
         return false;
     }
 }
+async function listMissingManagedPolicyFiles(repoRoot) {
+    const manifestPath = fileURLToPath(new URL("../../assets/framework.manifest.json", import.meta.url));
+    let parsed = {};
+    try {
+        parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const relPaths = Array.isArray(parsed.files)
+        ? parsed.files
+            .filter((entry) => entry?.required === true && typeof entry.path === "string")
+            .map((entry) => String(entry.path).replaceAll("\\", "/").trim())
+            .filter((relPath) => relPath.startsWith(".agentplane/policy/"))
+        : [];
+    const missing = [];
+    for (const relPath of relPaths) {
+        if (!(await pathExists(path.join(repoRoot, relPath)))) {
+            missing.push(relPath);
+        }
+    }
+    return missing.toSorted();
+}
 async function checkWorkspace(repoRoot) {
     const problems = [];
     const requiredFiles = [path.join(repoRoot, ".agentplane", "config.json")];
@@ -72,6 +96,19 @@ async function checkWorkspace(repoRoot) {
     if (!(await pathExists(gateway.absPath))) {
         problems.push("Missing required policy gateway file: AGENTS.md or CLAUDE.md");
     }
+    if (await pathExists(gateway.absPath)) {
+        const missingManagedPolicy = await listMissingManagedPolicyFiles(repoRoot);
+        if (missingManagedPolicy.length > 0) {
+            const listed = missingManagedPolicy.slice(0, 8).join(", ");
+            const more = missingManagedPolicy.length > 8 ? ` (+${missingManagedPolicy.length - 8} more)` : "";
+            problems.push("Managed policy tree is incomplete for the current framework gateway. " +
+                `Missing required files: ${listed}${more}. ` +
+                "This often means AGENTS.md/CLAUDE.md was updated manually or the repo was upgraded " +
+                "with an older agentplane CLI. Recovery: update or reinstall agentplane, then run " +
+                "`agentplane upgrade --yes` (or `agentplane upgrade --remote --yes`). " +
+                "See `docs/help/legacy-upgrade-recovery.mdx` for the shortest recovery path.");
+        }
+    }
     const agentsDir = path.join(repoRoot, ".agentplane", "agents");
     if (!(await isDirectory(agentsDir))) {
         problems.push("Missing required directory: .agentplane/agents");

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,CAsCjE"}
+{"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"}

package/dist/commands/finish.run.js

@@ -36,6 +36,7 @@ export function makeRunFinishHandler(getCtx) {
             statusCommitRequireClean: p.statusCommitRequireClean,
             confirmStatusCommit: p.confirmStatusCommit,
             closeCommit: p.closeCommit,
+            noCloseCommit: p.noCloseCommit,
             closeUnstageOthers: p.closeUnstageOthers,
             quiet: p.quiet,
         });

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

@@ -22,6 +22,7 @@ export type FinishParsed = {
     statusCommitRequireClean: boolean;
     confirmStatusCommit: boolean;
     closeCommit: boolean;
+    noCloseCommit: boolean;
     closeUnstageOthers: boolean;
     quiet: boolean;
 };

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,kBAAkB,EAAE,OAAO,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAsShD,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;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,CA6ThD,CAAC"}

package/dist/commands/finish.spec.js

@@ -145,6 +145,12 @@ export const finishSpec = {
             default: false,
             description: "After finishing, run a deterministic close commit for the task README (single-task only).",
         },
+        {
+            kind: "boolean",
+            name: "no-close-commit",
+            default: false,
+            description: "Disable the default deterministic close commit in direct mode (single-task only).",
+        },
         {
             kind: "boolean",
             name: "close-unstage-others",
@@ -228,12 +234,26 @@ export const finishSpec = {
                 message: "--close-commit requires exactly one task id",
             });
         }
-        if (raw.opts["close-commit"] === true &&
+        if (raw.opts["no-close-commit"] === true && taskIds.length !== 1) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "--no-close-commit requires exactly one task id",
+            });
+        }
+        if (raw.opts["close-commit"] === true && raw.opts["no-close-commit"] === true) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "--close-commit and --no-close-commit are mutually exclusive",
+            });
+        }
+        if ((raw.opts["close-commit"] === true || raw.opts["no-close-commit"] === true) &&
             (raw.opts["commit-from-comment"] === true || raw.opts["status-commit"] === true)) {
             throw usageError({
                 spec: finishSpec,
                 command: "finish",
-                message: "--close-commit cannot be combined with --commit-from-comment/--status-commit",
+                message: "--close-commit/--no-close-commit cannot be combined with --commit-from-comment/--status-commit",
             });
         }
         if (raw.opts["close-unstage-others"] === true && raw.opts["close-commit"] !== true) {
@@ -279,6 +299,7 @@ export const finishSpec = {
         statusCommitRequireClean: raw.opts["status-commit-require-clean"] === true,
         confirmStatusCommit: raw.opts["confirm-status-commit"] === true,
         closeCommit: raw.opts["close-commit"] === true,
+        noCloseCommit: raw.opts["no-close-commit"] === true,
         closeUnstageOthers: raw.opts["close-unstage-others"] === true,
         quiet: raw.opts.quiet === true,
     }),

package/dist/commands/release/apply.command.d.ts

@@ -6,6 +6,7 @@ export type ReleaseApplyFlags = {
     remote: string;
 };
 export type ReleaseApplyParsed = ReleaseApplyFlags;
+export declare function pushReleaseRefs(gitRoot: string, remote: string, tag: string): Promise<void>;
 export declare const releaseApplySpec: CommandSpec<ReleaseApplyParsed>;
 export declare const runReleaseApply: CommandHandler<ReleaseApplyParsed>;
 //# sourceMappingURL=apply.command.d.ts.map

package/dist/commands/release/apply.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/apply.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAU1E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AA4VnD,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAiF5D,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,kBAAkB,CAoL9D,CAAC"}
+{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/apply.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAU1E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AA4VnD,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASjG;AAED,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAiF5D,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,kBAAkB,CAgL9D,CAAC"}

package/dist/commands/release/apply.command.js

@@ -285,6 +285,16 @@ async function writeReleaseApplyReport(gitRoot, report) {
     await writeFile(latestPath, text, "utf8");
     return reportPath;
 }
+export async function pushReleaseRefs(gitRoot, remote, tag) {
+    await execFileAsync("git", ["push", "--no-verify", remote, "HEAD"], {
+        cwd: gitRoot,
+        env: gitEnv(),
+    });
+    await execFileAsync("git", ["push", "--no-verify", remote, tag], {
+        cwd: gitRoot,
+        env: gitEnv(),
+    });
+}
 export const releaseApplySpec = {
     id: ["release", "apply"],
     group: "Release",
@@ -497,11 +507,7 @@ export const runReleaseApply = async (ctx, flags) => {
     await execFileAsync("git", ["tag", plan.nextTag], { cwd: gitRoot, env: gitEnv() });
     process.stdout.write(`Release tag created: ${plan.nextTag}\n`);
     if (flags.push) {
-        await execFileAsync("git", ["push", flags.remote, "HEAD"], { cwd: gitRoot, env: gitEnv() });
-        await execFileAsync("git", ["push", flags.remote, plan.nextTag], {
-            cwd: gitRoot,
-            env: gitEnv(),
-        });
+        await pushReleaseRefs(gitRoot, flags.remote, plan.nextTag);
         process.stdout.write(`Pushed: ${flags.remote} HEAD + ${plan.nextTag}\n`);
     }
     else {

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

@@ -25,6 +25,7 @@ export declare function cmdFinish(opts: {
     statusCommitRequireClean: boolean;
     confirmStatusCommit: boolean;
     closeCommit?: boolean;
+    noCloseCommit?: boolean;
     closeUnstageOthers?: boolean;
     quiet: boolean;
 }): Promise<number>;

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

@@ -1 +1 @@
-{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAoCnC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,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,CAAC,EAAE,OAAO,CAAC;IACd,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,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsWlB"}
+{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAoCnC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,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,CAAC,EAAE,OAAO,CAAC;IACd,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,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsXlB"}

package/dist/commands/task/finish.js

@@ -51,18 +51,25 @@ export async function cmdFinish(opts) {
                 message: "--commit-from-comment/--status-commit requires exactly one task id",
             });
         }
-        if (opts.closeCommit && opts.taskIds.length !== 1) {
+        if ((opts.closeCommit || opts.noCloseCommit) && opts.taskIds.length !== 1) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "--close-commit requires exactly one task id",
+                message: "--close-commit/--no-close-commit requires exactly one task id",
             });
         }
-        if (opts.closeCommit && (opts.commitFromComment || opts.statusCommit)) {
+        if (opts.closeCommit && opts.noCloseCommit) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "--close-commit cannot be combined with --commit-from-comment/--status-commit",
+                message: "--close-commit and --no-close-commit are mutually exclusive",
+            });
+        }
+        if ((opts.closeCommit || opts.noCloseCommit) && (opts.commitFromComment || opts.statusCommit)) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "--close-commit/--no-close-commit cannot be combined with --commit-from-comment/--status-commit",
             });
         }
         const primaryTaskId = opts.taskIds[0] ?? "";
@@ -107,6 +114,12 @@ export async function cmdFinish(opts) {
             : await readHeadCommit(gitRoot);
         const useStore = backendIsLocalFileBackend(ctx);
         const store = useStore ? getTaskStore(ctx) : null;
+        const defaultDirectCloseCommit = ctx.config.workflow_mode === "direct" &&
+            useStore &&
+            opts.taskIds.length === 1 &&
+            !opts.commitFromComment &&
+            !statusCommitRequested;
+        const shouldCloseCommit = opts.closeCommit === true || (defaultDirectCloseCommit && opts.noCloseCommit !== true);
         const metaTaskId = opts.taskIds.length === 1 ? (opts.taskIds[0] ?? "") : "";
         const wantMeta = typeof opts.result === "string" || typeof opts.risk === "string" || opts.breaking === true;
         if (wantMeta && opts.taskIds.length !== 1) {
@@ -308,7 +321,7 @@ export async function cmdFinish(opts) {
                 config: ctx.config,
             });
         }
-        if (opts.closeCommit && primaryTaskId) {
+        if (shouldCloseCommit && primaryTaskId) {
             await cmdCommit({
                 ctx,
                 cwd: opts.cwd,
@@ -326,7 +339,7 @@ export async function cmdFinish(opts) {
                 allowCI: false,
                 requireClean: true,
                 quiet: opts.quiet,
-                closeUnstageOthers: opts.closeUnstageOthers === true,
+                closeUnstageOthers: opts.closeCommit === true && opts.closeUnstageOthers === true,
                 closeCheckOnly: false,
             });
         }

package/dist/commands/upgrade.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CA2JlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}
+{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CA8JlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}

package/dist/commands/upgrade.command.js

@@ -4,19 +4,19 @@ export const upgradeSpec = {
     id: ["upgrade"],
     group: "Setup",
     summary: "Upgrade the local agentplane framework bundle in the repo.",
-    description: "Upgrades the local agentplane framework bundle in the repo using a strict manifest of managed files. By default, upgrade generates an agent-assisted plan from the locally installed agentplane package assets (no network) and does not modify files. Use --auto to apply changes and create a dedicated upgrade commit. Use --remote to fetch a GitHub release bundle; network access is gated by config approvals.",
+    description: "Upgrades the local agentplane framework bundle in the repo using a strict manifest of managed files. By default, upgrade applies the bundled managed files from the locally installed agentplane package assets (no network) and creates a dedicated upgrade commit. Use --dry-run to preview changes without writing files, or --agent to generate a review plan instead of applying. Use --remote to fetch a GitHub release bundle; network access is gated by config approvals.",
     options: [
         {
             kind: "boolean",
             name: "agent",
             default: false,
-            description: "Generate an agent-assisted upgrade plan (no files are modified). This is the default mode.",
+            description: "Generate an agent-assisted upgrade plan instead of applying managed files.",
         },
         {
             kind: "boolean",
             name: "auto",
             default: false,
-            description: "Apply the upgrade automatically (writes managed files) and create a dedicated upgrade commit.",
+            description: "Apply the upgrade automatically (same behavior as the default mode; useful for explicit scripts).",
         },
         {
             kind: "boolean",
@@ -97,11 +97,15 @@ export const upgradeSpec = {
     examples: [
         {
             cmd: "agentplane upgrade",
-            why: "Generate an agent-assisted plan using locally installed assets (no network).",
+            why: "Apply managed files from the installed CLI assets and create an upgrade commit.",
         },
         {
-            cmd: "agentplane upgrade --auto",
-            why: "Apply the upgrade automatically (writes managed files).",
+            cmd: "agentplane upgrade --dry-run",
+            why: "Preview managed-file changes without modifying the repo.",
+        },
+        {
+            cmd: "agentplane upgrade --agent",
+            why: "Generate an agent-assisted upgrade plan instead of applying files.",
         },
         {
             cmd: "agentplane upgrade --remote --tag v0.1.9 --dry-run",
@@ -115,7 +119,7 @@ export const upgradeSpec = {
     parse: (raw) => {
         const noBackup = raw.opts["no-backup"] === true;
         return {
-            mode: raw.opts.auto === true ? "auto" : "agent",
+            mode: raw.opts.agent === true ? "agent" : "auto",
             remote: raw.opts.remote === true,
             allowTarball: raw.opts["allow-tarball"] === true,
             source: raw.opts.source,

package/dist/commands/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAiGF,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,GAAG;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAWA;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,GACG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAqB1C;AAUD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAgBT;AAmRD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6oBlB"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AA6GF,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,GAAG;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAWA;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,GACG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAqB1C;AAUD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAgBT;AAmRD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAupBlB"}

package/dist/commands/upgrade.js

@@ -17,6 +17,17 @@ const DEFAULT_UPGRADE_ASSET = "agentplane-upgrade.tar.gz";
 const DEFAULT_UPGRADE_CHECKSUM_ASSET = "agentplane-upgrade.tar.gz.sha256";
 const UPGRADE_DOWNLOAD_TIMEOUT_MS = 60_000;
 const UPGRADE_RELEASE_METADATA_TIMEOUT_MS = 15_000;
+function describeUpgradeSource(opts) {
+    if (opts.bundleLayout === "local_assets")
+        return "local installed agentplane CLI assets";
+    if (opts.bundleLayout === "repo_tarball")
+        return "GitHub repo tarball fallback";
+    if (opts.hasExplicitBundle)
+        return "explicit upgrade bundle";
+    if (opts.useRemote)
+        return "GitHub release bundle";
+    return "upgrade bundle";
+}
 async function safeRemovePath(targetPath) {
     try {
         await rm(targetPath, { recursive: true, force: true });
@@ -537,6 +548,14 @@ export async function cmdUpgradeParsed(opts) {
             ? fileURLToPath(new URL("../../assets/framework.manifest.json", import.meta.url))
             : path.join(bundleRoot, "framework.manifest.json");
         const manifest = await loadFrameworkManifestFromPath(manifestPath);
+        const modeLabel = flags.dryRun ? "dry-run" : flags.mode === "agent" ? "review" : "apply";
+        process.stdout.write(`Upgrade source: ${describeUpgradeSource({
+            bundleLayout,
+            hasExplicitBundle: hasBundle,
+            useRemote,
+        })}\n` +
+            `Upgrade version: ${upgradeVersionLabel}\n` +
+            `Upgrade mode: ${modeLabel}\n`);
         const additions = [];
         const updates = [];
         const skipped = [];
@@ -777,7 +796,7 @@ export async function cmdUpgradeParsed(opts) {
             await mkdir(runDir, { recursive: true });
             const managedFiles = manifest.files.map((f) => f.path.replaceAll("\\", "/").trim());
             const planMd = `# agentplane upgrade plan (${runId})\n\n` +
-                `Mode: agent-assisted (no files modified)\n\n` +
+                `Mode: agent-assisted review (no files modified)\n\n` +
                 `## Summary\n\n` +
                 `- additions: ${additions.length}\n` +
                 `- updates: ${updates.length}\n` +
@@ -798,7 +817,7 @@ export async function cmdUpgradeParsed(opts) {
                 `\n` +
                 `## Next steps\n\n` +
                 `1. Review the proposed changes list.\n` +
-                `2. Apply changes manually or re-run with \`agentplane upgrade --auto\` to apply managed files.\n` +
+                `2. Apply changes manually or re-run without \`--agent\` to apply managed files.\n` +
                 `3. Run \`agentplane doctor\` (or \`agentplane doctor --fix\`) and ensure checks pass.\n`;
             const constraintsMd = `# Upgrade constraints\n\n` +
                 `This upgrade is restricted to framework-managed files only.\n\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -55,7 +55,7 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.3.1",
+    "@agentplaneorg/core": "0.3.2",
     "yauzl": "^2.10.0"
   },
   "devDependencies": {