agentplane 0.3.6 → 0.3.8

package/dist/commands/task/block.js

@@ -1,13 +1,9 @@
 import { mapBackendError } from "../../cli/error-map.js";
 import { successMessage } from "../../cli/output.js";
-import { formatCommentBodyForCommit } from "../../shared/comment-format.js";
 import { CliError } from "../../shared/errors.js";
-import { commitFromComment } from "../guard/index.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
-import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
-import { readDirectWorkLock } from "../../shared/direct-work-lock.js";
-import { appendTaskEvent, defaultCommitEmojiForStatus, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, normalizeTaskDocVersion, nowIso, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { applyTaskStatusTransitionCommand, defaultCommitEmojiForStatus, nowIso, prepareTaskTransitionComment, requireStructuredComment, runTaskTransitionCommentCommit, } from "./shared.js";
 export async function cmdBlock(opts) {
     try {
         const ctx = opts.ctx ??
@@ -22,108 +18,54 @@ export async function cmdBlock(opts) {
         }
         const { prefix, min_chars: minChars } = ctx.config.tasks.comments.blocked;
         requireStructuredComment(opts.body, prefix, minChars);
-        const useStore = backendIsLocalFileBackend(ctx);
-        const store = useStore ? getTaskStore(ctx) : null;
-        const task = useStore
-            ? await store.get(opts.taskId)
-            : await loadTaskFromContext({ ctx, taskId: opts.taskId });
-        const currentStatus = String(task.status || "TODO").toUpperCase();
-        ensureStatusTransitionAllowed({
-            currentStatus,
-            nextStatus: "BLOCKED",
-            force: opts.force,
-        });
-        ensureCommentCommitAllowed({
+        const preparedComment = prepareTaskTransitionComment({
+            body: opts.body,
             enabled: opts.commitFromComment,
             config: ctx.config,
-            action: "block",
-            confirmed: opts.confirmStatusCommit,
-            quiet: opts.quiet,
-            statusFrom: currentStatus,
-            statusTo: "BLOCKED",
         });
-        const formattedComment = opts.commitFromComment
-            ? formatCommentBodyForCommit(opts.body, ctx.config)
-            : null;
-        const commentBody = formattedComment ?? opts.body;
-        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: commentBody }];
+        const commentBody = preparedComment.commentBody ?? opts.body;
         const at = nowIso();
-        await (useStore
-            ? store.patch(opts.taskId, (current) => {
-                const currentStatus = String(current.status || "TODO").toUpperCase();
-                ensureStatusTransitionAllowed({
-                    currentStatus,
-                    nextStatus: "BLOCKED",
-                    force: opts.force,
-                });
-                return {
-                    task: { status: "BLOCKED" },
-                    appendComments: [{ author: opts.author, body: commentBody }],
-                    appendEvents: [
-                        {
-                            type: "status",
-                            at,
-                            author: opts.author,
-                            from: currentStatus,
-                            to: "BLOCKED",
-                            note: commentBody,
-                        },
-                    ],
-                    docMeta: {
-                        touch: true,
-                        updatedBy: opts.author,
-                        version: normalizeTaskDocVersion(current.doc_version),
-                    },
-                };
-            })
-            : ctx.taskBackend.writeTask({
-                ...task,
-                status: "BLOCKED",
-                comments: commentsValue,
-                events: appendTaskEvent(task, {
-                    type: "status",
-                    at,
-                    author: opts.author,
-                    from: currentStatus,
-                    to: "BLOCKED",
-                    note: commentBody,
-                }),
-                doc_version: normalizeTaskDocVersion(task.doc_version),
-                doc_updated_at: at,
-                doc_updated_by: opts.author,
-            }));
+        const transition = await applyTaskStatusTransitionCommand({
+            ctx,
+            taskId: opts.taskId,
+            quiet: opts.quiet,
+            build: () => ({
+                at,
+                toStatus: "BLOCKED",
+                eventAuthor: opts.author,
+                updatedBy: opts.author,
+                note: commentBody,
+                comment: { author: opts.author, body: commentBody },
+                force: opts.force,
+                dependencyPolicy: { kind: "none" },
+                commentCommitPolicy: {
+                    enabled: opts.commitFromComment,
+                    action: "block",
+                    confirmed: opts.confirmStatusCommit,
+                    quiet: opts.quiet,
+                },
+            }),
+        });
         let commitInfo = null;
         if (opts.commitFromComment) {
-            const mode = ctx.config.workflow_mode;
-            let executorAgent = opts.author;
-            if (mode === "direct") {
-                const lock = await readDirectWorkLock(ctx.resolvedProject.agentplaneDir);
-                const lockAgent = lock?.task_id === opts.taskId ? (lock.agent?.trim() ?? "") : "";
-                if (lockAgent)
-                    executorAgent = lockAgent;
-            }
-            commitInfo = await commitFromComment({
+            commitInfo = await runTaskTransitionCommentCommit({
                 ctx,
                 cwd: opts.cwd,
                 rootOverride: opts.rootOverride,
                 taskId: opts.taskId,
-                primaryTag: resolvePrimaryTag(toStringArray(task.tags), ctx).primary,
-                executorAgent,
+                primaryTag: transition.primaryTag,
                 author: opts.author,
-                statusFrom: currentStatus,
+                statusFrom: transition.execution.currentStatus,
                 statusTo: "BLOCKED",
                 commentBody: opts.body,
-                formattedComment,
+                formattedComment: preparedComment.formattedComment,
                 emoji: opts.commitEmoji ?? defaultCommitEmojiForStatus("BLOCKED"),
                 allow: opts.commitAllow,
                 autoAllow: opts.commitAutoAllow || opts.commitAllow.length === 0,
                 allowTasks: opts.commitAllowTasks,
                 requireClean: opts.commitRequireClean,
                 quiet: opts.quiet,
-                config: ctx.config,
+                resolveExecutorAgent: true,
             });
         }
         if (!opts.quiet) {

package/dist/commands/task/close-duplicate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-duplicate.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-duplicate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIrF,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,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2DlB"}
+{"version":3,"file":"close-duplicate.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-duplicate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGrF,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,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDlB"}

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

@@ -2,7 +2,6 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { CliError } from "../../shared/errors.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { loadTaskFromContext } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
 import { recordVerifiedNoopClosure } from "./close-shared.js";
 export async function cmdTaskCloseDuplicate(opts) {
     try {
@@ -31,11 +30,6 @@ export async function cmdTaskCloseDuplicate(opts) {
             });
         }
         const canonical = await loadTaskFromContext({ ctx: opts.ctx, taskId: duplicateOf });
-        const useStore = backendIsLocalFileBackend(opts.ctx);
-        const store = useStore ? getTaskStore(opts.ctx) : null;
-        const task = useStore
-            ? await store.get(sourceId)
-            : await loadTaskFromContext({ ctx: opts.ctx, taskId: sourceId });
         const reason = opts.note?.trim();
         const canonicalTitle = canonical.title?.trim() ? ` (${canonical.title.trim()})` : "";
         const baseBody = `Verified: ${sourceId} is a bookkeeping duplicate of ${duplicateOf}${canonicalTitle}; ` +
@@ -43,7 +37,6 @@ export async function cmdTaskCloseDuplicate(opts) {
         const body = reason ? `${baseBody}\n\nReason: ${reason}` : baseBody;
         await recordVerifiedNoopClosure({
             ctx: opts.ctx,
-            task,
             taskId: sourceId,
             author: opts.author,
             body,

package/dist/commands/task/close-noop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-noop.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-noop.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,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,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDlB"}
+{"version":3,"file":"close-noop.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-noop.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,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,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgClB"}

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

@@ -1,7 +1,6 @@
 import { mapBackendError } from "../../cli/error-map.js";
 import { CliError } from "../../shared/errors.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { recordVerifiedNoopClosure } from "./close-shared.js";
 export async function cmdTaskCloseNoop(opts) {
@@ -16,31 +15,11 @@ export async function cmdTaskCloseNoop(opts) {
                 reason: "task close-noop --force",
             });
         }
-        const useStore = backendIsLocalFileBackend(ctx);
-        const store = useStore ? getTaskStore(ctx) : null;
-        const task = useStore
-            ? await store.get(opts.taskId)
-            : await ctx.taskBackend.getTask(opts.taskId);
-        if (!task) {
-            throw new CliError({
-                exitCode: 4,
-                code: "E_IO",
-                message: `Task not found: ${opts.taskId}`,
-            });
-        }
-        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)`,
-            });
-        }
         const normalizedNote = opts.note?.trim();
         const baseBody = "Verified: no implementation changes were required; closure is recorded as no-op bookkeeping.";
         const body = normalizedNote ? `${baseBody}\n\nNote: ${normalizedNote}` : baseBody;
         await recordVerifiedNoopClosure({
             ctx,
-            task,
             taskId: opts.taskId,
             author: opts.author,
             body,

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

@@ -1,8 +1,6 @@
-import { type TaskData } from "../../backends/task-backend.js";
 import { type CommandContext } from "../shared/task-backend.js";
 export declare function recordVerifiedNoopClosure(opts: {
     ctx: CommandContext;
-    task: TaskData;
     taskId: string;
     author: string;
     body: string;

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

@@ -1 +1 @@
-{"version":3,"file":"close-shared.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE/D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAShE,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2EhB"}
+{"version":3,"file":"close-shared.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-shared.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyChB"}

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

@@ -1,75 +1,42 @@
 import { CliError } from "../../shared/errors.js";
-import { backendIsLocalFileBackend, getTaskStore } 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.patch(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 {
-                task: {
-                    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,
                 },
-                appendComments: [{ author: opts.author, body: opts.body }],
-                appendEvents: [
-                    {
-                        type: "status",
-                        at,
-                        author: opts.author,
-                        from: String(current.status || "TODO").toUpperCase(),
-                        to: "DONE",
-                        note: opts.body,
-                    },
-                ],
-                docMeta: {
-                    touch: true,
-                    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;AAInC,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,CAsDlB"}
+{"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,53 +1,59 @@
 import { mapBackendError } from "../../cli/error-map.js";
 import { successMessage } from "../../cli/output.js";
-import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } 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
-            ? await store.get(opts.taskId)
-            : await loadTaskFromContext({ ctx, taskId: opts.taskId });
         const at = nowIso();
-        await (useStore
-            ? store.patch(opts.taskId, () => ({
-                appendComments: [{ author: opts.author, body: opts.body }],
-                appendEvents: [
-                    {
-                        type: "comment",
-                        at,
-                        author: opts.author,
-                        body: opts.body,
-                    },
-                ],
-                docMeta: {
-                    touch: true,
-                    updatedBy: opts.author,
-                    version: normalizeTaskDocVersion(task.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.command.d.ts

@@ -7,6 +7,7 @@ export type TaskDeriveParsed = {
     owner: string;
     priority: "low" | "normal" | "med" | "high";
     tags: string[];
+    verify: string[];
 };
 export declare const taskDeriveSpec: CommandSpec<TaskDeriveParsed>;
 export declare function makeRunTaskDeriveHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskDeriveParsed) => Promise<number>;

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

@@ -1 +1 @@
-{"version":3,"file":"derive.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,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;CAChB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAqExD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAarE"}
+{"version":3,"file":"derive.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,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,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAiFxD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAcrE"}

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

@@ -45,13 +45,24 @@ export const taskDeriveSpec = {
             minCount: 1,
             description: "Repeatable. Adds a tag (must provide at least one).",
         },
+        {
+            kind: "string",
+            name: "verify",
+            valueHint: "<command>",
+            repeatable: true,
+            description: "Repeatable. Verification commands/checks to run for this task.",
+        },
     ],
     examples: [
         {
-            cmd: 'agentplane task derive 202602070101-ABCD --title "Implement X" --description "Do the thing" --owner CODER --tag code',
-            why: "Create an implementation task derived from a spike.",
+            cmd: 'agentplane task derive 202602070101-ABCD --title "Implement X" --description "Do the thing" --owner CODER --tag code --verify "bun test"',
+            why: "Create an implementation task derived from a spike with seeded verify steps.",
         },
     ],
+    notes: [
+        "Derived tasks default to doc_version=3 and seed the README v3 section contract automatically.",
+        "For verify-required primary tags, this command seeds a default ## Verify Steps acceptance contract in README.",
+    ],
     validateRaw: (raw) => {
         const tags = toStringList(raw.opts.tag);
         if (tags.some((t) => t.trim() === "")) {
@@ -69,6 +80,7 @@ export const taskDeriveSpec = {
         owner: raw.opts.owner,
         priority: raw.opts.priority ?? "med",
         tags: toStringList(raw.opts.tag),
+        verify: (raw.opts.verify ?? []),
     }),
 };
 export function makeRunTaskDeriveHandler(getCtx) {
@@ -83,6 +95,7 @@ export function makeRunTaskDeriveHandler(getCtx) {
             owner: p.owner,
             priority: p.priority,
             tags: p.tags,
+            verify: p.verify,
         });
     };
 }

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

@@ -9,5 +9,6 @@ export declare function cmdTaskDerive(opts: {
     owner: string;
     priority: "low" | "normal" | "med" | "high";
     tags: string[];
+    verify: string[];
 }): Promise<number>;
 //# sourceMappingURL=derive.d.ts.map

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":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAepF,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;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiElB"}
+{"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,8 +1,11 @@
+import { setMarkdownSection } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
-import { unknownEntityMessage } from "../../cli/output.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 { extractTaskObservationSection, normalizeTaskDocVersion, nowIso, toStringArray, } from "./shared.js";
+import { buildDefaultVerifyStepsSection, defaultTaskDocV3, TASK_DOC_VERSION_V3, } from "./doc-template.js";
+import { extractTaskObservationSection, normalizeTaskDocVersion, nowIso, requiresVerifyStepsByPrimary, resolvePrimaryTag, toStringArray, warnIfUnknownOwner, } from "./shared.js";
 function normalizeOneLine(text, maxChars) {
     const normalized = text.trim().replaceAll(/\s+/g, " ");
     if (normalized.length <= maxChars)
@@ -45,7 +48,32 @@ export async function cmdTaskDerive(opts) {
         description = `${description} (derived from spike ${opts.spikeId})`;
         if (excerpt)
             description = `${description} [spike_notes: ${excerpt}]`;
-        const at = nowIso();
+        let doc = defaultTaskDocV3({ title: opts.title, description });
+        const spikeTag = (ctx.config.tasks.verify.spike_tag ?? "spike").trim().toLowerCase();
+        const primary = resolvePrimaryTag(opts.tags, ctx);
+        if (primary.usedFallback) {
+            process.stderr.write(`${warnMessage(`primary tag not found in task tags; using fallback primary=${primary.primary}`)}\n`);
+        }
+        const requiresVerifySteps = requiresVerifyStepsByPrimary(opts.tags, ctx.config);
+        await warnIfUnknownOwner(ctx, opts.owner);
+        if (requiresVerifySteps) {
+            doc = setMarkdownSection(doc, "Verify Steps", buildDefaultVerifyStepsSection({
+                primary: primary.primary,
+                verifyCommands: opts.verify,
+            }));
+            process.stderr.write(`${warnMessage("task requires Verify Steps by primary tag; seeded a default ## Verify Steps section in README (review and refine before approval/start)")}\n`);
+        }
+        const hasSpike = opts.tags.some((tag) => tag.trim().toLowerCase() === spikeTag);
+        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 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,
@@ -55,11 +83,13 @@ export async function cmdTaskDerive(opts) {
             owner: opts.owner,
             tags: opts.tags,
             depends_on: [opts.spikeId],
-            verify: [],
+            verify: opts.verify,
             comments: [],
-            doc_version: 2,
-            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":"AAmBA,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,CA4ClB"}
+{"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"}