agentplane 0.3.5 → 0.3.6

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

@@ -0,0 +1,14 @@
+import { type TaskData } from "../../backends/task-backend.js";
+import { type CommandContext } from "../shared/task-backend.js";
+export declare function recordVerifiedNoopClosure(opts: {
+    ctx: CommandContext;
+    task: TaskData;
+    taskId: string;
+    author: string;
+    body: string;
+    resultSummary: string;
+    quiet: boolean;
+    successMessage: string;
+    force: boolean;
+}): Promise<void>;
+//# sourceMappingURL=close-shared.d.ts.map

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

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

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

@@ -0,0 +1,76 @@
+import { CliError } from "../../shared/errors.js";
+import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+import { appendTaskEvent, normalizeTaskDocVersion, nowIso, requireStructuredComment, } from "./shared.js";
+export async function recordVerifiedNoopClosure(opts) {
+    if (!opts.force && String(opts.task.status || "TODO").toUpperCase() === "DONE") {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: `Task is already DONE: ${opts.taskId} (use --force to override)`,
+        });
+    }
+    const verifiedCfg = opts.ctx.config.tasks.comments.verified;
+    requireStructuredComment(opts.body, verifiedCfg.prefix, verifiedCfg.min_chars);
+    const at = nowIso();
+    const useStore = backendIsLocalFileBackend(opts.ctx);
+    const store = useStore ? getTaskStore(opts.ctx) : null;
+    await (useStore
+        ? store.patch(opts.taskId, (current) => {
+            if (!opts.force && String(current.status || "TODO").toUpperCase() === "DONE") {
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: `Task is already DONE: ${opts.taskId} (use --force to override)`,
+                });
+            }
+            return {
+                task: {
+                    status: "DONE",
+                    result_summary: opts.resultSummary,
+                    risk_level: "low",
+                    breaking: false,
+                },
+                appendComments: [{ author: opts.author, body: opts.body }],
+                appendEvents: [
+                    {
+                        type: "status",
+                        at,
+                        author: opts.author,
+                        from: String(current.status || "TODO").toUpperCase(),
+                        to: "DONE",
+                        note: opts.body,
+                    },
+                ],
+                docMeta: {
+                    touch: true,
+                    updatedBy: opts.author,
+                    version: normalizeTaskDocVersion(current.doc_version),
+                },
+            };
+        })
+        : opts.ctx.taskBackend.writeTask({
+            ...opts.task,
+            status: "DONE",
+            comments: [
+                ...(Array.isArray(opts.task.comments) ? opts.task.comments : []),
+                { author: opts.author, body: opts.body },
+            ],
+            events: appendTaskEvent(opts.task, {
+                type: "status",
+                at,
+                author: opts.author,
+                from: String(opts.task.status || "TODO").toUpperCase(),
+                to: "DONE",
+                note: opts.body,
+            }),
+            result_summary: opts.resultSummary,
+            risk_level: "low",
+            breaking: false,
+            doc_version: normalizeTaskDocVersion(opts.task.doc_version),
+            doc_updated_at: at,
+            doc_updated_by: opts.author,
+        }));
+    if (!opts.quiet) {
+        process.stdout.write(`${opts.successMessage}\n`);
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../../src/commands/task/comment.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAInC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAoClB"}
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../../src/commands/task/comment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAInC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAsDlB"}

package/dist/commands/task/comment.js

@@ -12,24 +12,42 @@ export async function cmdTaskComment(opts) {
         const task = useStore
             ? await store.get(opts.taskId)
             : await loadTaskFromContext({ ctx, taskId: opts.taskId });
-        const existing = Array.isArray(task.comments)
-            ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
-            : [];
         const at = nowIso();
-        const next = {
-            ...task,
-            comments: [...existing, { author: opts.author, body: opts.body }],
-            events: appendTaskEvent(task, {
-                type: "comment",
-                at,
-                author: opts.author,
-                body: opts.body,
-            }),
-            doc_version: normalizeTaskDocVersion(task.doc_version),
-            doc_updated_at: at,
-            doc_updated_by: opts.author,
-        };
-        await (useStore ? store.update(opts.taskId, () => next) : ctx.taskBackend.writeTask(next));
+        await (useStore
+            ? store.patch(opts.taskId, () => ({
+                appendComments: [{ author: opts.author, body: opts.body }],
+                appendEvents: [
+                    {
+                        type: "comment",
+                        at,
+                        author: opts.author,
+                        body: opts.body,
+                    },
+                ],
+                docMeta: {
+                    touch: true,
+                    updatedBy: opts.author,
+                    version: normalizeTaskDocVersion(task.doc_version),
+                },
+            }))
+            : ctx.taskBackend.writeTask({
+                ...task,
+                comments: [
+                    ...(Array.isArray(task.comments)
+                        ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
+                        : []),
+                    { author: opts.author, body: opts.body },
+                ],
+                events: appendTaskEvent(task, {
+                    type: "comment",
+                    at,
+                    author: opts.author,
+                    body: opts.body,
+                }),
+                doc_version: normalizeTaskDocVersion(task.doc_version),
+                doc_updated_at: at,
+                doc_updated_by: opts.author,
+            }));
         process.stdout.write(`${successMessage("commented", opts.taskId)}\n`);
         return 0;
     }

package/dist/commands/task/doc-set.command.d.ts

@@ -2,10 +2,11 @@ import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
 import type { CommandContext } from "../shared/task-backend.js";
 export type TaskDocSetParsed = {
     taskId: string;
-    section: string;
+    section?: string;
     text?: string;
     file?: string;
     updatedBy?: string;
+    fullDoc: boolean;
 };
 export declare const taskDocSetSpec: CommandSpec<TaskDocSetParsed>;
 export declare function makeRunTaskDocSetHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskDocSetParsed) => Promise<number>;

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

