agentplane 0.3.13 → 0.3.15

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

@@ -1,8 +1,8 @@
 import { PolicyEngine } from "../../policy/engine.js";
-import { loadTaskFromContext, writeTasksOrFallback } from "./task-backend.js";
-import { applyTaskStoreIntentsToTask, backendIsLocalFileBackend, getTaskStore, } from "./task-store.js";
+import { backendUsesLocalTaskStore, loadTaskFromContext, writeTasksOrFallback, } from "./task-backend.js";
+import { applyTaskStoreIntentsToTask, getTaskStore, } from "./task-store.js";
 export async function withTaskMutationStorage(opts) {
-    if (backendIsLocalFileBackend(opts.ctx)) {
+    if (backendUsesLocalTaskStore(opts.ctx)) {
         return await opts.local(getTaskStore(opts.ctx));
     }
     return await opts.remote(opts.ctx.taskBackend);
@@ -14,7 +14,7 @@ export async function applyTaskMutation(opts) {
         taskId: opts.taskId,
         git: { stagedPaths: [] },
     });
-    if (backendIsLocalFileBackend(opts.ctx)) {
+    if (backendUsesLocalTaskStore(opts.ctx)) {
         const store = getTaskStore(opts.ctx);
         const result = await store.update(opts.taskId, async (current) => {
             const plan = await opts.build({ ...current });

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

@@ -0,0 +1,34 @@
+import type { TaskData, TaskEvent } from "../../../backends/task-backend.js";
+import type { CachedTask, TaskComment, TaskStoreIntent, TaskStoreIntentResult, TaskStoreLike, TaskStoreMutationOptions, TaskStorePatch, TaskStoreTaskPatch } from "./types.js";
+export declare function setTaskFieldsIntent(task: TaskStoreTaskPatch): TaskStoreIntent;
+export declare function appendTaskCommentsIntent(comments: TaskComment[]): TaskStoreIntent;
+export declare function appendTaskCommentIntent(comment: TaskComment): TaskStoreIntent;
+export declare function appendTaskEventsIntent(events: TaskEvent[]): TaskStoreIntent;
+export declare function appendTaskEventIntent(event: TaskEvent): TaskStoreIntent;
+export declare function replaceTaskDocIntent(opts: {
+    doc: string;
+    expectedCurrentDoc?: string | null;
+}): TaskStoreIntent;
+export declare function setTaskSectionIntent(opts: {
+    section: string;
+    text: string;
+    requiredSections: string[];
+    expectedCurrentText?: string | null;
+}): TaskStoreIntent;
+export declare function touchTaskDocMetaIntent(opts?: {
+    updatedBy?: string;
+    version?: 2 | 3;
+}): TaskStoreIntent;
+export declare function taskStorePatchFromIntents(intents: TaskStoreIntentResult): TaskStorePatch | null | undefined;
+export declare function mutateTaskStore(store: TaskStoreLike, taskId: string, builder: (current: TaskData) => Promise<TaskStoreIntentResult> | TaskStoreIntentResult, opts?: TaskStoreMutationOptions): Promise<{
+    changed: boolean;
+    task: TaskData;
+}>;
+export declare function applyTaskStoreIntentsToTask(task: TaskData, intents: TaskStoreIntentResult, opts?: {
+    currentDocVersion?: 2 | 3;
+    docUpdatedAt?: string;
+}): TaskData;
+export declare function applyTaskStoreIntents(entry: CachedTask, intents: TaskStoreIntent[]): TaskData;
+export declare function resolveTaskStoreIntents(intents: TaskStoreIntentResult): TaskStoreIntent[];
+export declare function resolveTaskStorePatch(patch: TaskStorePatch | null | undefined): TaskStoreIntent[];
+//# sourceMappingURL=intents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../../../../src/commands/shared/task-store/intents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAK7E,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EAEX,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAE7E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,eAAe,CAEjF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,eAAe,CAE7E;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,eAAe,CAE3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe,CAEvE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,GAAG,eAAe,CAElB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,eAAe,CAElB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACZ,GACL,eAAe,CAEjB;AAuFD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,GAAG,IAAI,GAAG,SAAS,CA2DnC;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,EACtF,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAS/C;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,qBAAqB,EAC9B,IAAI,GAAE;IACJ,iBAAiB,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,QAAQ,CA0GV;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,QAAQ,CAI7F;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,EAAE,CAEjG"}

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

@@ -0,0 +1,265 @@
+import { applyTaskDocMutations, normalizeTaskDocVersion, taskDocToSectionMap, } from "@agentplaneorg/core";
+import { assertExpectedTaskDoc, assertExpectedTaskSection, } from "../../../shared/task-doc-conflicts.js";
+export function setTaskFieldsIntent(task) {
+    return { kind: "set-task-fields", task };
+}
+export function appendTaskCommentsIntent(comments) {
+    return { kind: "append-comments", comments };
+}
+export function appendTaskCommentIntent(comment) {
+    return appendTaskCommentsIntent([comment]);
+}
+export function appendTaskEventsIntent(events) {
+    return { kind: "append-events", events };
+}
+export function appendTaskEventIntent(event) {
+    return appendTaskEventsIntent([event]);
+}
+export function replaceTaskDocIntent(opts) {
+    return { kind: "replace-doc", ...opts };
+}
+export function setTaskSectionIntent(opts) {
+    return { kind: "set-section", ...opts };
+}
+export function touchTaskDocMetaIntent(opts = {}) {
+    return { kind: "touch-doc-meta", ...opts };
+}
+function normalizeComments(task) {
+    return Array.isArray(task.comments)
+        ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
+        : [];
+}
+function normalizeEvents(task) {
+    return Array.isArray(task.events)
+        ? task.events.filter((item) => !!item &&
+            typeof item.type === "string" &&
+            typeof item.at === "string" &&
+            typeof item.author === "string")
+        : [];
+}
+function applyDocMutationsToState(docState, mutations, opts) {
+    const applied = applyTaskDocMutations(docState, mutations, {
+        now: opts.docUpdatedAt,
+    });
+    return {
+        ...docState,
+        doc: applied.doc,
+        sections: applied.sections,
+        doc_version: applied.doc_version,
+        doc_updated_at: applied.doc_updated_at,
+        doc_updated_by: applied.doc_updated_by,
+    };
+}
+function normalizeTaskStoreIntents(intents) {
+    if (!intents)
+        return [];
+    if (Array.isArray(intents)) {
+        return intents.filter((intent) => intent != null);
+    }
+    return [intents];
+}
+function patchToIntents(patch) {
+    if (!patch)
+        return [];
+    const intents = [];
+    if (patch.task)
+        intents.push(setTaskFieldsIntent(patch.task));
+    if (patch.appendComments && patch.appendComments.length > 0) {
+        intents.push(appendTaskCommentsIntent(patch.appendComments));
+    }
+    if (patch.appendEvents && patch.appendEvents.length > 0) {
+        intents.push(appendTaskEventsIntent(patch.appendEvents));
+    }
+    if (patch.doc) {
+        intents.push(patch.doc.kind === "replace-doc"
+            ? replaceTaskDocIntent({
+                doc: patch.doc.doc,
+                expectedCurrentDoc: patch.doc.expectedCurrentDoc,
+            })
+            : setTaskSectionIntent({
+                section: patch.doc.section,
+                text: patch.doc.text,
+                requiredSections: patch.doc.requiredSections,
+                expectedCurrentText: patch.doc.expectedCurrentText,
+            }));
+    }
+    if (patch.docMeta && (patch.doc !== undefined || patch.docMeta.touch === true)) {
+        intents.push(touchTaskDocMetaIntent({
+            updatedBy: patch.docMeta.updatedBy,
+            version: patch.docMeta.version,
+        }));
+    }
+    return intents;
+}
+export function taskStorePatchFromIntents(intents) {
+    const normalized = normalizeTaskStoreIntents(intents);
+    if (normalized.length === 0)
+        return null;
+    const patch = {};
+    for (const intent of normalized) {
+        switch (intent.kind) {
+            case "set-task-fields": {
+                patch.task = patch.task ? { ...patch.task, ...intent.task } : { ...intent.task };
+                break;
+            }
+            case "append-comments": {
+                if (intent.comments.length > 0) {
+                    patch.appendComments = [...(patch.appendComments ?? []), ...intent.comments];
+                }
+                break;
+            }
+            case "append-events": {
+                if (intent.events.length > 0) {
+                    patch.appendEvents = [...(patch.appendEvents ?? []), ...intent.events];
+                }
+                break;
+            }
+            case "replace-doc": {
+                const docPatch = {
+                    kind: "replace-doc",
+                    doc: intent.doc,
+                };
+                if (intent.expectedCurrentDoc !== undefined) {
+                    docPatch.expectedCurrentDoc = intent.expectedCurrentDoc;
+                }
+                patch.doc = docPatch;
+                break;
+            }
+            case "set-section": {
+                const sectionPatch = {
+                    kind: "set-section",
+                    section: intent.section,
+                    text: intent.text,
+                    requiredSections: [...intent.requiredSections],
+                };
+                if (intent.expectedCurrentText !== undefined) {
+                    sectionPatch.expectedCurrentText = intent.expectedCurrentText;
+                }
+                patch.doc = sectionPatch;
+                break;
+            }
+            case "touch-doc-meta": {
+                patch.docMeta = {
+                    touch: true,
+                    updatedBy: intent.updatedBy ?? patch.docMeta?.updatedBy,
+                    version: intent.version ?? patch.docMeta?.version,
+                };
+                break;
+            }
+        }
+    }
+    return patch;
+}
+export async function mutateTaskStore(store, taskId, builder, opts = {}) {
+    if (typeof store.mutate === "function") {
+        return await store.mutate(taskId, builder, opts);
+    }
+    return await store.patch(taskId, async (current) => taskStorePatchFromIntents(await builder(current)), opts);
+}
+export function applyTaskStoreIntentsToTask(task, intents, opts = {}) {
+    const normalizedIntents = normalizeTaskStoreIntents(intents);
+    if (normalizedIntents.length === 0)
+        return { ...task };
+    const current = task;
+    const next = { ...current };
+    let docState = {
+        comments: next.comments ?? null,
+        doc: String(next.doc ?? ""),
+        doc_updated_by: next.doc_updated_by,
+        doc_version: normalizeTaskDocVersion(opts.currentDocVersion ?? task.doc_version),
+        owner: next.owner,
+        sections: next.sections ?? null,
+    };
+    let touchDoc = false;
+    for (const intent of normalizedIntents) {
+        switch (intent.kind) {
+            case "set-task-fields": {
+                Object.assign(next, intent.task);
+                docState = {
+                    ...docState,
+                    doc_updated_by: next.doc_updated_by,
+                    doc_version: normalizeTaskDocVersion(next.doc_version ?? docState.doc_version),
+                    owner: next.owner,
+                };
+                break;
+            }
+            case "append-comments": {
+                if (intent.comments.length > 0) {
+                    next.comments = [...normalizeComments(next), ...intent.comments];
+                    docState = { ...docState, comments: next.comments };
+                }
+                break;
+            }
+            case "append-events": {
+                if (intent.events.length > 0) {
+                    next.events = [...normalizeEvents(next), ...intent.events];
+                }
+                break;
+            }
+            case "replace-doc": {
+                if (intent.expectedCurrentDoc !== undefined) {
+                    assertExpectedTaskDoc({
+                        taskId: current.id,
+                        currentDoc: docState.doc,
+                        expectedDoc: intent.expectedCurrentDoc,
+                    });
+                }
+                docState = applyDocMutationsToState(docState, [{ kind: "replace-doc", doc: intent.doc }], {
+                    docUpdatedAt: opts.docUpdatedAt,
+                });
+                touchDoc = true;
+                break;
+            }
+            case "set-section": {
+                if (intent.expectedCurrentText !== undefined) {
+                    assertExpectedTaskSection({
+                        taskId: current.id,
+                        currentDoc: docState.doc,
+                        section: intent.section,
+                        expectedText: intent.expectedCurrentText,
+                    });
+                }
+                docState = applyDocMutationsToState(docState, [
+                    {
+                        kind: "set-section",
+                        section: intent.section,
+                        text: intent.text,
+                        requiredSections: intent.requiredSections,
+                    },
+                ], { docUpdatedAt: opts.docUpdatedAt });
+                touchDoc = true;
+                break;
+            }
+            case "touch-doc-meta": {
+                docState = applyDocMutationsToState(docState, [
+                    {
+                        kind: "touch-doc-meta",
+                        updatedBy: intent.updatedBy,
+                        version: intent.version,
+                    },
+                ], { docUpdatedAt: opts.docUpdatedAt });
+                touchDoc = true;
+                break;
+            }
+        }
+    }
+    if (touchDoc) {
+        next.doc = docState.doc;
+        next.sections = docState.sections ?? taskDocToSectionMap(docState.doc);
+        next.doc_version = docState.doc_version;
+        next.doc_updated_at = docState.doc_updated_at;
+        next.doc_updated_by = docState.doc_updated_by;
+    }
+    return next;
+}
+export function applyTaskStoreIntents(entry, intents) {
+    return applyTaskStoreIntentsToTask(entry.task, intents, {
+        currentDocVersion: normalizeTaskDocVersion(entry.parsed.frontmatter.doc_version),
+    });
+}
+export function resolveTaskStoreIntents(intents) {
+    return normalizeTaskStoreIntents(intents);
+}
+export function resolveTaskStorePatch(patch) {
+    return patchToIntents(patch);
+}

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

@@ -0,0 +1,28 @@
+import { type TaskData } from "../../../backends/task-backend.js";
+import { CliError } from "../../../shared/errors.js";
+import type { CachedTask, TaskStoreContext } from "./types.js";
+export declare function normalizeTaskRevision(value: unknown, fallback?: number): number;
+export declare function readStoredTaskRevision(value: unknown): number | null;
+export declare function isConcurrentReadmeChangeError(err: unknown): err is CliError;
+export declare function throwTaskRevisionConflict(opts: {
+    taskId: string;
+    expectedRevision: number;
+    currentRevision: number;
+}): never;
+export declare function readTaskReadmeCached(opts: {
+    ctx: TaskStoreContext;
+    taskId: string;
+}): Promise<CachedTask>;
+export declare function ensureUnchangedOnDisk(opts: {
+    readmePath: string;
+    expectedMtimeMs: number;
+}): Promise<void>;
+export declare function didReadmeChangeOnDisk(opts: {
+    readmePath: string;
+    expectedMtimeMs: number;
+}): Promise<boolean>;
+export declare function writeTaskReadme(opts: {
+    entry: CachedTask;
+    next: TaskData;
+}): Promise<boolean>;
+//# sourceMappingURL=readme.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readme.d.ts","sourceRoot":"","sources":["../../../../src/commands/shared/task-store/readme.ts"],"names":[],"mappings":"AAYA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAEpF,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAM/D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAE1E;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAM3E;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,KAAK,CAcR;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,gBAAgB,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BtB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,OAAO,CAAC,CASnB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CA2CnB"}

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

@@ -0,0 +1,125 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { docChanged, extractTaskDoc, mergeTaskDoc, normalizeTaskDocVersion, parseTaskReadme, renderTaskReadme, } from "@agentplaneorg/core";
+import { taskRecordToData } from "../../../backends/task-backend.js";
+import { exitCodeForError } from "../../../cli/exit-codes.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");
+}
+export function normalizeTaskRevision(value, fallback = 1) {
+    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
+}
+export function readStoredTaskRevision(value) {
+    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : null;
+}
+export function isConcurrentReadmeChangeError(err) {
+    return (err instanceof CliError &&
+        err.code === "E_IO" &&
+        err.message.startsWith("Task README changed concurrently:"));
+}
+export function throwTaskRevisionConflict(opts) {
+    throw new CliError({
+        exitCode: exitCodeForError("E_VALIDATION"),
+        code: "E_VALIDATION",
+        message: `Task revision changed concurrently: ${opts.taskId} ` +
+            `(expected revision ${opts.expectedRevision}, current revision ${opts.currentRevision})`,
+        context: {
+            task_id: opts.taskId,
+            expected_revision: opts.expectedRevision,
+            current_revision: opts.currentRevision,
+            reason_code: "task_revision_conflict",
+        },
+    });
+}
+export 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, rawText: text };
+}
+export async function ensureUnchangedOnDisk(opts) {
+    const st = await stat(opts.readmePath);
+    if (st.mtimeMs !== opts.expectedMtimeMs) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_IO"),
+            code: "E_IO",
+            message: `Task README changed concurrently: ${opts.readmePath}`,
+        });
+    }
+}
+export async function didReadmeChangeOnDisk(opts) {
+    try {
+        const st = await stat(opts.readmePath);
+        return st.mtimeMs !== opts.expectedMtimeMs;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return true;
+        throw err;
+    }
+}
+export async function writeTaskReadme(opts) {
+    const { entry, next } = opts;
+    const frontmatter = { ...entry.parsed.frontmatter, ...taskDataToFrontmatter(next) };
+    let body = entry.parsed.body ?? "";
+    const existingDoc = extractTaskDoc(body);
+    const now = new Date().toISOString();
+    const currentDocVersion = normalizeTaskDocVersion(entry.parsed.frontmatter.doc_version);
+    const requestedDocVersion = normalizeTaskDocVersion(next.doc_version, currentDocVersion);
+    if (next.doc !== undefined) {
+        const nextDoc = String(next.doc ?? "");
+        body = mergeTaskDoc(body, nextDoc);
+        if (docChanged(existingDoc, nextDoc) || !frontmatter.doc_updated_at) {
+            frontmatter.doc_version = requestedDocVersion;
+            frontmatter.doc_updated_at = now;
+            frontmatter.doc_updated_by = resolveDocUpdatedBy(next);
+        }
+    }
+    frontmatter.doc_version = normalizeTaskDocVersion(frontmatter.doc_version, requestedDocVersion);
+    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 storedRevision = readStoredTaskRevision(entry.parsed.frontmatter.revision);
+    frontmatter.revision = storedRevision ?? 1;
+    let nextText = renderTaskReadme(frontmatter, body);
+    nextText = nextText.endsWith("\n") ? nextText : `${nextText}\n`;
+    if (storedRevision !== null && nextText !== entry.rawText) {
+        frontmatter.revision = storedRevision + 1;
+        nextText = renderTaskReadme(frontmatter, body);
+        nextText = nextText.endsWith("\n") ? nextText : `${nextText}\n`;
+    }
+    await ensureUnchangedOnDisk({
+        readmePath: entry.readmePath,
+        expectedMtimeMs: entry.mtimeMs,
+    });
+    return await writeTextIfChanged(entry.readmePath, nextText);
+}

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

