agentplane 0.3.7 → 0.3.8

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

@@ -0,0 +1,181 @@
+import { ensureDocSections } from "@agentplaneorg/core";
+import { CliError } from "../../shared/errors.js";
+import { cmdCommit } from "../guard/index.js";
+import { loadTaskFromContext } from "../shared/task-backend.js";
+import { backendIsLocalFileBackend, getTaskStore, mutateTaskStore } from "../shared/task-store.js";
+import { ensureAgentFilledRequiredDocSections, executeTaskStatusTransitionRequest, ensureVerificationSatisfiedIfRequired, nowIso, resolvePrimaryTag, toStringArray, } from "./shared.js";
+export function existingCommitInfo(task) {
+    const hash = typeof task.commit?.hash === "string" ? task.commit.hash.trim() : "";
+    if (!hash)
+        return null;
+    const message = typeof task.commit?.message === "string" ? task.commit.message.trim() : "";
+    return { hash, message };
+}
+export 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 loadTaskForFinish(opts) {
+    if (opts.useStore) {
+        let captured = null;
+        let primaryStatusFrom = null;
+        let primaryTag = null;
+        await mutateTaskStore(opts.store, opts.taskId, (currentTask) => {
+            assertTaskCanFinish({
+                task: currentTask,
+                config: opts.ctx.config,
+                taskCount: opts.taskCount,
+                isMetaTask: opts.taskId === opts.metaTaskId,
+                resultProvided: opts.resultProvided,
+                resultSummary: opts.resultSummary,
+                force: opts.force,
+            });
+            captured = currentTask;
+            if (opts.capturePrimaryLifecycleMeta) {
+                primaryStatusFrom = String(currentTask.status || "TODO").toUpperCase();
+                primaryTag = resolvePrimaryTag(toStringArray(currentTask.tags), opts.ctx).primary;
+            }
+            return [];
+        });
+        if (!captured) {
+            throw new CliError({
+                exitCode: 4,
+                code: "E_IO",
+                message: `Task not found: ${opts.taskId}`,
+            });
+        }
+        return {
+            loaded: { taskId: opts.taskId, task: captured },
+            primaryStatusFrom,
+            primaryTag,
+        };
+    }
+    const task = await loadTaskFromContext({ ctx: opts.ctx, taskId: opts.taskId });
+    assertTaskCanFinish({
+        task,
+        config: opts.ctx.config,
+        taskCount: opts.taskCount,
+        isMetaTask: opts.taskId === opts.metaTaskId,
+        resultProvided: opts.resultProvided,
+        resultSummary: opts.resultSummary,
+        force: opts.force,
+    });
+    return {
+        loaded: { taskId: opts.taskId, task },
+        primaryStatusFrom: opts.capturePrimaryLifecycleMeta
+            ? String(task.status || "TODO").toUpperCase()
+            : null,
+        primaryTag: opts.capturePrimaryLifecycleMeta
+            ? resolvePrimaryTag(toStringArray(task.tags), opts.ctx).primary
+            : null,
+    };
+}
+export async function writeFinishedTasks(opts) {
+    const useStore = backendIsLocalFileBackend(opts.ctx);
+    const store = useStore ? getTaskStore(opts.ctx) : null;
+    const taskCount = opts.loadedTasks.length;
+    for (const { taskId, task } of opts.loadedTasks) {
+        const at = nowIso();
+        const applyTransition = async (currentTask) => {
+            assertTaskCanFinish({
+                task: currentTask,
+                config: opts.ctx.config,
+                taskCount,
+                isMetaTask: taskId === opts.metaTaskId,
+                resultProvided: opts.resultProvided,
+                resultSummary: opts.resultSummary,
+                force: opts.force,
+            });
+            return await executeTaskStatusTransitionRequest({
+                task: currentTask,
+                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 },
+                commit: opts.taskCommitInfo
+                    ? { hash: opts.taskCommitInfo.hash, message: opts.taskCommitInfo.message }
+                    : undefined,
+                extraFields: {
+                    ...(taskId === opts.metaTaskId && opts.resultSummary
+                        ? { result_summary: opts.resultSummary }
+                        : {}),
+                    ...(taskId === opts.metaTaskId && opts.riskLevel ? { risk_level: opts.riskLevel } : {}),
+                    ...(taskId === opts.metaTaskId && opts.breaking ? { breaking: true } : {}),
+                },
+                force: true,
+                dependencyPolicy: { kind: "none" },
+            });
+        };
+        if (useStore) {
+            await mutateTaskStore(store, taskId, async (currentTask) => {
+                const execution = await applyTransition(currentTask);
+                return execution.intents;
+            });
+        }
+        else {
+            const execution = await applyTransition(task);
+            await opts.ctx.taskBackend.writeTask(execution.nextTask);
+        }
+    }
+}
+export async function createTaskCloseCommit(opts) {
+    await cmdCommit({
+        ctx: opts.ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        baseBranchOverride: opts.baseBranchOverride ?? null,
+        taskId: opts.taskId,
+        message: "",
+        close: true,
+        allow: [],
+        autoAllow: false,
+        allowTasks: true,
+        allowBase: opts.ctx.config.workflow_mode === "branch_pr",
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        requireClean: true,
+        quiet: opts.quiet,
+        closeUnstageOthers: opts.closeUnstageOthers === true,
+        closeCheckOnly: false,
+        closeStageTaskArtifacts: opts.ctx.config.workflow_mode === "branch_pr",
+    });
+}

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

