agentplane 0.3.6 → 0.3.8

package/dist/commands/task/start.js

@@ -1,13 +1,9 @@
 import { mapBackendError } from "../../cli/error-map.js";
-import { infoMessage, successMessage, warnMessage } from "../../cli/output.js";
-import { formatCommentBodyForCommit } from "../../shared/comment-format.js";
+import { successMessage } from "../../cli/output.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, ensurePlanApprovedIfRequired, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, extractTaskObservationSection, defaultCommitEmojiForStatus, extractDocSection, isVerifyStepsFilled, normalizeTaskDocVersion, nowIso, requiresVerifyStepsByPrimary, requireStructuredComment, resolveTaskDependencyState, resolvePrimaryTag, taskObservationSectionName, toStringArray, } from "./shared.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { applyTaskStatusTransitionCommand, ensurePlanApprovedIfRequired, extractTaskObservationSection, defaultCommitEmojiForStatus, extractDocSection, isVerifyStepsFilled, normalizeTaskDocVersion, nowIso, prepareTaskTransitionComment, requiresVerifyStepsByPrimary, requireStructuredComment, runTaskTransitionCommentCommit, taskObservationSectionName, toStringArray, } from "./shared.js";
 function assertStartDocRequirements(task, config) {
     if (config.agents?.approvals?.require_plan === true)
         return;
@@ -58,136 +54,59 @@ export async function cmdStart(opts) {
         }
         const { prefix, min_chars: minChars } = ctx.config.tasks.comments.start;
         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 });