@@ -1 +1 @@
-{"version":3,"file":"doc-set.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc-set.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,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,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAiExD,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,CAYrE"}
+{"version":3,"file":"doc-set.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc-set.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,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,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAiGxD,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"}

package/dist/commands/task/doc-set.command.js

@@ -4,20 +4,29 @@ export const taskDocSetSpec = {
     id: ["task", "doc", "set"],
     group: "Task",
     summary: "Update a task README section.",
+    synopsis: [
+        "agentplane task doc set <task-id> --section <name> (--text <text> | --file <path>) [--updated-by <id>]",
+        "agentplane task doc set <task-id> --full-doc (--text <text> | --file <path>) [--updated-by <id>]",
+    ],
     args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
     options: [
         {
             kind: "string",
             name: "section",
             valueHint: "<name>",
-            required: true,
-            description: "Target section heading (must be one of config.tasks.doc.sections).",
+            description: "Target section heading (must be one of config.tasks.doc.sections). Required unless --full-doc is set.",
+        },
+        {
+            kind: "boolean",
+            name: "full-doc",
+            default: false,
+            description: "Treat the provided text/file as the full task README payload.",
         },
         {
             kind: "string",
             name: "text",
             valueHint: "<text>",
-            description: "Section content (mutually exclusive with --file).",
+            description: String.raw `Section content (mutually exclusive with --file). Literal escaped newlines (\n) are normalized for inline text.`,
         },
         {
             kind: "string",
@@ -41,8 +50,29 @@ export const taskDocSetSpec = {
             cmd: "agentplane task doc set 202602030608-F1Q8AB --section Plan --file ./plan.md",
             why: "Update one section using a file.",
         },
+        {
+            cmd: "agentplane task doc set 202602030608-F1Q8AB --full-doc --file ./task-readme.md",
+            why: "Replace the full task README payload explicitly.",
+        },
     ],
     validateRaw: (raw) => {
+        const fullDoc = raw.opts["full-doc"] === true;
+        const section = typeof raw.opts.section === "string" ? raw.opts.section.trim() : "";
+        if (fullDoc && section) {
+            throw usageError({
+                spec: taskDocSetSpec,
+                message: "Use either --section or --full-doc (not both).",
+            });
+        }
+        if (!fullDoc && !section) {
+            throw usageError({
+                spec: taskDocSetSpec,
+                message: "Missing required option: --section (or pass --full-doc).",
+            });
+        }
+        if (typeof raw.opts.section === "string" && section === "") {
+            throw usageError({ spec: taskDocSetSpec, message: "Invalid value for --section: empty." });
+        }
         const hasText = typeof raw.opts.text === "string";
         const hasFile = typeof raw.opts.file === "string";
         if (hasText === hasFile) {
@@ -59,10 +89,11 @@ export const taskDocSetSpec = {
     parse: (raw) => {
         return {
             taskId: String(raw.args["task-id"]),
-            section: String(raw.opts.section),
+            section: typeof raw.opts.section === "string" ? raw.opts.section : undefined,
             text: typeof raw.opts.text === "string" ? raw.opts.text : undefined,
             file: typeof raw.opts.file === "string" ? raw.opts.file : undefined,
             updatedBy: typeof raw.opts["updated-by"] === "string" ? raw.opts["updated-by"] : undefined,
+            fullDoc: raw.opts["full-doc"] === true,
         };
     },
 };
@@ -77,6 +108,7 @@ export function makeRunTaskDocSetHandler(getCtx) {
             text: p.text,
             file: p.file,
             updatedBy: p.updatedBy,
+            fullDoc: p.fullDoc,
         });
     };
 }

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

@@ -1 +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"}
+{"version":3,"file":"doc-template.d.ts","sourceRoot":"","sources":["../../../src/commands/task/doc-template.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB,IAAI,CAAC;AA2DrC,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

@@ -1,13 +1,8 @@
 import { setMarkdownSection } from "@agentplaneorg/core";
+import { decodeEscapedTaskTextNewlines } from "./shared/docs.js";
 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();
+    return decodeEscapedTaskTextNewlines(text).trim();
 }
 function normalizeTaskHumanInlineText(text) {
     return normalizeTaskHumanText(text)

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

@@ -6,7 +6,7 @@ export const taskDocSpec = {
     synopsis: [
         "agentplane task doc show <task-id> [--section <name>] [--quiet]",
         "agentplane task doc set <task-id> --section <name> (--text <text> | --file <path>) [--updated-by <id>]",
-        "agentplane task doc set <task-id> --section Summary --file ./task-readme.md  # if payload contains multiple known ## headings, apply as full-doc update",
+        "agentplane task doc set <task-id> --full-doc (--text <text> | --file <path>) [--updated-by <id>]",
     ],
     args: [{ name: "subcommand", required: false, valueHint: "<show|set>" }],
     parse: (raw) => {

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

@@ -4,10 +4,11 @@ export declare function cmdTaskDocSet(opts: {
     cwd: string;
     rootOverride?: string;
     taskId: string;
-    section: string;
+    section?: string;
     text?: string;
     file?: string;
     updatedBy?: string;
+    fullDoc: boolean;
 }): Promise<number>;
 export declare function cmdTaskDocShow(opts: {
     ctx?: CommandContext;

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":"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"}
+{"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"}

package/dist/commands/task/doc.js

@@ -1,24 +1,36 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureDocSections, normalizeDocSectionName, parseDocSections, setMarkdownSection, } from "@agentplaneorg/core";
+import { ensureDocSections, normalizeDocSectionName, normalizeTaskDoc, parseDocSections, setMarkdownSection, } 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";
 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);
+import { decodeEscapedTaskTextNewlines } from "./shared.js";
+function extractSectionTextForPatch(doc, section) {
     const { sections } = parseDocSections(doc);
-    const lines = sections.get(sectionKey)?.lines ?? [];
-    return normalizeOutcomeText(lines.join("\n"));
+    const entry = sections.get(normalizeDocSectionName(section));
+    return entry ? entry.lines.join("\n").trimEnd() : null;
+}
+function buildUpdatedTaskDoc(opts) {
+    const baseDoc = ensureDocSections(opts.baseDocRaw, opts.requiredSections);
+    if (opts.requestMode === "full-doc") {
+        return ensureDocSections(opts.text, opts.requiredSections);
+    }
+    let nextText = opts.text;
+    if (opts.headingKeys.size > 0 && opts.headingKeys.has(opts.targetKey)) {
+        const lines = nextText.replaceAll("\r\n", "\n").split("\n");
+        let firstContent = 0;
+        while (firstContent < lines.length && lines[firstContent]?.trim() === "")
+            firstContent++;
+        if ((lines[firstContent]?.trim() ?? "") === `## ${opts.section}`) {
+            lines.splice(firstContent, 1);
+            if (lines[firstContent]?.trim() === "")
+                lines.splice(firstContent, 1);
+            nextText = lines.join("\n");
+        }
+    }
+    return ensureDocSections(setMarkdownSection(baseDoc, opts.section ?? "", nextText), opts.requiredSections);
 }
 export async function cmdTaskDocSet(opts) {
     let updatedBy;
@@ -43,6 +55,9 @@ export async function cmdTaskDocSet(opts) {
         });
     }
     let text = opts.text ?? "";
+    if (hasText) {
+        text = decodeEscapedTaskTextNewlines(text);
+    }
     if (hasFile) {
         try {
             text = await readFile(path.resolve(opts.cwd, opts.file ?? ""), "utf8");
@@ -67,15 +82,29 @@ export async function cmdTaskDocSet(opts) {
         const useStore = backendIsLocalFileBackend(ctx);
         const store = useStore ? getTaskStore(ctx) : null;
         const allowed = config.tasks.doc.sections;
-        if (!allowed.includes(opts.section)) {
+        if (!opts.fullDoc && !opts.section) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Missing required option: --section (or pass --full-doc)",
+            });
+        }
+        if (opts.fullDoc && opts.section) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Use either --section or --full-doc (not both)",
+            });
+        }
+        if (!opts.fullDoc && !allowed.includes(opts.section ?? "")) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: unknownEntityMessage("doc section", opts.section),
+                message: unknownEntityMessage("doc section", opts.section ?? ""),
             });
         }
         const normalizedAllowed = new Set(allowed.map((section) => normalizeDocSectionName(section)));