@@ -0,0 +1,26 @@
+import type { TaskData } from "../../../backends/task-backend.js";
+import type { TaskStore as TaskStoreContract, TaskStoreContext, TaskStoreIntentResult, TaskStoreMutationOptions, TaskStorePatch } from "./types.js";
+export declare class TaskStore implements TaskStoreContract {
+    private ctx;
+    private cache;
+    constructor(ctx: TaskStoreContext);
+    get(taskId: string): Promise<TaskData>;
+    update(taskId: string, updater: (current: TaskData) => Promise<TaskData> | TaskData, opts?: TaskStoreMutationOptions): Promise<{
+        changed: boolean;
+        task: TaskData;
+    }>;
+    patch(taskId: string, builder: (current: TaskData) => Promise<TaskStorePatch | null | undefined> | TaskStorePatch | null | undefined, opts?: TaskStoreMutationOptions): Promise<{
+        changed: boolean;
+        task: TaskData;
+    }>;
+    mutate(taskId: string, builder: (current: TaskData) => Promise<TaskStoreIntentResult> | TaskStoreIntentResult, opts?: TaskStoreMutationOptions): Promise<{
+        changed: boolean;
+        task: TaskData;
+    }>;
+    private getCached;
+    private runWithRetry;
+    private writeNextTask;
+}
+export declare function getTaskStore(ctx: TaskStoreContext): TaskStore;
+export declare function backendIsLocalFileBackend(ctx: TaskStoreContext): boolean;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/commands/shared/task-store/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAiBlE,OAAO,KAAK,EAEV,SAAS,IAAI,iBAAiB,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,qBAAa,SAAU,YAAW,iBAAiB;IACjD,OAAO,CAAC,GAAG,CAAmB;IAC9B,OAAO,CAAC,KAAK,CAA0C;gBAE3C,GAAG,EAAE,gBAAgB;IAI3B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKtC,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,EAC5D,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IAM1C,KAAK,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,cAAc,GAAG,IAAI,GAAG,SAAS,EACnF,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IAQ1C,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,EACtF,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;YAOlC,SAAS;YAmBT,YAAY;YAiDZ,aAAa;CAgB5B;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,CAI7D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAExE"}

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

