agentplane 0.3.5 → 0.3.7

package/dist/commands/task/doc.js

@@ -1,24 +1,36 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureDocSections, normalizeDocSectionName, parseDocSections, setMarkdownSection, } from "@agentplaneorg/core";
+import { normalizeDocSectionName, normalizeTaskDoc, parseDocSections, renderTaskDocFromSections, setMarkdownSection, taskDocToSectionMap, ensureDocSections, } from "@agentplaneorg/core";
 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";
-function normalizeOutcomeText(value) {
-    return value
-        .replaceAll("\r\n", "\n")
-        .split("\n")
-        .map((line) => line.trimEnd())
-        .join("\n")
-        .trim();
-}
-function readSectionContent(doc, section) {
-    const sectionKey = normalizeDocSectionName(section);
+import { decodeEscapedTaskTextNewlines } from "./shared.js";
+function extractSectionTextForPatch(doc, section) {
     const { sections } = parseDocSections(doc);
-    const lines = sections.get(sectionKey)?.lines ?? [];
-    return normalizeOutcomeText(lines.join("\n"));
+    const entry = sections.get(normalizeDocSectionName(section));
+    return entry ? entry.lines.join("\n").trimEnd() : null;
+}
+function buildUpdatedTaskDoc(opts) {
+    const baseDoc = ensureDocSections(opts.baseDocRaw, opts.requiredSections);
+    if (opts.requestMode === "full-doc") {
+        return ensureDocSections(opts.text, opts.requiredSections);
+    }
+    let nextText = opts.text;
+    if (opts.headingKeys.size > 0 && opts.headingKeys.has(opts.targetKey)) {
+        const lines = nextText.replaceAll("\r\n", "\n").split("\n");
+        let firstContent = 0;
+        while (firstContent < lines.length && lines[firstContent]?.trim() === "")
+            firstContent++;
+        if ((lines[firstContent]?.trim() ?? "") === `## ${opts.section}`) {
+            lines.splice(firstContent, 1);
+            if (lines[firstContent]?.trim() === "")
+                lines.splice(firstContent, 1);
+            nextText = lines.join("\n");
+        }
+    }
+    return ensureDocSections(setMarkdownSection(baseDoc, opts.section ?? "", nextText), opts.requiredSections);
 }
 export async function cmdTaskDocSet(opts) {
     let updatedBy;
@@ -43,6 +55,9 @@ export async function cmdTaskDocSet(opts) {
         });
     }
     let text = opts.text ?? "";
+    if (hasText) {
+        text = decodeEscapedTaskTextNewlines(text);
+    }
     if (hasFile) {
         try {
             text = await readFile(path.resolve(opts.cwd, opts.file ?? ""), "utf8");
@@ -67,15 +82,29 @@ export async function cmdTaskDocSet(opts) {
         const useStore = backendIsLocalFileBackend(ctx);
         const store = useStore ? getTaskStore(ctx) : null;
         const allowed = config.tasks.doc.sections;
-        if (!allowed.includes(opts.section)) {
+        if (!opts.fullDoc && !opts.section) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Missing required option: --section (or pass --full-doc)",
+            });
+        }
+        if (opts.fullDoc && opts.section) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Use either --section or --full-doc (not both)",
+            });
+        }
+        if (!opts.fullDoc && !allowed.includes(opts.section ?? "")) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: unknownEntityMessage("doc section", opts.section),
+                message: unknownEntityMessage("doc section", opts.section ?? ""),
             });
         }
         const normalizedAllowed = new Set(allowed.map((section) => normalizeDocSectionName(section)));
-        const targetKey = normalizeDocSectionName(opts.section);
+        const targetKey = normalizeDocSectionName(opts.section ?? "");
         const headingKeys = new Set();
         for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
             const match = /^##\s+(.*)$/.exec(line.trim());
@@ -85,68 +114,91 @@ export async function cmdTaskDocSet(opts) {
             if (key && normalizedAllowed.has(key))
                 headingKeys.add(key);
         }