-        const targetKey = normalizeDocSectionName(opts.section);
+        const targetKey = normalizeDocSectionName(opts.section ?? "");
         const headingKeys = new Set();
         for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
             const match = /^##\s+(.*)$/.exec(line.trim());
@@ -85,68 +114,91 @@ export async function cmdTaskDocSet(opts) {
             if (key && normalizedAllowed.has(key))
                 headingKeys.add(key);
         }
-        const storeTask = useStore ? await store.get(opts.taskId) : null;
-        const baseDocRaw = useStore
-            ? 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))
+        const requestMode = opts.fullDoc
             ? "full-doc"
-            : "section";
-        if (headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))) {
-            const fullDoc = ensureDocSections(text, config.tasks.doc.required_sections);
-            await (useStore
-                ? store.update(opts.taskId, (current) => ({
-                    ...current,
-                    doc: fullDoc,
-                    ...(updatedBy ? { doc_updated_by: updatedBy } : {}),
-                }))
-                : backend.setTaskDoc(opts.taskId, fullDoc, updatedBy));
+            : headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))
+                ? "full-doc"
+                : "section";
+        let changed = false;
+        if (useStore) {
+            let expectedCurrentDoc;
+            let expectedCurrentSectionText;
+            const result = await store.patch(opts.taskId, (current) => {
+                const currentDocRaw = String(current.doc ?? "");
+                const nextDoc = buildUpdatedTaskDoc({
+                    baseDocRaw: currentDocRaw,
+                    section: opts.section,
+                    text,
+                    requestMode,
+                    requiredSections: config.tasks.doc.required_sections,
+                    headingKeys,
+                    targetKey,
+                });
+                const docChanged = normalizeTaskDoc(currentDocRaw) !== normalizeTaskDoc(nextDoc);
+                const shouldWrite = docChanged || updatedBy !== undefined;
+                if (!shouldWrite)
+                    return null;
+                if (!docChanged) {
+                    return {
+                        docMeta: {
+                            touch: true,
+                            ...(updatedBy ? { updatedBy } : {}),
+                        },
+                    };
+                }
+                if (requestMode === "full-doc") {
+                    expectedCurrentDoc ??= currentDocRaw;
+                    return {
+                        doc: {
+                            kind: "replace-doc",
+                            doc: nextDoc,
+                            expectedCurrentDoc,
+                        },
+                        ...(updatedBy ? { docMeta: { updatedBy } } : {}),
+                    };
+                }
+                expectedCurrentSectionText ??= extractSectionTextForPatch(currentDocRaw, opts.section ?? "");
+                return {
+                    doc: {
+                        kind: "set-section",
+                        section: opts.section ?? "",
+                        text: extractSectionTextForPatch(nextDoc, opts.section ?? "") ?? "",
+                        requiredSections: config.tasks.doc.required_sections,
+                        expectedCurrentText: expectedCurrentSectionText,
+                    },
+                    ...(updatedBy ? { docMeta: { updatedBy } } : {}),
+                };
+            });
+            changed = result.changed;
         }
         else {
-            let nextText = text;
-            if (headingKeys.size > 0 && headingKeys.has(targetKey)) {
-                const lines = nextText.replaceAll("\r\n", "\n").split("\n");
-                let firstContent = 0;
-                while (firstContent < lines.length && lines[firstContent]?.trim() === "")
-                    firstContent++;
-                if ((lines[firstContent]?.trim() ?? "") === `## ${opts.section}`) {
-                    lines.splice(firstContent, 1);
-                    if (lines[firstContent]?.trim() === "")
-                        lines.splice(firstContent, 1);
-                    nextText = lines.join("\n");
-                }
+            const baseDocRaw = (await backend.getTaskDoc(opts.taskId)) ?? "";
+            const nextDoc = buildUpdatedTaskDoc({
+                baseDocRaw,
+                section: opts.section,
+                text,
+                requestMode,
+                requiredSections: config.tasks.doc.required_sections,
+                headingKeys,
+                targetKey,
+            });
+            const docChanged = normalizeTaskDoc(baseDocRaw) !== normalizeTaskDoc(nextDoc);
+            const shouldWrite = docChanged || updatedBy !== undefined;
+            if (shouldWrite) {
+                await backend.setTaskDoc(opts.taskId, nextDoc, updatedBy);
             }
-            const nextDoc = setMarkdownSection(baseDoc, opts.section, nextText);
-            const normalized = ensureDocSections(nextDoc, config.tasks.doc.required_sections);
-            await (useStore
-                ? store.update(opts.taskId, (current) => ({
-                    ...current,
-                    doc: normalized,
-                    ...(updatedBy ? { doc_updated_by: updatedBy } : {}),
-                }))
-                : backend.setTaskDoc(opts.taskId, normalized, updatedBy));
+            changed = shouldWrite;
         }
-        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 outcome = changed
+            ? requestMode === "full-doc"
+                ? "full-doc-updated"
+                : "section-updated"
+            : "no-change";
         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`);
-        }
+        const outcomeTarget = opts.fullDoc ? "<full-doc>" : (opts.section ?? "");
+        const outcomeText = `task doc set outcome=${outcome} section=${outcomeTarget}`;
+        process.stderr.write(`${outcome === "no-change" ? warnMessage(outcomeText) : infoMessage(outcomeText)}\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;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,CA4XlB"}
+{"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"}