@@ -0,0 +1,105 @@
+import { exitCodeForError } from "../../../cli/exit-codes.js";
+import { CliError } from "../../../shared/errors.js";
+import { backendUsesLocalTaskStore } from "../task-backend.js";
+import { applyTaskStoreIntents, resolveTaskStoreIntents, resolveTaskStorePatch, } from "./intents.js";
+import { didReadmeChangeOnDisk, isConcurrentReadmeChangeError, normalizeTaskRevision, readTaskReadmeCached, throwTaskRevisionConflict, writeTaskReadme, } from "./readme.js";
+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 update(taskId, updater, opts = {}) {
+        return await this.runWithRetry(taskId, opts, async (entry) => {
+            return await updater({ ...entry.task });
+        });
+    }
+    async patch(taskId, builder, opts = {}) {
+        return await this.mutate(taskId, async (current) => resolveTaskStorePatch(await builder(current)), opts);
+    }
+    async mutate(taskId, builder, opts = {}) {
+        return await this.runWithRetry(taskId, opts, async (entry) => {
+            const intents = resolveTaskStoreIntents(await builder({ ...entry.task }));
+            return applyTaskStoreIntents(entry, intents);
+        });
+    }
+    async getCached(taskId) {
+        const key = taskId.trim();
+        if (!key) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_USAGE"),
+                code: "E_USAGE",
+                message: "task id is required",
+            });
+        }
+        const existing = this.cache.get(key);
+        if (existing)
+            return await existing;
+        const load = (async () => {
+            return await readTaskReadmeCached({ ctx: this.ctx, taskId: key });
+        })();
+        this.cache.set(key, load);
+        return await load;
+    }
+    async runWithRetry(taskId, opts, computeNext) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const entry = await this.getCached(taskId);
+            if (opts.expectedRevision !== undefined) {
+                const expectedRevision = normalizeTaskRevision(opts.expectedRevision);
+                const currentRevision = normalizeTaskRevision(entry.task.revision);
+                if (currentRevision !== expectedRevision) {
+                    throwTaskRevisionConflict({ taskId, expectedRevision, currentRevision });
+                }
+            }
+            let next;
+            try {
+                next = await computeNext(entry);
+            }
+            catch (err) {
+                if (attempt === 0 &&
+                    err instanceof CliError &&
+                    err.code === "E_VALIDATION" &&
+                    (await didReadmeChangeOnDisk({
+                        readmePath: entry.readmePath,
+                        expectedMtimeMs: entry.mtimeMs,
+                    }))) {
+                    this.cache.delete(taskId);
+                    continue;
+                }
+                throw err;
+            }
+            try {
+                return await this.writeNextTask(taskId, entry, next);
+            }
+            catch (err) {
+                if (attempt === 0 && isConcurrentReadmeChangeError(err)) {
+                    this.cache.delete(taskId);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        const task = await this.get(taskId);
+        return { changed: false, task };
+    }
+    async writeNextTask(taskId, entry, next) {
+        const changed = await writeTaskReadme({ entry, next });
+        this.cache.set(taskId, (async () => {
+            return await readTaskReadmeCached({ ctx: this.ctx, taskId });
+        })());
+        const updated = await this.get(taskId);
+        return { changed, task: updated };
+    }
+}
+export function getTaskStore(ctx) {
+    const memo = ctx.memo;
+    memo.taskStore ??= new TaskStore(ctx);
+    return memo.taskStore;
+}
+export function backendIsLocalFileBackend(ctx) {
+    return backendUsesLocalTaskStore(ctx);
+}