-        const storeTask = useStore ? await store.get(opts.taskId) : null;
-        const baseDocRaw = useStore
-            ? String(storeTask.doc ?? "")
-            : ((await backend.getTaskDoc(opts.taskId)) ?? "");
-        const baseDoc = ensureDocSections(baseDocRaw, config.tasks.doc.required_sections);
-        const baseSection = readSectionContent(baseDoc, opts.section);
-        const requestMode = headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))
+        const requestMode = opts.fullDoc
             ? "full-doc"
-            : "section";
-        if (headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))) {
-            const fullDoc = ensureDocSections(text, config.tasks.doc.required_sections);
-            await (useStore
-                ? store.update(opts.taskId, (current) => ({
-                    ...current,
-                    doc: fullDoc,
-                    ...(updatedBy ? { doc_updated_by: updatedBy } : {}),
-                }))
-                : backend.setTaskDoc(opts.taskId, fullDoc, updatedBy));
+            : headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))
+                ? "full-doc"
+                : "section";
+        let changed = false;
+        if (useStore) {
+            let expectedCurrentDoc;
+            let expectedCurrentSectionText;
+            const result = await store.patch(opts.taskId, (current) => {
+                const currentDocRaw = String(current.doc ?? "");
+                const nextDoc = buildUpdatedTaskDoc({
+                    baseDocRaw: currentDocRaw,
+                    section: opts.section,
+                    text,
+                    requestMode,
+                    requiredSections: config.tasks.doc.required_sections,
+                    headingKeys,
+                    targetKey,
+                });
+                const docChanged = normalizeTaskDoc(currentDocRaw) !== normalizeTaskDoc(nextDoc);
+                const shouldWrite = docChanged || updatedBy !== undefined;
+                if (!shouldWrite)
+                    return null;
+                if (!docChanged) {
+                    return {
+                        docMeta: {
+                            touch: true,
+                            ...(updatedBy ? { updatedBy } : {}),
+                        },
+                    };
+                }
+                if (requestMode === "full-doc") {
+                    expectedCurrentDoc ??= currentDocRaw;
+                    return {
+                        doc: {
+                            kind: "replace-doc",
+                            doc: nextDoc,
+                            expectedCurrentDoc,
+                        },
+                        ...(updatedBy ? { docMeta: { updatedBy } } : {}),
+                    };
+                }
+                expectedCurrentSectionText ??= extractSectionTextForPatch(currentDocRaw, opts.section ?? "");
+                return {
+                    doc: {
+                        kind: "set-section",
+                        section: opts.section ?? "",
+                        text: extractSectionTextForPatch(nextDoc, opts.section ?? "") ?? "",
+                        requiredSections: config.tasks.doc.required_sections,
+                        expectedCurrentText: expectedCurrentSectionText,
+                    },
+                    ...(updatedBy ? { docMeta: { updatedBy } } : {}),
+                };
+            });
+            changed = result.changed;
         }
         else {
-            let nextText = text;
-            if (headingKeys.size > 0 && headingKeys.has(targetKey)) {
-                const lines = nextText.replaceAll("\r\n", "\n").split("\n");
-                let firstContent = 0;
-                while (firstContent < lines.length && lines[firstContent]?.trim() === "")
-                    firstContent++;
-                if ((lines[firstContent]?.trim() ?? "") === `## ${opts.section}`) {
-                    lines.splice(firstContent, 1);
-                    if (lines[firstContent]?.trim() === "")
-                        lines.splice(firstContent, 1);
-                    nextText = lines.join("\n");
-                }
+            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);
             }