@@ -27,6 +27,7 @@ export declare function cmdFinish(opts: {
     closeCommit?: boolean;
     noCloseCommit?: boolean;
     closeUnstageOthers?: boolean;
+    baseBranchOverride?: string;
     quiet: boolean;
 }): Promise<number>;
 //# sourceMappingURL=finish.d.ts.map

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;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"}
+{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAqCpF,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,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4SlB"}

package/dist/commands/task/finish.js

@@ -1,17 +1,14 @@
-import { ensureDocSections } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { infoMessage, invalidValueMessage, successMessage } from "../../cli/output.js";
-import { formatCommentBodyForCommit } from "../../shared/comment-format.js";
 import { CliError } from "../../shared/errors.js";
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
-import { buildGitCommitEnv, cmdCommit, commitFromComment } from "../guard/index.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.js";
-import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.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";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+import { createTaskCloseCommit, existingCommitInfo, loadTaskForFinish, writeFinishedTasks, } from "./finish-shared.js";
+import { defaultCommitEmojiForStatus, enforceStatusCommitPolicy, prepareTaskTransitionComment, readCommitInfo, requireStructuredComment, runTaskTransitionCommentCommit, } from "./shared.js";
 async function clearDirectWorkLockIfMatches(opts) {
     const lockPath = path.join(opts.agentplaneDir, "cache", "direct-work.json");
     try {
@@ -28,43 +25,6 @@ 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 ??
@@ -88,6 +48,13 @@ export async function cmdFinish(opts) {
                 message: "--commit-from-comment/--status-commit requires exactly one task id",
             });
         }
+        if (opts.commitFromComment && statusCommitRequested) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "--commit-from-comment cannot be combined with --status-commit in finish; use one deterministic commit path.",
+            });
+        }
         if ((opts.closeCommit || opts.noCloseCommit) && opts.taskIds.length !== 1) {
             throw new CliError({
                 exitCode: 2,
@@ -145,10 +112,6 @@ export async function cmdFinish(opts) {
                 message: "--status-commit requires --status-commit-allow <path-prefix>",
             });
         }
-        const gitRoot = ctx.resolvedProject.gitRoot;
-        const commitInfo = opts.commit
-            ? await readCommitInfo(gitRoot, opts.commit)
-            : await readHeadCommit(gitRoot);
         const useStore = backendIsLocalFileBackend(ctx);
         const store = useStore ? getTaskStore(ctx) : null;
         const backendWritesTaskReadmes = ctx.taskBackend.capabilities.writes_task_readmes === true;
@@ -157,7 +120,12 @@ export async function cmdFinish(opts) {
             opts.taskIds.length === 1 &&
             !opts.commitFromComment &&
             !statusCommitRequested;
-        const shouldCloseCommit = opts.closeCommit === true || (defaultDirectCloseCommit && opts.noCloseCommit !== true);
+        const statusPathRequiresTrackedTaskCommit = backendWritesTaskReadmes &&
+            opts.taskIds.length === 1 &&
+            (opts.commitFromComment || statusCommitRequested);
+        const shouldCloseCommit = opts.closeCommit === true ||
+            statusPathRequiresTrackedTaskCommit ||
+            (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";
@@ -173,91 +141,36 @@ export async function cmdFinish(opts) {
         const breaking = opts.breaking === true;
         let primaryStatusFrom = null;
         let primaryTag = null;
+        const loadedTasks = [];
         for (const taskId of opts.taskIds) {
-            const task = useStore ? await store.get(taskId) : await loadTaskFromContext({ ctx, taskId });
-            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;
-                }
-            }
-            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),
-                        }),
-                    ];
-                });
-            }
-            else {
-                const existingComments = Array.isArray(task.comments)
-                    ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
-                    : [];
-                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 loaded = await loadTaskForFinish({
+                ctx,
+                store,
+                useStore,
+                taskId,
+                taskCount: opts.taskIds.length,
+                metaTaskId,
+                resultProvided,
+                resultSummary,
+                force: opts.force,
+                capturePrimaryLifecycleMeta: taskId === primaryTaskId,
+            });
+            loadedTasks.push(loaded.loaded);
+            if (taskId === primaryTaskId) {
+                primaryStatusFrom = loaded.primaryStatusFrom;
+                primaryTag = loaded.primaryTag;
             }
         }
