agentplane 0.3.2 → 0.3.3

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

@@ -11,7 +11,7 @@ function normalizeTaskIdsArg(raw) {
 export const taskMigrateDocSpec = {
     id: ["task", "migrate-doc"],
     group: "Task",
-    summary: "Migrate task README docs to the current template/metadata format.",
+    summary: "Migrate legacy task README docs to the current README v3 template/metadata format.",
     args: [{ name: "task-id", required: false, variadic: true, valueHint: "<task-id>" }],
     options: [
         { kind: "boolean", name: "all", default: false, description: "Migrate all task READMEs." },
@@ -29,6 +29,10 @@ export const taskMigrateDocSpec = {
             why: "Migrate specific task READMEs.",
         },
     ],
+    notes: [
+        "Use this after framework upgrade when doctor reports active legacy README v2 tasks or an active v2/v3 mixed state.",
+        "This command upgrades task-local docs; it does not replace framework-managed files such as AGENTS.md or .agentplane/policy/**.",
+    ],
     validateRaw: (raw) => {
         const all = raw.opts.all === true;
         const taskIds = normalizeTaskIdsArg(raw);

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

@@ -1 +1 @@
-{"version":3,"file":"migrate-doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.ts"],"names":[],"mappings":"AAmIA,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}
+{"version":3,"file":"migrate-doc.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.ts"],"names":[],"mappings":"AAkSA,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}

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

@@ -1,14 +1,128 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskReadme, resolveProject, } from "@agentplaneorg/core";
+import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskReadme, resolveProject, setMarkdownSection, } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { fileExists, getPathKind } from "../../cli/fs-utils.js";
 import { successMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
+import { extractDocSection, extractTaskObservationSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
+import { defaultTaskDocV3 } from "./doc-template.js";
+const V3_CANONICAL_ORDER = [
+    "Summary",
+    "Context",
+    "Scope",
+    "Plan",
+    "Verify Steps",
+    "Verification",
+    "Rollback Plan",
+    "Findings",
+];
+const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "findings", "notes"]);
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function normalizeSectionKey(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function parseMarkdownSections(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            if (current) {
+                current.text = current.text.trimEnd();
+                sections.push(current);
+            }
+            current = { title: (match[1] ?? "").trim(), text: "" };
+            continue;
+        }
+        if (current) {
+            current.text = current.text.length > 0 ? `${current.text}\n${line}` : line;
+        }
+    }
+    if (current) {
+        current.text = current.text.trimEnd();
+        sections.push(current);
+    }
+    return sections;
+}
+function renderMarkdownSections(sections) {
+    return sections
+        .map((section) => {
+        const text = section.text.trimEnd();
+        return text ? `## ${section.title}\n\n${text}` : `## ${section.title}\n`;
+    })
+        .join("\n\n")
+        .trimEnd();
+}
+function normalizeLiteralNewlinesInHumanSection(title, text) {
+    if (!HUMAN_TEXT_SECTIONS.has(normalizeSectionKey(title)))
+        return text.trimEnd();
+    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.trimEnd();
+}
+function firstSectionText(sections, title) {
+    const target = normalizeSectionKey(title);
+    return sections.find((section) => normalizeSectionKey(section.title) === target)?.text ?? null;
+}
+function mergeObservationText(doc, version) {
+    const preferred = extractTaskObservationSection(doc, version)?.trim() ?? "";
+    const notes = extractDocSection(doc, "Notes")?.trim() ?? "";
+    const findings = extractDocSection(doc, "Findings")?.trim() ?? "";
+    const out = [];
+    for (const candidate of [preferred, findings, notes]) {
+        if (!candidate)
+            continue;
+        if (out.includes(candidate))
+            continue;
+        out.push(candidate);
+    }
+    return out.join("\n\n").trim();
+}
+function migrateDocToV3(opts) {
+    const currentSections = parseMarkdownSections(opts.doc);
+    const defaultSections = parseMarkdownSections(defaultTaskDocV3({ title: opts.title, description: opts.description }));
+    const emitted = new Set();
+    const nextSections = [];
+    const observationText = mergeObservationText(opts.doc, 2);
+    for (const title of V3_CANONICAL_ORDER) {
+        const key = normalizeSectionKey(title);
+        const currentText = firstSectionText(currentSections, title);
+        const defaultText = firstSectionText(defaultSections, title) ?? "";
+        let nextText = currentText ?? defaultText;
+        if (title === "Context" && !(currentText ?? "").trim())
+            continue;
+        if (title === "Verification") {
+            nextText = normalizeVerificationSectionLayout(currentText ?? defaultText, 3);
+        }
+        if (title === "Findings") {
+            nextText = observationText || defaultText;
+        }
+        if (nextText === null)
+            continue;
+        nextText = normalizeLiteralNewlinesInHumanSection(title, nextText);
+        nextSections.push({ title, text: nextText.trimEnd() });
+        emitted.add(key);
+        if (title === "Findings")
+            emitted.add("notes");
+    }
+    for (const section of currentSections) {
+        const key = normalizeSectionKey(section.title);
+        if (emitted.has(key))
+            continue;
+        nextSections.push({ title: section.title, text: section.text.trimEnd() });
+        emitted.add(key);
+    }
+    return renderMarkdownSections(nextSections);
+}
 function ensurePlanApprovalFrontmatter(frontmatter) {
     const raw = frontmatter.plan_approval;
     if (isRecord(raw) && typeof raw.state === "string")
@@ -74,7 +188,27 @@ async function migrateTaskReadmeDoc(opts) {
     const required = opts.config.tasks.doc.required_sections;
     const extracted = extractTaskDoc(parsed.body);
     const baseDoc = extracted || parsed.body;
-    const nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
+    let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
+    const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
+    if (docVersion === 2) {
+        frontmatter.doc_version = 3;
+        nextDoc = migrateDocToV3({
+            title: typeof frontmatter.title === "string" ? frontmatter.title : "",
+            description: typeof frontmatter.description === "string" ? frontmatter.description : "",
+            doc: nextDoc,
+        });
+    }
+    else {
+        const verificationSection = extractDocSection(nextDoc, "Verification");
+        const normalizedVerification = normalizeVerificationSectionLayout(verificationSection, docVersion);
+        nextDoc = setMarkdownSection(nextDoc, "Verification", normalizedVerification);
+        for (const sectionTitle of ["Summary", "Context", "Scope", "Plan", "Findings", "Notes"]) {
+            const sectionText = extractDocSection(nextDoc, sectionTitle);
+            if (sectionText == null)
+                continue;
+            nextDoc = setMarkdownSection(nextDoc, sectionTitle, normalizeLiteralNewlinesInHumanSection(sectionTitle, sectionText));
+        }
+    }
     const nextBody = extracted ? mergeTaskDoc(parsed.body, nextDoc) : nextDoc;
     const rendered = renderTaskReadme(frontmatter, nextBody);
     const next = rendered.endsWith("\n") ? rendered : `${rendered}\n`;

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

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AASpF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AA6LF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoFlB"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAcpF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAmDF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgFlB"}

package/dist/commands/task/new.js

@@ -1,9 +1,10 @@
-import { ensureDocSections, setMarkdownSection } from "@agentplaneorg/core";
+import { setMarkdownSection } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { backendNotSupportedMessage, warnMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { ensureTaskDependsOnGraphIsAcyclic, nowIso, requiresVerifyStepsByPrimary, resolvePrimaryTag, warnIfUnknownOwner, } from "./shared.js";
+import { buildDefaultVerifyStepsSection, defaultTaskDocV3, TASK_DOC_VERSION_V3, } from "./doc-template.js";
 function dedupeTrimmed(values) {
     const seen = new Set();
     const out = [];
@@ -51,109 +52,6 @@ function sanitizeTaskNewParsed(p) {
     const verify = dedupeTrimmed(p.verify);
     return { ...p, title, description, owner, tags, dependsOn, verify };
 }
-function insertMarkdownSectionBefore(opts) {
-    const normalized = opts.body.replaceAll("\r\n", "\n");
-    if (normalized.includes(`## ${opts.section}`)) {
-        return setMarkdownSection(normalized, opts.section, opts.text);
-    }
-    const lines = normalized.split("\n");
-    const beforeHeading = `## ${opts.beforeSection}`;
-    const beforeIdx = lines.findIndex((line) => line.trim() === beforeHeading);
-    if (beforeIdx === -1)
-        return setMarkdownSection(normalized, opts.section, opts.text);
-    const textLines = opts.text.replaceAll("\r\n", "\n").split("\n");
-    const sectionLines = [`## ${opts.section}`, "", ...textLines, "", ""];
-    const out = [...lines.slice(0, beforeIdx), ...sectionLines, ...lines.slice(beforeIdx)];
-    return `${out.join("\n").trimEnd()}\n`;
-}
-function buildDefaultSummary(opts) {
-    return `${opts.title}\n\n${opts.description}`;
-}
-function buildDefaultScope(opts) {
-    return [
-        `- In scope: ${opts.description}.`,
-        `- 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 notes and finish with traceable commit metadata.",
-    ].join("\n");
-}
-function buildDefaultRisks() {
-    return [
-        "- Risk: hidden regressions in touched paths.",
-        "- Mitigation: run required checks before finish and record evidence.",
-    ].join("\n");
-}
-function buildDefaultRollbackPlan() {
-    return [
-        "- Revert task-related commit(s).",
-        "- Re-run required checks to confirm rollback safety.",
-    ].join("\n");
-}
-function defaultTaskDoc(opts) {
-    const verifyStepsTemplate = [
-        "<!-- TODO: FILL VERIFY STEPS -->",
-        "",
-        "### Scope",
-        "",
-        "",
-        "### Checks",
-        "",
-        "",
-        "### Evidence / Commands",
-        "",
-        "",
-        "### Pass criteria",
-        "",
-        "",
-    ].join("\n");
-    const verificationTemplate = [
-        "### Plan",
-        "",
-        "",
-        "### Results",
-        "",
-        "",
-        "<!-- BEGIN VERIFICATION RESULTS -->",
-        "<!-- END VERIFICATION RESULTS -->",
-    ].join("\n");
-    const baseDoc = ensureDocSections("", opts.requiredSections);
-    const withVerifySteps = insertMarkdownSectionBefore({
-        body: baseDoc,
-        section: "Verify Steps",
-        text: verifyStepsTemplate,
-        beforeSection: "Verification",
-    });
-    const withVerification = setMarkdownSection(withVerifySteps, "Verification", verificationTemplate);
-    const withSummary = setMarkdownSection(withVerification, "Summary", buildDefaultSummary({ title: opts.title, description: opts.description }));
-    const withScope = setMarkdownSection(withSummary, "Scope", buildDefaultScope({ title: opts.title, description: opts.description }));
-    const withPlan = setMarkdownSection(withScope, "Plan", buildDefaultPlan({ title: opts.title }));
-    const withRisks = setMarkdownSection(withPlan, "Risks", buildDefaultRisks());
-    return setMarkdownSection(withRisks, "Rollback Plan", buildDefaultRollbackPlan());
-}
-function buildDefaultVerifyStepsSection(opts) {
-    const checks = opts.verifyCommands.length > 0
-        ? opts.verifyCommands.map((command) => `- \`${command}\``).join("\n")
-        : "- Add explicit checks/commands for this task before approval.";
-    return [
-        "### Scope",
-        `- Primary tag: \`${opts.primary}\``,
-        "",
-        "### Checks",
-        checks,
-        "",
-        "### Evidence / Commands",
-        "- Record executed commands and key outputs.",
-        "",
-        "### Pass criteria",
-        "- Steps are reproducible and produce expected results.",
-        "",
-    ].join("\n");
-}
 export async function runTaskNewParsed(opts) {
     const p = sanitizeTaskNewParsed(opts.parsed);
     try {
@@ -179,15 +77,11 @@ export async function runTaskNewParsed(opts) {
             depends_on: p.dependsOn,
             verify: p.verify,
             comments: [],
-            doc_version: 2,
+            doc_version: TASK_DOC_VERSION_V3,
             doc_updated_at: nowIso(),
             doc_updated_by: p.owner,
             id_source: "generated",
-            doc: defaultTaskDoc({
-                requiredSections: ctx.config.tasks.doc.required_sections,
-                title: p.title,
-                description: p.description,
-            }),
+            doc: defaultTaskDocV3({ title: p.title, description: p.description }),
         };
         const spikeTag = (ctx.config.tasks.verify.spike_tag ?? "spike").trim().toLowerCase();
         const primary = resolvePrimaryTag(p.tags, ctx);

package/dist/commands/task/new.spec.js

@@ -3,7 +3,7 @@ export const taskNewSpec = {
     id: ["task", "new"],
     group: "Task",
     summary: "Create a new task (prints the generated task id).",
-    description: "Creates a TODO task with doc_version=2, seeds standard README sections, and writes it via the configured task backend.",
+    description: "Creates a TODO task with doc_version=3, seeds the README v3 section layout, and writes it via the configured task backend.",
     options: [
         {
             kind: "string",
@@ -65,8 +65,8 @@ export const taskNewSpec = {
         },
     ],
     notes: [
-        "Task README scaffolding is applied automatically during creation.",
-        "For verify-required primary tags, this command seeds a default ## Verify Steps section in README.",
+        "Task creation defaults to doc_version=3 and seeds the README v3 section contract automatically.",
+        "For verify-required primary tags, this command seeds a default ## Verify Steps acceptance contract in README.",
     ],
     parse: (raw) => ({
         title: raw.opts.title,

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

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAoDnC,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,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ElB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAsFlB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAuDnC,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,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ElB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA4FlB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}

package/dist/commands/task/plan.js

@@ -6,7 +6,7 @@ import { backendNotSupportedMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
 import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
-import { ensureAgentFilledRequiredDocSections, extractDocSection, isVerifyStepsFilled, nowIso, requiresVerifyStepsByPrimary, toStringArray, } from "./shared.js";
+import { ensureAgentFilledRequiredDocSections, extractDocSection, extractTaskObservationSection, isVerifyStepsFilled, nowIso, normalizeTaskDocVersion, taskObservationSectionName, requiresVerifyStepsByPrimary, toStringArray, } from "./shared.js";
 async function loadPlanTask(opts) {
     const ctx = opts.ctx ??
         (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
@@ -153,12 +153,13 @@ export async function cmdTaskPlanApprove(opts) {
                 }
             }
             if (isSpike) {
-                const notes = extractDocSection(baseDoc, "Notes");
-                if (!notes || notes.trim().length === 0) {
+                const observationSection = taskObservationSectionName(normalizeTaskDocVersion(task.doc_version));
+                const observation = extractTaskObservationSection(baseDoc, normalizeTaskDocVersion(task.doc_version));
+                if (!observation || observation.trim().length === 0) {
                     throw new CliError({
                         exitCode: 3,
                         code: "E_VALIDATION",
-                        message: `${task.id}: cannot approve plan for spike: ## Notes section is missing or empty ` +
+                        message: `${task.id}: cannot approve plan for spike: ## ${observationSection} section is missing or empty ` +
                             "(include Findings/Decision/Next Steps)",
                     });
                 }

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

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scaffold.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AA8BnC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuHlB"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scaffold.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAMnC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FlB"}

package/dist/commands/task/scaffold.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureDocSections, renderTaskReadme, setMarkdownSection, taskReadmePath, } from "@agentplaneorg/core";
+import { renderTaskReadme, taskReadmePath } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { successMessage, unknownEntityMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
@@ -8,23 +8,7 @@ import { loadCommandContext, taskDataToFrontmatter, } from "../shared/task-backe
 import { writeTextIfChanged } from "../../shared/write-if-changed.js";
 import { nowIso } from "./shared.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
-function insertMarkdownSectionBefore(opts) {
-    const normalized = opts.body.replaceAll("\r\n", "\n");
-    if (normalized.includes(`## ${opts.section}`)) {
-        return setMarkdownSection(normalized, opts.section, opts.text);
-    }
-    const lines = normalized.split("\n");
-    const beforeHeading = `## ${opts.beforeSection}`;
-    const beforeIdx = lines.findIndex((line) => line.trim() === beforeHeading);
-    if (beforeIdx === -1) {
-        // Fallback: append at the end if we can't find the insertion anchor.
-        return setMarkdownSection(normalized, opts.section, opts.text);
-    }
-    const textLines = opts.text.replaceAll("\r\n", "\n").split("\n");
-    const sectionLines = [`## ${opts.section}`, "", ...textLines, "", ""];
-    const out = [...lines.slice(0, beforeIdx), ...sectionLines, ...lines.slice(beforeIdx)];
-    return `${out.join("\n").trimEnd()}\n`;
-}
+import { defaultTaskDocV3, TASK_DOC_VERSION_V3 } from "./doc-template.js";
 export async function cmdTaskScaffold(opts) {
     try {
         const ctx = opts.ctx ??
@@ -79,7 +63,7 @@ export async function cmdTaskScaffold(opts) {
                 tags: [],
                 verify: [],
                 comments: [],
-                doc_version: 2,
+                doc_version: TASK_DOC_VERSION_V3,
                 doc_updated_at: nowIso(),
                 doc_updated_by: "UNKNOWN",
             };
@@ -90,41 +74,12 @@ export async function cmdTaskScaffold(opts) {
             baseTask.doc_updated_by.trim().toLowerCase() === "agentplane") {
             baseTask.doc_updated_by = baseTask.owner?.trim() ? baseTask.owner : "UNKNOWN";
         }
+        baseTask.doc_version = TASK_DOC_VERSION_V3;
         const frontmatter = taskDataToFrontmatter(baseTask);
-        const verifyStepsTemplate = [
-            "<!-- TODO: FILL VERIFY STEPS -->",
-            "",
-            "### Scope",
-            "",
-            "",
-            "### Checks",
-            "",
-            "",
-            "### Evidence / Commands",
-            "",
-            "",
-            "### Pass criteria",
-            "",
-            "",
-        ].join("\n");
-        const verificationTemplate = [
-            "### Plan",
-            "",
-            "",
-            "### Results",
-            "",
-            "",
-            "<!-- BEGIN VERIFICATION RESULTS -->",
-            "<!-- END VERIFICATION RESULTS -->",
-        ].join("\n");
-        const baseDoc = ensureDocSections("", config.tasks.doc.required_sections);
-        const withVerifySteps = insertMarkdownSectionBefore({
-            body: baseDoc,
-            section: "Verify Steps",
-            text: verifyStepsTemplate,
-            beforeSection: "Verification",
+        const body = defaultTaskDocV3({
+            title: baseTask.title,
+            description: baseTask.description ?? "",
         });
-        const body = setMarkdownSection(withVerifySteps, "Verification", verificationTemplate);
         const text = renderTaskReadme(frontmatter, body);
         await mkdir(path.dirname(readmePath), { recursive: true });
         await writeTextIfChanged(readmePath, text.endsWith("\n") ? text : `${text}\n`);

package/dist/commands/task/set-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-status.d.ts","sourceRoot":"","sources":["../../../src/commands/task/set-status.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgBnC,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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,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;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwJlB"}
+{"version":3,"file":"set-status.d.ts","sourceRoot":"","sources":["../../../src/commands/task/set-status.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAiBnC,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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,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;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwJlB"}

package/dist/commands/task/set-status.js

@@ -6,7 +6,7 @@ import { commitFromComment } from "../guard/index.js";
 import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { loadCommandContext, loadTaskFromContext, resolveDocUpdatedBy, } from "../shared/task-backend.js";
 import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
-import { appendTaskEvent, defaultCommitEmojiForStatus, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, normalizeTaskStatus, nowIso, readCommitInfo, resolveTaskDependencyState, resolvePrimaryTag, toStringArray, } from "./shared.js";
+import { appendTaskEvent, defaultCommitEmojiForStatus, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, normalizeTaskDocVersion, normalizeTaskStatus, nowIso, readCommitInfo, resolveTaskDependencyState, resolvePrimaryTag, toStringArray, } from "./shared.js";
 export async function cmdTaskSetStatus(opts) {
     const nextStatus = normalizeTaskStatus(opts.status);
     if (nextStatus === "DONE" && !opts.force) {
@@ -99,7 +99,7 @@ export async function cmdTaskSetStatus(opts) {
                 to: nextStatus,
                 note: commentBody,
             }),
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: eventAuthor,
         };

package/dist/commands/task/shared/dependencies.d.ts

@@ -0,0 +1,15 @@
+import type { TaskBackend, TaskData } from "../../../backends/task-backend.js";
+export type DependencyState = {
+    dependsOn: string[];
+    missing: string[];
+    incomplete: string[];
+};
+export declare function ensureTaskDependsOnGraphIsAcyclic(opts: {
+    backend: Pick<TaskBackend, "listTasks">;
+    taskId: string;
+    dependsOn: string[];
+}): Promise<void>;
+export declare function resolveTaskDependencyState(task: TaskData, backend: Pick<TaskBackend, "getTask" | "getTasks">): Promise<DependencyState>;
+export declare function buildDependencyState(tasks: TaskData[]): Map<string, DependencyState>;
+export declare function formatTaskLine(task: TaskData, depState?: DependencyState): string;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/commands/task/shared/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../../../src/commands/task/shared/dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAK/E,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAkCF,wBAAsB,iCAAiC,CAAC,IAAI,EAAE;IAC5D,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BhB;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,UAAU,CAAC,GACjD,OAAO,CAAC,eAAe,CAAC,CAuB1B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAqBpF;AAgBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,MAAM,CAejF"}