agentplane 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,70 @@
 # agentplane
 
-AgentPlane is an offline-first CLI for managing agent workflows (tasks, guardrails, recipes).
+[![npm](https://img.shields.io/npm/v/agentplane.svg)](https://www.npmjs.com/package/agentplane)
+[![Downloads](https://img.shields.io/npm/dm/agentplane.svg)](https://www.npmjs.com/package/agentplane)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://github.com/basilisk-labs/agentplane/blob/main/docs/user/prerequisites.mdx)
+
+Agent Plane is a policy-driven framework for running LLM agents inside real repositories. It turns "AI magic" into an engineering process: explicit approvals, role boundaries, and a reproducible execution pipeline. The goal is simple: make agents boring, safe, and auditable.
+
+## Why Agent Plane
+
+- You want agents that behave predictably inside real repos.
+- You need human approvals, clear roles, and traceable artifacts.
+- You want guardrails by default, not optional add-ons.
+- You want an offline-first CLI that keeps state local and inspectable.
+
+## 5-minute start
+
+Install and initialize the CLI:
+
+```bash
+npm install -g agentplane
+agentplane init
+agentplane quickstart
+```
+
+Create your first task and run the workflow:
+
+```bash
+agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
+agentplane verify <task-id>
+agentplane finish <task-id>
+```
+
+Prefer `npx` instead of a global install?
+
+```bash
+npx agentplane init
+npx agentplane quickstart
+```
+
+## What gets installed automatically
+
+- `.agentplane/` is created with config, tasks, agents, and caches.
+- `AGENTS.md` is created if missing and defines the policy/guardrails.
+- Built-in agent definitions are copied into `.agentplane/agents/`.
+- Optional recipes can install additional agents when you run `agentplane recipes install ...`.
+
+## Guardrails and artifacts
+
+- Approval gates for plans and network access (configured in `.agentplane/config.json`).
+- Role boundaries (ORCHESTRATOR, PLANNER, CODER, INTEGRATOR, etc.).
+- Agent definitions in `.agentplane/agents/`.
+- Task records in `.agentplane/tasks/` with a snapshot export in `.agentplane/tasks.json`.
+- A visible, reproducible pipeline:
+
+```text
+Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
+```
+
+## Features
+
+- Policy-first execution with explicit approvals and guardrails.
+- Role-based workflows for teams: ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR, etc.
+- Two workflow modes: `direct` (single checkout) and `branch_pr` (worktrees + integration).
+- Task tracking, verification, and exports baked in.
+- Recipes for repeatable setup and automation.
 
 ## Install
 
@@ -8,12 +72,42 @@ AgentPlane is an offline-first CLI for managing agent workflows (tasks, guardrai
 npm install -g agentplane
 ```
 
+Or run without installing:
+
+```bash
+npx agentplane --help
+```
+
 ## Requirements
 
 - Node.js >= 20
 
-## CLI
+## Common Commands
 
 ```bash
 agentplane --help
+agentplane quickstart
+agentplane config show
+agentplane task list
+agentplane task new --title "..." --description "..." --priority med --owner ORCHESTRATOR --tag docs
+agentplane verify <task-id>
+agentplane finish <task-id>
+agentplane recipes list
 ```
+
+## Docs and Guides
+
+- Documentation index: https://github.com/basilisk-labs/agentplane/tree/main/docs
+- Workflow overview: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/workflow.mdx
+- CLI commands: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/commands.mdx
+- Project layout: https://github.com/basilisk-labs/agentplane/blob/main/docs/developer/project-layout.mdx
+- Recipes: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes
+
+## Support
+
+- Issues: https://github.com/basilisk-labs/agentplane/issues
+- Contributing: https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md
+
+## License
+
+MIT

package/assets/AGENTS.md

@@ -163,6 +163,7 @@ Every task must have these sections in its README or task doc:
 
 ## Updating task docs
 
+- Workflow/task artifacts (task READMEs, PR artifacts, task exports) must be updated via `agentplane` commands, not manual edits.
 - Task README updates must be done via `agentplane task doc set ...`
 - Manual edits to `.agentplane/tasks/<task-id>/README.md` are prohibited.
 
@@ -170,6 +171,8 @@ Every task must have these sections in its README or task doc:
 
 # COMMIT WORKFLOW
 
+- Commits and pushes must go through `agentplane` commands (no direct `git commit`/`git push`). If a push is needed but no `agentplane` command exists, ask for guidance.
+
 ## Commit message semantics (canonical)
 
 There are two supported modes:

package/dist/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../src/command-guide.ts"],"names":[],"mappings":"AA4KA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA2EzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../src/command-guide.ts"],"names":[],"mappings":"AA4KA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA4EzC"}

package/dist/command-guide.js

@@ -228,6 +228,7 @@ export function renderQuickstart() {
         "- `--json`: emit JSON-formatted errors",
         "- `--help` / `-h`: show help",
         "- `--version`: show version",
+        "- `--no-update-check`: skip checking npm for a newer CLI version",
         "",
         "Notes:",
         "- `.env` at the repo root is loaded automatically (without overwriting existing environment variables).",

package/dist/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,IAAI,MAAM,CA2HnC"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,IAAI,MAAM,CA4HnC"}

package/dist/help.js

@@ -3,15 +3,16 @@ export function renderHelp() {
         "agentplane (v1 prototype)",
         "",
         "Usage:",
-        "  agentplane [--root <path>] [--json] <namespace> <command> [options]",
-        "  agentplane [--root <path>] [--json] <command> [options]",
+        "  agentplane [--root <path>] [--json] [--no-update-check] <namespace> <command> [options]",
+        "  agentplane [--root <path>] [--json] [--no-update-check] <command> [options]",
         "",
         "Core namespaces (implemented in this prototype): config, mode, task, ide, recipes, backend",
         "",
         "Flags:",
-        "  --help, -h     Show help",
-        "  --version      Show version",
-        "  --root <path>  Treat <path> as project root",
+        "  --help, -h           Show help",
+        "  --version            Show version",
+        "  --root <path>        Treat <path> as project root",
+        "  --no-update-check    Skip checking npm for a newer CLI version",
         "",
         "Quickstart commands:",
         "  agentplane quickstart",

package/dist/run-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../src/run-cli.ts"],"names":[],"mappings":"AAgtQA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAu/D5D"}
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../src/run-cli.ts"],"names":[],"mappings":"AA69QA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4/D5D"}

package/dist/run-cli.js

@@ -30,6 +30,7 @@ function gitEnv() {
 function parseGlobalArgs(argv) {
     let help = false;
     let version = false;
+    let noUpdateCheck = false;
     let jsonErrors = false;
     let root;
     const rest = [];
@@ -45,6 +46,10 @@ function parseGlobalArgs(argv) {
             version = true;
             continue;
         }
+        if (arg === "--no-update-check") {
+            noUpdateCheck = true;
+            continue;
+        }
         if (arg === "--json") {
             jsonErrors = true;
             continue;
@@ -63,7 +68,7 @@ function parseGlobalArgs(argv) {
         }
         rest.push(arg);
     }
-    return { globals: { help, version, root, jsonErrors }, rest };
+    return { globals: { help, version, noUpdateCheck, root, jsonErrors }, rest };
 }
 function writeError(err, jsonErrors) {
     const hint = renderErrorHint(err);
@@ -157,6 +162,79 @@ function usageMessage(usage, example) {
 function backendNotSupportedMessage(feature) {
     return `Backend does not support ${feature}`;
 }
+const UPDATE_CHECK_PACKAGE = "agentplane";
+const UPDATE_CHECK_URL = `https://registry.npmjs.org/${UPDATE_CHECK_PACKAGE}/latest`;
+const UPDATE_CHECK_TIMEOUT_MS = 1500;
+function parseVersionParts(version) {
+    const cleaned = version.trim().replace(/^v/i, "").split("+")[0] ?? "";
+    const [mainRaw, prereleaseRaw] = cleaned.split("-", 2);
+    const main = (mainRaw ?? "")
+        .split(".")
+        .filter((part) => part.length > 0)
+        .map((part) => {
+        const parsed = Number.parseInt(part, 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    });
+    return { main, prerelease: prereleaseRaw ? prereleaseRaw.trim() : null };
+}
+function compareVersions(left, right) {
+    const a = parseVersionParts(left);
+    const b = parseVersionParts(right);
+    const length = Math.max(a.main.length, b.main.length);
+    for (let i = 0; i < length; i++) {
+        const partA = a.main[i] ?? 0;
+        const partB = b.main[i] ?? 0;
+        if (partA !== partB)
+            return partA > partB ? 1 : -1;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === null)
+        return 1;
+    if (b.prerelease === null)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+async function fetchLatestNpmVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
+    try {
+        const res = await fetch(UPDATE_CHECK_URL, {
+            headers: { "User-Agent": "agentplane" },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const version = typeof data.version === "string" ? data.version.trim() : "";
+        return version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function maybeWarnOnUpdate(opts) {
+    if (opts.skip || opts.jsonErrors)
+        return;
+    if (isTruthyEnv(process.env.AGENTPLANE_NO_UPDATE_CHECK))
+        return;
+    const latest = await fetchLatestNpmVersion();
+    if (!latest)
+        return;
+    if (compareVersions(latest, opts.currentVersion) <= 0)
+        return;
+    const message = `Update available: ${UPDATE_CHECK_PACKAGE} ${opts.currentVersion} → ${latest}. Run: npm i -g ${UPDATE_CHECK_PACKAGE}@latest`;
+    process.stderr.write(`${warnMessage(message)}\n`);
+}
 function workflowModeMessage(actual, expected) {
     return `Invalid workflow_mode: ${actual ?? "unknown"} (expected ${expected})`;
 }
@@ -359,7 +437,7 @@ const BRANCH_STATUS_USAGE_EXAMPLE = "agentplane branch status --base main";
 const BRANCH_REMOVE_USAGE = "Usage: agentplane branch remove [--branch <name>] [--worktree <path>] [--force] [--quiet]";
 const BRANCH_REMOVE_USAGE_EXAMPLE = "agentplane branch remove --branch task/20260203-F1Q8AB --worktree .agentplane/worktrees/task";
 const UPGRADE_USAGE = "Usage: agentplane upgrade [--tag <tag>] [--dry-run] [--no-backup] [--source <repo-url>] [--bundle <path|url>] [--checksum <path|url>]";
-const UPGRADE_USAGE_EXAMPLE = "agentplane upgrade --tag v0.1.2 --dry-run";
+const UPGRADE_USAGE_EXAMPLE = "agentplane upgrade --tag v0.1.4 --dry-run";
 const INIT_USAGE = "Usage: agentplane init --ide <...> --workflow <...> --hooks <...> --require-plan-approval <...> --require-network-approval <...> [--recipes <...>] [--yes] [--force|--backup]";
 const INIT_USAGE_EXAMPLE = "agentplane init --ide codex --workflow direct --hooks false --require-plan-approval true --require-network-approval true --yes";
 const CONFIG_SET_USAGE = "Usage: agentplane config set <key> <value>";
@@ -1485,6 +1563,7 @@ async function cmdInit(opts) {
     let recipes = flags.recipes ?? defaults.recipes;
     let requirePlanApproval = flags.requirePlanApproval ?? defaults.requirePlanApproval;
     let requireNetworkApproval = flags.requireNetworkApproval ?? defaults.requireNetworkApproval;
+    const isInteractive = process.stdin.isTTY && !flags.yes;
     if (!process.stdin.isTTY &&
         !flags.yes &&
         (!flags.workflow ||
@@ -1497,7 +1576,7 @@ async function cmdInit(opts) {
             message: usageMessage(INIT_USAGE, INIT_USAGE_EXAMPLE),
         });
     }
-    if (process.stdin.isTTY && !flags.yes) {
+    if (isInteractive) {
         ide = flags.ide ?? defaults.ide;
         if (!flags.workflow) {
             const choice = await promptChoice("Select workflow mode", ["direct", "branch_pr"], workflow);
@@ -1534,7 +1613,9 @@ async function cmdInit(opts) {
     validateBundledRecipesSelection(recipes);
     try {
         const initRoot = path.resolve(opts.rootOverride ?? opts.cwd);
-        let gitRoot = await findGitRoot(initRoot);
+        const existingGitRoot = await findGitRoot(initRoot);
+        const gitRootExisted = Boolean(existingGitRoot);
+        let gitRoot = existingGitRoot;
         const baseBranchFallback = defaultConfig().base_branch;
         if (!gitRoot) {
             await gitInitRepo(initRoot, baseBranchFallback);
@@ -1544,7 +1625,13 @@ async function cmdInit(opts) {
             cwd: gitRoot,
             rootOverride: gitRoot,
         });
-        const initBaseBranch = await resolveInitBaseBranch(resolved.gitRoot, baseBranchFallback);
+        let initBaseBranch = await resolveInitBaseBranch(resolved.gitRoot, baseBranchFallback);
+        if (isInteractive && workflow === "branch_pr" && gitRootExisted) {
+            initBaseBranch = await promptInitBaseBranch({
+                gitRoot: resolved.gitRoot,
+                fallback: initBaseBranch,
+            });
+        }
         const configPath = path.join(resolved.agentplaneDir, "config.json");
         const backendPath = path.join(resolved.agentplaneDir, "backends", "local", "backend.json");
         const initDirs = [
@@ -1658,6 +1745,7 @@ async function cmdInit(opts) {
             baseBranch: initBaseBranch,
             installPaths,
             version: getVersion(),
+            skipHooks: hooks,
         });
         process.stdout.write(`${path.relative(resolved.gitRoot, resolved.agentplaneDir)}\n`);
         return 0;
@@ -2928,7 +3016,7 @@ async function cmdTaskNew(opts) {
             comments: [],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: flags.owner,
             id_source: "generated",
         };
         if (requiresVerify(flags.tags, config.tasks.verify.required_tags) &&
@@ -3061,6 +3149,7 @@ async function cmdTaskAdd(opts) {
         const tags = dedupeStrings(flags.tags);
         const dependsOn = dedupeStrings(flags.dependsOn);
         const verify = dedupeStrings(flags.verify);
+        const docUpdatedBy = (flags.commentAuthor ?? "").trim() || flags.owner;
         if (requiresVerify(tags, config.tasks.verify.required_tags) && verify.length === 0) {
             throw new CliError({
                 exitCode: 2,
@@ -3083,7 +3172,7 @@ async function cmdTaskAdd(opts) {
                 : [],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: docUpdatedBy,
             id_source: "explicit",
         }));
         if (backend.writeTasks) {
@@ -3756,10 +3845,15 @@ async function cmdTaskScaffold(opts) {
                 comments: [],
                 doc_version: 2,
                 doc_updated_at: nowIso(),
-                doc_updated_by: "agentplane",
+                doc_updated_by: "UNKNOWN",
             };
         if (flags.title)
             baseTask.title = flags.title;
+        if (typeof baseTask.doc_updated_by !== "string" ||
+            baseTask.doc_updated_by.trim().length === 0 ||
+            baseTask.doc_updated_by.trim().toLowerCase() === "agentplane") {
+            baseTask.doc_updated_by = baseTask.owner?.trim() ? baseTask.owner : "UNKNOWN";
+        }
         const frontmatter = taskDataToFrontmatter(baseTask);
         const body = ensureDocSections("", config.tasks.doc.required_sections);
         const text = renderTaskReadme(frontmatter, body);
@@ -3895,7 +3989,7 @@ async function cmdTaskComment(opts) {
             comments: [...existing, { author: opts.author, body: opts.body }],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(next);
         process.stdout.write(`${successMessage("commented", opts.taskId)}\n`);
@@ -3998,7 +4092,7 @@ async function cmdTaskSetStatus(opts) {
             comments,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: resolveDocUpdatedBy(task, opts.author),
         };
         if (opts.commit) {
             const commitInfo = await readCommitInfo(resolved.gitRoot, opts.commit);
@@ -4472,8 +4566,12 @@ async function gitAddPaths(cwd, paths) {
         return;
     await execFileAsync("git", ["add", "--", ...paths], { cwd, env: gitEnv() });
 }
-async function gitCommit(cwd, message) {
-    await execFileAsync("git", ["commit", "-m", message], { cwd, env: gitEnv() });
+async function gitCommit(cwd, message, opts) {
+    const args = ["commit", "-m", message];
+    if (opts?.skipHooks)
+        args.push("--no-verify");
+    const env = opts?.env ? { ...gitEnv(), ...opts.env } : gitEnv();
+    await execFileAsync("git", args, { cwd, env });
 }
 async function resolveInitBaseBranch(gitRoot, fallback) {
     let current = null;
@@ -4495,6 +4593,47 @@ async function resolveInitBaseBranch(gitRoot, fallback) {
     }
     return fallback;
 }
+async function promptInitBaseBranch(opts) {
+    const branches = await gitListBranches(opts.gitRoot);
+    let current = null;
+    try {
+        current = await gitCurrentBranch(opts.gitRoot);
+    }
+    catch {
+        current = null;
+    }
+    const promptNewBranch = async (hasBranches) => {
+        const raw = await promptInput(`Enter new base branch name (default ${opts.fallback}): `);
+        const candidate = raw.trim() || opts.fallback;
+        if (!candidate) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Base branch name cannot be empty",
+            });
+        }
+        if (await gitBranchExists(opts.gitRoot, candidate))
+            return candidate;
+        try {
+            await execFileAsync("git", hasBranches ? ["branch", candidate] : ["checkout", "-q", "-b", candidate], { cwd: opts.gitRoot, env: gitEnv() });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : `Failed to create branch ${candidate}`;
+            throw new CliError({ exitCode: 5, code: "E_GIT", message });
+        }
+        return candidate;
+    };
+    if (branches.length === 0) {
+        return await promptNewBranch(false);
+    }
+    const createLabel = "Create new branch";
+    const defaultChoice = current && branches.includes(current) ? current : (branches[0] ?? opts.fallback);
+    const choice = await promptChoice("Select base branch", [...branches, createLabel], defaultChoice);
+    if (choice === createLabel) {
+        return await promptNewBranch(true);
+    }
+    return choice;
+}
 async function ensureInitCommit(opts) {
     const stagedBefore = await gitStagedPaths(opts.gitRoot);
     if (stagedBefore.length > 0) {
@@ -4515,7 +4654,7 @@ async function ensureInitCommit(opts) {
     if (staged.length === 0)
         return;
     const message = `chore: install agentplane ${opts.version}`;
-    await gitCommit(opts.gitRoot, message);
+    await gitCommit(opts.gitRoot, message, { skipHooks: opts.skipHooks });
 }
 function toGitPath(filePath) {
     return filePath.split(path.sep).join("/");
@@ -5232,7 +5371,7 @@ async function cmdStart(opts) {
             comments: commentsValue,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(nextTask);
         let commitInfo = null;
@@ -5308,7 +5447,7 @@ async function cmdBlock(opts) {
             comments: commentsValue,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(nextTask);
         let commitInfo = null;
@@ -5409,7 +5548,7 @@ async function cmdFinish(opts) {
                 comments: commentsValue,
                 doc_version: 2,
                 doc_updated_at: nowIso(),
-                doc_updated_by: "agentplane",
+                doc_updated_by: opts.author,
             };
             await backend.writeTask(nextTask);
         }
@@ -6935,26 +7074,128 @@ function setMarkdownSection(body, section, text) {
     const out = [...lines.slice(0, start + 1), ...replacement, ...lines.slice(nextHeading)];
     return `${out.join("\n")}\n`;
 }
+function normalizeDocSectionName(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function normalizeDocUpdatedBy(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === "agentplane")
+        return "";
+    return trimmed;
+}
+function resolveDocUpdatedBy(task, author) {
+    const fromAuthor = normalizeDocUpdatedBy(author);
+    if (fromAuthor)
+        return fromAuthor;
+    const fromTask = normalizeDocUpdatedBy(typeof task.doc_updated_by === "string" ? task.doc_updated_by : undefined);
+    if (fromTask)
+        return fromTask;
+    return normalizeDocUpdatedBy(typeof task.owner === "string" ? task.owner : undefined);
+}
+function splitCombinedHeadingLines(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (!inFence && line.includes("## ")) {
+            const matches = [...line.matchAll(/##\s+/g)];
+            if (matches.length > 1 && matches[0]?.index === 0) {
+                let start = 0;
+                for (let i = 1; i < matches.length; i += 1) {
+                    const idx = matches[i]?.index ?? 0;
+                    const chunk = line.slice(start, idx).trimEnd();
+                    if (chunk)
+                        out.push(chunk);
+                    start = idx;
+                }
+                const last = line.slice(start).trimEnd();
+                if (last)
+                    out.push(last);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+function normalizeDocSections(doc, required) {
+    const lines = splitCombinedHeadingLines(doc);
+    const sections = new Map();
+    const order = [];
+    const pendingSeparator = new Set();
+    let currentKey = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            const title = match[1]?.trim() ?? "";
+            const key = normalizeDocSectionName(title);
+            if (key) {
+                const existing = sections.get(key);
+                if (existing) {
+                    if (existing.lines.some((entry) => entry.trim() !== "")) {
+                        pendingSeparator.add(key);
+                    }
+                }
+                else {
+                    sections.set(key, { title, lines: [] });
+                    order.push(key);
+                }
+                currentKey = key;
+                continue;
+            }
+        }
+        if (currentKey) {
+            const entry = sections.get(currentKey);
+            if (!entry)
+                continue;
+            if (pendingSeparator.has(currentKey) && line.trim() !== "") {
+                entry.lines.push("");
+                pendingSeparator.delete(currentKey);
+            }
+            entry.lines.push(line);
+        }
+    }
+    const out = [];
+    const seen = new Set(order);
+    for (const key of order) {
+        const section = sections.get(key);
+        if (!section)
+            continue;
+        out.push(`## ${section.title}`);
+        if (section.lines.length > 0) {
+            out.push(...section.lines);
+        }
+        else {
+            out.push("");
+        }
+        out.push("");
+    }
+    for (const requiredSection of required) {
+        const requiredKey = normalizeDocSectionName(requiredSection);
+        if (seen.has(requiredKey))
+            continue;
+        out.push(`## ${requiredSection}`, "", "");
+    }
+    return `${out.join("\n").trimEnd()}\n`;
+}
 function ensureDocSections(doc, required) {
     const trimmed = doc.trim();
     if (!trimmed) {
         const blocks = required.map((section) => `## ${section}\n`);
         return `${blocks.join("\n").trimEnd()}\n`;
     }
-    let out = doc.endsWith("\n") ? doc : `${doc}\n`;
-    for (const section of required) {
-        const needle = `## ${section}`;
-        if (!out.split("\n").some((line) => line.trim() === needle)) {
-            out = `${out.trimEnd()}\n\n${needle}\n`;
-        }
-    }
-    return out.endsWith("\n") ? out : `${out}\n`;
-}
-function normalizeDocSectionName(section) {
-    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+    return normalizeDocSections(doc, required);
 }
 function parseDocSections(doc) {
-    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const lines = splitCombinedHeadingLines(doc);
     const sections = new Map();
     const order = [];
     let currentKey = null;
@@ -7098,9 +7339,17 @@ async function cmdTaskDocSet(opts) {
             message: usageMessage(TASK_DOC_SET_USAGE, TASK_DOC_SET_USAGE_EXAMPLE),
         });
     }
-    const updatedBy = (flags.updatedBy ?? "agentplane").trim();
-    if (updatedBy.length === 0) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: "--updated-by must be non-empty" });
+    let updatedBy;
+    if (flags.updatedBy !== undefined) {
+        const trimmed = flags.updatedBy.trim();
+        if (trimmed.length === 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "--updated-by must be non-empty",
+            });
+        }
+        updatedBy = trimmed;
     }
     let text = flags.text ?? "";
     if (hasFile) {
@@ -7164,7 +7413,8 @@ async function cmdTaskDocSet(opts) {
                 }
             }
             const nextDoc = setMarkdownSection(baseDoc, flags.section, nextText);
-            await backend.setTaskDoc(opts.taskId, nextDoc, updatedBy);
+            const normalized = ensureDocSections(nextDoc, config.tasks.doc.required_sections);
+            await backend.setTaskDoc(opts.taskId, normalized, updatedBy);
         }
         const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
         process.stdout.write(`${path.join(tasksDir, opts.taskId, "README.md")}\n`);
@@ -7234,6 +7484,11 @@ export async function runCli(argv) {
             return 0;
         }
         await maybeLoadDotEnv({ cwd: process.cwd(), rootOverride: globals.root });
+        await maybeWarnOnUpdate({
+            currentVersion: getVersion(),
+            skip: globals.noUpdateCheck,
+            jsonErrors: globals.jsonErrors,
+        });
         const [namespace, command, ...args] = rest;
         if (namespace === "init") {
             const initArgs = command ? [command, ...args] : [];

package/dist/run-cli.test-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.test-helpers.d.ts","sourceRoot":"","sources":["../src/run-cli.test-helpers.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiCpD,wBAAgB,sBAAsB,IAAI,IAAI,CAgB7C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,YAAY;;;;EAgC3B;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAKrD;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjD;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpE;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAKhE;AAED,wBAAsB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CA+FtE;AAED,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAiBD;AAED,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlE;AAED,wBAAgB,WAAW,IAAI,MAAM,CAAC,UAAU,CAS/C;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYpF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzE"}
+{"version":3,"file":"run-cli.test-helpers.d.ts","sourceRoot":"","sources":["../src/run-cli.test-helpers.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAkCpD,wBAAgB,sBAAsB,IAAI,IAAI,CAsB7C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,YAAY;;;;EAgC3B;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAKrD;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjD;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpE;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAKhE;AAED,wBAAsB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CA+FtE;AAED,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAiBD;AAED,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlE;AAED,wBAAgB,WAAW,IAAI,MAAM,CAAC,UAAU,CAS/C;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYpF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzE"}

package/dist/run-cli.test-helpers.js

@@ -9,6 +9,7 @@ import { defaultConfig } from "@agentplaneorg/core";
 const execFileAsync = promisify(execFile);
 let agentplaneHome = null;
 const originalAgentplaneHome = process.env.AGENTPLANE_HOME;
+const originalNoUpdateCheck = process.env.AGENTPLANE_NO_UPDATE_CHECK;
 const recipeArchiveCache = new Map();
 let gitTemplateRoot = null;
 let gitTemplatePromise = null;
@@ -31,6 +32,7 @@ export function registerAgentplaneHome() {
     beforeAll(async () => {
         agentplaneHome = await mkdtemp(path.join(os.tmpdir(), "agentplane-home-"));
         process.env.AGENTPLANE_HOME = agentplaneHome;
+        process.env.AGENTPLANE_NO_UPDATE_CHECK = "1";
     });
     afterAll(async () => {
         if (agentplaneHome) {
@@ -42,6 +44,12 @@ export function registerAgentplaneHome() {
         else {
             process.env.AGENTPLANE_HOME = originalAgentplaneHome;
         }
+        if (originalNoUpdateCheck === undefined) {
+            delete process.env.AGENTPLANE_NO_UPDATE_CHECK;
+        }
+        else {
+            process.env.AGENTPLANE_NO_UPDATE_CHECK = originalNoUpdateCheck;
+        }
     });
 }
 export function getAgentplaneHome() {

package/dist/task-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../src/task-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../src/task-backend.ts"],"names":[],"mappings":"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"}

package/dist/task-backend.js

@@ -6,6 +6,7 @@ import { loadDotEnv } from "./env.js";
 const ID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 const TASK_ID_RE = new RegExp(String.raw `^\d{12}-[${ID_ALPHABET}]{4,}$`);
 const DOC_SECTION_HEADER = "## Summary";
+const DOC_SECTION_HEADER_RE = /^##\s+Summary(?:\s|$|#)/;
 const AUTO_SUMMARY_HEADER = "## Changes Summary (auto)";
 const DEFAULT_DOC_UPDATED_BY = "agentplane";
 const DOC_VERSION = 2;
@@ -41,13 +42,209 @@ function normalizeDoc(text) {
         .join("\n")
         .trim();
 }
+function normalizeDocSectionName(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function normalizeSectionLines(lines) {
+    const trimmedLines = [...lines];
+    while (trimmedLines.length > 0 && trimmedLines[0]?.trim() === "")
+        trimmedLines.shift();
+    while (trimmedLines.length > 0 && trimmedLines.at(-1)?.trim() === "")
+        trimmedLines.pop();
+    const out = [];
+    let inFence = false;
+    let pendingBlank = false;
+    for (const line of trimmedLines) {
+        const fenceCheck = line.trimStart();
+        if (fenceCheck.startsWith("```")) {
+            if (pendingBlank) {
+                out.push("");
+                pendingBlank = false;
+            }
+            out.push(line);
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        if (line.trim() === "") {
+            pendingBlank = true;
+            continue;
+        }
+        if (pendingBlank) {
+            out.push("");
+            pendingBlank = false;
+        }
+        out.push(line);
+    }
+    return out;
+}
+function splitCombinedHeadingLines(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (!inFence && line.includes("## ")) {
+            const matches = [...line.matchAll(/##\s+/g)];
+            if (matches.length > 1 && matches[0]?.index === 0) {
+                let start = 0;
+                for (let i = 1; i < matches.length; i += 1) {
+                    const idx = matches[i]?.index ?? 0;
+                    const chunk = line.slice(start, idx).trimEnd();
+                    if (chunk)
+                        out.push(chunk);
+                    start = idx;
+                }
+                const last = line.slice(start).trimEnd();
+                if (last)
+                    out.push(last);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+function normalizeTaskDoc(doc) {
+    const normalized = doc.replaceAll("\r\n", "\n");
+    const trimmed = normalized.replaceAll(/^\n+|\n+$/g, "");
+    if (!trimmed)
+        return "";
+    const lines = splitCombinedHeadingLines(trimmed);
+    const sections = new Map();
+    const order = [];
+    const pendingSeparator = new Set();
+    let currentKey = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            const title = match[1]?.trim() ?? "";
+            const key = normalizeDocSectionName(title);
+            if (key) {
+                const existing = sections.get(key);
+                if (existing) {
+                    if (existing.lines.some((entry) => entry.trim() !== "")) {
+                        pendingSeparator.add(key);
+                    }
+                }
+                else {
+                    sections.set(key, { title, lines: [] });
+                    order.push(key);
+                }
+                currentKey = key;
+                continue;
+            }
+        }
+        if (currentKey) {
+            const entry = sections.get(currentKey);
+            if (!entry)
+                continue;
+            if (pendingSeparator.has(currentKey) && line.trim() !== "") {
+                entry.lines.push("");
+                pendingSeparator.delete(currentKey);
+            }
+            entry.lines.push(line);
+        }
+    }
+    if (order.length === 0)
+        return trimmed;
+    const out = [];
+    for (const key of order) {
+        const section = sections.get(key);
+        if (!section)
+            continue;
+        const normalizedLines = normalizeSectionLines(section.lines);
+        if (normalizedLines.length > 0) {
+            out.push(`## ${section.title}`, "", ...normalizedLines, "");
+        }
+        else {
+            out.push(`## ${section.title}`, "", "");
+        }
+    }
+    return out.join("\n").trimEnd();
+}
 function docChanged(existing, updated) {
     return normalizeDoc(existing) !== normalizeDoc(updated);
 }
+function normalizeUpdatedBy(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === DEFAULT_DOC_UPDATED_BY.toLowerCase())
+        return "";
+    return trimmed;
+}
 function ensureDocMetadata(task, updatedBy) {
     task.doc_version = DOC_VERSION;
     task.doc_updated_at = nowIso();
-    task.doc_updated_by = updatedBy ?? DEFAULT_DOC_UPDATED_BY;
+    const explicit = normalizeUpdatedBy(updatedBy);
+    if (updatedBy !== undefined) {
+        task.doc_updated_by =
+            explicit || resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+        return;
+    }
+    task.doc_updated_by = resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+}
+function lastCommentAuthor(comments) {
+    if (!Array.isArray(comments))
+        return null;
+    const entries = comments;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (!isRecord(entry))
+            continue;
+        const author = entry.author;
+        if (typeof author === "string") {
+            const trimmed = author.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    return null;
+}
+function resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, fallback) {
+    if (updatedBy !== undefined) {
+        const explicit = normalizeUpdatedBy(updatedBy);
+        if (explicit)
+            return explicit;
+    }
+    const author = lastCommentAuthor(frontmatter.comments);
+    if (author)
+        return author;
+    const existing = normalizeUpdatedBy(frontmatter.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(frontmatter.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
+}
+function resolveDocUpdatedByFromTask(task, fallback) {
+    const author = lastCommentAuthor(task.comments);
+    if (author)
+        return author;
+    const existing = normalizeUpdatedBy(task.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(task.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
+}
+function isDocSectionHeader(line) {
+    return DOC_SECTION_HEADER_RE.test(line.trim());
 }
 export function extractTaskDoc(body) {
     if (!body)
@@ -55,13 +252,16 @@ export function extractTaskDoc(body) {
     const lines = body.split("\n");
     let startIdx = null;
     for (const [idx, line] of lines.entries()) {
-        if (line.trim() === DOC_SECTION_HEADER) {
+        if (isDocSectionHeader(line)) {
             startIdx = idx;
             break;
         }
     }
     if (startIdx === null)
         return "";
+    if (lines[startIdx]?.trim() !== DOC_SECTION_HEADER) {
+        lines[startIdx] = DOC_SECTION_HEADER;
+    }
     let endIdx = lines.length;
     for (let idx = startIdx + 1; idx < lines.length; idx++) {
         if (lines[idx]?.trim() === AUTO_SUMMARY_HEADER) {
@@ -69,15 +269,16 @@ export function extractTaskDoc(body) {
             break;
         }
     }
-    return lines.slice(startIdx, endIdx).join("\n").trimEnd();
+    const doc = lines.slice(startIdx, endIdx).join("\n").trimEnd();
+    return normalizeTaskDoc(doc);
 }
 export function mergeTaskDoc(body, doc) {
-    const docText = String(doc ?? "").replaceAll(/^\n+|\n+$/g, "");
+    const docText = normalizeTaskDoc(String(doc ?? ""));
     if (docText) {
         const lines = body ? body.split("\n") : [];
         let prefixIdx = null;
         for (const [idx, line] of lines.entries()) {
-            if (line.trim() === DOC_SECTION_HEADER) {
+            if (isDocSectionHeader(line)) {
                 prefixIdx = idx;
                 break;
             }
@@ -211,7 +412,7 @@ function taskDataToExport(task) {
             : [],
         doc_version: task.doc_version ?? DOC_VERSION,
         doc_updated_at: task.doc_updated_at ?? "",
-        doc_updated_by: task.doc_updated_by ?? DEFAULT_DOC_UPDATED_BY,
+        doc_updated_by: resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY),
         dirty: Boolean(task.dirty),
         id_source: task.id_source ?? "generated",
     };
@@ -383,7 +584,7 @@ export class LocalBackend {
             if (docChanged(existingDoc, docText)) {
                 payload.doc_version = DOC_VERSION;
                 payload.doc_updated_at = nowIso();
-                payload.doc_updated_by = this.updatedBy;
+                payload.doc_updated_by = resolveDocUpdatedByFromTask(task, this.updatedBy);
             }
         }
         if (payload.doc_version !== DOC_VERSION) {
@@ -393,7 +594,7 @@ export class LocalBackend {
             payload.doc_updated_at = nowIso();
         }
         if (payload.doc_updated_by === undefined || payload.doc_updated_by === "") {
-            payload.doc_updated_by = this.updatedBy;
+            payload.doc_updated_by = resolveDocUpdatedByFromTask(task, this.updatedBy);
         }
         await mkdir(path.dirname(readme), { recursive: true });
         const text = renderTaskReadme(payload, body || "");
@@ -409,7 +610,7 @@ export class LocalBackend {
         if (docChanged(extractTaskDoc(parsed.body), docText) || !frontmatter.doc_updated_at) {
             frontmatter.doc_version = DOC_VERSION;
             frontmatter.doc_updated_at = nowIso();
-            frontmatter.doc_updated_by = updatedBy ?? this.updatedBy;
+            frontmatter.doc_updated_by = resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, this.updatedBy);
         }
         if (frontmatter.doc_version !== DOC_VERSION) {
             frontmatter.doc_version = DOC_VERSION;
@@ -424,7 +625,7 @@ export class LocalBackend {
         const frontmatter = { ...parsed.frontmatter };
         frontmatter.doc_version = DOC_VERSION;
         frontmatter.doc_updated_at = nowIso();
-        frontmatter.doc_updated_by = updatedBy ?? this.updatedBy;
+        frontmatter.doc_updated_by = resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, this.updatedBy);
         const next = renderTaskReadme(frontmatter, parsed.body || "");
         await writeFile(readme, next.endsWith("\n") ? next : `${next}\n`, "utf8");
     }

package/dist/version.js

@@ -1,3 +1,3 @@
 export function getVersion() {
-    return "0.1.2";
+    return "0.1.4";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -54,6 +54,6 @@
     "prepublishOnly": "npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.1.2"
+    "@agentplaneorg/core": "0.1.4"
   }
 }