agentplane 0.3.2 → 0.3.4

package/dist/commands/runtime.command.js

@@ -0,0 +1,169 @@
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { usageError } from "../cli/spec/errors.js";
+import { suggestOne } from "../cli/spec/suggest.js";
+import { evaluateRepoCliVersionExpectation, } from "../shared/repo-cli-version.js";
+import { describeRuntimeMode, resolveRuntimeSourceInfo, } from "../shared/runtime-source.js";
+export const runtimeSpec = {
+    id: ["runtime"],
+    group: "Diagnostics",
+    summary: "Inspect which agentplane runtime/binary/package sources are active.",
+    synopsis: ["agentplane runtime <explain> [options]"],
+    args: [{ name: "cmd", required: false, variadic: true, valueHint: "<cmd>" }],
+    examples: [{ cmd: "agentplane runtime explain", why: "Show active runtime details." }],
+    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+};
+export const runtimeExplainSpec = {
+    id: ["runtime", "explain"],
+    group: "Diagnostics",
+    summary: "Explain the active binary, runtime mode, and resolved package roots.",
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable runtime details.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane runtime explain", why: "Show the active runtime as readable text." },
+        {
+            cmd: "agentplane runtime explain --json",
+            why: "Show runtime details for scripts and diagnostics tooling.",
+        },
+    ],
+    parse: (raw) => ({ json: raw.opts.json === true }),
+};
+function renderPath(value) {
+    return value ?? "unresolved";
+}
+export function buildFrameworkDevWorkflow(report) {
+    const available = report.framework.inFrameworkCheckout;
+    const reinstallScript = "scripts/reinstall-global-agentplane.sh";
+    const rebuildCommands = [
+        "bun run --filter=@agentplaneorg/core build",
+        "bun run --filter=agentplane build",
+    ];
+    const verifyCommand = "agentplane runtime explain";
+    const forceGlobalExample = "AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 agentplane <command>";
+    if (!available) {
+        return {
+            available,
+            rebuildCommands,
+            reinstallScript,
+            verifyCommand,
+            forceGlobalExample,
+            recommendation: null,
+        };
+    }
+    const recommendation = report.mode === "repo-local" || report.mode === "repo-local-handoff"
+        ? "Rebuild local packages after source changes; use the reinstall helper only when you need the global PATH command updated from this checkout."
+        : report.mode === "global-in-framework"
+            ? "Reinstall or update the global agentplane CLI from this checkout so the wrapper can hand off to the repo-local binary."
+            : report.mode === "global-forced-in-framework"
+                ? "Unset AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 unless you intentionally need the global installed CLI inside the framework checkout."
+                : "Use runtime explain after rebuild/reinstall to confirm which binary and package roots are active.";
+    return {
+        available,
+        rebuildCommands,
+        reinstallScript,
+        verifyCommand,
+        forceGlobalExample,
+        recommendation,
+    };
+}
+function buildRuntimeExplainPayload(report) {
+    return {
+        ...report,
+        frameworkDev: buildFrameworkDevWorkflow(report),
+        repoCliExpectation: {
+            expectedVersion: null,
+            activeVersion: report.agentplane.version,
+            state: "unconfigured",
+            summary: null,
+            recovery: null,
+        },
+    };
+}
+export function renderRuntimeExplainText(report, repoCliExpectation) {
+    const frameworkDev = buildFrameworkDevWorkflow(report);
+    const lines = [
+        `Mode: ${report.mode} (${describeRuntimeMode(report.mode)})`,
+        `Active binary: ${renderPath(report.activeBinaryPath)}`,
+        `Current cwd: ${report.cwd}`,
+        `Framework checkout: ${report.framework.inFrameworkCheckout ? "yes" : "no"}`,
+        `Framework repo root: ${renderPath(report.frameworkSources.repoRoot)}`,
+        `Framework agentplane root: ${renderPath(report.frameworkSources.agentplaneRoot)}`,
+        `Framework core root: ${renderPath(report.frameworkSources.coreRoot)}`,
+        `Resolved agentplane: ${report.agentplane.version ?? "unknown"} @ ${renderPath(report.agentplane.packageRoot)}`,
+        `Resolved @agentplaneorg/core: ${report.core.version ?? "unknown"} @ ${renderPath(report.core.packageRoot)}`,
+    ];
+    if (repoCliExpectation.expectedVersion) {
+        lines.push(`Repository expected agentplane CLI: ${repoCliExpectation.expectedVersion}`);
+        if (repoCliExpectation.summary) {
+            lines.push(`Repository CLI status: ${repoCliExpectation.summary}`);
+        }
+        if (repoCliExpectation.recovery) {
+            lines.push(`Recovery: ${repoCliExpectation.recovery}`);
+        }
+    }
+    if (report.handoffFromBinaryPath) {
+        lines.push(`Handoff from: ${report.handoffFromBinaryPath}`);
+    }
+    if (frameworkDev.available) {
+        lines.push("", "Framework dev workflow:", "1. Rebuild local packages after source changes:", ...frameworkDev.rebuildCommands.map((command) => `   - ${command}`), "2. If the global PATH install should resolve this checkout:", `   - ${frameworkDev.reinstallScript}`, "3. Re-verify the active runtime:", `   - ${frameworkDev.verifyCommand}`, "4. Optional: force the global installed CLI inside this checkout:", `   - ${frameworkDev.forceGlobalExample}`);
+        if (frameworkDev.recommendation) {
+            lines.push(`Recommendation: ${frameworkDev.recommendation}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function resolveRepoCliExpectation(opts) {
+    try {
+        const resolved = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const loaded = await loadConfig(resolved.agentplaneDir);
+        return evaluateRepoCliVersionExpectation(loaded.config, opts.report);
+    }
+    catch {
+        return {
+            expectedVersion: null,
+            activeVersion: opts.report.agentplane.version,
+            state: "unconfigured",
+            summary: null,
+            recovery: null,
+        };
+    }
+}
+export const runRuntime = (_ctx, p) => {
+    const input = p.cmd.join(" ");
+    const suggestion = suggestOne(input, ["explain"]);
+    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
+    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
+    return Promise.reject(usageError({
+        spec: runtimeSpec,
+        command: "runtime",
+        message: `${msg}${suffix}`,
+        context: { command: "runtime" },
+    }));
+};
+export const runRuntimeExplain = (ctx, p) => {
+    const report = resolveRuntimeSourceInfo({
+        cwd: ctx.cwd,
+        entryModuleUrl: import.meta.url,
+    });
+    return resolveRepoCliExpectation({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+        report,
+    }).then((repoCliExpectation) => {
+        const payload = { ...buildRuntimeExplainPayload(report), repoCliExpectation };
+        if (p.json) {
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            return 0;
+        }
+        process.stdout.write(`${renderRuntimeExplainText(report, repoCliExpectation)}\n`);
+        return 0;
+    });
+};

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

@@ -1 +1 @@
-{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-store.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,QAAQ,EAAoB,MAAM,gCAAgC,CAAC;AAI/F,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA0DpG,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,KAAK,CAA0C;gBAE3C,GAAG,EAAE,cAAc;IAIzB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAK9B,SAAS;IAsBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC3D,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;CAwEjD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,CAI3D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEtE"}
+{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-store.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,QAAQ,EAAoB,MAAM,gCAAgC,CAAC;AAI/F,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA8DpG,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,KAAK,CAA0C;gBAE3C,GAAG,EAAE,cAAc;IAIzB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAK9B,SAAS;IAsBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC3D,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;CA6EjD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,CAI3D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEtE"}

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

@@ -9,6 +9,9 @@ import { resolveDocUpdatedBy, taskDataToFrontmatter } from "./task-backend.js";
 function taskReadmePath(ctx, taskId) {
     return path.join(ctx.resolvedProject.gitRoot, ctx.config.paths.workflow_dir, taskId, "README.md");
 }
+function normalizeTaskDocVersion(value, fallback = 2) {
+    return value === 3 ? 3 : value === 2 ? 2 : fallback;
+}
 async function readTaskReadmeCached(opts) {
     const readmePath = taskReadmePath(opts.ctx, opts.taskId);
     let text;
@@ -89,17 +92,18 @@ export class TaskStore {
             let body = entry.parsed.body ?? "";
             const existingDoc = extractTaskDoc(body);
             const now = new Date().toISOString();
+            const currentDocVersion = normalizeTaskDocVersion(entry.parsed.frontmatter.doc_version);
+            const requestedDocVersion = normalizeTaskDocVersion(next.doc_version, currentDocVersion);
             if (next.doc !== undefined) {
                 const nextDoc = String(next.doc ?? "");
                 body = mergeTaskDoc(body, nextDoc);
                 if (docChanged(existingDoc, nextDoc) || !frontmatter.doc_updated_at) {
-                    frontmatter.doc_version = 2;
+                    frontmatter.doc_version = requestedDocVersion;
                     frontmatter.doc_updated_at = now;
                     frontmatter.doc_updated_by = resolveDocUpdatedBy(next);
                 }
             }
-            if (frontmatter.doc_version !== 2)
-                frontmatter.doc_version = 2;
+            frontmatter.doc_version = normalizeTaskDocVersion(frontmatter.doc_version, requestedDocVersion);
             if (typeof frontmatter.doc_updated_at !== "string" ||
                 frontmatter.doc_updated_at.trim() === "") {
                 frontmatter.doc_updated_at = now;

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

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../src/commands/task/add.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAoCpF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DlB"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../src/commands/task/add.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIpF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDlB"}

package/dist/commands/task/add.js

@@ -2,33 +2,7 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { dedupeStrings, normalizeTaskStatus, nowIso } from "./shared.js";
-import { ensureDocSections, setMarkdownSection } from "@agentplaneorg/core";
-function defaultTaskDoc(opts) {
-    const baseDoc = ensureDocSections("", opts.requiredSections);
-    const summary = `${opts.title}\n\n${opts.description}`;
-    const scope = [
-        `- In scope: ${opts.description}.`,
-        `- Out of scope: unrelated refactors not required for "${opts.title}".`,
-    ].join("\n");
-    const plan = [
-        `1. Implement the change for "${opts.title}".`,
-        "2. Run required checks and capture verification evidence.",
-        "3. Finalize task notes and finish with traceable commit metadata.",
-    ].join("\n");
-    const risks = [
-        "- Risk: hidden regressions in touched paths.",
-        "- Mitigation: run required checks before finish and record evidence.",
-    ].join("\n");
-    const rollback = [
-        "- Revert task-related commit(s).",
-        "- Re-run required checks to confirm rollback safety.",
-    ].join("\n");
-    const withSummary = setMarkdownSection(baseDoc, "Summary", summary);
-    const withScope = setMarkdownSection(withSummary, "Scope", scope);
-    const withPlan = setMarkdownSection(withScope, "Plan", plan);
-    const withRisks = setMarkdownSection(withPlan, "Risks", risks);
-    return setMarkdownSection(withRisks, "Rollback Plan", rollback);
-}
+import { defaultTaskDocV3, TASK_DOC_VERSION_V3 } from "./doc-template.js";
 export async function cmdTaskAdd(opts) {
     try {
         const ctx = opts.ctx ??
@@ -62,15 +36,11 @@ export async function cmdTaskAdd(opts) {
             comments: opts.commentAuthor && opts.commentBody
                 ? [{ author: opts.commentAuthor, body: opts.commentBody }]
                 : [],
-            doc_version: 2,
+            doc_version: TASK_DOC_VERSION_V3,
             doc_updated_at: nowIso(),
             doc_updated_by: docUpdatedBy,
             id_source: "explicit",
-            doc: defaultTaskDoc({
-                requiredSections: ctx.config.tasks.doc.required_sections,
-                title: opts.title,
-                description: opts.description,
-            }),
+            doc: defaultTaskDocV3({ title: opts.title, description: opts.description }),
         }));
         if (ctx.taskBackend.writeTasks) {
             await ctx.taskBackend.writeTasks(tasks);

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

@@ -1 +1 @@
-{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../src/commands/task/block.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgBnC,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,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;IACb,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,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HlB"}
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../src/commands/task/block.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAiBnC,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,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;IACb,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,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HlB"}

package/dist/commands/task/block.js

@@ -7,7 +7,7 @@ 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, defaultCommitEmojiForAgentId, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, nowIso, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
+import { appendTaskEvent, defaultCommitEmojiForAgentId, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, normalizeTaskDocVersion, nowIso, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
 export async function cmdBlock(opts) {
     try {
         const ctx = opts.ctx ??
@@ -63,7 +63,7 @@ export async function cmdBlock(opts) {
                 to: "BLOCKED",
                 note: commentBody,
             }),
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: opts.author,
         };

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":"AAIA,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,CAuFlB"}
+{"version":3,"file":"close-duplicate.d.ts","sourceRoot":"","sources":["../../../src/commands/task/close-duplicate.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AASrF,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,CAuFlB"}

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

@@ -3,7 +3,7 @@ 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 { appendTaskEvent, nowIso, requireStructuredComment } from "./shared.js";
+import { appendTaskEvent, normalizeTaskDocVersion, nowIso, requireStructuredComment, } from "./shared.js";
 export async function cmdTaskCloseDuplicate(opts) {
     try {
         const sourceId = opts.taskId.trim();
@@ -69,7 +69,7 @@ export async function cmdTaskCloseDuplicate(opts) {
             result_summary: `Closed as duplicate of ${duplicateOf}.`,
             risk_level: "low",
             breaking: false,
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: opts.author,
         };

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,CAsElB"}
+{"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;AAQpF,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,CAsElB"}

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

@@ -3,7 +3,7 @@ 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 { appendTaskEvent, nowIso, requireStructuredComment } from "./shared.js";
+import { appendTaskEvent, normalizeTaskDocVersion, nowIso, requireStructuredComment, } from "./shared.js";
 export async function cmdTaskCloseNoop(opts) {
     try {
         const ctx = opts.ctx ??
@@ -59,7 +59,7 @@ export async function cmdTaskCloseNoop(opts) {
             result_summary: "No-op closure recorded.",
             risk_level: "low",
             breaking: false,
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: opts.author,
         };

package/dist/commands/task/comment.js

@@ -2,7 +2,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 { appendTaskEvent, nowIso } from "./shared.js";
+import { appendTaskEvent, normalizeTaskDocVersion, nowIso } from "./shared.js";
 export async function cmdTaskComment(opts) {
     try {
         const ctx = opts.ctx ??
@@ -25,7 +25,7 @@ export async function cmdTaskComment(opts) {
                 author: opts.author,
                 body: opts.body,
             }),
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: opts.author,
         };

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;AAUpF,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,CAgElB"}
+{"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"}

package/dist/commands/task/derive.js

@@ -2,7 +2,7 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { unknownEntityMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
-import { extractDocSection, nowIso, toStringArray } from "./shared.js";
+import { extractTaskObservationSection, normalizeTaskDocVersion, nowIso, toStringArray, } from "./shared.js";
 function normalizeOneLine(text, maxChars) {
     const normalized = text.trim().replaceAll(/\s+/g, " ");
     if (normalized.length <= maxChars)
@@ -37,8 +37,8 @@ export async function cmdTaskDerive(opts) {
             });
         }
         const spikeDoc = typeof spike.doc === "string" ? spike.doc : "";
-        const notes = extractDocSection(spikeDoc, "Notes") ?? "";
-        const excerpt = notes.trim() ? normalizeOneLine(notes, 180) : "";
+        const observation = extractTaskObservationSection(spikeDoc, normalizeTaskDocVersion(spike.doc_version)) ?? "";
+        const excerpt = observation.trim() ? normalizeOneLine(observation, 180) : "";
         const suffixLength = ctx.config.tasks.id_suffix_length_default;
         const taskId = await ctx.taskBackend.generateTaskId({ length: suffixLength, attempts: 1000 });
         let description = opts.description.trim();

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

@@ -0,0 +1,10 @@
+export declare const TASK_DOC_VERSION_V3 = 3;
+export declare function defaultTaskDocV3(opts: {
+    title: string;
+    description: string;
+}): string;
+export declare function buildDefaultVerifyStepsSection(opts: {
+    primary: string;
+    verifyCommands: string[];
+}): string;
+//# sourceMappingURL=doc-template.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doc-template.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc-template.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAkErC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAkCrF;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,MAAM,CA2BT"}

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

@@ -0,0 +1,104 @@
+import { setMarkdownSection } from "@agentplaneorg/core";
+export const TASK_DOC_VERSION_V3 = 3;
+function normalizeTaskHumanText(text) {
+    let next = text.replaceAll("\r\n", "\n");
+    const escapedDoubleNewline = next.includes(String.raw `\n\n`) || next.includes(String.raw `\r\n\r\n`);
+    const escapedNewlineMatches = next.match(/\\n/g) ?? [];
+    if (escapedDoubleNewline || escapedNewlineMatches.length >= 2) {
+        next = next.replaceAll(String.raw `\r\n`, "\n").replaceAll(String.raw `\n`, "\n");
+    }
+    return next.trim();
+}
+function normalizeTaskHumanInlineText(text) {
+    return normalizeTaskHumanText(text)
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(" ");
+}
+function ensureTrailingSentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+function buildDefaultSummary(opts) {
+    return `${opts.title}\n\n${normalizeTaskHumanText(opts.description)}`;
+}
+function buildDefaultScope(opts) {
+    const summary = ensureTrailingSentence(normalizeTaskHumanInlineText(opts.description));
+    return [
+        `- In scope: ${summary}`,
+        `- Out of scope: unrelated refactors not required for "${opts.title}".`,
+    ].join("\n");
+}
+function buildDefaultPlan(opts) {
+    return [
+        `1. Implement the change for "${opts.title}".`,
+        "2. Run required checks and capture verification evidence.",
+        "3. Finalize task findings and finish with traceable commit metadata.",
+    ].join("\n");
+}
+function buildDefaultVerifyStepsTemplate() {
+    return [
+        "<!-- TODO: REPLACE WITH TASK-SPECIFIC ACCEPTANCE STEPS -->",
+        "",
+        "1. <Action>. Expected: <observable result>.",
+        "2. <Action>. Expected: <observable result>.",
+        "3. <Action>. Expected: <observable result>.",
+    ].join("\n");
+}
+function buildDefaultVerificationTemplate() {
+    return ["<!-- BEGIN VERIFICATION RESULTS -->", "<!-- END VERIFICATION RESULTS -->"].join("\n");
+}
+function buildDefaultRollbackPlan() {
+    return [
+        "- Revert task-related commit(s).",
+        "- Re-run required checks to confirm rollback safety.",
+    ].join("\n");
+}
+export function defaultTaskDocV3(opts) {
+    let body = [
+        "## Summary",
+        "",
+        "## Scope",
+        "",
+        "## Plan",
+        "",
+        "## Verify Steps",
+        "",
+        "## Verification",
+        "",
+        "## Rollback Plan",
+        "",
+        "## Findings",
+        "",
+    ].join("\n");
+    body = setMarkdownSection(body, "Summary", buildDefaultSummary({ title: opts.title, description: opts.description }));
+    body = setMarkdownSection(body, "Scope", buildDefaultScope({ title: opts.title, description: opts.description }));
+    body = setMarkdownSection(body, "Plan", buildDefaultPlan({ title: opts.title }));
+    body = setMarkdownSection(body, "Verify Steps", buildDefaultVerifyStepsTemplate());
+    body = setMarkdownSection(body, "Verification", buildDefaultVerificationTemplate());
+    body = setMarkdownSection(body, "Rollback Plan", buildDefaultRollbackPlan());
+    body = setMarkdownSection(body, "Findings", "");
+    return body;
+}
+export function buildDefaultVerifyStepsSection(opts) {
+    const commandSteps = opts.verifyCommands.length > 0
+        ? opts.verifyCommands.map((command, index) => `${index + 1}. Run \`${command}\`. Expected: it succeeds and confirms the requested outcome for this task.`)
+        : [];
+    const genericSteps = [
+        `Review the changed artifact or behavior for the \`${opts.primary}\` task. Expected: the requested outcome is visible and matches the approved scope.`,
+        "Compare the final result against the task summary and touched scope. Expected: remaining follow-up is either resolved or explicit in ## Findings.",
+    ];
+    if (commandSteps.length === 0) {
+        return [
+            "<!-- TODO: REPLACE WITH TASK-SPECIFIC ACCEPTANCE STEPS -->",
+            "",
+            "1. Review the changed artifact or behavior. Expected: the requested outcome is visible and matches the approved scope.",
+            "2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched scope.",
+            "3. Compare the final result against the task summary and scope. Expected: any remaining follow-up is explicit in ## Findings.",
+        ].join("\n");
+    }
+    return [
+        ...commandSteps,
+        ...genericSteps.map((step, index) => `${commandSteps.length + index + 1}. ${step}`),
+    ].join("\n");
+}

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":"AAaA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,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,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6GlB;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":"AAkBA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAmBpF,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,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2IlB;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"}

package/dist/commands/task/doc.js

@@ -2,10 +2,24 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { ensureDocSections, normalizeDocSectionName, parseDocSections, setMarkdownSection, } from "@agentplaneorg/core";
 import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
-import { infoMessage, unknownEntityMessage, backendNotSupportedMessage } from "../../cli/output.js";
+import { infoMessage, unknownEntityMessage, backendNotSupportedMessage, warnMessage, } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+function normalizeOutcomeText(value) {
+    return value
+        .replaceAll("\r\n", "\n")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .trim();
+}
+function readSectionContent(doc, section) {
+    const sectionKey = normalizeDocSectionName(section);
+    const { sections } = parseDocSections(doc);
+    const lines = sections.get(sectionKey)?.lines ?? [];
+    return normalizeOutcomeText(lines.join("\n"));
+}
 export async function cmdTaskDocSet(opts) {
     let updatedBy;
     if (opts.updatedBy !== undefined) {
@@ -76,6 +90,10 @@ export async function cmdTaskDocSet(opts) {
             ? String(storeTask.doc ?? "")
             : ((await backend.getTaskDoc(opts.taskId)) ?? "");
         const baseDoc = ensureDocSections(baseDocRaw, config.tasks.doc.required_sections);
+        const baseSection = readSectionContent(baseDoc, opts.section);
+        const requestMode = headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))
+            ? "full-doc"
+            : "section";
         if (headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))) {
             const fullDoc = ensureDocSections(text, config.tasks.doc.required_sections);
             await (useStore
@@ -110,8 +128,25 @@ export async function cmdTaskDocSet(opts) {
                 }))
                 : backend.setTaskDoc(opts.taskId, normalized, updatedBy));
         }
