agentplane 0.3.6 → 0.3.7

package/dist/commands/task/comment.js

@@ -1,7 +1,7 @@
 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 { appendTaskCommentIntent, appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, touchTaskDocMetaIntent, } from "../shared/task-store.js";
 import { appendTaskEvent, normalizeTaskDocVersion, nowIso } from "./shared.js";
 export async function cmdTaskComment(opts) {
     try {
@@ -9,27 +9,22 @@ export async function cmdTaskComment(opts) {
             (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 task = useStore ? null : 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,
+            ? store.mutate(opts.taskId, (current) => [
+                appendTaskCommentIntent({ author: opts.author, body: opts.body }),
+                appendTaskEventIntent({
+                    type: "comment",
+                    at,
+                    author: opts.author,
+                    body: opts.body,
+                }),
+                touchTaskDocMetaIntent({
                     updatedBy: opts.author,
-                    version: normalizeTaskDocVersion(task.doc_version),
-                },
-            }))
+                    version: normalizeTaskDocVersion(current.doc_version),
+                }),
+            ])
             : ctx.taskBackend.writeTask({
                 ...task,
                 comments: [

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":"AAKA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAuBpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGlB"}

package/dist/commands/task/derive.js

@@ -1,8 +1,10 @@
+import { setMarkdownSection, taskDocToSectionMap } 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 { 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,6 +47,25 @@ export async function cmdTaskDerive(opts) {
         description = `${description} (derived from spike ${opts.spikeId})`;
         if (excerpt)
             description = `${description} [spike_notes: ${excerpt}]`;
+        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 at = nowIso();
         await ctx.taskBackend.writeTask({
             id: taskId,
@@ -55,9 +76,11 @@ export async function cmdTaskDerive(opts) {
             owner: opts.owner,
             tags: opts.tags,
             depends_on: [opts.spikeId],
-            verify: [],
+            verify: opts.verify,
             comments: [],
-            doc_version: 2,
+            doc,
+            sections: taskDocToSectionMap(doc),
+            doc_version: TASK_DOC_VERSION_V3,
             doc_updated_at: at,
             doc_updated_by: opts.owner,
             id_source: "generated",

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;AA6CpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgLlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDlB"}

package/dist/commands/task/doc.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureDocSections, normalizeDocSectionName, normalizeTaskDoc, parseDocSections, setMarkdownSection, } from "@agentplaneorg/core";
+import { normalizeDocSectionName, normalizeTaskDoc, parseDocSections, renderTaskDocFromSections, setMarkdownSection, taskDocToSectionMap, ensureDocSections, } from "@agentplaneorg/core";
 import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
 import { infoMessage, unknownEntityMessage, backendNotSupportedMessage, warnMessage, } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
@@ -222,19 +222,30 @@ export async function cmdTaskDocShow(opts) {
         const useStore = backendIsLocalFileBackend(ctx);
         const storeTask = useStore ? await getTaskStore(ctx).get(opts.taskId) : null;
         const doc = useStore
-            ? String(storeTask.doc ?? "")
+            ? storeTask?.sections && Object.keys(storeTask.sections).length > 0
+                ? renderTaskDocFromSections(storeTask.sections)
+                : String(storeTask?.doc ?? "")
             : ((await backend.getTaskDoc(opts.taskId)) ?? "");
+        const canonicalSections = new Map();
+        for (const [title, text] of Object.entries(useStore && storeTask?.sections && Object.keys(storeTask.sections).length > 0
+            ? storeTask.sections
+            : taskDocToSectionMap(doc))) {
+            canonicalSections.set(normalizeDocSectionName(title), {
+                title,
+                lines: String(text ?? "").split("\n"),
+            });
+        }
         if (opts.section) {
             const sectionKey = normalizeDocSectionName(opts.section);
-            const { sections } = parseDocSections(doc);
-            const entry = sections.get(sectionKey);
+            const entry = canonicalSections.get(sectionKey);
             const content = entry?.lines ?? [];
-            if (content.length > 0) {
+            if (content.some((line) => line.trim().length > 0)) {
                 process.stdout.write(`${content.join("\n").trimEnd()}\n`);
                 return 0;
             }
             if (!opts.quiet) {
                 process.stdout.write(`${infoMessage(`section has no content: ${opts.section}`)}\n`);
+                return 0;
             }
             return 0;
         }

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

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

package/dist/commands/task/finish.js

@@ -9,7 +9,7 @@ import { buildGitCommitEnv, cmdCommit, commitFromComment } from "../guard/index.
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+import { appendTaskCommentIntent, appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, mutateTaskStore, setTaskFieldsIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
 import { readDirectWorkLock } from "../../shared/direct-work-lock.js";
 import { appendTaskEvent, defaultCommitEmojiForStatus, enforceStatusCommitPolicy, ensureAgentFilledRequiredDocSections, ensureVerificationSatisfiedIfRequired, normalizeTaskDocVersion, nowIso, readCommitInfo, readHeadCommit, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
 async function clearDirectWorkLockIfMatches(opts) {
@@ -175,24 +175,24 @@ export async function cmdFinish(opts) {
         let primaryTag = null;
         for (const taskId of opts.taskIds) {
             const task = useStore ? await store.get(taskId) : await loadTaskFromContext({ ctx, taskId });
-            assertTaskCanFinish({
-                task,
-                config: ctx.config,
-                taskCount: opts.taskIds.length,
-                isMetaTask: taskId === metaTaskId,
-                resultProvided,
-                resultSummary,
-                force: opts.force,
-            });
-            if (taskId === primaryTaskId &&
-                (opts.commitFromComment || statusCommitRequested) &&
-                primaryStatusFrom === null) {
-                primaryStatusFrom = String(task.status || "TODO").toUpperCase();
-                primaryTag = resolvePrimaryTag(toStringArray(task.tags), ctx).primary;
+            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 store.patch(taskId, (current) => {
+                await mutateTaskStore(store, taskId, (current) => {
                     assertTaskCanFinish({
                         task: current,
                         config: ctx.config,
@@ -203,31 +203,32 @@ export async function cmdFinish(opts) {
                         force: opts.force,
                     });
                     const currentStatus = String(current.status || "TODO").toUpperCase();
-                    return {
-                        task: {
+                    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 } : {}),
-                        },
-                        appendComments: [{ author: opts.author, body: opts.body }],
-                        appendEvents: [
-                            {
-                                type: "status",
-                                at,
-                                author: opts.author,
-                                from: currentStatus,
-                                to: "DONE",
-                                note: opts.body,
-                            },
-                        ],
-                        docMeta: {
-                            touch: 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 {
@@ -314,16 +315,15 @@ export async function cmdFinish(opts) {
             // 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
-                ? store.patch(primaryTaskId, (current) => ({
-                    task: {
+                ? mutateTaskStore(store, primaryTaskId, (current) => [
+                    setTaskFieldsIntent({
                         commit: { hash: committed.hash, message: committed.message },
-                    },
-                    docMeta: {
-                        touch: true,
+                    }),
+                    touchTaskDocMetaIntent({
                         updatedBy: opts.author,
                         version: normalizeTaskDocVersion(current.doc_version),
-                    },
-                }))
+                    }),
+                ])
                 : (async () => {
                     const taskAfterCommit = await loadTaskFromContext({ ctx, taskId: primaryTaskId });
                     const updatedAfterCommit = {

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

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

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

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

package/dist/commands/task/migrate-doc.js

@@ -1,12 +1,13 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskReadme, resolveProject, setMarkdownSection, } from "@agentplaneorg/core";
+import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskDocFromSections, renderTaskReadme, resolveProject, setMarkdownSection, taskDocToSectionMap, } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { fileExists, getPathKind } from "../../cli/fs-utils.js";
 import { successMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
-import { exportTaskProjectionSnapshot, loadCommandContext } from "../shared/task-backend.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { exportTaskProjectionSnapshot, loadCommandContext, } from "../shared/task-backend.js";
 import { extractDocSection, extractTaskObservationSection, decodeEscapedTaskTextNewlines, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
 import { defaultTaskDocV3 } from "./doc-template.js";
 const V3_CANONICAL_ORDER = [
@@ -22,6 +23,21 @@ const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "fin
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function normalizeRevision(value) {
+    return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : null;
+}
+function normalizeCanonicalSections(value) {
+    if (!isRecord(value))
+        return null;
+    const out = {};
+    for (const [title, text] of Object.entries(value)) {
+        const normalizedTitle = title.trim();
+        if (!normalizedTitle || typeof text !== "string")
+            continue;
+        out[normalizedTitle] = text.replaceAll("\r\n", "\n").trimEnd();
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 function normalizeSectionKey(section) {
     return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
 }
@@ -177,9 +193,12 @@ async function migrateTaskReadmeDoc(opts) {
     ensurePlanApprovalFrontmatter(frontmatter);
     ensureVerificationFrontmatter(frontmatter);
     normalizeFrontmatterNoteTimestamps(frontmatter);
+    const canonicalSections = normalizeCanonicalSections(frontmatter.sections);
     const required = opts.config.tasks.doc.required_sections;
     const extracted = extractTaskDoc(parsed.body);
-    const baseDoc = extracted || parsed.body;
+    const baseDoc = canonicalSections === null
+        ? extracted || parsed.body
+        : renderTaskDocFromSections(canonicalSections);
     let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
     const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
     if (docVersion === 2) {
@@ -202,6 +221,8 @@ async function migrateTaskReadmeDoc(opts) {
         }
     }
     const nextBody = extracted ? mergeTaskDoc(parsed.body, nextDoc) : nextDoc;
+    frontmatter.sections = taskDocToSectionMap(nextDoc);
+    frontmatter.revision = normalizeRevision(frontmatter.revision) ?? 1;
     const rendered = renderTaskReadme(frontmatter, nextBody);
     const next = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
     if (next === original)
@@ -226,48 +247,118 @@ async function resolveReadmePaths(opts) {
     }
     return out;
 }
-export async function cmdTaskMigrateDoc(opts) {
-    const params = { all: opts.all, quiet: opts.quiet, taskIds: opts.taskIds };
+async function exportProjectionSnapshotIfChanged(opts) {
+    if (!(opts.ctx.taskBackend.exportProjectionSnapshot || opts.ctx.taskBackend.exportTasksJson)) {
+        return [];
+    }
+    const relOutputPath = opts.tasksPath.replaceAll("\\", "/");
+    const outputPath = path.join(opts.resolvedGitRoot, relOutputPath);
+    let before = null;
+    try {
+        before = await readFile(outputPath, "utf8");
+    }
+    catch {
+        before = null;
+    }
+    await exportTaskProjectionSnapshot({ ctx: opts.ctx, outputPath });
+    let after = null;
     try {
-        const resolved = await resolveProject({
+        after = await readFile(outputPath, "utf8");
+    }
+    catch {
+        after = null;
+    }
+    if (before === after)
+        return [];
+    return (await canStageGitPath(opts.resolvedGitRoot, relOutputPath)) ? [relOutputPath] : [];
+}
+async function canStageGitPath(gitRoot, relPath) {
+    try {
+        await execFileAsync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        return true;
+    }
+    catch {
+        // Continue below: untracked paths may still be stageable when they are not ignored.
+    }
+    try {
+        await execFileAsync("git", ["check-ignore", "--quiet", "--", relPath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+export async function migrateTaskDocsInWorkspace(opts) {
+    const resolved = opts.resolvedProject ??
+        (await resolveProject({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
-        });
-        const loaded = await loadConfig(resolved.agentplaneDir);
-        const ctx = await loadCommandContext({
+        }));
+    let config = opts.config;
+    if (!config) {
+        const loadedConfig = await loadConfig(resolved.agentplaneDir);
+        config = loadedConfig.config;
+    }
+    const ctx = opts.ctx ??
+        (await loadCommandContext({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
             resolvedProject: resolved,
-            config: loaded.config,
-        });
-        const tasksDir = path.join(resolved.gitRoot, loaded.config.paths.workflow_dir);
-        const readmePaths = await resolveReadmePaths({ tasksDir, params });
-        if (!params.all) {
-            for (const readmePath of readmePaths) {
-                if (!(await fileExists(readmePath))) {
-                    const taskId = path.basename(path.dirname(readmePath));
-                    throw new CliError({
-                        exitCode: exitCodeForError("E_IO"),
-                        code: "E_IO",
-                        message: `Task README not found: ${taskId}`,
-                    });
-                }
-            }
-        }
-        let changed = 0;
+            config,
+        }));
+    const params = { all: opts.all, quiet: false, taskIds: opts.taskIds };
+    const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
+    const readmePaths = await resolveReadmePaths({ tasksDir, params });
+    if (!opts.all) {
         for (const readmePath of readmePaths) {
-            const res = await migrateTaskReadmeDoc({ readmePath, config: loaded.config });
-            if (res.changed)
-                changed += 1;
+            if (!(await fileExists(readmePath))) {
+                const taskId = path.basename(path.dirname(readmePath));
+                throw new CliError({
+                    exitCode: exitCodeForError("E_IO"),
+                    code: "E_IO",
+                    message: `Task README not found: ${taskId}`,
+                });
+            }
         }
-        // Refresh the local export snapshot so doctor and other snapshot-based checks
-        // immediately observe the migrated README contract without a separate task export.
-        if (ctx.taskBackend.exportProjectionSnapshot || ctx.taskBackend.exportTasksJson) {
-            const outPath = path.join(resolved.gitRoot, loaded.config.paths.tasks_path);
-            await exportTaskProjectionSnapshot({ ctx, outputPath: outPath });
+    }
+    let changed = 0;
+    const changedPaths = [];
+    for (const readmePath of readmePaths) {
+        const res = await migrateTaskReadmeDoc({ readmePath, config });
+        if (!res.changed)
+            continue;
+        changed += 1;
+        const relReadmePath = path.relative(resolved.gitRoot, readmePath).replaceAll("\\", "/");
+        if (await canStageGitPath(resolved.gitRoot, relReadmePath)) {
+            changedPaths.push(relReadmePath);
         }
+    }
+    if (changed > 0) {
+        changedPaths.push(...(await exportProjectionSnapshotIfChanged({
+            ctx,
+            resolvedGitRoot: resolved.gitRoot,
+            tasksPath: config.paths.tasks_path,
+        })));
+    }
+    return { changed, changedPaths: [...new Set(changedPaths)] };
+}
+export async function cmdTaskMigrateDoc(opts) {
+    const params = { all: opts.all, quiet: opts.quiet, taskIds: opts.taskIds };
+    try {
+        const result = await migrateTaskDocsInWorkspace({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+            all: params.all,
+            taskIds: params.taskIds,
+        });
         if (!params.quiet) {
-            process.stdout.write(`${successMessage("migrated task docs", undefined, `changed=${changed}`)}\n`);
+            process.stdout.write(`${successMessage("migrated task docs", undefined, `changed=${result.changed}`)}\n`);
         }
         return 0;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAcpF,MAAM,MAAM,aAAa,GAAG;IAC1B,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,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAmDF,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,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgFlB"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAcpF,MAAM,MAAM,aAAa,GAAG;IAC1B,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,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAmDF,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,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFlB"}

package/dist/commands/task/new.js

@@ -1,4 +1,4 @@
-import { setMarkdownSection } from "@agentplaneorg/core";
+import { setMarkdownSection, taskDocToSectionMap } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { backendNotSupportedMessage, warnMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
@@ -73,6 +73,7 @@ export async function runTaskNewParsed(opts) {
             status: "TODO",
             priority: p.priority,
             owner: p.owner,
+            revision: 1,
             tags: p.tags,
             depends_on: p.dependsOn,
             verify: p.verify,
@@ -107,6 +108,7 @@ export async function runTaskNewParsed(opts) {
         if (hasSpike && hasImplementationTags) {
             process.stderr.write(`${warnMessage("spike is combined with a primary tag that requires verify steps; consider splitting spike vs implementation tasks")}\n`);
         }
+        task.sections = taskDocToSectionMap(task.doc ?? "");
         await ctx.taskBackend.writeTask(task);
         process.stdout.write(`${taskId}\n`);
         return 0;