agentplane 0.1.8 → 0.2.0

package/dist/commands/shared/git-context.d.ts

@@ -0,0 +1,23 @@
+export declare class GitContext {
+    readonly gitRoot: string;
+    private memo;
+    constructor(opts: {
+        gitRoot: string;
+    });
+    private statusPorcelainZ;
+    statusChangedPaths(): Promise<string[]>;
+    statusStagedPaths(): Promise<string[]>;
+    statusUnstagedTrackedPaths(): Promise<string[]>;
+    headCommit(): Promise<string>;
+    stage(paths: string[]): Promise<void>;
+    commit(opts: {
+        message: string;
+        body?: string;
+        env?: NodeJS.ProcessEnv;
+    }): Promise<void>;
+    headHashSubject(): Promise<{
+        hash: string;
+        subject: string;
+    }>;
+}
+//# sourceMappingURL=git-context.d.ts.map

package/dist/commands/shared/git-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-context.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-context.ts"],"names":[],"mappings":"AAyEA,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,IAAI,CAGL;gBAEK,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;YAIvB,gBAAgB;IAmBxB,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKvC,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKtC,0BAA0B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKrD,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAWvB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxF,eAAe,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAWpE"}

package/dist/commands/shared/git-context.js

@@ -0,0 +1,140 @@
+import { execFileAsync, gitEnv } from "./git.js";
+function uniqSorted(paths) {
+    return [...new Set(paths)].toSorted((a, b) => a.localeCompare(b));
+}
+function parsePorcelainV1Z(output) {
+    const text = Buffer.isBuffer(output) ? output.toString("utf8") : output;
+    const parts = text.split("\0").filter((p) => p.length > 0);
+    const changed = [];
+    const staged = [];
+    const unstagedTracked = [];
+    const untracked = [];
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i] ?? "";
+        if (entry.length < 3)
+            continue;
+        const x = entry[0] ?? " ";
+        const y = entry[1] ?? " ";
+        // Porcelain v1: `XY <path>` (or `XY <orig>` NUL `<path>` for renames/copies).
+        if (entry[2] !== " ")
+            continue;
+        const pathA = entry.slice(3);
+        if (!pathA)
+            continue;
+        if (x === "!" && y === "!") {
+            // Ignored file (`!!`): not a "changed path" for guard/staging semantics.
+            continue;
+        }
+        const isUntracked = x === "?" && y === "?";
+        if (isUntracked) {
+            changed.push(pathA);
+            untracked.push(pathA);
+            continue;
+        }
+        const isRenameOrCopy = x === "R" || x === "C";
+        if (isRenameOrCopy) {
+            const pathB = parts[i + 1] ?? "";
+            if (pathB) {
+                // Include both sides so allowlist staging can cover renames across prefixes.
+                changed.push(pathA, pathB);
+                staged.push(pathA, pathB);
+            }
+            else {
+                changed.push(pathA);
+                staged.push(pathA);
+            }
+            i++;
+            continue;
+        }
+        changed.push(pathA);
+        if (x !== " ")
+            staged.push(pathA);
+        if (y !== " ")
+            unstagedTracked.push(pathA);
+    }
+    return {
+        changedPaths: uniqSorted(changed),
+        stagedPaths: uniqSorted(staged),
+        unstagedTrackedPaths: uniqSorted(unstagedTracked),
+        untrackedPaths: uniqSorted(untracked),
+    };
+}
+export class GitContext {
+    gitRoot;
+    memo = {};
+    constructor(opts) {
+        this.gitRoot = opts.gitRoot;
+    }
+    async statusPorcelainZ() {
+        this.memo.status ??= (async () => {
+            // `--untracked-files=all` is required so allowlist staging can match individual files
+            // under untracked directories (tests + real-world "new task" flows).
+            const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], {
+                cwd: this.gitRoot,
+                env: gitEnv(),
+                encoding: "buffer",
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return parsePorcelainV1Z(stdout);
+        })();
+        return await this.memo.status;
+    }
+    async statusChangedPaths() {
+        const status = await this.statusPorcelainZ();
+        return status.changedPaths;
+    }
+    async statusStagedPaths() {
+        const status = await this.statusPorcelainZ();
+        return status.stagedPaths;
+    }
+    async statusUnstagedTrackedPaths() {
+        const status = await this.statusPorcelainZ();
+        return status.unstagedTrackedPaths;
+    }
+    headCommit() {
+        this.memo.headCommit ??= (async () => {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+                cwd: this.gitRoot,
+                env: gitEnv(),
+            });
+            return String(stdout).trim();
+        })();
+        return this.memo.headCommit;
+    }
+    async stage(paths) {
+        const unique = uniqSorted(paths.map((p) => p.trim()).filter(Boolean));
+        if (unique.length === 0)
+            return;
+        await execFileAsync("git", ["add", "-A", "--", ...unique], {
+            cwd: this.gitRoot,
+            env: gitEnv(),
+        });
+        // Invalidate memoized status: staging changes index state.
+        this.memo.status = undefined;
+    }
+    async commit(opts) {
+        const args = ["commit", "-m", opts.message];
+        if (opts.body)
+            args.push("-m", opts.body);
+        await execFileAsync("git", args, {
+            cwd: this.gitRoot,
+            env: opts.env ?? gitEnv(),
+            // Commit hooks can produce large output (lint/test logs).
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        // Invalidate memoized values: commit updates HEAD and working tree state.
+        this.memo.status = undefined;
+        this.memo.headCommit = undefined;
+    }
+    async headHashSubject() {
+        const { stdout } = await execFileAsync("git", ["log", "-1", "--pretty=%H%x00%s"], {
+            cwd: this.gitRoot,
+            env: gitEnv(),
+            encoding: "buffer",
+            maxBuffer: 1024 * 1024,
+        });
+        const text = Buffer.isBuffer(stdout) ? stdout.toString("utf8") : String(stdout);
+        const [hash = "", subject = ""] = text.split("\0", 2);
+        return { hash: hash.trim(), subject: subject.trim() };
+    }
+}

package/dist/commands/shared/policy-deny.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyResult } from "../../policy/types.js";
+export declare function throwIfPolicyDenied(res: PolicyResult): void;
+//# sourceMappingURL=policy-deny.d.ts.map