-        assertStartDocRequirements(task, ctx.config);
-        ensurePlanApprovedIfRequired(task, ctx.config);
-        const currentStatus = String(task.status || "TODO").toUpperCase();
-        ensureStatusTransitionAllowed({
-            currentStatus,
-            nextStatus: "DOING",
-            force: opts.force,
-        });
-        ensureCommentCommitAllowed({
+        const preparedComment = prepareTaskTransitionComment({
+            body: opts.body,
             enabled: opts.commitFromComment,
             config: ctx.config,
-            action: "start",
-            confirmed: opts.confirmStatusCommit,
-            quiet: opts.quiet,
-            statusFrom: currentStatus,
-            statusTo: "DOING",
         });
-        if (!opts.force) {
-            const dep = await resolveTaskDependencyState(task, ctx.taskBackend);
-            if (dep.missing.length > 0 || dep.incomplete.length > 0) {
-                if (!opts.quiet) {
-                    if (dep.missing.length > 0) {
-                        process.stderr.write(`${warnMessage(`missing deps: ${dep.missing.join(", ")}`)}\n`);
-                    }
-                    if (dep.incomplete.length > 0) {
-                        process.stderr.write(`${warnMessage(`incomplete deps: ${dep.incomplete.join(", ")}`)}\n`);
-                    }
-                }
-                throw new CliError({
-                    exitCode: 2,
-                    code: "E_USAGE",
-                    message: `Task is not ready: ${task.id} (use --force to override)`,
-                });
-            }
-        }
-        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 transition = await applyTaskStatusTransitionCommand({
+            ctx,
+            taskId: opts.taskId,
+            quiet: opts.quiet,
+            build: (current) => {
                 assertStartDocRequirements(current, ctx.config);
                 ensurePlanApprovedIfRequired(current, ctx.config);
-                const currentStatus = String(current.status || "TODO").toUpperCase();
-                ensureStatusTransitionAllowed({
-                    currentStatus,
-                    nextStatus: "DOING",
-                    force: opts.force,
-                });
                 return {
-                    task: { status: "DOING" },
-                    appendComments: [{ author: opts.author, body: commentBody }],
-                    appendEvents: [
-                        {
-                            type: "status",
-                            at,
-                            author: opts.author,
-                            from: currentStatus,
-                            to: "DOING",
-                            note: commentBody,
-                        },
-                    ],
-                    docMeta: {
-                        touch: true,
-                        updatedBy: opts.author,
-                        version: normalizeTaskDocVersion(current.doc_version),
-                    },
-                };
-            })
-            : ctx.taskBackend.writeTask({
-                ...task,
-                status: "DOING",
-                comments: commentsValue,
-                events: appendTaskEvent(task, {
-                    type: "status",
                     at,
-                    author: opts.author,
-                    from: currentStatus,
-                    to: "DOING",
+                    toStatus: "DOING",
+                    eventAuthor: opts.author,
+                    updatedBy: opts.author,
                     note: commentBody,
-                }),
-                doc_version: normalizeTaskDocVersion(task.doc_version),
-                doc_updated_at: at,
-                doc_updated_by: opts.author,
-            }));
+                    comment: { author: opts.author, body: commentBody },
+                    force: opts.force,
+                    dependencyPolicy: { kind: "require-ready" },
+                    commentCommitPolicy: {
+                        enabled: opts.commitFromComment,
+                        action: "start",
+                        confirmed: opts.confirmStatusCommit,
+                        quiet: opts.quiet,
+                    },
+                };
+            },
+        });
         let commitInfo = null;
         if (opts.commitFromComment) {
-            if (!opts.quiet) {
-                process.stdout.write(`${infoMessage("task marked DOING; creating commit from start comment")}\n`);
-            }
-            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: "DOING",
                 commentBody: opts.body,
-                formattedComment,
+                formattedComment: preparedComment.formattedComment,
                 emoji: opts.commitEmoji ?? defaultCommitEmojiForStatus("DOING"),
                 allow: opts.commitAllow,
                 autoAllow: opts.commitAutoAllow || opts.commitAllow.length === 0,
                 allowTasks: opts.commitAllowTasks,
                 requireClean: opts.commitRequireClean,
                 quiet: opts.quiet,
-                config: ctx.config,
+                progressMessage: "task marked DOING; creating commit from start comment",
+                resolveExecutorAgent: true,
             });
         }
         if (!opts.quiet) {

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

@@ -1,8 +1,7 @@
 import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
-type TaskGroupParsed = {
-    cmd: string[];
-};
+import { type GroupCommandParsed } from "../../cli/group-command.js";
+type TaskGroupParsed = GroupCommandParsed;
 export declare const taskSpec: CommandSpec<TaskGroupParsed>;
-export declare const runTask: CommandHandler<TaskGroupParsed>;
+export declare const runTask: CommandHandler<GroupCommandParsed>;
 export {};
 //# sourceMappingURL=task.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/task.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAItF,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA6BzC,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,eAAe,CA8BjD,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,eAAe,CAWnD,CAAC"}
+{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/task.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AACpC,KAAK,eAAe,GAAG,kBAAkB,CAAC;AAE1C,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,eAAe,CA8CjD,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,kBAAkB,CAOtD,CAAC"}

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

@@ -1,31 +1,4 @@
-import { usageError } from "../../cli/spec/errors.js";
-import { suggestOne } from "../../cli/spec/suggest.js";
-const TASK_SUBCOMMANDS = [
-    "add",
-    "close-duplicate",
-    "close-noop",
-    "comment",
-    "derive",
-    "doc",
-    "export",
-    "lint",
-    "list",
-    "migrate",
-    "migrate-doc",
-    "new",
-    "next",
-    "normalize",
-    "plan",
-    "rebuild-index",
-    "scrub",
-    "search",
-    "set-status",
-    "show",
-    "start-ready",
-    "update",
-    "verify",
-    "verify-show",
-];
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
 export const taskSpec = {
     id: ["task"],
     group: "Task",
@@ -54,18 +27,30 @@ export const taskSpec = {
             cmd: "agentplane task verify-show <task-id>",
             why: "Show Verify Steps before running checks.",
         },
+        {
+            cmd: "agentplane task run <task-id>",
+            why: "Run an existing task through the shared runner flow.",
+        },
+        {
+            cmd: 'agentplane task handoff record <task-id> --from CODER --reason "Paused for handoff"',
+            why: "Persist a first-class handoff snapshot.",
+        },
+        {
+            cmd: 'agentplane task hosted-close --event-json "$GITHUB_EVENT_PATH"',
+            why: "Apply deterministic task closure from a merged hosted PR event on an automation branch.",
+        },
+        {
+            cmd: "agentplane task resume-context <task-id>",
+            why: "Inspect deterministic recovery context before resuming or retrying a run.",
+        },
     ],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
-export const runTask = (_ctx, p) => {
-    const input = p.cmd.join(" ");
-    const suggestion = suggestOne(input, [...TASK_SUBCOMMANDS]);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const message = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    throw usageError({
+export const runTask = async (_ctx, p) => {
+    throwGroupCommandUsage({
         spec: taskSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["task"]),
         command: "task",
-        message: `${message}${suffix}`,
-        context: { command: "task" },
     });
 };

package/dist/commands/task/verify-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-record.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-record.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAanC,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AAqRzC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB"}
+{"version":3,"file":"verify-record.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-record.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AASpF,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AA+IzC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB"}

package/dist/commands/task/verify-record.js

@@ -1,54 +1,12 @@
-import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureDocSections, setMarkdownSection } from "@agentplaneorg/core";
 import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
 import { backendNotSupportedMessage, successMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.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 { appendTaskEvent, extractDocSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, nowIso, VERIFICATION_RESULTS_BEGIN, VERIFICATION_RESULTS_END, } from "./shared.js";
-function appendBetweenMarkers(sectionText, entryText, version) {
-    const ensured = normalizeVerificationSectionLayout(sectionText, version);
-    const beginIdx = ensured.indexOf(VERIFICATION_RESULTS_BEGIN);
-    const endIdx = ensured.indexOf(VERIFICATION_RESULTS_END);
-    if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
-        throw new Error("Verification results markers are malformed");
-    }
-    const beforeEnd = ensured.slice(0, endIdx).trimEnd();
-    const afterEnd = ensured.slice(endIdx).trimStart();
-    const entry = entryText.trimEnd();
-    const parts = [
-        beforeEnd,
-        ...(beforeEnd.endsWith(VERIFICATION_RESULTS_BEGIN) ? [] : [""]),
-        entry,
-        "",
-        afterEnd,
-    ];
-    return parts.join("\n").trimEnd();
-}
-function renderVerificationEntry(opts) {
-    const lines = [
-        `#### ${opts.at} — VERIFY — ${opts.state}`,
-        "",
-        `By: ${opts.by}`,
-        "",
-        `Note: ${opts.note}`,
-    ];
-    const verifyStepsRef = (opts.verifyStepsRef ?? "").trim();
-    if (verifyStepsRef) {
-        lines.push("", `VerifyStepsRef: ${verifyStepsRef}`);
-    }
-    const details = (opts.details ?? "").trim();
-    if (details) {
-        lines.push("", "Details:", "", details);
-    }
-    return `${lines.join("\n").trimEnd()}\n`;
-}
-function sha256Hex(text) {
-    return createHash("sha256").update(text, "utf8").digest("hex");
-}
+import { loadCommandContext } from "../shared/task-backend.js";
+import { applyTaskMutation } from "../shared/task-mutation.js";
+import { decodeEscapedTaskTextNewlines, executeTaskVerificationTransitionRequest, nowIso, } from "./shared.js";
 async function recordVerificationResult(opts) {
     const ctx = opts.ctx ??
         (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
@@ -63,115 +21,29 @@ async function recordVerificationResult(opts) {
             message: backendNotSupportedMessage("task docs"),
         });
     }
-    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();
-    if (useStore) {
-        await store.patch(opts.taskId, (current) => {
-            const existingDoc = String(current.doc ?? "");
-            const baseDoc = ensureDocSections(existingDoc, config.tasks.doc.required_sections);
-            const verificationSection = extractDocSection(baseDoc, "Verification") ?? "";
-            const verifySteps = extractDocSection(baseDoc, "Verify Steps");
-            const verifyStepsHash = verifySteps
-                ? sha256Hex(verifySteps.replaceAll("\r\n", "\n").trim())
-                : null;
-            const docVersion = normalizeTaskDocVersion(current.doc_version);
-            const verifyStepsRef = [
-                `doc_version=${String(docVersion)}`,
-                `doc_updated_at=${String(current.doc_updated_at ?? "missing")}`,
-                `excerpt_hash=sha256:${verifyStepsHash ?? "missing"}`,
-            ].join(", ");
-            const entry = renderVerificationEntry({
+    await applyTaskMutation({
+        ctx,
+        taskId: opts.taskId,
+        build: async (current) => {
+            const execution = executeTaskVerificationTransitionRequest({
+                task: current,
                 at,
-                state: opts.state,
                 by: opts.by,
                 note: opts.note,
+                state: opts.state,
                 details: opts.details ?? null,
-                verifyStepsRef,
+                doc: (typeof current.doc === "string" ? current.doc : "") ||
+                    (await backend.getTaskDoc(current.id)),
+                requiredSections: config.tasks.doc.required_sections,
             });
-            const nextVerification = appendBetweenMarkers(verificationSection, entry, docVersion);
-            return {
-                task: {
-                    status: opts.state === "needs_rework" ? "DOING" : current.status,
-                    commit: opts.state === "needs_rework" ? null : (current.commit ?? null),
-                    verification: {
-                        state: opts.state,
-                        updated_at: at,
-                        updated_by: opts.by,
-                        note: opts.note,
-                    },
-                },
-                doc: {
-                    kind: "set-section",
-                    section: "Verification",
-                    text: nextVerification,
-                    requiredSections: config.tasks.doc.required_sections,
-                },
-                appendEvents: [
-                    {
-                        type: "verify",
-                        at,
-                        author: opts.by,
-                        state: opts.state,
-                        note: opts.note,
-                    },
-                ],
-                docMeta: { updatedBy: opts.by },
-            };
-        });
-    }
-    else {
-        const existingDoc = (typeof task.doc === "string" ? task.doc : "") || (await backend.getTaskDoc(task.id));
-        const baseDoc = ensureDocSections(existingDoc ?? "", config.tasks.doc.required_sections);
-        const verificationSection = extractDocSection(baseDoc, "Verification") ?? "";
-        const verifySteps = extractDocSection(baseDoc, "Verify Steps");
-        const verifyStepsHash = verifySteps
-            ? sha256Hex(verifySteps.replaceAll("\r\n", "\n").trim())
-            : null;
-        const docVersion = normalizeTaskDocVersion(task.doc_version);
-        const verifyStepsRef = [
-            `doc_version=${String(docVersion)}`,
-            `doc_updated_at=${String(task.doc_updated_at ?? "missing")}`,
-            `excerpt_hash=sha256:${verifyStepsHash ?? "missing"}`,
-        ].join(", ");
-        const entry = renderVerificationEntry({
-            at,
-            state: opts.state,
-            by: opts.by,
-            note: opts.note,
-            details: opts.details ?? null,
-            verifyStepsRef,
-        });
-        const nextVerification = appendBetweenMarkers(verificationSection, entry, docVersion);
-        const nextDoc = ensureDocSections(setMarkdownSection(baseDoc, "Verification", nextVerification), config.tasks.doc.required_sections);
-        await backend.writeTask({
-            ...task,
-            status: opts.state === "needs_rework" ? "DOING" : task.status,
-            commit: opts.state === "needs_rework" ? null : (task.commit ?? null),
-            doc: nextDoc,
-            doc_updated_by: opts.by,
-            events: appendTaskEvent(task, {
-                type: "verify",
-                at,
-                author: opts.by,
-                state: opts.state,
-                note: opts.note,
-            }),
-            verification: {
-                state: opts.state,
-                updated_at: at,
-                updated_by: opts.by,
-                note: opts.note,
-            },
-        });
-    }
+            return { intents: execution.intents };
+        },
+    });
     if (!opts.quiet) {
-        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, task.id, "README.md");
+        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, opts.taskId, "README.md");
         const relReadmePath = path.relative(resolved.gitRoot, readmePath);
-        process.stdout.write(`${successMessage("verified", task.id, `state=${opts.state} readme=${relReadmePath}`)}\n`);
+        process.stdout.write(`${successMessage("verified", opts.taskId, `state=${opts.state} readme=${relReadmePath}`)}\n`);
     }
 }
 async function resolveVerifyRecordInput(opts) {
@@ -200,6 +72,9 @@ async function resolveVerifyRecordInput(opts) {
             throw mapCoreError(err, { command: opts.command, filePath: opts.file });
         }
     }
+    if (typeof details === "string") {
+        details = decodeEscapedTaskTextNewlines(details);
+    }
     return { by, note, details };
 }
 async function executeVerifyRecordCommand(opts) {

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

@@ -1 +1 @@
-{"version":3,"file":"verify.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAYxD,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAKpF"}
+{"version":3,"file":"verify.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAYxD,CAAC;AAEF,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM1F"}

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

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

package/dist/commands/task.test-helpers.d.ts

@@ -0,0 +1,13 @@
+import { defaultConfig, type ResolvedProject } from "@agentplaneorg/core";
+import type { TaskBackend, TaskData } from "../backends/task-backend.js";
+import type { CommandContext } from "./shared/task-backend.js";
+export declare function makeTaskFixture(overrides?: Partial<TaskData>): TaskData;
+export declare function makeTaskBackendDouble(overrides?: Partial<TaskBackend>): TaskBackend;
+export declare function makeTaskCommandContext(opts?: {
+    taskBackend?: TaskBackend;
+    overrides?: Partial<CommandContext>;
+    configureConfig?: (config: ReturnType<typeof defaultConfig>) => void;
+    git?: CommandContext["git"];
+    resolvedProject?: ResolvedProject;
+}): CommandContext;
+//# sourceMappingURL=task.test-helpers.d.ts.map

package/dist/commands/task.test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.test-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/task.test-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAGzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,wBAAgB,eAAe,CAAC,SAAS,GAAE,OAAO,CAAC,QAAQ,CAAM,GAAG,QAAQ,CAiB3E;AAED,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAuBvF;AAED,wBAAgB,sBAAsB,CACpC,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,KAAK,IAAI,CAAC;IACrE,GAAG,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;CAC9B,GACL,cAAc,CAwBhB"}

package/dist/commands/task.test-helpers.js

@@ -0,0 +1,65 @@
+import { defaultConfig } from "@agentplaneorg/core";
+import { GitContext } from "./shared/git-context.js";
+export function makeTaskFixture(overrides = {}) {
+    return {
+        id: "T-1",
+        title: "Title",
+        description: "Desc",
+        status: "TODO",
+        priority: "normal",
+        owner: "CODER",
+        depends_on: [],
+        tags: [],
+        verify: [],
+        comments: [],
+        events: [],
+        doc_version: 3,
+        doc_updated_by: "CODER",
+        ...overrides,
+    };
+}
+export function makeTaskBackendDouble(overrides = {}) {
+    return {
+        id: "mock",
+        capabilities: {
+            canonical_source: "local",
+            projection: "canonical",
+            projection_read_mode: "fallback",
+            reads_from_projection_by_default: false,
+            supports_task_revisions: true,
+            supports_revision_guarded_writes: true,
+            may_access_network_on_read: false,
+            may_access_network_on_write: false,
+            supports_projection_refresh: false,
+            supports_push_sync: false,
+            supports_snapshot_export: false,
+        },
+        listTasks: () => Promise.resolve([]),
+        getTask: () => Promise.resolve(null),
+        writeTask: () => Promise.resolve(),
+        getTaskDoc: () => Promise.resolve(""),
+        setTaskDoc: () => Promise.resolve(),
+        ...overrides,
+    };
+}
+export function makeTaskCommandContext(opts = {}) {
+    const config = defaultConfig();
+    config.paths.workflow_dir = ".agentplane/tasks";
+    opts.configureConfig?.(config);
+    const resolved = opts.resolvedProject ??
+        {
+            gitRoot: "/repo",
+            agentplaneDir: "/repo/.agentplane",
+        };
+    const backend = opts.taskBackend ?? makeTaskBackendDouble();
+    const ctx = {
+        resolvedProject: resolved,
+        config,
+        taskBackend: backend,
+        backendId: backend.id,
+        backendConfigPath: "/repo/.agentplane/backends/local/backend.json",
+        git: opts.git ?? new GitContext({ gitRoot: resolved.gitRoot }),
+        memo: {},
+    };
+    return { ...ctx, ...opts.overrides };
+}

package/dist/commands/upgrade/apply.d.ts

@@ -7,6 +7,8 @@ export declare function ensureCleanTrackedTreeForUpgrade(gitRoot: string): Promi
 export declare function createUpgradeCommit(opts: {
     gitRoot: string;
     paths: string[];
+    tasksPath: string;
+    workflowDir: string;
     versionLabel: string;
     source: "local_assets" | "upgrade_bundle" | "repo_tarball";
     additions: number;

package/dist/commands/upgrade/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/apply.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAUtD,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BrF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoEpD;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ChB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,mBAAmB,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4CnB"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/apply.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAUtD,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BrF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA8FpD;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ChB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,mBAAmB,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4CnB"}