agentplane 0.2.19 → 0.2.21

package/dist/cli/run-cli/commands/init/write-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}
+{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

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

@@ -13,6 +13,8 @@ export async function ensureAgentplaneDirs(agentplaneDir, backend) {
 export async function writeInitConfig(opts) {
     const rawConfig = defaultConfig();
     setByDottedKey(rawConfig, "workflow_mode", opts.workflow);
+    setByDottedKey(rawConfig, "status_commit_policy", opts.workflow === "branch_pr" ? "confirm" : "warn");
+    setByDottedKey(rawConfig, "finish_auto_status_commit", String(opts.workflow === "branch_pr"));
     setByDottedKey(rawConfig, "tasks_backend.config_path", path.relative(opts.gitRoot, opts.backendConfigPathAbs));
     setByDottedKey(rawConfig, "agents.approvals.require_plan", String(opts.requirePlanApproval));
     setByDottedKey(rawConfig, "agents.approvals.require_network", String(opts.requireNetworkApproval));

package/dist/cli/run-cli/commands/init/write-gitignore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-gitignore.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-gitignore.ts"],"names":[],"mappings":"AAiCA,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB,EAAE,OAAO,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhB"}
+{"version":3,"file":"write-gitignore.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-gitignore.ts"],"names":[],"mappings":"AAmBA,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB,EAAE,OAAO,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhB"}

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

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { readFile } from "node:fs/promises";
+import { AGENT_PROMPT_GITIGNORE_LINES, RUNTIME_GITIGNORE_LINES, } from "../../../../shared/runtime-artifacts.js";
 import { writeTextIfChanged } from "../../../../shared/write-if-changed.js";
 async function readTextIfExists(filePath) {
     try {
@@ -12,28 +13,12 @@ async function readTextIfExists(filePath) {
         throw err;
     }
 }
-const RUNTIME_IGNORE_LINES = [
-    "# agentplane: ignore runtime/transient workspace artifacts",
-    ".env",
-    ".agentplane/worktrees",
-    ".agentplane/cache",
-    ".agentplane/recipes-cache",
-    ".agentplane/.upgrade",
-    ".agentplane/.release",
-    ".agentplane/upgrade",
-    ".agentplane/tasks.json",
-];
-const AGENT_PROMPT_IGNORE_LINES = [
-    "# agentplane: ignore local agent prompts/templates",
-    "AGENTS.md",
-    ".agentplane/agents/",
-];
 export async function ensureInitGitignore(opts) {
     const gitignorePath = path.join(opts.gitRoot, ".gitignore");
     const existing = (await readTextIfExists(gitignorePath)) ?? "";
     const ensuredLines = opts.includeAgentPromptFiles
-        ? [...RUNTIME_IGNORE_LINES, ...AGENT_PROMPT_IGNORE_LINES]
-        : [...RUNTIME_IGNORE_LINES];
+        ? [...RUNTIME_GITIGNORE_LINES, ...AGENT_PROMPT_GITIGNORE_LINES]
+        : [...RUNTIME_GITIGNORE_LINES];
     const existingLines = existing.split(/\r?\n/);
     const existingSet = new Set(existingLines.map((line) => line.trimEnd()));
     const missing = ensuredLines.filter((line) => !existingSet.has(line));

package/dist/cli/run-cli/commands/init.d.ts

@@ -1,6 +1,7 @@
 import type { CommandHandler, CommandSpec } from "../../spec/spec.js";
 import { type ExecutionProfile } from "@agentplaneorg/core";
 type InitFlags = {
+    setupProfile?: "prod" | "dev";
     ide?: "codex" | "cursor" | "windsurf";
     workflow?: "direct" | "branch_pr";
     backend?: "local" | "redmine";

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/init.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAa7B,KAAK,SAAS,GAAG;IACf,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAsBF,KAAK,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5D,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CA2K5C,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CACmB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/init.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAa7B,KAAK,SAAS,GAAG;IACf,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAsBF,KAAK,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5D,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAoL5C,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CACmB,CAAC"}

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

@@ -45,6 +45,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 asks only essential questions; dev asks the full setup questionnaire.",
+        },
         {
             kind: "string",
             name: "ide",
@@ -167,6 +174,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 +234,7 @@ 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";
     const isInteractive = process.stdin.isTTY && !flags.yes;
     if (!process.stdin.isTTY &&
         !flags.yes &&
@@ -257,9 +266,13 @@ async function cmdInit(opts) {
             return result;
         };
         process.stdout.write(renderInitWelcome());
+        process.stdout.write(renderInitSection("Setup Profile", "Choose how much init should ask. prod keeps the flow compact; dev exposes full controls."));
+        if (!flags.setupProfile) {
+            setupProfile = (await askChoice("Setup profile", ["prod", "dev"], setupProfile));
+        }
         process.stdout.write(renderInitSection("Workflow", "Choose how branches/backends/approvals should be initialized for this repository."));
         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 +280,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 ?? defaults.hooks;
+            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 ?? defaults.strictUnsafeConfirm;
+            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,CAmL5D"}

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 {};
         }
     }
 }
@@ -395,7 +457,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/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"}

package/dist/commands/finish.spec.js

@@ -136,6 +136,18 @@ export const finishSpec = {
             default: false,
             description: "Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment or --status-commit).",
         },
+        {
+            kind: "boolean",
+            name: "close-commit",
+            default: false,
+            description: "After finishing, run a deterministic close commit for the task README (single-task only).",
+        },
+        {
+            kind: "boolean",
+            name: "close-unstage-others",
+            default: false,
+            description: "With --close-commit: unstage any currently staged paths before staging the task README.",
+        },
         { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
     ],
     examples: [
@@ -160,6 +172,28 @@ export const finishSpec = {
                 message: "--commit-from-comment/--status-commit requires exactly one task id",
             });
         }
+        if (raw.opts["close-commit"] === true && taskIds.length !== 1) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "--close-commit requires exactly one task id",
+            });
+        }
+        if (raw.opts["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",
+            });
+        }
+        if (raw.opts["close-unstage-others"] === true && raw.opts["close-commit"] !== true) {
+            throw usageError({
+                spec: finishSpec,
+                command: "finish",
+                message: "--close-unstage-others requires --close-commit",
+            });
+        }
         const hasMeta = typeof raw.opts.result === "string" ||
             typeof raw.opts.risk === "string" ||
             raw.opts.breaking === true;
