agentplane 0.3.6 → 0.3.8

package/dist/commands/backend.js

@@ -1,8 +1,9 @@
-import { backendNotSupportedMessage } from "../cli/output.js";
+import { backendNotSupportedMessage, createCliEmitter } from "../cli/output.js";
 import { mapBackendError } from "../cli/error-map.js";
 import { CliError } from "../shared/errors.js";
 import { loadCommandContext } from "./shared/task-backend.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
+const output = createCliEmitter();
 export async function cmdBackendSyncParsed(opts) {
     try {
         const ctx = opts.ctx ??
@@ -89,3 +90,112 @@ export async function cmdSyncParsed(opts) {
         throw mapBackendError(err, { command: "sync", root: opts.rootOverride ?? null });
     }
 }
+export async function cmdBackendMigrateCanonicalStateParsed(opts) {
+    try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const backend = ctx.taskBackend;
+        const backendId = ctx.backendId;
+        const config = ctx.config;
+        if (opts.flags.backendId && backendId && opts.flags.backendId !== backendId) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Configured backend is "${backendId}", not "${opts.flags.backendId}"`,
+                context: {
+                    command: "backend migrate-canonical-state",
+                    reason_code: "sync_backend_mismatch",
+                },
+            });
+        }
+        if (!backend.migrateCanonicalState) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: backendNotSupportedMessage("migrateCanonicalState()"),
+            });
+        }
+        if (backendId !== "local") {
+            await ensureNetworkApproved({
+                config,
+                yes: opts.flags.yes,
+                reason: `backend migrate-canonical-state may access the network (backend: ${backendId})`,
+            });
+        }
+        const result = await backend.migrateCanonicalState();
+        if (!opts.flags.quiet) {
+            output.success("backend migrate-canonical-state", undefined, `scanned=${result.scanned} migrated=${result.migrated.length} skipped-structured=${result.skippedStructured.length} skipped-no-doc=${result.skippedNoDoc.length} failed=${result.failed.length}`);
+        }
+        if (result.failed.length > 0) {
+            for (const failure of result.failed.slice(0, 20)) {
+                output.warn(`backend migrate-canonical-state failed for ${failure.taskId}: ${failure.reason}`);
+            }
+            return 1;
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, {
+            command: "backend migrate-canonical-state",
+            root: opts.rootOverride ?? null,
+        });
+    }
+}
+export async function cmdBackendInspectParsed(opts) {
+    try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const backend = ctx.taskBackend;
+        const backendId = ctx.backendId;
+        const config = ctx.config;
+        if (opts.flags.backendId && backendId && opts.flags.backendId !== backendId) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Configured backend is "${backendId}", not "${opts.flags.backendId}"`,
+                context: {
+                    command: "backend inspect",
+                    reason_code: "inspect_backend_mismatch",
+                },
+            });
+        }
+        if (!backend.inspectConfiguration) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: backendNotSupportedMessage("inspectConfiguration()"),
+            });
+        }
+        if (backendId !== "local") {
+            await ensureNetworkApproved({
+                config,
+                yes: opts.flags.yes,
+                reason: `backend inspect may access the network (backend: ${backendId})`,
+            });
+        }
+        const result = await backend.inspectConfiguration();
+        if (opts.flags.quiet)
+            return 0;
+        const canonicalStateSummary = result.canonicalState.configuredFieldId === null
+            ? result.canonicalState.visibleFieldId === null
+                ? "missing"
+                : `visible-unconfigured:${result.canonicalState.visibleFieldId}`
+            : `configured:${result.canonicalState.configuredFieldId}`;
+        output.success("backend inspect", undefined, `visible-fields=${result.visibleCustomFields.length} canonical-state=${canonicalStateSummary} drift=${result.configuredFieldNameDrift.length}`);
+        output.line(`canonical_state configured=${result.canonicalState.configuredFieldId ?? "unset"} visible=${result.canonicalState.visibleFieldId ?? "absent"}`);
+        for (const drift of result.configuredFieldNameDrift) {
+            output.line(`drift key=${drift.key} configured-id=${drift.configuredId} visible-name=${JSON.stringify(drift.visibleName)}`);
+        }
+        for (const field of result.visibleCustomFields) {
+            output.line(`field id=${field.id} name=${JSON.stringify(field.name)} non-empty=${field.nonEmptyCount}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, { command: "backend inspect", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/branch/base.command.d.ts

@@ -1,7 +1,6 @@
 import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
-type BranchBaseGroupParsed = {
-    cmd: string[];
-};
+import { type GroupCommandParsed } from "../../cli/group-command.js";
+type BranchBaseGroupParsed = GroupCommandParsed;
 export declare const branchBaseSpec: CommandSpec<BranchBaseGroupParsed>;
 export declare const branchBaseGetSpec: CommandSpec<Record<string, never>>;
 export declare const branchBaseClearSpec: CommandSpec<Record<string, never>>;

package/dist/commands/branch/base.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.command.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/base.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAW1E,KAAK,qBAAqB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE/C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,qBAAqB,CAa7D,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKhE,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKlE,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKpE,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CA4C9D,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,qBAAqB,CAc/D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAElE,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAEpE,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAEtE,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAOhE,CAAC"}
+{"version":3,"file":"base.command.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/base.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAUpC,KAAK,qBAAqB,GAAG,kBAAkB,CAAC;AAEhD,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,qBAAqB,CAa7D,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKhE,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKlE,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAKpE,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CA4C9D,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,qBAAqB,CAQ/D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAElE,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAEpE,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAEtE,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAOhE,CAAC"}

package/dist/commands/branch/base.command.js

@@ -1,5 +1,5 @@
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
 import { usageError } from "../../cli/spec/errors.js";
-import { suggestOne } from "../../cli/spec/suggest.js";
 import { cmdBranchBaseClear, cmdBranchBaseExplain, cmdBranchBaseGet, cmdBranchBaseSet, } from "./index.js";
 export const branchBaseSpec = {
     id: ["branch", "base"],
@@ -13,7 +13,7 @@ export const branchBaseSpec = {
         { cmd: "agentplane branch base clear", why: "Clear the pinned base branch." },
         { cmd: "agentplane branch base explain", why: "Show current/pinned/effective base details." },
     ],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
 export const branchBaseGetSpec = {
     id: ["branch", "base", "get"],
@@ -78,18 +78,14 @@ export const branchBaseSetSpec = {
         useCurrent: raw.opts.current === true,
     }),
 };
-export const runBranchBase = (_ctx, p) => {
-    const input = p.cmd.join(" ");
-    const candidates = ["get", "set", "clear", "explain"];
-    const suggestion = suggestOne(input, candidates);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    return Promise.reject(usageError({
+export const runBranchBase = async (_ctx, p) => {
+    throwGroupCommandUsage({
         spec: branchBaseSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["branch", "base"]),
         command: "branch base",
-        message: `${msg}${suffix}`,
-        context: { command: "branch base" },
-    }));
+        contextCommand: "branch base",
+    });
 };
 export const runBranchBaseGet = async (ctx) => {
     return await cmdBranchBaseGet({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });

package/dist/commands/branch/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/base.ts"],"names":[],"mappings":"AAaA,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAWlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ClB"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/base.ts"],"names":[],"mappings":"AAeA,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAWlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+ClB"}

package/dist/commands/branch/base.js

@@ -1,7 +1,9 @@
 import { clearPinnedBaseBranch, getPinnedBaseBranch, loadConfig, resolveBaseBranch, resolveProject, setPinnedBaseBranch, } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
+import { createCliEmitter } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { gitBranchExists, gitCurrentBranch } from "../shared/git-ops.js";
+const output = createCliEmitter();
 export async function cmdBranchBaseGet(opts) {
     try {
         const pinned = await getPinnedBaseBranch({
@@ -15,7 +17,7 @@ export async function cmdBranchBaseGet(opts) {
                 message: "Base branch is not pinned (use `agentplane branch base set`).",
             });
         }
-        process.stdout.write(`${pinned}\n`);
+        output.line(pinned);
         return 0;
     }
     catch (err) {
@@ -47,7 +49,7 @@ export async function cmdBranchBaseSet(opts) {
             rootOverride: opts.rootOverride ?? null,
             value: nextValue,
         });
-        process.stdout.write(`${value}\n`);
+        output.line(value);
         return 0;
     }
     catch (err) {
@@ -60,7 +62,7 @@ export async function cmdBranchBaseClear(opts) {
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
         });
-        process.stdout.write(`${cleared ? "cleared" : "no-op"}\n`);
+        output.line(cleared ? "cleared" : "no-op");
         return 0;
     }
     catch (err) {
@@ -98,12 +100,14 @@ export async function cmdBranchBaseExplain(opts) {
         if (effective && !(await gitBranchExists(resolved.gitRoot, effective))) {
             warnings.push(`Effective base branch not found: ${effective}`);
         }
-        process.stdout.write(`current_branch=${current ?? "-"}\n`);
-        process.stdout.write(`pinned_base=${pinned ?? "-"}\n`);
-        process.stdout.write(`effective_base=${effective ?? "-"}\n`);
+        output.lines([
+            `current_branch=${current ?? "-"}`,
+            `pinned_base=${pinned ?? "-"}`,
+            `effective_base=${effective ?? "-"}`,
+        ]);
         if (warnings.length > 0) {
             for (const warning of warnings) {
-                process.stdout.write(`warning=${warning}\n`);
+                output.line(`warning=${warning}`);
             }
         }
         return 0;

package/dist/commands/branch/cleanup-merged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup-merged.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/cleanup-merged.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIpF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0IlB"}
+{"version":3,"file":"cleanup-merged.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/cleanup-merged.ts"],"names":[],"mappings":"AAiBA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAKnC,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsIlB"}

package/dist/commands/branch/cleanup-merged.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { resolveBaseBranch } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
-import { successMessage, unknownEntityMessage, workflowModeMessage } from "../../cli/output.js";
+import { createCliEmitter, unknownEntityMessage, workflowModeMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { ensureGitClean } from "../guard/index.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
@@ -9,8 +9,9 @@ import { gitDiffNames } from "../shared/git-diff.js";
 import { gitBranchExists, gitCurrentBranch } from "../shared/git-ops.js";
 import { findWorktreeForBranch, gitListTaskBranches, parseTaskIdFromBranch, } from "../shared/git-worktree.js";
 import { isPathWithin, resolvePathFallback } from "../shared/path.js";
-import { loadCommandContext } from "../shared/task-backend.js";
+import { listTaskProjection, loadCommandContext, } from "../shared/task-backend.js";
 import { archivePrArtifacts } from "./internal/archive-pr.js";
+const output = createCliEmitter();
 export async function cmdCleanupMerged(opts) {
     try {
         const ctx = opts.ctx ??
@@ -54,7 +55,7 @@ export async function cmdCleanupMerged(opts) {
             });
         }
         const repoRoot = await resolvePathFallback(resolved.gitRoot);
-        const tasks = await ctx.taskBackend.listTasks();
+        const tasks = (await listTaskProjection(ctx)) ?? [];
         const tasksById = new Map(tasks.map((task) => [task.id, task]));
         const prefix = config.branch.task_prefix;
         const branches = await gitListTaskBranches(resolved.gitRoot, prefix);
@@ -80,18 +81,18 @@ export async function cmdCleanupMerged(opts) {
         const sortedCandidates = candidates.toSorted((a, b) => a.taskId.localeCompare(b.taskId));
         if (!opts.quiet) {
             const archiveLabel = opts.archive ? " archive=on" : "";
-            process.stdout.write(`cleanup merged (base=${baseBranch}${archiveLabel})\n`);
+            output.line(`cleanup merged (base=${baseBranch}${archiveLabel})`);
             if (sortedCandidates.length === 0) {
-                process.stdout.write("no candidates\n");
+                output.line("no candidates");
                 return 0;
             }
             for (const item of sortedCandidates) {
-                process.stdout.write(`- ${item.taskId}: branch=${item.branch} worktree=${item.worktreePath ?? "-"}\n`);
+                output.line(`- ${item.taskId}: branch=${item.branch} worktree=${item.worktreePath ?? "-"}`);
             }
         }
         if (!opts.yes) {
             if (!opts.quiet) {
-                process.stdout.write("Re-run with --yes to delete these branches/worktrees.\n");
+                output.line("Re-run with --yes to delete these branches/worktrees.");
             }
             return 0;
         }
@@ -129,7 +130,7 @@ export async function cmdCleanupMerged(opts) {
             });
         }
         if (!opts.quiet) {
-            process.stdout.write(`${successMessage("cleanup merged", undefined, `deleted=${candidates.length}`)}\n`);
+            output.success("cleanup merged", undefined, `deleted=${candidates.length}`);
         }
         return 0;
     }

package/dist/commands/branch/remove.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/remove.ts"],"names":[],"mappings":"AAYA,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoElB"}
+{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/remove.ts"],"names":[],"mappings":"AAYA,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqElB"}

package/dist/commands/branch/remove.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { loadConfig, resolveProject } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
-import { successMessage, unknownEntityMessage } from "../../cli/output.js";
+import { createCliEmitter, unknownEntityMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
@@ -10,6 +10,7 @@ import { isPathWithin, resolvePathFallback } from "../shared/path.js";
 export async function cmdBranchRemove(opts) {
     const branch = (opts.branch ?? "").trim();
     const worktree = (opts.worktree ?? "").trim();
+    const output = createCliEmitter();
     if (!branch && !worktree) {
         throw new CliError({
             exitCode: 2,
@@ -45,7 +46,7 @@ export async function cmdBranchRemove(opts) {
             }
             await execFileAsync("git", ["worktree", "remove", ...(opts.force ? ["--force"] : []), worktreePath], { cwd: resolved.gitRoot, env: gitEnv() });
             if (!opts.quiet) {
-                process.stdout.write(`${successMessage("removed worktree", worktreePath)}\n`);
+                output.success("removed worktree", worktreePath);
             }
         }
         if (branch) {
@@ -61,7 +62,7 @@ export async function cmdBranchRemove(opts) {
                 env: gitEnv(),
             });
             if (!opts.quiet) {
-                process.stdout.write(`${successMessage("removed branch", branch)}\n`);
+                output.success("removed branch", branch);
             }
         }
         return 0;

package/dist/commands/branch/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/status.ts"],"names":[],"mappings":"AAUA,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DlB"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/status.ts"],"names":[],"mappings":"AAWA,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DlB"}

package/dist/commands/branch/status.js

@@ -1,11 +1,12 @@
 import { loadConfig, resolveBaseBranch, resolveProject } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
-import { unknownEntityMessage } from "../../cli/output.js";
+import { createCliEmitter, unknownEntityMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { gitAheadBehind } from "../shared/git-diff.js";
 import { gitBranchExists, gitCurrentBranch } from "../shared/git-ops.js";
 import { findWorktreeForBranch, parseTaskIdFromBranch } from "../shared/git-worktree.js";
+const output = createCliEmitter();
 export async function cmdBranchStatus(opts) {
     try {
         const resolved = await resolveProject({
@@ -51,9 +52,9 @@ export async function cmdBranchStatus(opts) {
         const taskId = parseTaskIdFromBranch(loaded.config.branch.task_prefix, branch);
         const worktree = await findWorktreeForBranch(resolved.gitRoot, branch);
         const { ahead, behind } = await gitAheadBehind(resolved.gitRoot, base, branch);
-        process.stdout.write(`branch=${branch} base=${base} ahead=${ahead} behind=${behind} task_id=${taskId ?? "-"}\n`);
+        output.line(`branch=${branch} base=${base} ahead=${ahead} behind=${behind} task_id=${taskId ?? "-"}`);
         if (worktree) {
-            process.stdout.write(`worktree=${worktree}\n`);
+            output.line(`worktree=${worktree}`);
         }
         return 0;
     }

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

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

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

@@ -1,13 +1,15 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveBaseBranch } from "@agentplaneorg/core";
+import { LocalBackend } from "../../backends/task-backend.js";
 import { mapBackendError } from "../../cli/error-map.js";
 import { fileExists } from "../../cli/fs-utils.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
-import { successMessage } from "../../cli/output.js";
+import { createCliEmitter } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
-import { gitBranchExists, gitCurrentBranch } from "../shared/git-ops.js";
+import { gitAheadBehind } from "../shared/git-diff.js";
+import { gitBranchExists, gitBranchUpstream, gitCurrentBranch } from "../shared/git-ops.js";
 import { isPathWithin } from "../shared/path.js";
 import { loadBackendTask, loadCommandContext, } from "../shared/task-backend.js";
 import { ensurePlanApprovedIfRequired } from "../task/shared.js";
@@ -40,6 +42,26 @@ async function writeDirectWorkLock(agentplaneDir, lock) {
     await mkdir(dir, { recursive: true });
     await writeFile(directWorkLockPath(agentplaneDir), JSON.stringify(lock, null, 2) + "\n", "utf8");
 }
+async function materializeLocalBackendReadmesForWorktree(opts) {
+    if (!(opts.backend instanceof LocalBackend))
+        return;
+    const sourceRoot = path.resolve(opts.backend.root);
+    if (!isPathWithin(opts.repoRoot, sourceRoot))
+        return;
+    const relativeRoot = path.relative(opts.repoRoot, sourceRoot);
+    const targetRoot = path.join(opts.worktreePath, relativeRoot);
+    const entries = await readdir(sourceRoot, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const sourceReadme = path.join(sourceRoot, entry.name, "README.md");
+        if (!(await fileExists(sourceReadme)))
+            continue;
+        const targetReadme = path.join(targetRoot, entry.name, "README.md");
+        await mkdir(path.dirname(targetReadme), { recursive: true });
+        await copyFile(sourceReadme, targetReadme);
+    }
+}
 async function ensureGitClean(gitRoot) {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain"], {
         cwd: gitRoot,
@@ -82,8 +104,23 @@ async function ensureGitClean(gitRoot) {
         message: "Working tree has non-task changes. In workflow_mode=direct, agentplane runs tasks in a single stream on the current branch; commit/stash your changes before starting a different task.",
     });
 }
+async function ensureCurrentBaseBranch(gitRoot, baseBranch) {
+    const upstreamBranch = await gitBranchUpstream(gitRoot, baseBranch);
+    if (!upstreamBranch)
+        return;
+    const { behind } = await gitAheadBehind(gitRoot, upstreamBranch, baseBranch);
+    if (behind === 0)
+        return;
+    throw new CliError({
+        exitCode: exitCodeForError("E_GIT"),
+        code: "E_GIT",
+        message: `Base branch ${baseBranch} is behind its upstream ${upstreamBranch} by ${behind} commit(s). ` +
+            "Refresh the base branch before `agentplane work start` to avoid DIRTY hosted PRs.",
+    });
+}
 export async function cmdWorkStart(opts) {
     try {
+        const output = createCliEmitter();
         validateWorkAgent(opts.agent);
         validateWorkSlug(opts.slug);
         const ctx = opts.ctx ??
@@ -132,7 +169,7 @@ export async function cmdWorkStart(opts) {
                 branch: currentBranch,
                 started_at: new Date().toISOString(),
             });
-            process.stdout.write(`${successMessage("work start", opts.taskId, `mode=direct branch=${currentBranch}`)}\n`);
+            output.success("work start", opts.taskId, `mode=direct branch=${currentBranch}`);
             return 0;
         }
         let baseRef = currentBranch;
@@ -157,6 +194,7 @@ export async function cmdWorkStart(opts) {
                     message: `work start must be run on base branch ${baseBranch} (current: ${currentBranch})`,
                 });
             }
+            await ensureCurrentBaseBranch(resolved.gitRoot, baseBranch);
             baseRef = baseBranch;
         }
         const prefix = config.branch.task_prefix;
@@ -185,6 +223,11 @@ export async function cmdWorkStart(opts) {
                 ? ["worktree", "add", worktreePath, branchName]
                 : ["worktree", "add", "-b", branchName, worktreePath, baseRef];
             await execFileAsync("git", worktreeArgs, { cwd: resolved.gitRoot, env: gitEnv() });
+            await materializeLocalBackendReadmesForWorktree({
+                backend: ctx.taskBackend,
+                repoRoot: resolved.gitRoot,
+                worktreePath,
+            });
         }
         else {
             if (branchExists) {
@@ -202,7 +245,7 @@ export async function cmdWorkStart(opts) {
                 });
             }
         }
-        process.stdout.write(`${successMessage("work start", branchName, opts.worktree ? `worktree=${path.relative(resolved.gitRoot, worktreePath)}` : "")}\n`);
+        output.success("work start", branchName, opts.worktree ? `worktree=${path.relative(resolved.gitRoot, worktreePath)}` : "");
         return 0;
     }
     catch (err) {

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

@@ -1,8 +1,7 @@
 import type { CommandCtx, CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+import { type GroupCommandParsed } from "../../cli/group-command.js";
 import type { CommandContext } from "../shared/task-backend.js";
-type CleanupGroupParsed = {
-    cmd: string[];
-};
+type CleanupGroupParsed = GroupCommandParsed;
 export declare const cleanupSpec: CommandSpec<CleanupGroupParsed>;
 export type CleanupMergedParsed = {
     base: string | null;

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

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

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

@@ -1,5 +1,5 @@
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
 import { usageError } from "../../cli/spec/errors.js";
-import { suggestOne } from "../../cli/spec/suggest.js";
 import { cmdCleanupMerged } from "../branch/index.js";
 export const cleanupSpec = {
     id: ["cleanup"],
@@ -10,7 +10,7 @@ export const cleanupSpec = {
     examples: [
         { cmd: "agentplane cleanup merged --yes", why: "Delete merged task branches/worktrees." },
     ],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
 export const cleanupMergedSpec = {
     id: ["cleanup", "merged"],
@@ -47,18 +47,14 @@ export const cleanupMergedSpec = {
         quiet: raw.opts.quiet === true,
     }),
 };
-export const runCleanup = (_ctx, p) => {
-    const input = p.cmd.join(" ");
-    const candidates = ["merged"];
-    const suggestion = suggestOne(input, candidates);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    return Promise.reject(usageError({
+export const runCleanup = async (_ctx, p) => {
+    throwGroupCommandUsage({
         spec: cleanupSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["cleanup"]),
         command: "cleanup",
-        message: `${msg}${suffix}`,
-        context: { command: "cleanup" },
-    }));
+        contextCommand: "cleanup",
+    });
 };
 export function makeRunCleanupMergedHandler(getCtx) {
     return async (ctx, p) => {

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;AAOvD,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,CA+JhD,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;AAOvD,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,CAwLhD,CAAC"}

package/dist/commands/commit.spec.js

@@ -49,23 +49,38 @@ export const commitSpec = {
             kind: "boolean",
             name: "allow-tasks",
             default: false,
-            description: "Allow the tasks export snapshot plus artifacts under the active task subtree.",
+            description: "Allow the tasks export snapshot plus artifacts under the active task subtree; standalone path scope.",
         },
         {
             kind: "boolean",
             name: "allow-base",
             default: false,
-            description: "Allow base branch edits.",
+            description: "Allow base branch edits; branch override only, not a path allowlist.",
         },
         {
             kind: "boolean",
             name: "allow-policy",
             default: false,
-            description: "Allow policy edits (e.g. AGENTS.md).",
+            description: "Allow policy edits (e.g. AGENTS.md); standalone path scope.",
+        },
+        {
+            kind: "boolean",
+            name: "allow-config",
+            default: false,
+            description: "Allow config edits; standalone path scope.",
+        },
+        {
+            kind: "boolean",
+            name: "allow-hooks",
+            default: false,
+            description: "Allow hooks edits; standalone path scope.",
+        },
+        {
+            kind: "boolean",
+            name: "allow-ci",
+            default: false,
+            description: "Allow CI workflow edits; standalone path scope.",
         },
-        { kind: "boolean", name: "allow-config", default: false, description: "Allow config edits." },
-        { kind: "boolean", name: "allow-hooks", default: false, description: "Allow hooks edits." },
-        { kind: "boolean", name: "allow-ci", default: false, description: "Allow CI workflow edits." },
         {
             kind: "boolean",
             name: "require-clean",
@@ -79,11 +94,20 @@ export const commitSpec = {
             cmd: 'agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: implement allowlist guard" --allow packages/agentplane',
             why: "Create a commit after validating allowlist and subject policy.",
         },
+        {
+            cmd: 'agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: update publish workflow" --allow-ci',
+            why: "Commit CI-only changes without a redundant explicit workflow path prefix.",
+        },
         {
             cmd: "agentplane commit 202602030608-F1Q8AB --close",
             why: "Create a close commit for the task README using a deterministic message builder.",
         },
     ],
+    notes: [
+        "Protected path-scoped overrides can stand alone without a duplicate explicit prefix: `--allow-tasks`, `--allow-policy`, `--allow-config`, `--allow-hooks`, and `--allow-ci` each admit their own path family.",
+        "Top-level `agentplane commit` can auto-stage those protected path scopes when the git index starts empty.",
+        "`--allow-base` is different: it only overrides base-branch protection and never selects file paths by itself.",
+    ],
     validateRaw: (raw) => {
         const close = raw.opts.close === true;
         const msg = typeof raw.opts.message === "string" ? raw.opts.message.trim() : "";