package/dist/commands/shared/policy-deny.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-deny.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/policy-deny.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAS3D"}

package/dist/commands/shared/policy-deny.js

@@ -0,0 +1,12 @@
+import { CliError } from "../../shared/errors.js";
+export function throwIfPolicyDenied(res) {
+    if (res.ok)
+        return;
+    const messages = res.errors.map((e) => e.message).join("\n");
+    const chosen = res.errors.find((e) => e.code === "E_INTERNAL") ??
+        res.errors.find((e) => e.code === "E_USAGE") ??
+        res.errors[0];
+    if (!chosen)
+        return;
+    throw new CliError({ exitCode: chosen.exitCode, code: chosen.code, message: messages });
+}

package/dist/commands/shared/task-backend.d.ts

@@ -1,15 +1,43 @@
 import { loadTaskBackend, type TaskData } from "../../backends/task-backend.js";
+import { GitContext } from "./git-context.js";
+export type CommandMemo = {
+    taskList?: Promise<TaskData[]>;
+    changedPaths?: Promise<string[]>;
+    headCommit?: Promise<string>;
+};
+export type CommandContext = {
+    resolvedProject: Awaited<ReturnType<typeof loadTaskBackend>>["resolved"];
+    config: Awaited<ReturnType<typeof loadTaskBackend>>["config"];
+    taskBackend: Awaited<ReturnType<typeof loadTaskBackend>>["backend"];
+    backendId: string;
+    backendConfigPath: string;
+    git: GitContext;
+    memo: CommandMemo;
+    resolved: CommandContext["resolvedProject"];
+    backend: CommandContext["taskBackend"];
+};
 export declare function resolveDocUpdatedBy(task: TaskData, author?: string): string;
 export declare function taskDataToFrontmatter(task: TaskData): Record<string, unknown>;
