agentplane 0.3.7 → 0.3.8

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

@@ -1,72 +1,42 @@
 import { CliError } from "../../shared/errors.js";
-import { appendTaskCommentIntent, appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, setTaskFieldsIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
-import { appendTaskEvent, normalizeTaskDocVersion, nowIso, requireStructuredComment, } from "./shared.js";
+import { applyTaskMutation } from "../shared/task-mutation.js";
+import { executeTaskStatusTransitionRequest, nowIso, requireStructuredComment } from "./shared.js";
 export async function recordVerifiedNoopClosure(opts) {
-    if (!opts.force && String(opts.task.status || "TODO").toUpperCase() === "DONE") {
-        throw new CliError({
-            exitCode: 2,
-            code: "E_USAGE",
-            message: `Task is already DONE: ${opts.taskId} (use --force to override)`,
-        });
-    }
     const verifiedCfg = opts.ctx.config.tasks.comments.verified;
     requireStructuredComment(opts.body, verifiedCfg.prefix, verifiedCfg.min_chars);
     const at = nowIso();
-    const useStore = backendIsLocalFileBackend(opts.ctx);
-    const store = useStore ? getTaskStore(opts.ctx) : null;
-    await (useStore
-        ? store.mutate(opts.taskId, (current) => {
-            if (!opts.force && String(current.status || "TODO").toUpperCase() === "DONE") {
+    await applyTaskMutation({
+        ctx: opts.ctx,
+        taskId: opts.taskId,
+        build: async (task) => {
+            if (!opts.force && String(task.status || "TODO").toUpperCase() === "DONE") {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
                     message: `Task is already DONE: ${opts.taskId} (use --force to override)`,
                 });
             }
-            return [
-                setTaskFieldsIntent({
-                    status: "DONE",
+            const execution = await executeTaskStatusTransitionRequest({
+                task,
+                backend: opts.ctx.taskBackend,
+                config: opts.ctx.config,
+                at,
+                toStatus: "DONE",
+                eventAuthor: opts.author,
+                updatedBy: opts.author,
+                note: opts.body,
+                comment: { author: opts.author, body: opts.body },
+                extraFields: {
                     result_summary: opts.resultSummary,
                     risk_level: "low",
                     breaking: false,
-                }),
-                appendTaskCommentIntent({ author: opts.author, body: opts.body }),
-                appendTaskEventIntent({
-                    type: "status",
-                    at,
-                    author: opts.author,
-                    from: String(current.status || "TODO").toUpperCase(),
-                    to: "DONE",
-                    note: opts.body,
-                }),
-                touchTaskDocMetaIntent({
-                    updatedBy: opts.author,
-                    version: normalizeTaskDocVersion(current.doc_version),
-                }),
-            ];
-        })
-        : opts.ctx.taskBackend.writeTask({
-            ...opts.task,
-            status: "DONE",
-            comments: [
-                ...(Array.isArray(opts.task.comments) ? opts.task.comments : []),
-                { author: opts.author, body: opts.body },
-            ],
-            events: appendTaskEvent(opts.task, {
-                type: "status",
-                at,
-                author: opts.author,
-                from: String(opts.task.status || "TODO").toUpperCase(),
-                to: "DONE",
-                note: opts.body,
-            }),
-            result_summary: opts.resultSummary,
-            risk_level: "low",
-            breaking: false,
-            doc_version: normalizeTaskDocVersion(opts.task.doc_version),
-            doc_updated_at: at,
-            doc_updated_by: opts.author,
-        }));
+                },
+                force: true,
+                dependencyPolicy: { kind: "none" },
+            });
+            return { intents: execution.intents, nextTask: execution.nextTask };
+        },
+    });
     if (!opts.quiet) {
         process.stdout.write(`${opts.successMessage}\n`);
     }

package/dist/commands/task/comment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../../src/commands/task/comment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAUnC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDlB"}
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../../src/commands/task/comment.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAqDpF,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB"}

package/dist/commands/task/comment.js

@@ -1,48 +1,59 @@
 import { mapBackendError } from "../../cli/error-map.js";
 import { successMessage } from "../../cli/output.js";
-import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { appendTaskCommentIntent, appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, touchTaskDocMetaIntent, } from "../shared/task-store.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { applyTaskMutation } from "../shared/task-mutation.js";
+import { appendTaskCommentIntent, appendTaskEventIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
 import { appendTaskEvent, normalizeTaskDocVersion, nowIso } from "./shared.js";
+function buildCommentMutation(opts) {
+    return {
+        intents: [
+            appendTaskCommentIntent({ author: opts.author, body: opts.body }),
+            appendTaskEventIntent({
+                type: "comment",
+                at: opts.at,
+                author: opts.author,
+                body: opts.body,
+            }),
+            touchTaskDocMetaIntent({
+                updatedBy: opts.author,
+                version: normalizeTaskDocVersion(opts.task.doc_version),
+            }),
+        ],
+        nextTask: {
+            ...opts.task,
+            comments: [
+                ...(Array.isArray(opts.task.comments)
+                    ? opts.task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
+                    : []),
+                { author: opts.author, body: opts.body },
+            ],
+            events: appendTaskEvent(opts.task, {
+                type: "comment",
+                at: opts.at,
+                author: opts.author,
+                body: opts.body,
+            }),
+            doc_version: normalizeTaskDocVersion(opts.task.doc_version),
+            doc_updated_at: opts.at,
+            doc_updated_by: opts.author,
+        },
+    };
+}
 export async function cmdTaskComment(opts) {
     try {
         const ctx = opts.ctx ??
             (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
-        const useStore = backendIsLocalFileBackend(ctx);
-        const store = useStore ? getTaskStore(ctx) : null;
-        const task = useStore ? null : await loadTaskFromContext({ ctx, taskId: opts.taskId });
         const at = nowIso();
-        await (useStore
-            ? store.mutate(opts.taskId, (current) => [
-                appendTaskCommentIntent({ author: opts.author, body: opts.body }),
-                appendTaskEventIntent({
-                    type: "comment",
-                    at,
-                    author: opts.author,
-                    body: opts.body,
-                }),
-                touchTaskDocMetaIntent({
-                    updatedBy: opts.author,
-                    version: normalizeTaskDocVersion(current.doc_version),
-                }),
-            ])
-            : ctx.taskBackend.writeTask({
-                ...task,
-                comments: [
-                    ...(Array.isArray(task.comments)
-                        ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
-                        : []),
-                    { author: opts.author, body: opts.body },
-                ],
-                events: appendTaskEvent(task, {
-                    type: "comment",
-                    at,
-                    author: opts.author,
-                    body: opts.body,
-                }),
-                doc_version: normalizeTaskDocVersion(task.doc_version),
-                doc_updated_at: at,
-                doc_updated_by: opts.author,
-            }));
+        await applyTaskMutation({
+            ctx,
+            taskId: opts.taskId,
+            build: (task) => buildCommentMutation({
+                task,
+                at,
+                author: opts.author,
+                body: opts.body,
+            }),
+        });
         process.stdout.write(`${successMessage("commented", opts.taskId)}\n`);
         return 0;
     }

package/dist/commands/task/derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAuBpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGlB"}
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAuBpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4GlB"}

package/dist/commands/task/derive.js

@@ -1,7 +1,8 @@
-import { setMarkdownSection, taskDocToSectionMap } from "@agentplaneorg/core";
+import { setMarkdownSection } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { unknownEntityMessage, warnMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
+import { buildTaskDocState } from "../../shared/task-doc-state.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { buildDefaultVerifyStepsSection, defaultTaskDocV3, TASK_DOC_VERSION_V3, } from "./doc-template.js";
 import { extractTaskObservationSection, normalizeTaskDocVersion, nowIso, requiresVerifyStepsByPrimary, resolvePrimaryTag, toStringArray, warnIfUnknownOwner, } from "./shared.js";
@@ -66,7 +67,13 @@ export async function cmdTaskDerive(opts) {
         if (hasSpike && requiresVerifySteps) {
             process.stderr.write(`${warnMessage("spike is combined with a primary tag that requires verify steps; consider splitting spike vs implementation tasks")}\n`);
         }
-        const at = nowIso();
+        const docState = buildTaskDocState({
+            doc,
+            owner: opts.owner,
+            updatedBy: opts.owner,
+            version: TASK_DOC_VERSION_V3,
+            updatedAt: nowIso(),
+        });
         await ctx.taskBackend.writeTask({
             id: taskId,
             title: opts.title,
@@ -78,11 +85,11 @@ export async function cmdTaskDerive(opts) {
             depends_on: [opts.spikeId],
             verify: opts.verify,
             comments: [],
-            doc,
-            sections: taskDocToSectionMap(doc),
-            doc_version: TASK_DOC_VERSION_V3,
-            doc_updated_at: at,
-            doc_updated_by: opts.owner,
+            doc: docState.doc,
+            sections: docState.sections,
+            doc_version: docState.doc_version,
+            doc_updated_at: docState.doc_updated_at,
+            doc_updated_by: docState.doc_updated_by,
             id_source: "generated",
         });
         process.stdout.write(`${taskId}\n`);

package/dist/commands/task/doc.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAelD,CAAC;AAEF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9E"}
+{"version":3,"file":"doc.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAelD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpF"}

package/dist/commands/task/doc.command.js

@@ -1,4 +1,4 @@
-import { usageError } from "../../cli/spec/errors.js";
+import { loadDirectSubcommandNames, throwGroupCommandUsage } from "../../cli/group-command.js";
 export const taskDocSpec = {
     id: ["task", "doc"],
     group: "Task",
@@ -15,9 +15,10 @@ export const taskDocSpec = {
         };
     },
 };
-export function runTaskDoc(_ctx, p) {
-    if (!p.subcommand) {
-        throw usageError({ spec: taskDocSpec, message: "Missing subcommand." });
-    }
-    throw usageError({ spec: taskDocSpec, message: `Unknown subcommand: ${p.subcommand}` });
+export async function runTaskDoc(_ctx, p) {
+    throwGroupCommandUsage({
+        spec: taskDocSpec,
+        cmd: p.subcommand ? [p.subcommand] : [],
+        subcommands: await loadDirectSubcommandNames(["task", "doc"]),
+    });
 }

package/dist/commands/task/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AA6CpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgLlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDlB"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAkDpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6KlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDlB"}

package/dist/commands/task/doc.js

@@ -5,17 +5,18 @@ import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
 import { infoMessage, unknownEntityMessage, backendNotSupportedMessage, warnMessage, } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
-import { decodeEscapedTaskTextNewlines } from "./shared.js";
+import { applyTaskMutation, withTaskMutationStorage } from "../shared/task-mutation.js";
+import { replaceTaskDocIntent, setTaskSectionIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
+import { decodeEscapedTaskTextNewlines, resolveWritableDocSections } from "./shared.js";
 function extractSectionTextForPatch(doc, section) {
     const { sections } = parseDocSections(doc);
     const entry = sections.get(normalizeDocSectionName(section));
     return entry ? entry.lines.join("\n").trimEnd() : null;
 }
 function buildUpdatedTaskDoc(opts) {
-    const baseDoc = ensureDocSections(opts.baseDocRaw, opts.requiredSections);
+    const baseDoc = ensureDocSections(opts.baseDocRaw, opts.sectionOrder);
     if (opts.requestMode === "full-doc") {
-        return ensureDocSections(opts.text, opts.requiredSections);
+        return ensureDocSections(opts.text, opts.sectionOrder);
     }
     let nextText = opts.text;
     if (opts.headingKeys.size > 0 && opts.headingKeys.has(opts.targetKey)) {
@@ -30,7 +31,7 @@ function buildUpdatedTaskDoc(opts) {
             nextText = lines.join("\n");
         }
     }
-    return ensureDocSections(setMarkdownSection(baseDoc, opts.section ?? "", nextText), opts.requiredSections);
+    return ensureDocSections(setMarkdownSection(baseDoc, opts.section ?? "", nextText), opts.sectionOrder);
 }
 export async function cmdTaskDocSet(opts) {
     let updatedBy;
@@ -72,15 +73,13 @@ export async function cmdTaskDocSet(opts) {
         const backend = ctx.taskBackend;
         const resolved = ctx.resolvedProject;
         const config = ctx.config;
-        if (!backend.getTaskDoc || !backend.setTaskDoc) {
+        if (!backend.getTaskDoc || !backend.writeTask) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
                 message: backendNotSupportedMessage("task docs"),
             });
         }
-        const useStore = backendIsLocalFileBackend(ctx);
-        const store = useStore ? getTaskStore(ctx) : null;
         const allowed = config.tasks.doc.sections;
         if (!opts.fullDoc && !opts.section) {
             throw new CliError({
@@ -119,18 +118,27 @@ export async function cmdTaskDocSet(opts) {
             : headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))
                 ? "full-doc"
                 : "section";
+        const sectionOrder = requestMode === "full-doc"
+            ? [...config.tasks.doc.required_sections]
+            : resolveWritableDocSections({
+                allowedSections: allowed,
+                requiredSections: config.tasks.doc.required_sections,
+                targetSection: opts.section ?? "",
+            });
         let changed = false;
-        if (useStore) {
-            let expectedCurrentDoc;
-            let expectedCurrentSectionText;
-            const result = await store.patch(opts.taskId, (current) => {
-                const currentDocRaw = String(current.doc ?? "");
+        const result = await applyTaskMutation({
+            ctx,
+            taskId: opts.taskId,
+            build: async (current) => {
+                const currentDocRaw = typeof current.doc === "string"
+                    ? current.doc
+                    : ((await backend.getTaskDoc(opts.taskId)) ?? "");
                 const nextDoc = buildUpdatedTaskDoc({
                     baseDocRaw: currentDocRaw,
                     section: opts.section,
                     text,
                     requestMode,
-                    requiredSections: config.tasks.doc.required_sections,
+                    sectionOrder,
                     headingKeys,
                     targetKey,
                 });
@@ -140,55 +148,42 @@ export async function cmdTaskDocSet(opts) {
                     return null;
                 if (!docChanged) {
                     return {
-                        docMeta: {
-                            touch: true,
-                            ...(updatedBy ? { updatedBy } : {}),
-                        },
+                        intents: [touchTaskDocMetaIntent({ updatedBy })],
                     };
                 }
                 if (requestMode === "full-doc") {
-                    expectedCurrentDoc ??= currentDocRaw;
                     return {
-                        doc: {
-                            kind: "replace-doc",
-                            doc: nextDoc,
-                            expectedCurrentDoc,
+                        intents: [
+                            replaceTaskDocIntent({
+                                doc: nextDoc,
+                                expectedCurrentDoc: currentDocRaw,
+                            }),
+                            ...(updatedBy ? [touchTaskDocMetaIntent({ updatedBy })] : []),
+                        ],
+                        writeOptions: {
+                            expectedCurrentDoc: currentDocRaw,
                         },
-                        ...(updatedBy ? { docMeta: { updatedBy } } : {}),
                     };
                 }
-                expectedCurrentSectionText ??= extractSectionTextForPatch(currentDocRaw, opts.section ?? "");
+                const expectedCurrentSectionText = extractSectionTextForPatch(currentDocRaw, opts.section ?? "");
                 return {
-                    doc: {
-                        kind: "set-section",
-                        section: opts.section ?? "",
-                        text: extractSectionTextForPatch(nextDoc, opts.section ?? "") ?? "",
-                        requiredSections: config.tasks.doc.required_sections,
+                    intents: [
+                        setTaskSectionIntent({
+                            section: opts.section ?? "",
+                            text: extractSectionTextForPatch(nextDoc, opts.section ?? "") ?? "",
+                            requiredSections: sectionOrder,
+                            expectedCurrentText: expectedCurrentSectionText,
+                        }),
+                        ...(updatedBy ? [touchTaskDocMetaIntent({ updatedBy })] : []),
+                    ],
+                    writeOptions: {
                         expectedCurrentText: expectedCurrentSectionText,
+                        expectedSection: opts.section ?? "",
                     },
-                    ...(updatedBy ? { docMeta: { updatedBy } } : {}),
                 };
-            });
-            changed = result.changed;
-        }
-        else {
-            const baseDocRaw = (await backend.getTaskDoc(opts.taskId)) ?? "";
-            const nextDoc = buildUpdatedTaskDoc({
-                baseDocRaw,
-                section: opts.section,
-                text,
-                requestMode,
-                requiredSections: config.tasks.doc.required_sections,
-                headingKeys,
-                targetKey,
-            });
-            const docChanged = normalizeTaskDoc(baseDocRaw) !== normalizeTaskDoc(nextDoc);
-            const shouldWrite = docChanged || updatedBy !== undefined;
-            if (shouldWrite) {
-                await backend.setTaskDoc(opts.taskId, nextDoc, updatedBy);
-            }
-            changed = shouldWrite;
-        }
+            },
+        });
+        changed = result.changed;
         const outcome = changed
             ? requestMode === "full-doc"
                 ? "full-doc-updated"
@@ -219,17 +214,18 @@ export async function cmdTaskDocShow(opts) {
                 message: backendNotSupportedMessage("task docs"),
             });
         }
-        const useStore = backendIsLocalFileBackend(ctx);
-        const storeTask = useStore ? await getTaskStore(ctx).get(opts.taskId) : null;
-        const doc = useStore
-            ? storeTask?.sections && Object.keys(storeTask.sections).length > 0
-                ? renderTaskDocFromSections(storeTask.sections)
-                : String(storeTask?.doc ?? "")
-            : ((await backend.getTaskDoc(opts.taskId)) ?? "");
+        const doc = await withTaskMutationStorage({
+            ctx,
+            local: async (store) => {
+                const storeTask = await store.get(opts.taskId);
+                return storeTask?.sections && Object.keys(storeTask.sections).length > 0
+                    ? renderTaskDocFromSections(storeTask.sections)
+                    : String(storeTask?.doc ?? "");
+            },
+            remote: async (remoteBackend) => (await remoteBackend.getTaskDoc(opts.taskId)) ?? "",
+        });
         const canonicalSections = new Map();
-        for (const [title, text] of Object.entries(useStore && storeTask?.sections && Object.keys(storeTask.sections).length > 0
-            ? storeTask.sections
-            : taskDocToSectionMap(doc))) {
+        for (const [title, text] of Object.entries(taskDocToSectionMap(doc))) {
             canonicalSections.set(normalizeDocSectionName(title), {
                 title,
                 lines: String(text ?? "").split("\n"),

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

@@ -0,0 +1,60 @@
+import type { TaskData } from "../../backends/task-backend.js";
+import { type CommandContext } from "../shared/task-backend.js";
+import { getTaskStore } from "../shared/task-store.js";
+export type ResolvedCommitInfo = {
+    hash: string;
+    message: string;
+};
+export type LoadedFinishTask = {
+    taskId: string;
+    task: TaskData;
+};
+export declare function existingCommitInfo(task: TaskData): ResolvedCommitInfo | null;
+export declare function assertTaskCanFinish(opts: {
+    task: TaskData;
+    config: CommandContext["config"];
+    taskCount: number;
+    isMetaTask: boolean;
+    resultProvided: boolean;
+    resultSummary: string;
+    force: boolean;
+}): void;
+export declare function loadTaskForFinish(opts: {
+    ctx: CommandContext;
+    store: ReturnType<typeof getTaskStore> | null;
+    useStore: boolean;
+    taskId: string;
+    taskCount: number;
+    metaTaskId: string;
+    resultProvided: boolean;
+    resultSummary: string;
+    force: boolean;
+    capturePrimaryLifecycleMeta: boolean;
+}): Promise<{
+    loaded: LoadedFinishTask;
+    primaryStatusFrom: string | null;
+    primaryTag: string | null;
+}>;
+export declare function writeFinishedTasks(opts: {
+    ctx: CommandContext;
+    loadedTasks: LoadedFinishTask[];
+    metaTaskId: string;
+    author: string;
+    body: string;
+    force: boolean;
+    resultProvided: boolean;
+    resultSummary: string;
+    riskLevel?: "low" | "med" | "high";
+    breaking: boolean;
+    taskCommitInfo: ResolvedCommitInfo | null;
+}): Promise<void>;
+export declare function createTaskCloseCommit(opts: {
+    ctx: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    taskId: string;
+    baseBranchOverride?: string;
+    quiet: boolean;
+    closeUnstageOthers?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=finish-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"finish-shared.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish-shared.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAG/D,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAA6B,YAAY,EAAmB,MAAM,yBAAyB,CAAC;AAWnG,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,kBAAkB,GAAG,IAAI,CAK5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,IAAI,CAyCP;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,GAAG,IAAI,CAAC;IAC9C,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,2BAA2B,EAAE,OAAO,CAAC;CACtC,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,gBAAgB,CAAC;IACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAuDD;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,cAAc,CAAC;IACpB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDhB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB"}