+        const tasksMissingCommit = loadedTasks
+            .filter(({ task }) => !existingCommitInfo(task))
+            .map(({ taskId }) => taskId);
+        if (!opts.commitFromComment && !opts.commit && tasksMissingCommit.length > 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "finish requires --commit <hash> or existing task commit metadata on every task; implicit HEAD fallback was removed.",
+            });
+        }
         if (opts.commitFromComment || statusCommitRequested) {
             enforceStatusCommitPolicy({
                 policy: ctx.config.status_commit_policy,
@@ -268,22 +181,18 @@ export async function cmdFinish(opts) {
                 statusTo: "DONE",
             });
         }
-        // tasks.json is export-only; generated via `agentplane task export`.
-        let executorAgent = null;
-        if (opts.commitFromComment || statusCommitRequested) {
-            const mode = ctx.config.workflow_mode;
-            executorAgent = opts.author;
-            if (mode === "direct") {
-                const lock = await readDirectWorkLock(ctx.resolvedProject.agentplaneDir);
-                const lockAgent = lock?.task_id === primaryTaskId ? (lock.agent?.trim() ?? "") : "";
-                if (lockAgent)
-                    executorAgent = lockAgent;
-            }
-        }
+        const gitRoot = ctx.resolvedProject.gitRoot;
+        let taskCommitInfo = opts.commit
+            ? await readCommitInfo(gitRoot, opts.commit)
+            : null;
+        const preparedComment = opts.commitFromComment || statusCommitRequested
+            ? prepareTaskTransitionComment({
+                body: opts.body,
+                enabled: true,
+                config: ctx.config,
+            })
+            : null;
         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,
@@ -291,71 +200,28 @@ export async function cmdFinish(opts) {
                     message: invalidValueMessage("--commit-emoji", opts.commitEmoji, "✅ (finish commits must use a checkmark)"),
                 });
             }
-            const committed = await commitFromComment({
+            taskCommitInfo = await runTaskTransitionCommentCommit({
                 ctx,
                 cwd: opts.cwd,
                 rootOverride: opts.rootOverride,
                 taskId: primaryTaskId,
                 primaryTag: primaryTag ?? "meta",
-                executorAgent: executorAgent ?? undefined,
                 author: opts.author,
                 statusFrom: primaryStatusFrom ?? undefined,
                 statusTo: "DONE",
                 commentBody: opts.body,
-                formattedComment: formatCommentBodyForCommit(opts.body, ctx.config),
+                formattedComment: preparedComment?.formattedComment ?? null,
                 emoji: opts.commitEmoji ?? defaultCommitEmojiForStatus("DONE"),
                 allow: opts.commitAllow,
                 autoAllow: false,
                 allowTasks: opts.commitAllowTasks,
                 requireClean: opts.commitRequireClean,
                 quiet: opts.quiet,
-                config: ctx.config,
+                progressMessage: "creating commit from verification comment",
+                resolveExecutorAgent: true,
             });
-            // 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.
-            await (useStore
-                ? 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]);
-                const env = buildGitCommitEnv({
-                    taskId: primaryTaskId,
-                    agentId: executorAgent ?? undefined,
-                    statusTo: "DONE",
-                    allowTasks: true,
-                    allowBase: false,
-                    allowPolicy: false,
-                    allowConfig: false,
-                    allowHooks: false,
-                    allowCI: false,
-                });
-                await ctx.git.commitAmendNoEdit({ env });
-            }
         }
         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,