-            const nextDoc = setMarkdownSection(baseDoc, opts.section, nextText);
-            const normalized = ensureDocSections(nextDoc, config.tasks.doc.required_sections);
-            await (useStore
-                ? store.update(opts.taskId, (current) => ({
-                    ...current,
-                    doc: normalized,
-                    ...(updatedBy ? { doc_updated_by: updatedBy } : {}),
-                }))
-                : backend.setTaskDoc(opts.taskId, normalized, updatedBy));
-        }
-        const updatedTask = useStore ? await store.get(opts.taskId) : null;
-        const updatedDocRaw = useStore
-            ? String(updatedTask?.doc ?? "")
-            : ((await backend.getTaskDoc(opts.taskId)) ?? "");
-        const updatedDoc = ensureDocSections(updatedDocRaw, config.tasks.doc.required_sections);
-        const updatedSection = readSectionContent(updatedDoc, opts.section);
-        const docChanged = normalizeOutcomeText(baseDoc) !== normalizeOutcomeText(updatedDoc);
-        const sectionChanged = baseSection !== updatedSection;
+            changed = shouldWrite;
+        }
+        const outcome = changed
+            ? requestMode === "full-doc"
+                ? "full-doc-updated"
+                : "section-updated"
+            : "no-change";
         const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
         process.stdout.write(`${path.join(tasksDir, opts.taskId, "README.md")}\n`);