@@ -195,6 +229,8 @@ export const finishSpec = {
         statusCommitAutoAllow: raw.opts["status-commit-auto-allow"] === true,
         statusCommitRequireClean: raw.opts["status-commit-require-clean"] === true,
         confirmStatusCommit: raw.opts["confirm-status-commit"] === true,
+        closeCommit: raw.opts["close-commit"] === true,
+        closeUnstageOthers: raw.opts["close-unstage-others"] === true,
         quiet: raw.opts.quiet === true,
     }),
 };

package/dist/commands/guard/impl/allow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"allow.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/allow.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEvF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAS9D;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOpB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCpB"}
+{"version":3,"file":"allow.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/allow.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAkBvF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOpB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2CpB"}

package/dist/commands/guard/impl/allow.js

@@ -4,18 +4,37 @@ import { gitPathIsUnderPrefix, normalizeGitPathPrefix } from "../../../shared/gi
 import { CliError } from "../../../shared/errors.js";
 import { GitContext } from "../../shared/git-context.js";
 import { loadCommandContext } from "../../shared/task-backend.js";
+function normalizeAllowPrefixes(prefixes) {
+    const unique = [
+        ...new Set(prefixes.map((prefix) => normalizeGitPathPrefix(prefix)).filter(Boolean)),
+    ].toSorted((a, b) => (a.length === b.length ? a.localeCompare(b) : a.length - b.length));
+    // "." is repo-wide and makes all other prefixes redundant.
+    if (unique.includes("."))
+        return ["."];
+    const compact = [];
+    for (const prefix of unique) {
+        if (compact.some((existing) => gitPathIsUnderPrefix(prefix, existing)))
+            continue;
+        compact.push(prefix);
+    }
+    return compact;
+}
 export function suggestAllowPrefixes(paths) {
     const out = new Set();
     for (const filePath of paths) {
         if (!filePath)
             continue;
-        const idx = filePath.lastIndexOf("/");
-        if (idx <= 0)
-            out.add(filePath);
-        else
-            out.add(filePath.slice(0, idx));
+        const trimmed = filePath.trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.lastIndexOf("/");
+        const rawPrefix = idx <= 0 ? trimmed : trimmed.slice(0, idx);
+        const normalized = normalizeGitPathPrefix(rawPrefix);
+        if (!normalized)
+            continue;
+        out.add(rawPrefix.startsWith("/") && !normalized.startsWith("/") ? `/${normalized}` : normalized);
     }
-    return [...out].toSorted((a, b) => a.localeCompare(b));
+    return [...out].filter(Boolean).toSorted((a, b) => a.localeCompare(b));
 }
 export async function gitStatusChangedPaths(opts) {
     const resolved = await resolveProject({
@@ -55,7 +74,14 @@ export async function stageAllowlist(opts) {
             message: "No changes to stage (working tree clean)",
         });
     }
-    const allow = opts.allow.map((prefix) => normalizeGitPathPrefix(prefix));
+    const allow = normalizeAllowPrefixes(opts.allow);
+    if (allow.length === 0) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Provide at least one allowed prefix",
+        });
+    }
     const denied = new Set();
     if (!opts.allowTasks)
         denied.add(opts.tasksPath);