+        const updatedTask = useStore ? await store.get(opts.taskId) : null;
+        const updatedDocRaw = useStore
+            ? String(updatedTask?.doc ?? "")
+            : ((await backend.getTaskDoc(opts.taskId)) ?? "");
+        const updatedDoc = ensureDocSections(updatedDocRaw, config.tasks.doc.required_sections);
+        const updatedSection = readSectionContent(updatedDoc, opts.section);
+        const docChanged = normalizeOutcomeText(baseDoc) !== normalizeOutcomeText(updatedDoc);
+        const sectionChanged = baseSection !== updatedSection;
         const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
         process.stdout.write(`${path.join(tasksDir, opts.taskId, "README.md")}\n`);
+        if (!docChanged) {
+            process.stderr.write(`${warnMessage(`task doc set wrote no effective README change for section ${opts.section}`)}\n`);
+        }
+        else if (requestMode === "full-doc") {
+            process.stderr.write(`${infoMessage(`task doc set applied a full-doc update; target section ${opts.section} ${sectionChanged ? "changed" : "did not change"}`)}\n`);
+        }
+        else {
+            process.stderr.write(`${infoMessage(`task doc set updated section ${opts.section}${sectionChanged ? "" : " (effective section content unchanged)"}`)}\n`);
+        }
         return 0;
     }
     catch (err) {

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

package/dist/commands/task/finish.js

@@ -1,6 +1,6 @@
 import { ensureDocSections } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
-import { invalidValueMessage, successMessage } from "../../cli/output.js";
+import { infoMessage, invalidValueMessage, successMessage } from "../../cli/output.js";
 import { formatCommentBodyForCommit } from "../../shared/comment-format.js";
 import { CliError } from "../../shared/errors.js";
 import { readFile, rm } from "node:fs/promises";
@@ -11,7 +11,7 @@ import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.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, enforceStatusCommitPolicy, ensureAgentFilledRequiredDocSections, ensureVerificationSatisfiedIfRequired, nowIso, readCommitInfo, readHeadCommit, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
+import { appendTaskEvent, defaultCommitEmojiForStatus, enforceStatusCommitPolicy, ensureAgentFilledRequiredDocSections, ensureVerificationSatisfiedIfRequired, normalizeTaskDocVersion, nowIso, readCommitInfo, readHeadCommit, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
 async function clearDirectWorkLockIfMatches(opts) {
     const lockPath = path.join(opts.agentplaneDir, "cache", "direct-work.json");
     try {
@@ -201,7 +201,7 @@ export async function cmdFinish(opts) {
                 result_summary: taskId === metaTaskId && resultSummary ? resultSummary : task.result_summary,
                 risk_level: taskId === metaTaskId && riskLevel ? riskLevel : task.risk_level,
                 breaking: taskId === metaTaskId && breaking ? true : task.breaking,
-                doc_version: 2,
+                doc_version: normalizeTaskDocVersion(task.doc_version),
                 doc_updated_at: at,
                 doc_updated_by: opts.author,
             };
@@ -268,7 +268,7 @@ export async function cmdFinish(opts) {
             const updatedAfterCommit = {
                 ...taskAfterCommit,
                 commit: { hash: committed.hash, message: committed.message },
-                doc_version: 2,
+                doc_version: normalizeTaskDocVersion(taskAfterCommit.doc_version),
                 doc_updated_at: nowIso(),
                 doc_updated_by: opts.author,
             };
@@ -322,6 +322,9 @@ export async function cmdFinish(opts) {
             });
         }
         if (shouldCloseCommit && primaryTaskId) {
+            if (!opts.quiet) {
+                process.stdout.write(`${infoMessage("task marked DONE; creating deterministic close commit")}\n`);
+            }
             await cmdCommit({
                 ctx,
                 cwd: opts.cwd,

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

@@ -1 +1 @@
-{"version":3,"file":"migrate-doc.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAa,MAAM,wBAAwB,CAAC;AAKjF,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAUF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CA6ChE,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQjG"}
+{"version":3,"file":"migrate-doc.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAa,MAAM,wBAAwB,CAAC;AAKjF,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAUF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAiDhE,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQjG"}