@@ -363,50 +229,53 @@ export async function cmdFinish(opts) {
                     message: invalidValueMessage("--status-commit-emoji", opts.statusCommitEmoji, "✅ (finish commits must use a checkmark)"),
                 });
             }
-            await commitFromComment({
+            await runTaskTransitionCommentCommit({
                 ctx,
                 cwd: opts.cwd,
                 rootOverride: opts.rootOverride,
                 taskId: primaryTaskId,
                 primaryTag: primaryTag ?? "meta",
-                executorAgent: executorAgent ?? undefined,
                 author: opts.author,
                 statusFrom: primaryStatusFrom ?? undefined,
                 statusTo: "DONE",
                 commentBody: opts.body,
-                formattedComment: formatCommentBodyForCommit(opts.body, ctx.config),
+                formattedComment: preparedComment?.formattedComment ?? null,
                 emoji: opts.statusCommitEmoji ?? defaultCommitEmojiForStatus("DONE"),
                 allow: opts.statusCommitAllow,
                 autoAllow: false,
                 allowTasks: true,
                 requireClean: opts.statusCommitRequireClean,
                 quiet: opts.quiet,
-                config: ctx.config,
+                progressMessage: "creating status commit",
+                resolveExecutorAgent: true,
             });
         }
+        await writeFinishedTasks({
+            ctx,
+            loadedTasks,
+            metaTaskId,
+            author: opts.author,
+            body: opts.body,
+            force: opts.force,
+            resultProvided,
+            resultSummary,
+            riskLevel,
+            breaking,
+            taskCommitInfo,
+        });
+        // tasks.json is export-only; generated via `agentplane task export`.
         if (shouldCloseCommit && primaryTaskId) {
             if (!opts.quiet) {
                 process.stdout.write(`${infoMessage("task marked DONE; creating deterministic close commit")}\n`);
             }
-            await cmdCommit({
+            await createTaskCloseCommit({
                 ctx,
                 cwd: opts.cwd,
                 rootOverride: opts.rootOverride,
                 taskId: primaryTaskId,
-                message: "",
-                close: true,
-                allow: [],
-                autoAllow: false,
-                allowTasks: true,
-                allowBase: false,
-                allowPolicy: false,
-                allowConfig: false,
-                allowHooks: false,
-                allowCI: false,
-                requireClean: true,
+                baseBranchOverride: opts.baseBranchOverride,
                 quiet: opts.quiet,
                 closeUnstageOthers: opts.closeCommit === true && opts.closeUnstageOthers === true,
-                closeCheckOnly: false,
             });
         }
         if (ctx.config.workflow_mode === "direct") {

package/dist/commands/task/handoff-record.command.d.ts

@@ -0,0 +1,17 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+export type TaskHandoffRecordParsed = {
+    taskId: string;
+    fromRole: string;
+    toRole?: string;
+    reason: string;
+    note?: string;
+    runId?: string;
+    nextActions: string[];
+    risks: string[];
+    openQuestions: string[];
+    evidencePaths: string[];
+    json: boolean;
+};
+export declare const taskHandoffRecordSpec: CommandSpec<TaskHandoffRecordParsed>;
+export declare const runTaskHandoffRecord: (ctx: CommandCtx, parsed: TaskHandoffRecordParsed) => Promise<number>;
+//# sourceMappingURL=handoff-record.command.d.ts.map

package/dist/commands/task/handoff-record.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-record.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/handoff-record.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAQtE,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,uBAAuB,CA+FtE,CAAC;AAIF,eAAO,MAAM,oBAAoB,GAAU,KAAK,UAAU,EAAE,QAAQ,uBAAuB,oBA0C1F,CAAC"}