agentplane 0.2.19 → 0.2.22

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

@@ -18,6 +18,32 @@ import { ensureAgentsFiles } from "./init/write-agents.js";
 import { ensureInitGitignore } from "./init/write-gitignore.js";
 import { ensureInitRedmineEnvTemplate } from "./init/write-env.js";
 import { renderInitSection, renderInitWelcome } from "./init/ui.js";
+const setupProfilePresets = {
+    prod: {
+        mode: "prod",
+        description: "Production bootstrap: compact flow with default managed-file and approval settings.",
+        defaultHooks: false,
+        defaultStrictUnsafeConfirm: false,
+    },
+    "prod-strict": {
+        mode: "prod",
+        description: "Production bootstrap + strict defaults for safer installs (hooks on, strict unsafe confirmations).",
+        defaultHooks: true,
+        defaultStrictUnsafeConfirm: true,
+    },
+    dev: {
+        mode: "dev",
+        description: "Developer bootstrap: full questionnaire for every init aspect.",
+        defaultHooks: false,
+        defaultStrictUnsafeConfirm: false,
+    },
+    "dev-safe": {
+        mode: "dev",
+        description: "Developer bootstrap with explicit unsafe-action confirmation by default.",
+        defaultHooks: false,
+        defaultStrictUnsafeConfirm: true,
+    },
+};
 function parseBooleanValueForInit(flag, value) {
     const normalized = value.trim().toLowerCase();
     if (["1", "true", "yes", "y", "on"].includes(normalized))
@@ -45,6 +71,13 @@ export const initSpec = {
     summary: "Initialize agentplane project files under .agentplane/.",
     description: "Creates .agentplane/ config, backend stubs, and agent templates in the target directory. If the target directory is not a git repository, it initializes one and (by default) writes an initial install commit. Use --gitignore-agents to keep agent templates local (gitignored) and skip the install commit. In interactive mode it prompts for missing inputs; use --yes for non-interactive mode.",
     options: [
+        {
+            kind: "string",
+            name: "setup-profile",
+            valueHint: "<prod|dev>",
+            choices: ["prod", "dev"],
+            description: "Interactive preset. prod is the default and asks only essential questions; dev asks the full setup questionnaire.",
+        },
         {
             kind: "string",
             name: "ide",
@@ -167,6 +200,7 @@ export const initSpec = {
         const requireVerifyRaw = raw.opts["require-verify-approval"];
         const recipesRaw = raw.opts.recipes;
         return {
+            setupProfile: raw.opts["setup-profile"],
             ide: raw.opts.ide,
             workflow: raw.opts.workflow,
             backend: raw.opts.backend,
@@ -226,6 +260,8 @@ async function cmdInit(opts) {
     let requireVerifyApproval = flags.requireVerifyApproval ?? defaults.requireVerifyApproval;
     let executionProfile = flags.executionProfile ?? defaults.executionProfile;
     let strictUnsafeConfirm = flags.strictUnsafeConfirm ?? defaults.strictUnsafeConfirm;
+    let setupProfile = flags.setupProfile ?? "prod";
+    let setupProfilePreset = flags.setupProfile ?? "prod";
     const isInteractive = process.stdin.isTTY && !flags.yes;
     if (!process.stdin.isTTY &&
         !flags.yes &&
@@ -257,9 +293,26 @@ async function cmdInit(opts) {
             return result;
         };
         process.stdout.write(renderInitWelcome());
-        process.stdout.write(renderInitSection("Workflow", "Choose how branches/backends/approvals should be initialized for this repository."));
+        const presetLines = Object.entries(setupProfilePresets).map(([id, preset]) => `- ${id}: ${preset.description}`);
+        process.stdout.write(renderInitSection("Setup Preset", "Choose a bootstrap preset. It controls what questions are shown and safe defaults used."));
+        process.stdout.write(`${presetLines.join("\n")}\n\n`);
+        if (flags.setupProfile) {
+            setupProfilePreset = flags.setupProfile;
+        }
+        else {
+            const selected = await askChoice("Setup preset", ["prod", "prod-strict", "dev", "dev-safe"], "prod");
+            setupProfilePreset = selected;
+        }
+        const selectedPreset = setupProfilePresets[setupProfilePreset];
+        setupProfile = selectedPreset.mode;
+        if (flags.hooks === undefined)
+            hooks = selectedPreset.defaultHooks;
+        if (flags.strictUnsafeConfirm === undefined) {
+            strictUnsafeConfirm = selectedPreset.defaultStrictUnsafeConfirm;
+        }
+        process.stdout.write(renderInitSection("Workflow", "Choose how this repository will be orchestrated: direct means one branch, branch_pr means PR-first tasks."));
         ide = flags.ide ?? defaults.ide;
-        if (!flags.workflow) {
+        if (!flags.workflow && setupProfile === "dev") {
             const choice = await askChoice("Workflow mode", ["direct", "branch_pr"], workflow);
             workflow = choice === "branch_pr" ? "branch_pr" : "direct";
         }
@@ -267,36 +320,48 @@ async function cmdInit(opts) {
             const choice = await askChoice("Task backend", ["local", "redmine"], backend);
             backend = choice === "redmine" ? "redmine" : "local";
         }
-        if (flags.hooks === undefined) {
-            hooks = await askYesNo("Install managed git hooks now?", hooks);
-        }
-        process.stdout.write(renderInitSection("Execution Profile", "Set default autonomy/effort for agents. You can change this later in config."));
-        if (!flags.executionProfile) {
-            executionProfile = (await askChoice("Execution profile", ["conservative", "balanced", "aggressive"], executionProfile));
-        }
-        if (flags.strictUnsafeConfirm === undefined) {
-            strictUnsafeConfirm = await askYesNo("Require strict explicit confirmation for extra unsafe actions?", strictUnsafeConfirm);
-        }
-        process.stdout.write(renderInitSection("Approvals", "Control whether plan/network/verification actions require explicit approval by default."));
-        if (flags.requirePlanApproval === undefined) {
-            requirePlanApproval = await askYesNo("Require plan approval before work starts?", requirePlanApproval);
-        }
-        if (flags.requireNetworkApproval === undefined) {
-            requireNetworkApproval = await askYesNo("Require explicit approval for network actions?", requireNetworkApproval);
-        }
-        if (flags.requireVerifyApproval === undefined) {
-            requireVerifyApproval = await askYesNo("Require explicit approval before recording verification?", requireVerifyApproval);
+        if (setupProfile === "dev") {
+            if (flags.hooks === undefined) {
+                hooks = await askYesNo("Install managed git hooks now?", hooks);
+            }
+            process.stdout.write(renderInitSection("Execution Profile", "Set default autonomy/effort for agents. You can change this later in config."));
+            if (!flags.executionProfile) {
+                executionProfile = (await askChoice("Execution profile", ["conservative", "balanced", "aggressive"], executionProfile));
+            }
+            if (flags.strictUnsafeConfirm === undefined) {
+                strictUnsafeConfirm = await askYesNo("Require strict explicit confirmation for extra unsafe actions?", strictUnsafeConfirm);
+            }
+            process.stdout.write(renderInitSection("Approvals", "Control whether plan/network/verification actions require explicit approval by default."));
+            if (flags.requirePlanApproval === undefined) {
+                requirePlanApproval = await askYesNo("Require plan approval before work starts?", requirePlanApproval);
+            }
+            if (flags.requireNetworkApproval === undefined) {
+                requireNetworkApproval = await askYesNo("Require explicit approval for network actions?", requireNetworkApproval);
+            }
+            if (flags.requireVerifyApproval === undefined) {
+                requireVerifyApproval = await askYesNo("Require explicit approval before recording verification?", requireVerifyApproval);
+            }
+            process.stdout.write(renderInitSection("Recipes", "Optional: install recipe packs now (comma-separated IDs) or choose none."));
+            if (!flags.recipes) {
+                process.stdout.write(`${renderBundledRecipesHint()}\n`);
+                const answer = await askInput("Install optional recipes (comma separated, or none): ");
+                recipes = answer
+                    ? answer
+                        .split(",")
+                        .map((item) => item.trim())
+                        .filter(Boolean)
+                    : [];
+            }
         }
-        process.stdout.write(renderInitSection("Recipes", "Optional: install recipe packs now (comma-separated IDs) or choose none."));
-        if (!flags.recipes) {
-            process.stdout.write(`${renderBundledRecipesHint()}\n`);
-            const answer = await askInput("Install optional recipes (comma separated, or none): ");
-            recipes = answer
-                ? answer
-                    .split(",")
-                    .map((item) => item.trim())
-                    .filter(Boolean)
-                : [];
+        else {
+            hooks = flags.hooks ?? selectedPreset.defaultHooks;
+            recipes = flags.recipes ?? defaults.recipes;
+            requirePlanApproval = flags.requirePlanApproval ?? defaults.requirePlanApproval;
+            requireNetworkApproval = flags.requireNetworkApproval ?? defaults.requireNetworkApproval;
+            requireVerifyApproval = flags.requireVerifyApproval ?? defaults.requireVerifyApproval;
+            executionProfile = flags.executionProfile ?? defaults.executionProfile;
+            strictUnsafeConfirm = flags.strictUnsafeConfirm ?? selectedPreset.defaultStrictUnsafeConfirm;
+            process.stdout.write(renderInitSection("Defaults Applied", "Using compact prod defaults for hooks, approvals, execution profile, and recipes."));
         }
     }
     if (flags.yes) {

package/dist/cli/run-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAoWA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0K5D"}
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAibA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiL5D"}

package/dist/cli/run-cli.js

@@ -134,9 +134,9 @@ function matchCommandCatalog(tokens) {
     return best;
 }
 function writeError(err, jsonErrors) {
-    const hint = renderErrorHint(err);
+    const guidance = resolveErrorGuidance(err);
     if (jsonErrors) {
-        process.stdout.write(`${formatJsonError(err)}\n`);
+        process.stdout.write(`${formatJsonError(err, { hint: guidance.hint, nextAction: guidance.nextAction })}\n`);
     }
     else {
         const header = `error [${err.code}]`;
@@ -146,8 +146,11 @@ function writeError(err, jsonErrors) {
         else {
             process.stderr.write(`${header}: ${err.message}\n`);
         }
-        if (hint) {
-            process.stderr.write(`hint: ${hint}\n`);
+        if (guidance.hint) {
+            process.stderr.write(`hint: ${guidance.hint}\n`);
+        }
+        if (guidance.nextAction) {
+            process.stderr.write(`next_action: ${guidance.nextAction.command} (${guidance.nextAction.reason})\n`);
         }
     }
 }
@@ -158,33 +161,92 @@ function resolveAgentplaneHome() {
         return overridden;
     return path.join(os.homedir(), ".agentplane");
 }
-function renderErrorHint(err) {
+function resolveErrorGuidance(err) {
     const command = typeof err.context?.command === "string" ? err.context.command : undefined;
     const usage = command ? `agentplane help ${command} --compact` : "agentplane help";
     switch (err.code) {
         case "E_USAGE": {
-            return `See \`${usage}\` for usage.`;
+            return {
+                hint: `See \`${usage}\` for usage.`,
+                nextAction: {
+                    command: usage,
+                    reason: "inspect required arguments and flags",
+                    reasonCode: "usage_help",
+                },
+            };
         }
         case "E_GIT": {
             if (command?.startsWith("branch")) {
-                return "Check git repo/branch; run `git branch` or pass --root <path>.";
+                return {
+                    hint: "Check git repo/branch; run `git branch` or pass --root <path>.",
+                    nextAction: {
+                        command: "git branch",
+                        reason: "inspect repository branch state",
+                        reasonCode: "git_branch_state",
+                    },
+                };
             }
             if (command === "guard commit" || command === "commit") {
-                return "Check git status/index; stage changes and retry.";
+                return {
+                    hint: "Check git status/index; stage changes and retry.",
+                    nextAction: {
+                        command: "git status --short",
+                        reason: "inspect staged/unstaged changes before commit",
+                        reasonCode: "git_index_state",
+                    },
+                };
             }
-            return "Check git repo context; pass --root <path> if needed.";
+            return {
+                hint: "Check git repo context; pass --root <path> if needed.",
+                nextAction: {
+                    command: "git status --short --untracked-files=no",
+                    reason: "confirm repository context and tracked changes",
+                    reasonCode: "git_context",
+                },
+            };
         }
         case "E_NETWORK": {
-            return "Check network access and credentials.";
+            return {
+                hint: "Check network access and credentials.",
+                nextAction: {
+                    command: "agentplane preflight --json",
+                    reason: "recheck approvals and network requirements",
+                    reasonCode: "network_gate",
+                },
+            };
         }
         case "E_BACKEND": {
             if (command?.includes("sync")) {
-                return "Check backend config under .agentplane/backends and retry.";
+                return {
+                    hint: "Check backend config under .agentplane/backends and retry.",
+                    nextAction: {
+                        command: "agentplane config show",
+                        reason: "verify backend config path and active settings",
+                        reasonCode: "backend_sync_config",
+                    },
+                };
             }
-            return "Check backend config under .agentplane/backends.";
+            return {
+                hint: "Check backend config under .agentplane/backends.",
+                nextAction: {
+                    command: "agentplane config show",
+                    reason: "inspect backend configuration",
+                    reasonCode: "backend_config",
+                },
+            };
+        }
+        case "E_VALIDATION": {
+            return {
+                hint: "Fix invalid config/input shape and rerun.",
+                nextAction: {
+                    command: "agentplane preflight --json",
+                    reason: "pinpoint validation failure in one report",
+                    reasonCode: "validation_preflight",
+                },
+            };
         }
         default: {
-            return undefined;
+            return {};
         }
     }
 }
@@ -342,9 +404,6 @@ export async function runCli(argv) {
         const resolved = matched?.entry.needsProject === false
             ? null
             : await maybeResolveProject({ cwd, rootOverride: globals.root });
-        if (resolved) {
-            await loadDotEnv(resolved.gitRoot);
-        }
         let projectPromise = resolved
             ? Promise.resolve(resolved)
             : null;
@@ -361,6 +420,7 @@ export async function runCli(argv) {
         const getLoadedConfig = async (commandForErrorContext) => {
             configPromise ??= (async () => {
                 const project = await getResolvedProject(commandForErrorContext);
+                await loadDotEnv(project.gitRoot);
                 return await loadConfig(project.agentplaneDir);
             })();
             try {
@@ -395,7 +455,16 @@ export async function runCli(argv) {
         });
         let ctxPromise = null;
         const getCtx = async (commandForErrorContext) => {
-            ctxPromise ??= resolveContext({ cwd, rootOverride: globals.root ?? null });
+            ctxPromise ??= (async () => {
+                const resolvedProject = await getResolvedProject(commandForErrorContext);
+                const loadedConfig = await getLoadedConfig(commandForErrorContext);
+                return await resolveContext({
+                    cwd,
+                    rootOverride: globals.root ?? null,
+                    resolvedProject,
+                    config: loadedConfig.config,
+                });
+            })();
             try {
                 return await ctxPromise;
             }

package/dist/cli/spec/docs-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/docs-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA2BjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAsGnE"}
+{"version":3,"file":"docs-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/docs-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAmCjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAsGnE"}

package/dist/cli/spec/docs-render.js

@@ -1,6 +1,13 @@
-function escInline(text) {
+function escCode(text) {
     return text.replaceAll("`", "\\`");
 }
+function escText(text) {
+    return text
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("`", "\\`");
+}
 function toAnchor(text) {
     return text
         .toLowerCase()
@@ -49,8 +56,8 @@ export function renderCliDocsMdx(specs) {
         const groupHeader = ["", `## ${group}`];
         const commandBlocks = specs.flatMap((s) => {
             const summaryLines = s.description
-                ? ["", escInline(s.summary), "", escInline(s.description)]
-                : ["", escInline(s.summary)];
+                ? ["", escText(s.summary), "", escText(s.description)]
+                : ["", escText(s.summary)];
             const usageLines = ["", "Usage:", "", "```text", ...(s.usage ?? []), "```"];
             const visibleOpts = (s.options ?? []).filter((o) => !o.hidden);
             const optionLines = visibleOpts.length === 0
@@ -73,11 +80,11 @@ export function renderCliDocsMdx(specs) {
                             o.deprecated ? `deprecated=${o.deprecated}` : null,
                         ].filter((x) => x !== null);
                         const suffix = meta.length > 0 ? ` (${meta.join(", ")})` : "";
-                        return `- \`${escInline(head)}\`: ${escInline(o.description)}${escInline(suffix)}`;
+                        return `- \`${escCode(head)}\`: ${escText(o.description)}${escText(suffix)}`;
                     }),
                 ];
             const notesLines = s.notes && s.notes.length > 0
-                ? ["", "Notes:", "", ...s.notes.map((n) => `- ${escInline(n)}`)]
+                ? ["", "Notes:", "", ...s.notes.map((n) => `- ${escText(n)}`)]
                 : [];
             const examplesLines = s.examples && s.examples.length > 0
                 ? [
@@ -85,7 +92,7 @@ export function renderCliDocsMdx(specs) {
                     "Examples:",
                     "",
                     ...s.examples.flatMap((ex) => {
-                        const why = ex.why ? [`- ${escInline(ex.why)}`] : [];
+                        const why = ex.why ? [`- ${escText(ex.why)}`] : [];
                         return ["```sh", ex.cmd, "```", ...why];
                     }),
                 ]

package/dist/commands/backend/sync.command.d.ts

@@ -1,4 +1,4 @@
-import type { CommandCtx, CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
 import type { CommandContext } from "../shared/task-backend.js";
 import { type BackendSyncParsed } from "../backend.js";
 type BackendRootParsed = {
@@ -6,7 +6,8 @@ type BackendRootParsed = {
 };
 export declare const backendSpec: CommandSpec<BackendRootParsed>;
 export declare const backendSyncSpec: CommandSpec<BackendSyncParsed>;
-export declare function makeRunBackendHandler(getCtx: (cmd: string) => Promise<CommandContext>): CommandHandler<BackendRootParsed>;
+declare function runBackendRootGroup(_ctx: CommandCtx, p: BackendRootParsed): Promise<number>;
+export declare function makeRunBackendHandler(_getCtx: (cmd: string) => Promise<CommandContext>): typeof runBackendRootGroup;
 export declare function makeRunBackendSyncHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: BackendSyncParsed) => Promise<number>;
 export {};
 //# sourceMappingURL=sync.command.d.ts.map

package/dist/commands/backend/sync.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7E,KAAK,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAQtD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,qCAgBrF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE"}
+{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7E,KAAK,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAQtD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,iBAAS,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,8BAEtF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE"}

package/dist/commands/backend/sync.command.js

@@ -50,21 +50,19 @@ export const backendSyncSpec = {
         quiet: raw.opts.quiet === true,
     }),
 };
-export function makeRunBackendHandler(getCtx) {
-    const handler = async (_ctx, p) => {
-        // Resolve context once for consistent error mapping and approval gating.
-        await getCtx("backend");
-        const input = p.cmd.join(" ");
-        const suggestion = suggestOne(input, ["sync"]);
-        const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-        const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-        throw usageError({
-            spec: backendSyncSpec,
-            message: `${msg}${suffix}`,
-            context: { command: "backend sync" },
-        });
-    };
-    return handler;
+function runBackendRootGroup(_ctx, p) {
+    const input = p.cmd.join(" ");
+    const suggestion = suggestOne(input, ["sync"]);
+    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
+    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
+    throw usageError({
+        spec: backendSyncSpec,
+        message: `${msg}${suffix}`,
+        context: { command: "backend sync" },
+    });
+}
+export function makeRunBackendHandler(_getCtx) {
+    return runBackendRootGroup;
 }
 export function makeRunBackendSyncHandler(getCtx) {
     return async (ctx, p) => {

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

@@ -1 +1 @@
-{"version":3,"file":"commit.command.d.ts","sourceRoot":"","sources":["../../src/commands/commit.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,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,CAoBjE"}
+{"version":3,"file":"commit.command.d.ts","sourceRoot":"","sources":["../../src/commands/commit.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,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,CAsBjE"}

package/dist/commands/commit.command.js

@@ -19,6 +19,8 @@ export function makeRunCommitHandler(getCtx) {
             allowCI: p.allowCI,
             requireClean: p.requireClean,
             quiet: p.quiet,
+            closeUnstageOthers: p.closeUnstageOthers,
+            closeCheckOnly: p.closeCheckOnly,
         });
     };
 }

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

@@ -13,6 +13,8 @@ export type CommitParsed = {
     allowCI: boolean;
     requireClean: boolean;
     quiet: boolean;
+    closeUnstageOthers: boolean;
+    closeCheckOnly: boolean;
 };
 export declare const commitSpec: CommandSpec<CommitParsed>;
 //# sourceMappingURL=commit.spec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"commit.spec.d.ts","sourceRoot":"","sources":["../../src/commands/commit.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAuHhD,CAAC"}
+{"version":3,"file":"commit.spec.d.ts","sourceRoot":"","sources":["../../src/commands/commit.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAmJhD,CAAC"}

package/dist/commands/commit.spec.js

@@ -18,6 +18,18 @@ export const commitSpec = {
             default: false,
             description: "Generate a deterministic close commit message from task snapshot + verification + recorded implementation commit; stages only the task README.",
         },
+        {
+            kind: "boolean",
+            name: "unstage-others",
+            default: false,
+            description: "With --close: unstage any currently staged paths before staging the task README.",
+        },
+        {
+            kind: "boolean",
+            name: "check-only",
+            default: false,
+            description: "With --close: run preflight checks and print the planned close commit subject without creating a commit.",
+        },
         {
             kind: "string",
             name: "allow",
@@ -92,6 +104,18 @@ export const commitSpec = {
                 message: "Use either --message or --close (not both).",
             });
         }
+        if (!close && raw.opts["unstage-others"] === true) {
+            throw usageError({
+                spec: commitSpec,
+                message: "--unstage-others requires --close.",
+            });
+        }
+        if (!close && raw.opts["check-only"] === true) {
+            throw usageError({
+                spec: commitSpec,
+                message: "--check-only requires --close.",
+            });
+        }
         const allow = raw.opts.allow;
         if (Array.isArray(allow) && allow.some((s) => typeof s === "string" && s.trim() === "")) {
             throw usageError({ spec: commitSpec, message: "Invalid value for --allow: empty." });
@@ -115,5 +139,7 @@ export const commitSpec = {
         allowCI: raw.opts["allow-ci"] === true,
         requireClean: raw.opts["require-clean"] === true,
         quiet: raw.opts.quiet === true,
+        closeUnstageOthers: raw.opts["unstage-others"] === true,
+        closeCheckOnly: raw.opts["check-only"] === true,
     }),
 };

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;AAI1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA+OrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAwBlD,CAAC"}
+{"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;AAK1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsPrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAwBlD,CAAC"}

package/dist/commands/doctor.run.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveProject } from "@agentplaneorg/core";
 import { warnMessage, successMessage } from "../cli/output.js";
+import { RUNTIME_GITIGNORE_LINES } from "../shared/runtime-artifacts.js";
 import { execFileAsync, gitEnv } from "./shared/git.js";
 import { loadCommandContext } from "./shared/task-backend.js";
 async function listTsFiles(rootDir) {
@@ -132,13 +133,21 @@ async function safeFixGitignore(repoRoot) {
         return { changed: false, note: "Skip: .gitignore not found." };
     }
     const lines = existing.split(/\r?\n/);
-    const entry = ".agentplane/.upgrade/";
-    if (lines.some((l) => l.trim() === entry)) {
-        return { changed: false, note: "OK: .gitignore already ignores .agentplane/.upgrade/." };
-    }
-    const next = `${existing.trimEnd()}\n${entry}\n`;
+    const existingSet = new Set(lines.map((line) => line.trimEnd()));
+    const missing = RUNTIME_GITIGNORE_LINES.filter((line) => !existingSet.has(line));
+    if (missing.length === 0) {
+        return { changed: false, note: "OK: .gitignore already contains agentplane runtime ignores." };
+    }
+    const nextLines = [...lines];
+    if (nextLines.length > 0 && nextLines.at(-1) !== "")
+        nextLines.push("");
+    nextLines.push(...missing, "");
+    const next = `${nextLines.join("\n")}`.replaceAll(/\n{2,}$/g, "\n");
     await fs.writeFile(gitignorePath, next, "utf8");
-    return { changed: true, note: "Fixed: added .agentplane/.upgrade/ to .gitignore." };
+    return {
+        changed: true,
+        note: `Fixed: added agentplane runtime ignores to .gitignore (${missing.length} lines).`,
+    };
 }
 async function safeFixTaskIndex(repoRoot) {
     try {

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

package/dist/commands/finish.run.js

@@ -35,6 +35,8 @@ export function makeRunFinishHandler(getCtx) {
             statusCommitAutoAllow: p.statusCommitAutoAllow,
             statusCommitRequireClean: p.statusCommitRequireClean,
             confirmStatusCommit: p.confirmStatusCommit,
+            closeCommit: p.closeCommit,
+            closeUnstageOthers: p.closeUnstageOthers,
             quiet: p.quiet,
         });
     };

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

@@ -21,6 +21,8 @@ export type FinishParsed = {
     statusCommitAutoAllow: boolean;
     statusCommitRequireClean: boolean;
     confirmStatusCommit: boolean;
+    closeCommit: boolean;
+    closeUnstageOthers: boolean;
     quiet: boolean;
 };
 export declare const finishSpec: CommandSpec<FinishParsed>;

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

@@ -1 +1 @@
-{"version":3,"file":"finish.spec.d.ts","sourceRoot":"","sources":["../../src/commands/finish.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD,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,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CA6MhD,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;AAKvD,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,CAqPhD,CAAC"}