-        if (!docChanged) {
-            process.stderr.write(`${warnMessage(`task doc set wrote no effective README change for section ${opts.section}`)}\n`);
-        }
-        else if (requestMode === "full-doc") {
-            process.stderr.write(`${infoMessage(`task doc set applied a full-doc update; target section ${opts.section} ${sectionChanged ? "changed" : "did not change"}`)}\n`);
-        }
-        else {
-            process.stderr.write(`${infoMessage(`task doc set updated section ${opts.section}${sectionChanged ? "" : " (effective section content unchanged)"}`)}\n`);
-        }
+        const outcomeTarget = opts.fullDoc ? "<full-doc>" : (opts.section ?? "");
+        const outcomeText = `task doc set outcome=${outcome} section=${outcomeTarget}`;
+        process.stderr.write(`${outcome === "no-change" ? warnMessage(outcomeText) : infoMessage(outcomeText)}\n`);
         return 0;
     }
     catch (err) {
@@ -170,19 +222,30 @@ export async function cmdTaskDocShow(opts) {
         const useStore = backendIsLocalFileBackend(ctx);
         const storeTask = useStore ? await getTaskStore(ctx).get(opts.taskId) : null;
         const doc = useStore
-            ? String(storeTask.doc ?? "")
+            ? storeTask?.sections && Object.keys(storeTask.sections).length > 0
+                ? renderTaskDocFromSections(storeTask.sections)
+                : String(storeTask?.doc ?? "")
             : ((await backend.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))) {
+            canonicalSections.set(normalizeDocSectionName(title), {
+                title,
+                lines: String(text ?? "").split("\n"),
+            });
+        }
         if (opts.section) {
             const sectionKey = normalizeDocSectionName(opts.section);
-            const { sections } = parseDocSections(doc);
-            const entry = sections.get(sectionKey);
+            const entry = canonicalSections.get(sectionKey);
             const content = entry?.lines ?? [];
-            if (content.length > 0) {
+            if (content.some((line) => line.trim().length > 0)) {
                 process.stdout.write(`${content.join("\n").trimEnd()}\n`);
                 return 0;
             }
             if (!opts.quiet) {
                 process.stdout.write(`${infoMessage(`section has no content: ${opts.section}`)}\n`);
+                return 0;
             }
             return 0;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAqCnC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,wBAAwB,EAAE,OAAO,CAAC;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4XlB"}
+{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgGnC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,wBAAwB,EAAE,OAAO,CAAC;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8YlB"}

package/dist/commands/task/finish.js

@@ -9,7 +9,7 @@ import { buildGitCommitEnv, cmdCommit, commitFromComment } from "../guard/index.
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+import { appendTaskCommentIntent, appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, mutateTaskStore, setTaskFieldsIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
 import { readDirectWorkLock } from "../../shared/direct-work-lock.js";
 import { appendTaskEvent, defaultCommitEmojiForStatus, enforceStatusCommitPolicy, ensureAgentFilledRequiredDocSections, ensureVerificationSatisfiedIfRequired, normalizeTaskDocVersion, nowIso, readCommitInfo, readHeadCommit, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
 async function clearDirectWorkLockIfMatches(opts) {
@@ -28,6 +28,43 @@ async function clearDirectWorkLockIfMatches(opts) {
         // best-effort
     }
 }
+function assertTaskCanFinish(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.task.id} (use --force to override)`,
+        });
+    }
+    ensureVerificationSatisfiedIfRequired(opts.task, opts.config);
+    const normalizedDoc = ensureDocSections(typeof opts.task.doc === "string" ? opts.task.doc : "", opts.config.tasks.doc.required_sections);
+    ensureAgentFilledRequiredDocSections({
+        task: opts.task,
+        config: opts.config,
+        doc: normalizedDoc,
+        action: "finish task",
+    });
+    if (!opts.isMetaTask)
+        return;
+    const tags = Array.isArray(opts.task.tags)
+        ? opts.task.tags.filter((t) => typeof t === "string")
+        : [];
+    const isSpike = tags.includes("spike");
+    if (!isSpike && opts.taskCount === 1 && !opts.resultSummary) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Missing required --result for non-spike tasks.",
+        });
+    }
+    if (opts.resultProvided && !opts.resultSummary) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Invalid value for --result: empty.",
+        });
+    }
+}
 export async function cmdFinish(opts) {
     try {
         const ctx = opts.ctx ??
@@ -123,6 +160,7 @@ export async function cmdFinish(opts) {
         const shouldCloseCommit = opts.closeCommit === true || (defaultDirectCloseCommit && opts.noCloseCommit !== true);
         const metaTaskId = opts.taskIds.length === 1 ? (opts.taskIds[0] ?? "") : "";
         const wantMeta = typeof opts.result === "string" || typeof opts.risk === "string" || opts.breaking === true;
+        const resultProvided = typeof opts.result === "string";
         if (wantMeta && opts.taskIds.length !== 1) {
             throw new CliError({
                 exitCode: 2,
@@ -137,78 +175,88 @@ export async function cmdFinish(opts) {
         let primaryTag = null;
         for (const taskId of opts.taskIds) {
             const task = useStore ? await store.get(taskId) : await loadTaskFromContext({ ctx, taskId });
-            if (!opts.force) {
-                const currentStatus = String(task.status || "TODO").toUpperCase();
-                if (currentStatus === "DONE") {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: `Task is already DONE: ${task.id} (use --force to override)`,
-                    });
+            if (!useStore) {
+                assertTaskCanFinish({
+                    task,
+                    config: ctx.config,
+                    taskCount: opts.taskIds.length,
+                    isMetaTask: taskId === metaTaskId,
+                    resultProvided,
+                    resultSummary,
+                    force: opts.force,
+                });
+                if (taskId === primaryTaskId && (opts.commitFromComment || statusCommitRequested)) {
+                    primaryStatusFrom = String(task.status || "TODO").toUpperCase();
+                    primaryTag = resolvePrimaryTag(toStringArray(task.tags), ctx).primary;
                 }
             }
-            if (taskId === primaryTaskId &&
-                (opts.commitFromComment || statusCommitRequested) &&
-                primaryStatusFrom === null) {
-                primaryStatusFrom = String(task.status || "TODO").toUpperCase();
-                primaryTag = resolvePrimaryTag(toStringArray(task.tags), ctx).primary;
+            const at = nowIso();
+            if (useStore) {
+                await mutateTaskStore(store, taskId, (current) => {
+                    assertTaskCanFinish({
+                        task: current,
+                        config: ctx.config,
+                        taskCount: opts.taskIds.length,
+                        isMetaTask: taskId === metaTaskId,
+                        resultProvided,
+                        resultSummary,
+                        force: opts.force,
+                    });
+                    const currentStatus = String(current.status || "TODO").toUpperCase();
+                    if (taskId === primaryTaskId && (opts.commitFromComment || statusCommitRequested)) {
+                        primaryStatusFrom = currentStatus;
+                        primaryTag = resolvePrimaryTag(toStringArray(current.tags), ctx).primary;
+                    }
+                    return [
+                        setTaskFieldsIntent({
+                            status: "DONE",
+                            commit: { hash: commitInfo.hash, message: commitInfo.message },
+                            ...(taskId === metaTaskId && resultSummary ? { result_summary: resultSummary } : {}),
+                            ...(taskId === metaTaskId && riskLevel ? { risk_level: riskLevel } : {}),
+                            ...(taskId === metaTaskId && breaking ? { breaking: true } : {}),
+                        }),
+                        appendTaskCommentIntent({ author: opts.author, body: opts.body }),
+                        appendTaskEventIntent({
+                            type: "status",
+                            at,
+                            author: opts.author,
+                            from: currentStatus,
+                            to: "DONE",
+                            note: opts.body,
+                        }),
+                        touchTaskDocMetaIntent({
+                            updatedBy: opts.author,
+                            version: normalizeTaskDocVersion(current.doc_version),
+                        }),
+                    ];
+                });
             }
-            ensureVerificationSatisfiedIfRequired(task, ctx.config);
-            const normalizedDoc = ensureDocSections(typeof task.doc === "string" ? task.doc : "", ctx.config.tasks.doc.required_sections);
-            ensureAgentFilledRequiredDocSections({
-                task,
-                config: ctx.config,
-                doc: normalizedDoc,
-                action: "finish task",
-            });
-            if (taskId === metaTaskId) {
-                const tags = Array.isArray(task.tags)
-                    ? task.tags.filter((t) => typeof t === "string")
+            else {
+                const existingComments = Array.isArray(task.comments)
+                    ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
                     : [];
-                const isSpike = tags.includes("spike");
-                if (!isSpike && opts.taskIds.length === 1 && !resultSummary) {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: "Missing required --result for non-spike tasks.",
-                    });
-                }
-                if (typeof opts.result === "string" && !resultSummary) {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: "Invalid value for --result: empty.",
-                    });
-                }
+                const nextTask = {
+                    ...task,
+                    status: "DONE",
+                    commit: { hash: commitInfo.hash, message: commitInfo.message },
+                    comments: [...existingComments, { author: opts.author, body: opts.body }],
+                    events: appendTaskEvent(task, {
+                        type: "status",
+                        at,
+                        author: opts.author,
+                        from: String(task.status || "TODO").toUpperCase(),
+                        to: "DONE",
+                        note: opts.body,
+                    }),
+                    result_summary: taskId === metaTaskId && resultSummary ? resultSummary : task.result_summary,
+                    risk_level: taskId === metaTaskId && riskLevel ? riskLevel : task.risk_level,
+                    breaking: taskId === metaTaskId && breaking ? true : task.breaking,
+                    doc_version: normalizeTaskDocVersion(task.doc_version),
+                    doc_updated_at: at,
+                    doc_updated_by: opts.author,
+                };
+                await ctx.taskBackend.writeTask(nextTask);
             }
-            const existingComments = Array.isArray(task.comments)
-                ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
-                : [];
-            const commentsValue = [...existingComments, { author: opts.author, body: opts.body }];
-            const at = nowIso();
-            const nextTask = {
-                ...task,
-                status: "DONE",
-                commit: { hash: commitInfo.hash, message: commitInfo.message },
-                comments: commentsValue,
-                events: appendTaskEvent(task, {
-                    type: "status",
-                    at,
-                    author: opts.author,
-                    from: String(task.status || "TODO").toUpperCase(),
-                    to: "DONE",
-                    note: opts.body,
-                }),
-                result_summary: taskId === metaTaskId && resultSummary ? resultSummary : task.result_summary,
-                risk_level: taskId === metaTaskId && riskLevel ? riskLevel : task.risk_level,
-                breaking: taskId === metaTaskId && breaking ? true : task.breaking,
-                doc_version: normalizeTaskDocVersion(task.doc_version),
-                doc_updated_at: at,
-                doc_updated_by: opts.author,
-            };
-            await (useStore
-                ? store.update(taskId, () => nextTask)
-                : ctx.taskBackend.writeTask(nextTask));
         }
         if (opts.commitFromComment || statusCommitRequested) {
             enforceStatusCommitPolicy({
@@ -233,6 +281,9 @@ export async function cmdFinish(opts) {
             }
         }
         if (opts.commitFromComment) {
+            if (!opts.quiet) {
+                process.stdout.write(`${infoMessage("task marked DONE; creating commit from verification comment")}\n`);
+            }
             if (typeof opts.commitEmoji === "string" && opts.commitEmoji.trim() !== "✅") {
                 throw new CliError({
                     exitCode: 2,
@@ -263,19 +314,27 @@ export async function cmdFinish(opts) {
             // commitFromComment creates the git commit and returns the actual head hash/subject.
             // Refresh task commit metadata to this hash and amend the same commit in local mode so
             // "task done" metadata does not require a manual follow-up close commit.
-            const taskAfterCommit = useStore
-                ? await store.get(primaryTaskId)
-                : await loadTaskFromContext({ ctx, taskId: primaryTaskId });
-            const updatedAfterCommit = {
-                ...taskAfterCommit,
-                commit: { hash: committed.hash, message: committed.message },
-                doc_version: normalizeTaskDocVersion(taskAfterCommit.doc_version),
-                doc_updated_at: nowIso(),
-                doc_updated_by: opts.author,
-            };
             await (useStore
-                ? store.update(primaryTaskId, () => updatedAfterCommit)
-                : ctx.taskBackend.writeTask(updatedAfterCommit));
+                ? mutateTaskStore(store, primaryTaskId, (current) => [
+                    setTaskFieldsIntent({
+                        commit: { hash: committed.hash, message: committed.message },
+                    }),
+                    touchTaskDocMetaIntent({
+                        updatedBy: opts.author,
+                        version: normalizeTaskDocVersion(current.doc_version),
+                    }),
+                ])
+                : (async () => {
+                    const taskAfterCommit = await loadTaskFromContext({ ctx, taskId: primaryTaskId });
+                    const updatedAfterCommit = {
+                        ...taskAfterCommit,
+                        commit: { hash: committed.hash, message: committed.message },
+                        doc_version: normalizeTaskDocVersion(taskAfterCommit.doc_version),
+                        doc_updated_at: nowIso(),
+                        doc_updated_by: opts.author,
+                    };
+                    await ctx.taskBackend.writeTask(updatedAfterCommit);
+                })());
             if (backendWritesTaskReadmes) {
                 const workflowReadmeRelPath = path.join(ctx.config.paths.workflow_dir, primaryTaskId, "README.md");
                 await ctx.git.stage([workflowReadmeRelPath]);
@@ -294,6 +353,9 @@ export async function cmdFinish(opts) {
             }
         }
         if (statusCommitRequested) {
+            if (!opts.quiet) {
+                process.stdout.write(`${infoMessage("task marked DONE; creating status commit")}\n`);
+            }
             if (typeof opts.statusCommitEmoji === "string" && opts.statusCommitEmoji.trim() !== "✅") {
                 throw new CliError({
                     exitCode: 2,

package/dist/commands/task/migrate-doc.d.ts

@@ -1,3 +1,18 @@
+import { resolveProject, type AgentplaneConfig } from "@agentplaneorg/core";
+import { type CommandContext } from "../shared/task-backend.js";
+export type TaskDocMigrationResult = {
+    changed: number;
+    changedPaths: string[];
+};
+export declare function migrateTaskDocsInWorkspace(opts: {
+    cwd: string;
+    rootOverride?: string | null;
+    all: boolean;
+    taskIds: string[];
+    resolvedProject?: Awaited<ReturnType<typeof resolveProject>>;
+    config?: AgentplaneConfig;
+    ctx?: CommandContext;
+}): Promise<TaskDocMigrationResult>;
 export declare function cmdTaskMigrateDoc(opts: {
     cwd: string;
     rootOverride?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"migrate-doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.ts"],"names":[],"mappings":"AAiSA,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDlB"}
+{"version":3,"file":"migrate-doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.ts"],"names":[],"mappings":"AAGA,OAAO,EAUL,cAAc,EAGd,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAanC,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AA+TF,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA4DlC;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBlB"}