+export declare function loadCommandContext(opts: {
+    cwd: string;
+    rootOverride?: string | null;
+}): Promise<CommandContext>;
+export declare function loadTaskFromContext(opts: {
+    ctx: CommandContext;
+    taskId: string;
+}): Promise<TaskData>;
 export declare function loadBackendTask(opts: {
+    ctx?: CommandContext;
     cwd: string;
     rootOverride?: string | null;
     taskId: string;
 }): Promise<{
-    backend: Awaited<ReturnType<typeof loadTaskBackend>>["backend"];
+    backend: CommandContext["taskBackend"];
     backendId: string;
-    resolved: Awaited<ReturnType<typeof loadTaskBackend>>["resolved"];
-    config: Awaited<ReturnType<typeof loadTaskBackend>>["config"];
+    backendConfigPath: string;
+    resolved: CommandContext["resolvedProject"];
+    config: CommandContext["config"];
     task: TaskData;
 }>;
+export declare function listTasksMemo(ctx: CommandContext): Promise<TaskData[]>;
 //# sourceMappingURL=task-backend.d.ts.map

package/dist/commands/shared/task-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAShF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyB7E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAClE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9D,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC,CAgBD"}
+{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACzE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9D,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,UAAU,CAAC;IAEhB,IAAI,EAAE,WAAW,CAAC;IAGlB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;CACxC,CAAC;AASF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+B7E;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAepB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC,CAaD;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAG5E"}

package/dist/commands/shared/task-backend.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { CliError } from "../../shared/errors.js";
 import { loadTaskBackend } from "../../backends/task-backend.js";
+import { GitContext } from "./git-context.js";
 function normalizeDocUpdatedBy(value) {
     const trimmed = value?.trim() ?? "";
     if (!trimmed)
@@ -26,6 +27,9 @@ export function taskDataToFrontmatter(task) {
     return {
         id: task.id,
         title: task.title,
+        result_summary: task.result_summary,
+        risk_level: task.risk_level,
+        breaking: task.breaking,
         status: task.status,
         priority: task.priority,
         owner: task.owner,
@@ -36,20 +40,36 @@ export function taskDataToFrontmatter(task) {
         verification,
         commit: task.commit ?? null,
         comments: task.comments ?? [],
+        events: task.events ?? [],
         doc_version: task.doc_version,
         doc_updated_at: task.doc_updated_at,
         doc_updated_by: task.doc_updated_by,
         description: task.description ?? "",
+        id_source: task.id_source,
+        dirty: task.dirty,
     };
 }
-export async function loadBackendTask(opts) {
-    const { backend, backendId, resolved, config } = await loadTaskBackend({
+export async function loadCommandContext(opts) {
+    const { backend, backendId, backendConfigPath, resolved, config } = await loadTaskBackend({
         cwd: opts.cwd,
         rootOverride: opts.rootOverride ?? null,
     });
-    const task = await backend.getTask(opts.taskId);
+    return {
+        resolvedProject: resolved,
+        config,
+        taskBackend: backend,
+        backendId,
+        backendConfigPath,
+        git: new GitContext({ gitRoot: resolved.gitRoot }),
+        memo: {},
+        resolved,
+        backend,
+    };
+}
+export async function loadTaskFromContext(opts) {
+    const task = await opts.ctx.taskBackend.getTask(opts.taskId);
     if (!task) {
-        const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
+        const tasksDir = path.join(opts.ctx.resolvedProject.gitRoot, opts.ctx.config.paths.workflow_dir);
         const readmePath = path.join(tasksDir, opts.taskId, "README.md");
         throw new CliError({
             exitCode: 4,
@@ -57,5 +77,22 @@ export async function loadBackendTask(opts) {
             message: `ENOENT: no such file or directory, open '${readmePath}'`,
         });
     }
-    return { backend, backendId, resolved, config, task };
+    return task;
+}
+export async function loadBackendTask(opts) {
+    const ctx = opts.ctx ??
+        (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+    const task = await loadTaskFromContext({ ctx, taskId: opts.taskId });
+    return {
+        backend: ctx.taskBackend,
+        backendId: ctx.backendId,
+        backendConfigPath: ctx.backendConfigPath,
+        resolved: ctx.resolvedProject,
+        config: ctx.config,
+        task,
+    };
+}
+export async function listTasksMemo(ctx) {
+    ctx.memo.taskList ??= ctx.taskBackend.listTasks();
+    return await ctx.memo.taskList;
 }

package/dist/commands/shared/task-store.d.ts

@@ -0,0 +1,16 @@
+import { type TaskData } from "../../backends/task-backend.js";
+import { type CommandContext } from "./task-backend.js";
+export declare class TaskStore {
+    private ctx;
+    private cache;
+    constructor(ctx: CommandContext);
+    get(taskId: string): Promise<TaskData>;
+    private getCached;
+    update(taskId: string, updater: (current: TaskData) => Promise<TaskData> | TaskData): Promise<{
+        changed: boolean;
+        task: TaskData;
+    }>;
+}
+export declare function getTaskStore(ctx: CommandContext): TaskStore;
+export declare function backendIsLocalFileBackend(ctx: CommandContext): boolean;
+//# sourceMappingURL=task-store.d.ts.map

package/dist/commands/shared/task-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-store.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,QAAQ,EAAoB,MAAM,gCAAgC,CAAC;AAG/F,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA0DpG,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,KAAK,CAA0C;gBAE3C,GAAG,EAAE,cAAc;IAIzB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAK9B,SAAS;IAkBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC3D,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;CAwEjD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,CAI3D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEtE"}

package/dist/commands/shared/task-store.js

@@ -0,0 +1,142 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { docChanged, extractTaskDoc, mergeTaskDoc, parseTaskReadme, renderTaskReadme, } from "@agentplaneorg/core";
+import { LocalBackend, taskRecordToData } from "../../backends/task-backend.js";
+import { CliError } from "../../shared/errors.js";
+import { writeTextIfChanged } from "../../shared/write-if-changed.js";
+import { resolveDocUpdatedBy, taskDataToFrontmatter } from "./task-backend.js";
+function taskReadmePath(ctx, taskId) {
+    return path.join(ctx.resolvedProject.gitRoot, ctx.config.paths.workflow_dir, taskId, "README.md");
+}
+async function readTaskReadmeCached(opts) {
+    const readmePath = taskReadmePath(opts.ctx, opts.taskId);
+    let text;
+    let st;
+    try {
+        st = await stat(readmePath);
+        text = await readFile(readmePath, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            throw new CliError({
+                exitCode: 4,
+                code: "E_IO",
+                message: `ENOENT: no such file or directory, open '${readmePath}'`,
+            });
+        }
+        throw err;
+    }
+    const parsed = parseTaskReadme(text);
+    const task = taskRecordToData({
+        id: opts.taskId,
+        frontmatter: parsed.frontmatter,
+        body: parsed.body,
+        readmePath,
+    });
+    return { task, readmePath, mtimeMs: st.mtimeMs, parsed };
+}
+async function ensureUnchangedOnDisk(opts) {
+    const st = await stat(opts.readmePath);
+    if (st.mtimeMs !== opts.expectedMtimeMs) {
+        throw new CliError({
+            exitCode: 4,
+            code: "E_IO",
+            message: `Task README changed concurrently: ${opts.readmePath}`,
+        });
+    }
+}
+export class TaskStore {
+    ctx;
+    cache = new Map();
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async get(taskId) {
+        const entry = await this.getCached(taskId);
+        return entry.task;
+    }
+    async getCached(taskId) {
+        const key = taskId.trim();
+        if (!key) {
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "task id is required" });
+        }
+        const existing = this.cache.get(key);
+        if (existing)
+            return await existing;
+        const load = (async () => {
+            // For now, TaskStore does file-based caching. Non-file backends can still rely on
+            // backend.getTask/writeTask elsewhere, but lifecycle/status commands in this repo
+            // operate on the local task README files.
+            return await readTaskReadmeCached({ ctx: this.ctx, taskId: key });
+        })();
+        this.cache.set(key, load);
+        return await load;
+    }
+    async update(taskId, updater) {
+        // One retry on concurrent modification: re-read latest and re-apply updater.
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const entry = await this.getCached(taskId);
+            const current = entry.task;
+            const next = await updater({ ...current });
+            // Start from existing frontmatter to preserve any unknown keys.
+            const frontmatter = { ...entry.parsed.frontmatter, ...taskDataToFrontmatter(next) };
+            let body = entry.parsed.body ?? "";
+            const existingDoc = extractTaskDoc(body);
+            const now = new Date().toISOString();
+            if (next.doc !== undefined) {
+                const nextDoc = String(next.doc ?? "");
+                body = mergeTaskDoc(body, nextDoc);
+                if (docChanged(existingDoc, nextDoc) || !frontmatter.doc_updated_at) {
+                    frontmatter.doc_version = 2;
+                    frontmatter.doc_updated_at = now;
+                    frontmatter.doc_updated_by = resolveDocUpdatedBy(next);
+                }
+            }
+            if (frontmatter.doc_version !== 2)
+                frontmatter.doc_version = 2;
+            if (typeof frontmatter.doc_updated_at !== "string" ||
+                frontmatter.doc_updated_at.trim() === "") {
+                frontmatter.doc_updated_at = now;
+            }
+            if (typeof frontmatter.doc_updated_by !== "string" ||
+                frontmatter.doc_updated_by.trim() === "") {
+                frontmatter.doc_updated_by = resolveDocUpdatedBy(next);
+            }
+            const rendered = renderTaskReadme(frontmatter, body);
+            try {
+                await ensureUnchangedOnDisk({
+                    readmePath: entry.readmePath,
+                    expectedMtimeMs: entry.mtimeMs,
+                });
+            }
+            catch (err) {
+                if (attempt === 0 && err instanceof CliError) {
+                    // Refresh cache and retry once.
+                    this.cache.delete(taskId);
+                    continue;
+                }
+                throw err;
+            }
+            const nextText = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
+            const changed = await writeTextIfChanged(entry.readmePath, nextText);
+            // Refresh cache with latest content on disk.
+            this.cache.set(taskId, (async () => {
+                return await readTaskReadmeCached({ ctx: this.ctx, taskId });
+            })());
+            const updated = await this.get(taskId);
+            return { changed, task: updated };
+        }
+        // Unreachable, but keeps TS happy.
+        const task = await this.get(taskId);
+        return { changed: false, task };
+    }
+}
+export function getTaskStore(ctx) {
+    const memo = ctx.memo;
+    memo.taskStore ??= new TaskStore(ctx);
+    return memo.taskStore;
+}
+export function backendIsLocalFileBackend(ctx) {
+    return ctx.taskBackend instanceof LocalBackend;
+}

package/dist/commands/start.command.d.ts

@@ -0,0 +1,19 @@
+import type { CommandCtx, CommandSpec } from "../cli/spec/spec.js";
+import type { CommandContext } from "./shared/task-backend.js";
+export type StartParsed = {
+    taskId: string;
+    author: string;
+    body: string;
+    commitFromComment: boolean;
+    commitEmoji?: string;
+    commitAllow: string[];
+    commitAutoAllow: boolean;
+    commitAllowTasks: boolean;
+    commitRequireClean: boolean;
+    confirmStatusCommit: boolean;
+    force: boolean;
+    quiet: boolean;
+};
+export declare const startSpec: CommandSpec<StartParsed>;
+export declare function makeRunStartHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: StartParsed) => Promise<number>;
+//# sourceMappingURL=start.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"start.command.d.ts","sourceRoot":"","sources":["../../src/commands/start.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,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,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAQF,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,WAAW,CAmH9C,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACpE,KAAK,UAAU,EAAE,GAAG,WAAW,KAAG,OAAO,CAAC,MAAM,CAAC,CAmBhE"}

package/dist/commands/start.command.js

@@ -0,0 +1,143 @@
+import { usageError } from "../cli/spec/errors.js";
+import { cmdStart } from "./task/start.js";
+function toStringList(v) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    return [];
+}
+export const startSpec = {
+    id: ["start"],
+    group: "Lifecycle",
+    summary: "Transition a task to DOING and record a structured Start comment.",
+    args: [
+        {
+            name: "task-id",
+            required: true,
+            valueHint: "<task-id>",
+            description: "Existing task id.",
+        },
+    ],
+    options: [
+        {
+            kind: "string",
+            name: "author",
+            valueHint: "<id>",
+            required: true,
+            description: "Comment author id (e.g. CODER).",
+        },
+        {
+            kind: "string",
+            name: "body",
+            valueHint: "<text>",
+            required: true,
+            description: "Structured comment body (must match the configured Start: prefix).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-from-comment",
+            default: false,
+            description: "Create a status commit using the comment body.",
+        },
+        {
+            kind: "string",
+            name: "commit-emoji",
+            valueHint: "<emoji>",
+            description: "Override the status commit emoji (used with --commit-from-comment).",
+        },
+        {
+            kind: "string",
+            name: "commit-allow",
+            valueHint: "<path-prefix>",
+            repeatable: true,
+            description: "Repeatable. Allowlist path prefixes to stage for the status commit (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-auto-allow",
+            default: false,
+            description: "Auto-allow inferred allowlist paths if none are provided (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-allow-tasks",
+            default: true,
+            hidden: true,
+            description: "Deprecated. Tasks are always allowed for status commits.",
+            deprecated: "no-op",
+        },
+        {
+            kind: "boolean",
+            name: "commit-require-clean",
+            default: false,
+            description: "Require a clean working tree for the status commit (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "confirm-status-commit",
+            default: false,
+            description: "Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "force",
+            default: false,
+            description: "Override readiness checks and status transition restrictions.",
+        },
+        { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
+    ],
+    examples: [
+        {
+            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI"',
+            why: "Start work on a task.",
+        },
+        {
+            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI" --commit-from-comment --commit-allow packages/agentplane/src',
+            why: "Start work and create a status commit from the comment.",
+        },
+    ],
+    validateRaw: (raw) => {
+        const author = typeof raw.opts.author === "string" ? raw.opts.author.trim() : "";
+        const body = typeof raw.opts.body === "string" ? raw.opts.body.trim() : "";
+        if (!author)
+            throw usageError({ spec: startSpec, message: "Invalid value for --author: empty." });
+        if (!body)
+            throw usageError({ spec: startSpec, message: "Invalid value for --body: empty." });
+    },
+    parse: (raw) => ({
+        taskId: typeof raw.args["task-id"] === "string" ? raw.args["task-id"] : "",
+        author: raw.opts.author,
+        body: raw.opts.body,
+        commitFromComment: raw.opts["commit-from-comment"] === true,
+        commitEmoji: raw.opts["commit-emoji"],
+        commitAllow: toStringList(raw.opts["commit-allow"]),
+        commitAutoAllow: raw.opts["commit-auto-allow"] === true,
+        commitAllowTasks: raw.opts["commit-allow-tasks"] !== false,
+        commitRequireClean: raw.opts["commit-require-clean"] === true,
+        confirmStatusCommit: raw.opts["confirm-status-commit"] === true,
+        force: raw.opts.force === true,
+        quiet: raw.opts.quiet === true,
+    }),
+};
+export function makeRunStartHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdStart({
+            ctx: await getCtx("start"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            taskId: p.taskId,
+            author: p.author,
+            body: p.body,
+            commitFromComment: p.commitFromComment,
+            commitEmoji: p.commitEmoji,
+            commitAllow: p.commitAllow,
+            commitAutoAllow: p.commitAutoAllow,
+            commitAllowTasks: p.commitAllowTasks,
+            commitRequireClean: p.commitRequireClean,
+            confirmStatusCommit: p.confirmStatusCommit,
+            force: p.force,
+            quiet: p.quiet,
+        });
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { CommandCtx, CommandSpec } from "../cli/spec/spec.js";
+import type { CommandContext } from "./shared/task-backend.js";
+import { type SyncParsed } from "./backend.js";
+export declare const syncSpec: CommandSpec<SyncParsed>;
+export declare function makeRunSyncHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: SyncParsed) => Promise<number>;
+//# sourceMappingURL=sync.command.d.ts.map