agentplane 0.3.6 → 0.3.8

package/dist/commands/task/hosted-merge-sync.js

@@ -0,0 +1,277 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { normalizeTaskDocVersion } from "@agentplaneorg/core";
+import { CliError } from "../../shared/errors.js";
+import { writeJsonStableIfChanged } from "../../shared/write-if-changed.js";
+import { execFileAsync } from "../shared/git.js";
+import { parseTaskIdFromBranch } from "../shared/git-worktree.js";
+import { parsePrMeta } from "../shared/pr-meta.js";
+import { appendTaskEvent } from "./shared.js";
+function normalizeMergedPr(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const number = typeof record.number === "number" ? record.number : null;
+    if (!number || number <= 0)
+        return null;
+    const mergeCommit = record.mergeCommit &&
+        typeof record.mergeCommit === "object" &&
+        !Array.isArray(record.mergeCommit)
+        ? {
+            oid: typeof record.mergeCommit.oid === "string"
+                ? String(record.mergeCommit.oid)
+                : null,
+        }
+        : null;
+    return {
+        number,
+        title: typeof record.title === "string" ? record.title : null,
+        url: typeof record.url === "string" ? record.url : null,
+        mergedAt: typeof record.mergedAt === "string" ? record.mergedAt : null,
+        baseRefName: typeof record.baseRefName === "string" ? record.baseRefName : null,
+        headRefName: typeof record.headRefName === "string" ? record.headRefName : null,
+        headRefOid: typeof record.headRefOid === "string" ? record.headRefOid : null,
+        mergeCommit,
+    };
+}
+function normalizePullRequestLike(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.merged !== true)
+        return null;
+    const number = typeof record.number === "number" ? record.number : null;
+    const mergeCommitSha = typeof record.merge_commit_sha === "string" && record.merge_commit_sha.trim().length > 0
+        ? record.merge_commit_sha.trim()
+        : null;
+    const head = record.head && typeof record.head === "object" && !Array.isArray(record.head)
+        ? record.head
+        : null;
+    const base = record.base && typeof record.base === "object" && !Array.isArray(record.base)
+        ? record.base
+        : null;
+    const headRefName = typeof head?.ref === "string" ? head.ref : null;
+    const headRefOid = typeof head?.sha === "string" ? head.sha : null;
+    const baseRefName = typeof base?.ref === "string" ? base.ref : null;
+    if (!number || number <= 0 || !mergeCommitSha || !headRefName)
+        return null;
+    return {
+        number,
+        title: typeof record.title === "string" ? record.title : null,
+        url: typeof record.html_url === "string" ? record.html_url : null,
+        mergedAt: typeof record.merged_at === "string" ? record.merged_at : null,
+        baseRefName,
+        headRefName,
+        headRefOid,
+        mergeCommit: { oid: mergeCommitSha },
+    };
+}
+function pickHostedMergedPr(records) {
+    const merged = records
+        .map((record) => normalizeMergedPr(record))
+        .filter((record) => !!record && !!record.mergeCommit?.oid);
+    if (merged.length === 0)
+        return null;
+    return (merged.toSorted((a, b) => {
+        const left = a.mergedAt ?? "";
+        const right = b.mergedAt ?? "";
+        return right.localeCompare(left);
+    })[0] ?? null);
+}
+export function resolveHostedMergeTargetFromEvent(opts) {
+    if (!opts.event || typeof opts.event !== "object" || Array.isArray(opts.event))
+        return null;
+    const pullRequest = opts.event.pull_request;
+    const mergedPr = normalizePullRequestLike(pullRequest);
+    if (!mergedPr?.headRefName || !mergedPr.mergeCommit?.oid)
+        return null;
+    const taskId = parseTaskIdFromBranch(opts.branchPrefix, mergedPr.headRefName);
+    if (!taskId)
+        return null;
+    return {
+        taskId,
+        branch: mergedPr.headRefName,
+        mergedPr,
+    };
+}
+async function resolveHostedMergedPr(opts) {
+    const { stdout } = await execFileAsync("gh", [
+        "pr",
+        "list",
+        "--state",
+        "merged",
+        "--head",
+        opts.branch,
+        "--json",
+        "number,title,url,mergedAt,baseRefName,headRefName,headRefOid,mergeCommit",
+    ], {
+        cwd: opts.cwd,
+        env: process.env,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const parsed = JSON.parse(stdout);
+    return Array.isArray(parsed) ? pickHostedMergedPr(parsed) : null;
+}
+function buildSyncedPrMeta(opts) {
+    const at = opts.mergedPr.mergedAt ?? new Date().toISOString();
+    return {
+        ...opts.meta,
+        branch: opts.branch,
+        status: "MERGED",
+        base: opts.mergedPr.baseRefName ?? opts.meta.base,
+        merge_strategy: opts.meta.merge_strategy,
+        merged_at: opts.meta.merged_at ?? at,
+        merge_commit: opts.mergedPr.mergeCommit?.oid ?? opts.meta.merge_commit,
+        head_sha: opts.mergedPr.headRefOid ?? opts.meta.head_sha,
+        updated_at: at,
+    };
+}
+function buildSyncedTask(opts) {
+    const at = opts.mergedPr.mergedAt ?? new Date().toISOString();
+    const currentStatus = String(opts.task.status || "TODO").toUpperCase();
+    const note = `Hosted PR #${opts.mergedPr.number} merged on GitHub main; ` +
+        "task projection reconciled from hosted PR artifacts.";
+    const statusEvent = {
+        type: "status",
+        at,
+        author: "INTEGRATOR",
+        from: currentStatus,
+        to: "DONE",
+        note,
+    };
+    const mergeHash = opts.mergedPr.mergeCommit?.oid ?? "";
+    const mergeMessage = opts.mergedPr.title?.trim();
+    return {
+        ...opts.task,
+        status: "DONE",
+        result_summary: opts.task.result_summary ?? `Merged via PR #${opts.mergedPr.number}.`,
+        commit: opts.task.commit?.hash?.trim()
+            ? opts.task.commit
+            : mergeHash
+                ? {
+                    hash: mergeHash,
+                    message: (mergeMessage && mergeMessage.length > 0 ? mergeMessage : null) ??
+                        `Hosted PR #${opts.mergedPr.number} merged on GitHub main`,
+                }
+                : null,
+        events: appendTaskEvent(opts.task, statusEvent),
+        doc_version: normalizeTaskDocVersion(opts.task.doc_version),
+        doc_updated_at: at,
+        doc_updated_by: "INTEGRATOR",
+    };
+}
+async function readPrMetaIfPresent(opts) {
+    const metaPath = path.join(opts.ctx.resolvedProject.gitRoot, opts.ctx.config.paths.workflow_dir, opts.taskId, "pr", "meta.json");
+    try {
+        const raw = await readFile(metaPath, "utf8");
+        return { meta: parsePrMeta(raw, opts.taskId), metaPath };
+    }
+    catch {
+        return null;
+    }
+}
+function needsHostedMergeSync(opts) {
+    const currentStatus = String(opts.task.status || "TODO").toUpperCase();
+    const expectedCommit = opts.mergedPr.mergeCommit?.oid ?? "";
+    const expectedBase = opts.mergedPr.baseRefName ?? opts.meta.base ?? "";
+    const expectedHeadSha = opts.mergedPr.headRefOid ?? opts.meta.head_sha ?? "";
+    if (currentStatus !== "DONE")
+        return true;
+    if ((opts.task.commit?.hash ?? "") !== expectedCommit)
+        return true;
+    if (opts.meta.status !== "MERGED")
+        return true;
+    if ((opts.meta.merge_commit ?? "") !== expectedCommit)
+        return true;
+    if ((opts.meta.branch ?? "") !== opts.branch)
+        return true;
+    if ((opts.meta.base ?? "") !== expectedBase)
+        return true;
+    if (opts.meta.head_sha?.trim() !== expectedHeadSha)
+        return true;
+    return false;
+}
+export async function syncHostedMergedTask(opts) {
+    if (opts.ctx.backendId !== "local" || opts.ctx.config.workflow_mode !== "branch_pr") {
+        return { tasks: opts.tasks, synced: 0 };
+    }
+    const task = opts.tasks.find((entry) => entry.id === opts.target.taskId);
+    if (!task) {
+        if (opts.missingTask === "error") {
+            throw new CliError({
+                exitCode: 3,
+                code: "E_VALIDATION",
+                message: `Hosted task closure could not find task artifact: ${opts.target.taskId}`,
+            });
+        }
+        return { tasks: opts.tasks, synced: 0 };
+    }
+    const prMetaRecord = await readPrMetaIfPresent({ ctx: opts.ctx, taskId: opts.target.taskId });
+    if (!prMetaRecord) {
+        if (opts.missingPrMeta === "error") {
+            throw new CliError({
+                exitCode: 3,
+                code: "E_VALIDATION",
+                message: `Hosted task closure could not find pr/meta.json for ${opts.target.taskId}`,
+            });
+        }
+        return { tasks: opts.tasks, synced: 0 };
+    }
+    if (!needsHostedMergeSync({
+        task,
+        meta: prMetaRecord.meta,
+        mergedPr: opts.target.mergedPr,
+        branch: opts.target.branch,
+    })) {
+        return { tasks: opts.tasks, synced: 0 };
+    }
+    const nextMeta = buildSyncedPrMeta({
+        meta: prMetaRecord.meta,
+        mergedPr: opts.target.mergedPr,
+        branch: opts.target.branch,
+    });
+    await writeJsonStableIfChanged(prMetaRecord.metaPath, nextMeta);
+    return {
+        tasks: opts.tasks.map((entry) => entry.id === opts.target.taskId
+            ? buildSyncedTask({ task: entry, mergedPr: opts.target.mergedPr })
+            : entry),
+        synced: 1,
+    };
+}
+export async function syncHostedMergedTasks(opts) {
+    if (opts.ctx.backendId !== "local" || opts.ctx.config.workflow_mode !== "branch_pr") {
+        return { tasks: opts.tasks, synced: 0 };
+    }
+    const nextTasks = [];
+    let synced = 0;
+    for (const task of opts.tasks) {
+        const prMetaRecord = await readPrMetaIfPresent({ ctx: opts.ctx, taskId: task.id });
+        if (!prMetaRecord) {
+            nextTasks.push(task);
+            continue;
+        }
+        const branch = prMetaRecord.meta.branch?.trim() ?? "";
+        if (!branch) {
+            nextTasks.push(task);
+            continue;
+        }
+        const mergedPr = await resolveHostedMergedPr({
+            cwd: opts.ctx.resolvedProject.gitRoot,
+            branch,
+        });
+        if (!mergedPr?.mergeCommit?.oid) {
+            nextTasks.push(task);
+            continue;
+        }
+        const syncedTask = await syncHostedMergedTask({
+            ctx: opts.ctx,
+            tasks: [task],
+            target: { taskId: task.id, branch, mergedPr },
+            missingTask: "noop",
+            missingPrMeta: "noop",
+        });
+        nextTasks.push(syncedTask.tasks[0] ?? task);
+        synced += syncedTask.synced;
+    }
+    return { tasks: nextTasks, synced };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/task/list.ts"],"names":[],"mappings":"AACA,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEnG,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ClB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/task/list.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAElB"}

package/dist/commands/task/list.js

@@ -1,40 +1,23 @@
 import { mapBackendError } from "../../cli/error-map.js";
-import { listTasksMemo, loadCommandContext } from "../shared/task-backend.js";
-import { buildDependencyState, dedupeStrings, formatTaskLine, handleTaskListWarnings, toStringArray, } from "./shared.js";
+import { listTaskSummariesMemo, loadCommandContext, } from "../shared/task-backend.js";
+import { formatTaskLine, handleTaskListWarnings, queryTaskProjection, } from "./shared.js";
 export async function cmdTaskListWithFilters(opts) {
     try {
         const ctx = opts.ctx ??
             (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
-        const tasks = await listTasksMemo(ctx);
+        const tasks = await listTaskSummariesMemo(ctx);
         handleTaskListWarnings({ backend: ctx.taskBackend, strictRead: opts.filters.strictRead });
-        const depState = buildDependencyState(tasks);
-        let filtered = tasks;
-        if (opts.filters.status.length > 0) {
-            const wanted = new Set(opts.filters.status.map((s) => s.trim().toUpperCase()));
-            filtered = filtered.filter((task) => wanted.has(String(task.status || "TODO").toUpperCase()));
-        }
-        if (opts.filters.owner.length > 0) {
-            const wanted = new Set(opts.filters.owner.map((o) => o.trim().toUpperCase()));
-            filtered = filtered.filter((task) => wanted.has(String(task.owner || "").toUpperCase()));
-        }
-        if (opts.filters.tag.length > 0) {
-            const wanted = new Set(opts.filters.tag.map((t) => t.trim()).filter(Boolean));
-            filtered = filtered.filter((task) => {
-                const tags = dedupeStrings(toStringArray(task.tags));
-                return tags.some((tag) => wanted.has(tag));
-            });
-        }
-        const sorted = filtered.toSorted((a, b) => a.id.localeCompare(b.id));
-        for (const task of sorted) {
+        const { depState, items } = queryTaskProjection({ tasks, filters: opts.filters });
+        for (const task of items) {
             process.stdout.write(`${formatTaskLine(task, depState.get(task.id))}\n`);
         }
         if (!opts.filters.quiet) {
             const counts = {};
-            for (const task of sorted) {
+            for (const task of items) {
                 const status = String(task.status || "TODO").toUpperCase();
                 counts[status] = (counts[status] ?? 0) + 1;
             }
-            const total = sorted.length;
+            const total = items.length;
             const summary = Object.keys(counts)
                 .toSorted()
                 .map((key) => `${key}=${counts[key]}`)

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

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

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

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

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

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

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

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

package/dist/commands/task/new.js

@@ -2,6 +2,7 @@ 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 { buildTaskDocState } from "../../shared/task-doc-state.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";
@@ -66,6 +67,13 @@ export async function runTaskNewParsed(opts) {
             });
         }
         const taskId = await ctx.taskBackend.generateTaskId({ length: suffixLength, attempts: 1000 });
+        const docState = buildTaskDocState({
+            doc: defaultTaskDocV3({ title: p.title, description: p.description }),
+            owner: p.owner,
+            updatedBy: p.owner,
+            version: TASK_DOC_VERSION_V3,
+            updatedAt: nowIso(),
+        });
         const task = {
             id: taskId,
             title: p.title,
@@ -73,15 +81,17 @@ export async function runTaskNewParsed(opts) {
             status: "TODO",
             priority: p.priority,
             owner: p.owner,
+            revision: 1,
+            origin: { system: "manual" },
             tags: p.tags,
             depends_on: p.dependsOn,
             verify: p.verify,
             comments: [],
-            doc_version: TASK_DOC_VERSION_V3,
-            doc_updated_at: nowIso(),
-            doc_updated_by: p.owner,
+            doc_version: docState.doc_version,
+            doc_updated_at: docState.doc_updated_at,
+            doc_updated_by: docState.doc_updated_by,
             id_source: "generated",
-            doc: defaultTaskDocV3({ title: p.title, description: p.description }),
+            doc: docState.doc,
         };
         const spikeTag = (ctx.config.tasks.verify.spike_tag ?? "spike").trim().toLowerCase();
         const primary = resolvePrimaryTag(p.tags, ctx);
@@ -107,6 +117,18 @@ export async function runTaskNewParsed(opts) {
         if (hasSpike && hasImplementationTags) {
             process.stderr.write(`${warnMessage("spike is combined with a primary tag that requires verify steps; consider splitting spike vs implementation tasks")}\n`);
         }
+        const normalizedDoc = buildTaskDocState({
+            doc: task.doc ?? "",
+            owner: p.owner,
+            updatedBy: task.doc_updated_by,
+            version: TASK_DOC_VERSION_V3,
+            updatedAt: task.doc_updated_at,
+        });
+        task.doc = normalizedDoc.doc;
+        task.sections = normalizedDoc.sections;
+        task.doc_version = normalizedDoc.doc_version;
+        task.doc_updated_at = normalizedDoc.doc_updated_at;
+        task.doc_updated_by = normalizedDoc.doc_updated_by;
         await ctx.taskBackend.writeTask(task);
         process.stdout.write(`${taskId}\n`);
         return 0;

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

@@ -1 +1 @@
-{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../../src/commands/task/next.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEpF,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ClB"}
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../../src/commands/task/next.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBlB"}