agentplane 0.3.6 → 0.3.7

package/dist/commands/task/verify-record.js

@@ -7,8 +7,8 @@ import { backendNotSupportedMessage, successMessage } from "../../cli/output.js"
 import { CliError } from "../../shared/errors.js";
 import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
-import { appendTaskEvent, extractDocSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, nowIso, VERIFICATION_RESULTS_BEGIN, VERIFICATION_RESULTS_END, } from "./shared.js";
+import { appendTaskEventIntent, backendIsLocalFileBackend, getTaskStore, setTaskFieldsIntent, setTaskSectionIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
+import { appendTaskEvent, decodeEscapedTaskTextNewlines, extractDocSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, nowIso, VERIFICATION_RESULTS_BEGIN, VERIFICATION_RESULTS_END, } from "./shared.js";
 function appendBetweenMarkers(sectionText, entryText, version) {
     const ensured = normalizeVerificationSectionLayout(sectionText, version);
     const beginIdx = ensured.indexOf(VERIFICATION_RESULTS_BEGIN);
@@ -65,12 +65,10 @@ async function recordVerificationResult(opts) {
     }
     const useStore = backendIsLocalFileBackend(ctx);
     const store = useStore ? getTaskStore(ctx) : null;
-    const task = useStore
-        ? await store.get(opts.taskId)
-        : await loadTaskFromContext({ ctx, taskId: opts.taskId });
+    const task = useStore ? null : await loadTaskFromContext({ ctx, taskId: opts.taskId });
     const at = nowIso();
     if (useStore) {
-        await store.patch(opts.taskId, (current) => {
+        await store.mutate(opts.taskId, (current) => {
             const existingDoc = String(current.doc ?? "");
             const baseDoc = ensureDocSections(existingDoc, config.tasks.doc.required_sections);
             const verificationSection = extractDocSection(baseDoc, "Verification") ?? "";
@@ -93,8 +91,8 @@ async function recordVerificationResult(opts) {
                 verifyStepsRef,
             });
             const nextVerification = appendBetweenMarkers(verificationSection, entry, docVersion);
-            return {
-                task: {
+            return [
+                setTaskFieldsIntent({
                     status: opts.state === "needs_rework" ? "DOING" : current.status,
                     commit: opts.state === "needs_rework" ? null : (current.commit ?? null),
                     verification: {
@@ -103,38 +101,37 @@ async function recordVerificationResult(opts) {
                         updated_by: opts.by,
                         note: opts.note,
                     },
-                },
-                doc: {
-                    kind: "set-section",
+                }),
+                setTaskSectionIntent({
                     section: "Verification",
                     text: nextVerification,
                     requiredSections: config.tasks.doc.required_sections,
-                },
-                appendEvents: [
-                    {
-                        type: "verify",
-                        at,
-                        author: opts.by,
-                        state: opts.state,
-                        note: opts.note,
-                    },
-                ],
-                docMeta: { updatedBy: opts.by },
-            };
+                }),
+                appendTaskEventIntent({
+                    type: "verify",
+                    at,
+                    author: opts.by,
+                    state: opts.state,
+                    note: opts.note,
+                }),
+                touchTaskDocMetaIntent({ updatedBy: opts.by }),
+            ];
         });
     }
     else {
-        const existingDoc = (typeof task.doc === "string" ? task.doc : "") || (await backend.getTaskDoc(task.id));
+        const remoteTask = task;
+        const existingDoc = (typeof remoteTask.doc === "string" ? remoteTask.doc : "") ||
+            (await backend.getTaskDoc(remoteTask.id));
         const baseDoc = ensureDocSections(existingDoc ?? "", config.tasks.doc.required_sections);
         const verificationSection = extractDocSection(baseDoc, "Verification") ?? "";
         const verifySteps = extractDocSection(baseDoc, "Verify Steps");
         const verifyStepsHash = verifySteps
             ? sha256Hex(verifySteps.replaceAll("\r\n", "\n").trim())
             : null;
-        const docVersion = normalizeTaskDocVersion(task.doc_version);
+        const docVersion = normalizeTaskDocVersion(remoteTask.doc_version);
         const verifyStepsRef = [
             `doc_version=${String(docVersion)}`,
-            `doc_updated_at=${String(task.doc_updated_at ?? "missing")}`,
+            `doc_updated_at=${String(remoteTask.doc_updated_at ?? "missing")}`,
             `excerpt_hash=sha256:${verifyStepsHash ?? "missing"}`,
         ].join(", ");
         const entry = renderVerificationEntry({
@@ -148,12 +145,12 @@ async function recordVerificationResult(opts) {
         const nextVerification = appendBetweenMarkers(verificationSection, entry, docVersion);
         const nextDoc = ensureDocSections(setMarkdownSection(baseDoc, "Verification", nextVerification), config.tasks.doc.required_sections);
         await backend.writeTask({
-            ...task,
-            status: opts.state === "needs_rework" ? "DOING" : task.status,
-            commit: opts.state === "needs_rework" ? null : (task.commit ?? null),
+            ...remoteTask,
+            status: opts.state === "needs_rework" ? "DOING" : remoteTask.status,
+            commit: opts.state === "needs_rework" ? null : (remoteTask.commit ?? null),
             doc: nextDoc,
             doc_updated_by: opts.by,
-            events: appendTaskEvent(task, {
+            events: appendTaskEvent(remoteTask, {
                 type: "verify",
                 at,
                 author: opts.by,
@@ -169,9 +166,9 @@ async function recordVerificationResult(opts) {
         });
     }
     if (!opts.quiet) {
-        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, task.id, "README.md");
+        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, opts.taskId, "README.md");
         const relReadmePath = path.relative(resolved.gitRoot, readmePath);
-        process.stdout.write(`${successMessage("verified", task.id, `state=${opts.state} readme=${relReadmePath}`)}\n`);
+        process.stdout.write(`${successMessage("verified", opts.taskId, `state=${opts.state} readme=${relReadmePath}`)}\n`);
     }
 }
 async function resolveVerifyRecordInput(opts) {
@@ -200,6 +197,9 @@ async function resolveVerifyRecordInput(opts) {
             throw mapCoreError(err, { command: opts.command, filePath: opts.file });
         }
     }
+    if (typeof details === "string") {
+        details = decodeEscapedTaskTextNewlines(details);
+    }
     return { by, note, details };
 }
 async function executeVerifyRecordCommand(opts) {

package/dist/commands/upgrade/apply.d.ts

@@ -7,6 +7,8 @@ export declare function ensureCleanTrackedTreeForUpgrade(gitRoot: string): Promi
 export declare function createUpgradeCommit(opts: {
     gitRoot: string;
     paths: string[];
+    tasksPath: string;
+    workflowDir: string;
     versionLabel: string;
     source: "local_assets" | "upgrade_bundle" | "repo_tarball";
     additions: number;

package/dist/commands/upgrade/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/apply.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAUtD,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BrF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoEpD;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ChB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,mBAAmB,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4CnB"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/apply.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAUtD,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BrF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA8FpD;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ChB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,mBAAmB,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAC3D,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4CnB"}

package/dist/commands/upgrade/apply.js

@@ -5,6 +5,7 @@ import { backupPath, fileExists } from "../../cli/fs-utils.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { withDiagnosticContext } from "../../shared/diagnostics.js";
 import { CliError } from "../../shared/errors.js";
+import { protectedPathKindForFile } from "../../shared/protected-paths.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
 async function safeRemovePath(targetPath) {
     try {
@@ -74,10 +75,41 @@ export async function createUpgradeCommit(opts) {
         `Source: ${opts.source}\n` +
         `Managed-Changes: add=${opts.additions}, update=${opts.updates}, unchanged=${opts.unchanged}\n` +
         `Incidents-Appended: ${opts.incidentsAppendedCount}\n`;
+    const allow = {
+        allowTasks: false,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+    };
+    for (const filePath of uniquePaths) {
+        const kind = protectedPathKindForFile({
+            filePath,
+            tasksPath: opts.tasksPath,
+            workflowDir: opts.workflowDir,
+        });
+        if (kind === "tasks")
+            allow.allowTasks = true;
+        if (kind === "policy")
+            allow.allowPolicy = true;
+        if (kind === "config")
+            allow.allowConfig = true;
+        if (kind === "hooks")
+            allow.allowHooks = true;
+        if (kind === "ci")
+            allow.allowCI = true;
+    }
     try {
         await execFileAsync("git", ["commit", "-m", subject, "-m", body], {
             cwd: opts.gitRoot,
-            env: gitEnv(),
+            env: {
+                ...gitEnv(),
+                AGENTPLANE_ALLOW_TASKS: allow.allowTasks ? "1" : "0",
+                AGENTPLANE_ALLOW_POLICY: allow.allowPolicy ? "1" : "0",
+                AGENTPLANE_ALLOW_CONFIG: allow.allowConfig ? "1" : "0",
+                AGENTPLANE_ALLOW_HOOKS: allow.allowHooks ? "1" : "0",
+                AGENTPLANE_ALLOW_CI: allow.allowCI ? "1" : "0",
+            },
             maxBuffer: 10 * 1024 * 1024,
         });
     }

package/dist/commands/upgrade.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CA8JlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}
+{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAwLlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}

package/dist/commands/upgrade.command.js

@@ -72,6 +72,12 @@ export const upgradeSpec = {
             default: false,
             description: "Report changes without modifying files.",
         },
+        {
+            kind: "boolean",
+            name: "migrate-task-docs",
+            default: false,
+            description: "After applying the framework upgrade, migrate legacy task README docs in the same run.",
+        },
         {
             kind: "boolean",
             name: "no-backup",
@@ -115,6 +121,10 @@ export const upgradeSpec = {
             cmd: "agentplane upgrade --bundle ./agentplane-upgrade.tar.gz --checksum ./agentplane-upgrade.tar.gz.sha256",
             why: "Upgrade from local bundle files (no network).",
         },
+        {
+            cmd: "agentplane upgrade --yes --migrate-task-docs",
+            why: "Apply the framework upgrade and migrate legacy task README docs in one operator run.",
+        },
     ],
     parse: (raw) => {
         const noBackup = raw.opts["no-backup"] === true;
@@ -130,6 +140,7 @@ export const upgradeSpec = {
             checksumAsset: raw.opts["checksum-asset"],
             dryRun: raw.opts["dry-run"] === true,
             backup: !noBackup,
+            migrateTaskDocs: raw.opts["migrate-task-docs"] === true,
             yes: raw.opts.yes === true,
         };
     },
@@ -151,6 +162,20 @@ export const upgradeSpec = {
                 message: "Remote upgrade options (--tag/--source/--asset/--checksum-asset) require --remote.",
             });
         }
+        if (p.migrateTaskDocs && p.mode === "agent") {
+            throw usageError({
+                spec: upgradeSpec,
+                command: "upgrade",
+                message: "Option --migrate-task-docs cannot be used with --agent.",
+            });
+        }
+        if (p.migrateTaskDocs && p.dryRun) {
+            throw usageError({
+                spec: upgradeSpec,
+                command: "upgrade",
+                message: "Option --migrate-task-docs cannot be used with --dry-run.",
+            });
+        }
     },
 };
 export const runUpgrade = (ctx, flags) => cmdUpgradeParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, flags });

package/dist/commands/upgrade.d.ts

@@ -10,6 +10,7 @@ export type UpgradeFlags = {
     allowTarball: boolean;
     dryRun: boolean;
     backup: boolean;
+    migrateTaskDocs: boolean;
     yes: boolean;
 };
 export declare function cmdUpgradeParsed(opts: {

package/dist/commands/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA4CA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAuMF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsiBlB;AAED,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA+CA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,OAAO,CAAC;IACzB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAuMF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2kBlB;AAED,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}

package/dist/commands/upgrade.js

@@ -11,7 +11,10 @@ import { exitCodeForError } from "../cli/exit-codes.js";
 import { warnMessage } from "../cli/output.js";
 import { CliError } from "../shared/errors.js";
 import { ensureWorkflowArtifacts } from "../shared/workflow-artifacts.js";
+import { checkTaskReadmeMigrationState } from "./doctor/workspace.js";
+import { loadCommandContext } from "./shared/task-backend.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
+import { migrateTaskDocsInWorkspace } from "./task/migrate-doc.js";
 import { getVersion } from "../meta/version.js";
 import { applyManagedFiles, cleanupAutoUpgradeArtifacts, createUpgradeCommit, ensureCleanTrackedTreeForUpgrade, persistUpgradeState, } from "./upgrade/apply.js";
 import { printUpgradeDryRun, writeUpgradeAgentReview } from "./upgrade/report.js";
@@ -210,6 +213,12 @@ export async function cmdUpgradeParsed(opts) {
         rootOverride: opts.rootOverride ?? null,
     });
     const loaded = await loadConfig(resolved.agentplaneDir);
+    const commandCtx = await loadCommandContext({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+        resolvedProject: resolved,
+        config: loaded.config,
+    });
     if (flags.mode === "auto" && !flags.dryRun) {
         await ensureCleanTrackedTreeForUpgrade(resolved.gitRoot);
     }
@@ -624,6 +633,21 @@ export async function cmdUpgradeParsed(opts) {
             createdBackups,
             toBaselineKey,
         });
+        const migratedTaskDocs = flags.migrateTaskDocs
+            ? await migrateTaskDocsInWorkspace({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+                all: true,
+                taskIds: [],
+                resolvedProject: resolved,
+                config: loaded.config,
+                ctx: commandCtx,
+            })
+            : { changed: 0, changedPaths: [] };
+        if (flags.migrateTaskDocs) {
+            const details = migratedTaskDocs.changed > 0 ? `changed=${migratedTaskDocs.changed}` : "already current";
+            process.stdout.write(`Task README migration: ${details}\n`);
+        }
         const hasManagedMutations = additions.length > 0 || updates.length > 0;
         const shouldMutateConfig = await persistUpgradeState({
             agentplaneDir: resolved.agentplaneDir,
@@ -655,6 +679,7 @@ export async function cmdUpgradeParsed(opts) {
             ...new Set([
                 ...additions,
                 ...updates,
+                ...migratedTaskDocs.changedPaths,
                 ...workflowArtifacts.commitPaths,
                 ...(shouldMutateConfig ? [CONFIG_REL_PATH] : []),
             ]),
@@ -662,6 +687,8 @@ export async function cmdUpgradeParsed(opts) {
         const commit = await createUpgradeCommit({
             gitRoot: resolved.gitRoot,
             paths: commitPaths,
+            tasksPath: loaded.config.paths.tasks_path,
+            workflowDir: loaded.config.paths.workflow_dir,
             versionLabel: upgradeVersionLabel,
             source: bundleLayout,
             additions: additions.length,
@@ -677,6 +704,13 @@ export async function cmdUpgradeParsed(opts) {
         if (commit) {
             process.stdout.write(`Upgrade commit: ${commit.hash.slice(0, 12)} ${commit.subject}\n`);
         }
+        const taskReadmeMigrationFindings = await checkTaskReadmeMigrationState(resolved.gitRoot, commandCtx);
+        if (taskReadmeMigrationFindings.length > 0) {
+            process.stderr.write(`${warnMessage("upgrade post-check: task README migration follow-up detected")}\n`);
+            for (const finding of taskReadmeMigrationFindings) {
+                process.stderr.write(`- ${finding}\n`);
+            }
+        }
         return 0;
     }
     finally {

package/dist/policy/rules/allowlist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/allowlist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAmD9D"}
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/allowlist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAqD9D"}

package/dist/policy/rules/allowlist.js

@@ -1,18 +1,21 @@
 import { gitPathIsUnderPrefix, normalizeGitPathPrefix } from "../../shared/git-path.js";
-import { taskArtifactPrefixes } from "../../shared/protected-paths.js";
+import { protectedPathAllowPrefixes } from "../../shared/protected-paths.js";
 import { gitError, okResult } from "../result.js";
 export function allowlistRule(ctx) {
     const allowRaw = ctx.allow?.prefixes ?? [];
     const staged = ctx.git.stagedPaths ?? [];
     const allow = allowRaw.map((p) => normalizeGitPathPrefix(p));
-    const taskAllow = ctx.allow?.allowTasks === true
-        ? taskArtifactPrefixes({
-            tasksPath: ctx.config.paths.tasks_path,
-            workflowDir: ctx.config.paths.workflow_dir,
-            taskId: ctx.taskId,
-        })
-        : [];
-    const effectiveAllow = [...new Set([...allow, ...taskAllow])];
+    const protectedAllow = protectedPathAllowPrefixes({
+        tasksPath: ctx.config.paths.tasks_path,
+        workflowDir: ctx.config.paths.workflow_dir,
+        taskId: ctx.taskId,
+        allowTasks: ctx.allow?.allowTasks === true,
+        allowPolicy: ctx.allow?.allowPolicy === true,
+        allowConfig: ctx.allow?.allowConfig === true,
+        allowHooks: ctx.allow?.allowHooks === true,
+        allowCI: ctx.allow?.allowCI === true,
+    });
+    const effectiveAllow = [...new Set([...allow, ...protectedAllow])];
     if (staged.length === 0) {
         return { ok: false, errors: [gitError("No staged files (git index empty)")], warnings: [] };
     }

package/dist/ports/task-backend-port.d.ts

@@ -1,8 +1,8 @@
-import type { TaskData } from "../backends/task-backend.js";
+import type { TaskData, TaskWriteOptions } from "../backends/task-backend.js";
 export type TaskBackendPort = {
     listTasks(): Promise<TaskData[]>;
     getTask(id: string): Promise<TaskData | null>;
-    writeTask(task: TaskData): Promise<void>;
+    writeTask(task: TaskData, opts?: TaskWriteOptions): Promise<void>;
     exportProjectionSnapshot(path: string): Promise<void>;
 };
 //# sourceMappingURL=task-backend-port.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"task-backend-port.d.ts","sourceRoot":"","sources":["../../src/ports/task-backend-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC"}
+{"version":3,"file":"task-backend-port.d.ts","sourceRoot":"","sources":["../../src/ports/task-backend-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE9E,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC"}

package/dist/shared/protected-paths.d.ts

@@ -9,6 +9,16 @@ export declare function taskArtifactPrefixes(opts: {
     workflowDir?: string;
     taskId?: string;
 }): string[];
+export declare function protectedPathAllowPrefixes(opts: {
+    tasksPath: string;
+    workflowDir?: string;
+    taskId?: string;
+    allowTasks?: boolean;
+    allowPolicy?: boolean;
+    allowConfig?: boolean;
+    allowHooks?: boolean;
+    allowCI?: boolean;
+}): string[];
 export declare function getProtectedPathOverride(kind: ProtectedPathKind): ProtectedPathOverride;
 export declare function protectedPathKindForFile(opts: {
     filePath: string;

package/dist/shared/protected-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAYF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,EAAE,CAOX;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,iBAAiB,GAAG,IAAI,CAsC3B"}
+{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAYF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,EAAE,CAOX;AAYD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,EAAE,CAkBX;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,iBAAiB,GAAG,IAAI,CAsC3B"}

package/dist/shared/protected-paths.js

@@ -16,6 +16,39 @@ export function taskArtifactPrefixes(opts) {
         out.add(workflowPrefix);
     return [...out].toSorted((a, b) => a.localeCompare(b));
 }
+const POLICY_PATH_PREFIXES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "packages/agentplane/assets/AGENTS.md",
+    ".agentplane/agents",
+];
+const CONFIG_PATH_PREFIXES = [".agentplane/config.json", ".agentplane/backends"];
+const HOOK_PATH_PREFIXES = ["lefthook.yml"];
+const CI_PATH_PREFIXES = [".github/workflows", ".github/actions"];
+export function protectedPathAllowPrefixes(opts) {
+    const out = new Set();
+    if (opts.allowTasks) {
+        for (const prefix of taskArtifactPrefixes(opts))
+            out.add(prefix);
+    }
+    if (opts.allowPolicy) {
+        for (const prefix of POLICY_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowConfig) {
+        for (const prefix of CONFIG_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowHooks) {
+        for (const prefix of HOOK_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowCI) {
+        for (const prefix of CI_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    return [...out].toSorted((a, b) => a.localeCompare(b));
+}
 export function getProtectedPathOverride(kind) {
     switch (kind) {
         case "tasks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -55,7 +55,7 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.3.6",
+    "@agentplaneorg/core": "0.3.7",
     "yauzl": "^2.10.0"
   },
   "devDependencies": {