agentplane 0.3.1 → 0.3.3

package/dist/commands/task/start.js

@@ -7,7 +7,7 @@ import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
 import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
 import { readDirectWorkLock } from "../../shared/direct-work-lock.js";
-import { appendTaskEvent, ensurePlanApprovedIfRequired, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, defaultCommitEmojiForAgentId, extractDocSection, isVerifyStepsFilled, nowIso, requiresVerifyStepsByPrimary, requireStructuredComment, resolveTaskDependencyState, resolvePrimaryTag, toStringArray, } from "./shared.js";
+import { appendTaskEvent, ensurePlanApprovedIfRequired, ensureCommentCommitAllowed, ensureStatusTransitionAllowed, extractTaskObservationSection, defaultCommitEmojiForAgentId, extractDocSection, isVerifyStepsFilled, normalizeTaskDocVersion, nowIso, requiresVerifyStepsByPrimary, requireStructuredComment, resolveTaskDependencyState, resolvePrimaryTag, taskObservationSectionName, toStringArray, } from "./shared.js";
 export async function cmdStart(opts) {
     try {
         const ctx = opts.ctx ??
@@ -47,12 +47,14 @@ export async function cmdStart(opts) {
                     }
                 }
                 if (isSpike) {
-                    const notes = extractDocSection(doc, "Notes");
-                    if (!notes || notes.trim().length === 0) {
+                    const docVersion = normalizeTaskDocVersion(task.doc_version);
+                    const observationSection = taskObservationSectionName(docVersion);
+                    const observation = extractTaskObservationSection(doc, docVersion);
+                    if (!observation || observation.trim().length === 0) {
                         throw new CliError({
                             exitCode: 3,
                             code: "E_VALIDATION",
-                            message: `${task.id}: cannot start spike: ## Notes section is missing or empty ` +
+                            message: `${task.id}: cannot start spike: ## ${observationSection} section is missing or empty ` +
                                 "(include Findings/Decision/Next Steps)",
                         });
                     }
@@ -117,7 +119,7 @@ export async function cmdStart(opts) {
                 to: "DOING",
                 note: commentBody,
             }),
-            doc_version: 2,
+            doc_version: normalizeTaskDocVersion(task.doc_version),
             doc_updated_at: at,
             doc_updated_by: opts.author,
         };

package/dist/commands/task/verify-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-record.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-record.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAKnC,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AAkKzC,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,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,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;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,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,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB"}
+{"version":3,"file":"verify-record.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-record.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAanC,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AAgJzC,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,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,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;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,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,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB"}

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

@@ -8,28 +8,11 @@ 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, nowIso } from "./shared.js";
-const RESULTS_BEGIN = "<!-- BEGIN VERIFICATION RESULTS -->";
-const RESULTS_END = "<!-- END VERIFICATION RESULTS -->";
-function ensureVerificationResultsMarkers(sectionText) {
-    const normalized = sectionText.replaceAll("\r\n", "\n").trimEnd();
-    if (!normalized) {
-        return ["### Plan", "", "", "### Results", "", "", RESULTS_BEGIN, RESULTS_END].join("\n");
-    }
-    const hasBegin = normalized.includes(RESULTS_BEGIN);
-    const hasEnd = normalized.includes(RESULTS_END);
-    if (hasBegin && hasEnd)
-        return normalized;
-    const out = [normalized];
-    if (!normalized.endsWith("\n"))
-        out.push("");
-    out.push("", RESULTS_BEGIN, RESULTS_END);
-    return out.join("\n").trimEnd();
-}
-function appendBetweenMarkers(sectionText, entryText) {
-    const ensured = ensureVerificationResultsMarkers(sectionText);
-    const beginIdx = ensured.indexOf(RESULTS_BEGIN);
-    const endIdx = ensured.indexOf(RESULTS_END);
+import { appendTaskEvent, 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);
+    const endIdx = ensured.indexOf(VERIFICATION_RESULTS_END);
     if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
         throw new Error("Verification results markers are malformed");
     }
@@ -38,7 +21,7 @@ function appendBetweenMarkers(sectionText, entryText) {
     const entry = entryText.trimEnd();
     const parts = [
         beforeEnd,
-        ...(beforeEnd.endsWith(RESULTS_BEGIN) ? [] : [""]),
+        ...(beforeEnd.endsWith(VERIFICATION_RESULTS_BEGIN) ? [] : [""]),
         entry,
         "",
         afterEnd,
@@ -94,8 +77,9 @@ async function recordVerificationResult(opts) {
     const verifyStepsHash = verifySteps
         ? sha256Hex(verifySteps.replaceAll("\r\n", "\n").trim())
         : null;
+    const docVersion = normalizeTaskDocVersion(task.doc_version);
     const verifyStepsRef = [
-        `doc_version=${String(task.doc_version ?? "missing")}`,
+        `doc_version=${String(docVersion)}`,
         `doc_updated_at=${String(task.doc_updated_at ?? "missing")}`,
         `excerpt_hash=sha256:${verifyStepsHash ?? "missing"}`,
     ].join(", ");
@@ -108,7 +92,7 @@ async function recordVerificationResult(opts) {
         details: opts.details ?? null,
         verifyStepsRef,
     });
-    const nextVerification = appendBetweenMarkers(verificationSection, entry);
+    const nextVerification = appendBetweenMarkers(verificationSection, entry, docVersion);
     const nextDoc = ensureDocSections(setMarkdownSection(baseDoc, "Verification", nextVerification), config.tasks.doc.required_sections);
     const nextTask = {
         ...task,

package/dist/commands/task/verify-show.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-show.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-show.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAyBhE,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC7E,KAAK,UAAU,EAAE,GAAG,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAAC,CAUzE"}
+{"version":3,"file":"verify-show.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/verify-show.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CA6BhE,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC7E,KAAK,UAAU,EAAE,GAAG,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAAC,CAUzE"}

package/dist/commands/task/verify-show.command.js

@@ -2,7 +2,7 @@ import { cmdTaskDocShow } from "./doc.js";
 export const taskVerifyShowSpec = {
     id: ["task", "verify-show"],
     group: "Task",
-    summary: 'Print the task Verify Steps section (alias for task doc show --section "Verify Steps").',
+    summary: 'Print the task Verify Steps acceptance contract (alias for task doc show --section "Verify Steps").',
     args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
     options: [
         {
@@ -19,6 +19,10 @@ export const taskVerifyShowSpec = {
             why: "Print Verify Steps without erroring when missing.",
         },
     ],
+    notes: [
+        "`## Verify Steps` is the ex-ante acceptance contract for the verifier.",
+        "Verification results are recorded later in `## Verification` via `agentplane verify ...`.",
+    ],
     parse: (raw) => ({
         taskId: String(raw.args["task-id"]),
         quiet: raw.opts.quiet === true,

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

@@ -0,0 +1,44 @@
+import type { UpgradeReviewRecord } from "./types.js";
+export declare function cleanupAutoUpgradeArtifacts(opts: {
+    upgradeStateDir: string;
+    createdBackups: string[];
+}): Promise<void>;
+export declare function ensureCleanTrackedTreeForUpgrade(gitRoot: string): Promise<void>;
+export declare function createUpgradeCommit(opts: {
+    gitRoot: string;
+    paths: string[];
+    versionLabel: string;
+    source: "local_assets" | "upgrade_bundle" | "repo_tarball";
+    additions: number;
+    updates: number;
+    unchanged: number;
+    incidentsAppendedCount: number;
+}): Promise<{
+    hash: string;
+    subject: string;
+} | null>;
+export declare function applyManagedFiles(opts: {
+    gitRoot: string;
+    additions: string[];
+    updates: string[];
+    backup: boolean;
+    fileContents: Map<string, Buffer>;
+    baselineDir: string;
+    createdBackups: string[];
+    toBaselineKey: (rel: string) => string | null;
+}): Promise<void>;
+export declare function persistUpgradeState(opts: {
+    agentplaneDir: string;
+    rawConfig: Record<string, unknown>;
+    normalizedSourceToPersist: string | null;
+    expectedCliVersionToPersist: string | null;
+    hasManagedMutations: boolean;
+    statePath: string;
+    upgradeStateDir: string;
+    source: "local_assets" | "upgrade_bundle" | "repo_tarball";
+    reviewRecords: UpgradeReviewRecord[];
+    additions: number;
+    updates: number;
+    skipped: number;
+}): Promise<boolean>;
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/upgrade/apply.js

@@ -0,0 +1,180 @@
+import { lstat, mkdir, readlink, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { saveConfig, setByDottedKey } from "@agentplaneorg/core";
+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 { execFileAsync, gitEnv } from "../shared/git.js";
+async function safeRemovePath(targetPath) {
+    try {
+        await rm(targetPath, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
+export async function cleanupAutoUpgradeArtifacts(opts) {
+    for (const backupPath of opts.createdBackups) {
+        await safeRemovePath(backupPath);
+    }
+    await safeRemovePath(path.join(opts.upgradeStateDir, "agent"));
+}
+export async function ensureCleanTrackedTreeForUpgrade(gitRoot) {
+    const { stdout } = await execFileAsync("git", ["status", "--short", "--untracked-files=no"], {
+        cwd: gitRoot,
+        env: gitEnv(),
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const dirty = String(stdout ?? "")
+        .split(/\r?\n/u)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+    if (dirty.length === 0)
+        return;
+    throw new CliError({
+        exitCode: exitCodeForError("E_GIT"),
+        code: "E_GIT",
+        message: "Upgrade --auto requires a clean tracked working tree.\n" +
+            `Found tracked changes:\n${dirty.map((line) => `  ${line}`).join("\n")}`,
+        context: withDiagnosticContext({ command: "upgrade" }, {
+            state: "managed upgrade cannot apply over tracked local edits",
+            likelyCause: "auto-apply upgrade is about to replace framework-managed files, but the repository already has tracked modifications",
+            nextAction: {
+                command: "git status --short --untracked-files=no",
+                reason: "inspect or clear tracked changes before rerunning `agentplane upgrade --yes`",
+                reasonCode: "upgrade_dirty_tree",
+            },
+        }),
+    });
+}
+export async function createUpgradeCommit(opts) {
+    const uniquePaths = [...new Set(opts.paths.filter(Boolean))];
+    if (uniquePaths.length === 0)
+        return null;
+    await execFileAsync("git", ["add", "--", ...uniquePaths], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const { stdout: stagedOut } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+        encoding: "buffer",
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const staged = (Buffer.isBuffer(stagedOut) ? stagedOut.toString("utf8") : String(stagedOut ?? ""))
+        .split("\0")
+        .map((entry) => entry.trim())
+        .some(Boolean);
+    if (!staged)
+        return null;
+    const subject = `⬆️ upgrade: apply framework ${opts.versionLabel}`;
+    const body = `Upgrade-Version: ${opts.versionLabel}\n` +
+        `Source: ${opts.source}\n` +
+        `Managed-Changes: add=${opts.additions}, update=${opts.updates}, unchanged=${opts.unchanged}\n` +
+        `Incidents-Appended: ${opts.incidentsAppendedCount}\n`;
+    try {
+        await execFileAsync("git", ["commit", "-m", subject, "-m", body], {
+            cwd: opts.gitRoot,
+            env: gitEnv(),
+            maxBuffer: 10 * 1024 * 1024,
+        });
+    }
+    catch (err) {
+        const details = err?.stderr ?? "";
+        throw new CliError({
+            exitCode: exitCodeForError("E_GIT"),
+            code: "E_GIT",
+            message: "Upgrade applied but failed to create the upgrade commit.\n" +
+                "Fix commit policy/hook issues and commit the staged upgrade files as a dedicated upgrade commit.\n" +
+                (String(details).trim() ? `Details:\n${String(details).trim()}` : ""),
+            context: withDiagnosticContext({ command: "upgrade" }, {
+                state: "managed files were updated, but the upgrade commit was blocked",
+                likelyCause: "the generated upgrade commit hit a git hook or commit policy failure after the framework files were already staged",
+                nextAction: {
+                    command: `git commit -m "⬆️ upgrade: apply framework ${opts.versionLabel}"`,
+                    reason: "record the already-staged framework changes as one dedicated upgrade commit after fixing the blocking hook or policy",
+                    reasonCode: "upgrade_commit_blocked",
+                },
+            }),
+        });
+    }
+    const { stdout: hashOut } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+    });
+    return { hash: String(hashOut ?? "").trim(), subject };
+}
+export async function applyManagedFiles(opts) {
+    for (const rel of [...opts.additions, ...opts.updates]) {
+        const destPath = path.join(opts.gitRoot, rel);
+        if (opts.backup && (await fileExists(destPath))) {
+            const backup = await backupPath(destPath);
+            opts.createdBackups.push(backup);
+        }
+        await mkdir(path.dirname(destPath), { recursive: true });
+        const data = opts.fileContents.get(rel);
+        if (data) {
+            if (rel === "AGENTS.md" || rel === "CLAUDE.md") {
+                try {
+                    const st = await lstat(destPath);
+                    if (st.isSymbolicLink()) {
+                        const linkTarget = await readlink(destPath);
+                        const targetAbs = path.resolve(path.dirname(destPath), linkTarget);
+                        const relFromRoot = path.relative(opts.gitRoot, targetAbs);
+                        if (relFromRoot.startsWith("..") || path.isAbsolute(relFromRoot)) {
+                            throw new CliError({
+                                exitCode: exitCodeForError("E_VALIDATION"),
+                                code: "E_VALIDATION",
+                                message: `Refusing to overwrite symlinked ${rel} target outside repo: ${linkTarget}. ` +
+                                    "Replace the symlink with a regular file and retry.",
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    const code = err?.code;
+                    if (code !== "ENOENT")
+                        throw err;
+                }
+            }
+            await writeFile(destPath, data);
+        }
+        const baselineKey = opts.toBaselineKey(rel);
+        if (baselineKey && data) {
+            const baselinePath = path.join(opts.baselineDir, baselineKey);
+            await mkdir(path.dirname(baselinePath), { recursive: true });
+            await writeFile(baselinePath, data);
+        }
+    }
+}
+export async function persistUpgradeState(opts) {
+    const hasSourceMigration = opts.normalizedSourceToPersist !== null;
+    const shouldMutateConfig = opts.hasManagedMutations || hasSourceMigration;
+    if (shouldMutateConfig) {
+        const raw = { ...opts.rawConfig };
+        if (opts.normalizedSourceToPersist) {
+            setByDottedKey(raw, "framework.source", opts.normalizedSourceToPersist);
+        }
+        setByDottedKey(raw, "framework.last_update", new Date().toISOString());
+        if (opts.expectedCliVersionToPersist) {
+            setByDottedKey(raw, "framework.cli.expected_version", opts.expectedCliVersionToPersist);
+        }
+        await saveConfig(opts.agentplaneDir, raw);
+    }
+    await writeFile(opts.statePath, JSON.stringify({
+        applied_at: new Date().toISOString(),
+        source: opts.source,
+        updated: { add: opts.additions, update: opts.updates, unchanged: opts.skipped },
+    }, null, 2) + "\n", "utf8");
+    await writeFile(path.join(opts.upgradeStateDir, "last-review.json"), JSON.stringify({
+        generated_at: new Date().toISOString(),
+        counts: {
+            total: opts.reviewRecords.length,
+            needsSemanticReview: opts.reviewRecords.filter((r) => r.needsSemanticReview).length,
+        },
+        files: opts.reviewRecords,
+    }, null, 2) + "\n", "utf8");
+    return shouldMutateConfig;
+}

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

@@ -0,0 +1,21 @@
+import type { FrameworkManifest, UpgradeReviewRecord } from "./types.js";
+export declare function printUpgradeDryRun(opts: {
+    additions: string[];
+    updates: string[];
+    skipped: string[];
+    merged: string[];
+}): void;
+export declare function writeUpgradeAgentReview(opts: {
+    gitRoot: string;
+    runRoot: string;
+    manifest: FrameworkManifest;
+    additions: string[];
+    updates: string[];
+    skipped: string[];
+    merged: string[];
+    reviewRecords: UpgradeReviewRecord[];
+}): Promise<{
+    relRunDir: string;
+    needsReviewCount: number;
+}>;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEzE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,IAAI,CAQP;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,mBAAmB,EAAE,CAAC;CACtC,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC,CA2F3D"}

package/dist/commands/upgrade/report.js

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function printUpgradeDryRun(opts) {
+    process.stdout.write(`Upgrade dry-run: ${opts.additions.length} add, ${opts.updates.length} update, ${opts.skipped.length} unchanged\n`);
+    for (const rel of opts.additions)
+        process.stdout.write(`ADD ${rel}\n`);
+    for (const rel of opts.updates)
+        process.stdout.write(`UPDATE ${rel}\n`);
+    for (const rel of opts.skipped)
+        process.stdout.write(`SKIP ${rel}\n`);
+    for (const rel of opts.merged)
+        process.stdout.write(`MERGE ${rel}\n`);
+}
+export async function writeUpgradeAgentReview(opts) {
+    const runId = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    const runDir = path.join(opts.runRoot, runId);
+    await mkdir(runDir, { recursive: true });
+    const managedFiles = opts.manifest.files.map((f) => f.path.replaceAll("\\", "/").trim());
+    const needsReviewCount = opts.reviewRecords.filter((r) => r.needsSemanticReview).length;
+    const planMd = `# agentplane upgrade plan (${runId})\n\n` +
+        `Mode: agent-assisted review (no files modified)\n\n` +
+        `## Summary\n\n` +
+        `- additions: ${opts.additions.length}\n` +
+        `- updates: ${opts.updates.length}\n` +
+        `- unchanged: ${opts.skipped.length}\n` +
+        `- merged (auto-safe transforms already applied to incoming): ${opts.merged.length}\n\n` +
+        `## Managed files (manifest)\n\n` +
+        managedFiles.map((p) => `- ${p}`).join("\n") +
+        `\n\n` +
+        `## Proposed changes\n\n` +
+        opts.additions.map((p) => `- ADD ${p}`).join("\n") +
+        (opts.additions.length > 0 ? "\n" : "") +
+        opts.updates.map((p) => `- UPDATE ${p}`).join("\n") +
+        (opts.updates.length > 0 ? "\n" : "") +
+        opts.merged.map((p) => `- MERGE ${p}`).join("\n") +
+        (opts.merged.length > 0 ? "\n" : "") +
+        opts.skipped.map((p) => `- SKIP ${p}`).join("\n") +
+        (opts.skipped.length > 0 ? "\n" : "") +
+        `\n` +
+        `## Next steps\n\n` +
+        `1. Review the proposed changes list.\n` +
+        `2. Apply changes manually or re-run without \`--agent\` to apply managed files.\n` +
+        `3. Run \`agentplane doctor\` (or \`agentplane doctor --fix\`) and ensure checks pass.\n`;
+    const constraintsMd = `# Upgrade constraints\n\n` +
+        `This upgrade is restricted to framework-managed files only.\n\n` +
+        `## Must not touch\n\n` +
+        `- .agentplane/tasks/** (task data)\n` +
+        `- .agentplane/tasks.json (export snapshot)\n` +
+        `- .agentplane/backends/** (backend configuration)\n` +
+        `- .agentplane/config.json (project config)\n` +
+        `- .git/**\n\n` +
+        `## Notes\n\n` +
+        `- The upgrade bundle is validated against framework.manifest.json.\n` +
+        `- The policy gateway file at workspace root is AGENTS.md or CLAUDE.md.\n`;
+    const reportMd = `# Upgrade report (${runId})\n\n` +
+        `## Actions taken\n\n` +
+        `- [ ] Reviewed plan.md\n` +
+        `- [ ] Applied changes (manual or --auto)\n` +
+        `- [ ] Ran doctor\n` +
+        `- [ ] Ran tests / lint\n\n` +
+        `## Notes\n\n` +
+        `- \n`;
+    await writeFile(path.join(runDir, "plan.md"), planMd, "utf8");
+    await writeFile(path.join(runDir, "constraints.md"), constraintsMd, "utf8");
+    await writeFile(path.join(runDir, "report.md"), reportMd, "utf8");
+    await writeFile(path.join(runDir, "files.json"), JSON.stringify({
+        additions: opts.additions,
+        updates: opts.updates,
+        skipped: opts.skipped,
+        merged: opts.merged,
+    }, null, 2) + "\n", "utf8");
+    await writeFile(path.join(runDir, "review.json"), JSON.stringify({
+        generated_at: new Date().toISOString(),
+        counts: {
+            total: opts.reviewRecords.length,
+            needsSemanticReview: needsReviewCount,
+        },
+        files: opts.reviewRecords,
+    }, null, 2) + "\n", "utf8");
+    return { relRunDir: path.relative(opts.gitRoot, runDir), needsReviewCount };
+}

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

@@ -0,0 +1,35 @@
+import type { FrameworkManifest, GitHubRelease } from "./types.js";
+export declare function describeUpgradeSource(opts: {
+    bundleLayout: "local_assets" | "upgrade_bundle" | "repo_tarball";
+    hasExplicitBundle: boolean;
+    useRemote: boolean;
+}): string;
+export declare function loadFrameworkManifestFromPath(manifestPath: string): Promise<FrameworkManifest>;
+export declare function normalizeFrameworkSourceForUpgrade(source: string): {
+    source: string;
+    owner: string;
+    repo: string;
+    migrated: boolean;
+};
+export declare function resolveUpgradeDownloadFromRelease(opts: {
+    release: GitHubRelease;
+    owner: string;
+    repo: string;
+    assetName: string;
+    checksumName: string;
+}): {
+    kind: "assets";
+    bundleUrl: string;
+    checksumUrl: string;
+} | {
+    kind: "tarball";
+    tarballUrl: string;
+};
+export declare function resolveRepoTarballUrl(opts: {
+    release: GitHubRelease;
+    owner: string;
+    repo: string;
+    explicitTag?: string;
+}): string;
+export declare function resolveUpgradeRoot(extractedDir: string): Promise<string>;
+//# sourceMappingURL=source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/source.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,YAAY,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;IACjE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAMT;AAED,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAmBD,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,GAAG;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAWA;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,GACG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAqB1C;AAQD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAgBT;AAED,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ9E"}

package/dist/commands/upgrade/source.js

@@ -0,0 +1,109 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { invalidFieldMessage, invalidValueMessage, requiredFieldMessage, } from "../../cli/output.js";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { CliError } from "../../shared/errors.js";
+export function describeUpgradeSource(opts) {
+    if (opts.bundleLayout === "local_assets")
+        return "local installed agentplane CLI assets";
+    if (opts.bundleLayout === "repo_tarball")
+        return "GitHub repo tarball fallback";
+    if (opts.hasExplicitBundle)
+        return "explicit upgrade bundle";
+    if (opts.useRemote)
+        return "GitHub release bundle";
+    return "upgrade bundle";
+}
+export async function loadFrameworkManifestFromPath(manifestPath) {
+    const text = await readFile(manifestPath, "utf8");
+    const parsed = JSON.parse(text);
+    if (parsed?.schema_version !== 1 || !Array.isArray(parsed?.files)) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: "Invalid framework.manifest.json (expected schema_version=1 and files array).",
+        });
+    }
+    return parsed;
+}
+function parseGitHubRepo(source) {
+    const trimmed = source.trim();
+    if (!trimmed)
+        throw new Error(requiredFieldMessage("config.framework.source"));
+    if (!trimmed.includes("github.com")) {
+        throw new Error(invalidFieldMessage("config.framework.source", "GitHub URL"));
+    }
+    try {
+        const url = new URL(trimmed);
+        const parts = url.pathname.replaceAll(".git", "").split("/").filter(Boolean);
+        if (parts.length < 2)
+            throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
+        return { owner: parts[0], repo: parts[1] };
+    }
+    catch {
+        throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
+    }
+}
+export function normalizeFrameworkSourceForUpgrade(source) {
+    const { owner, repo } = parseGitHubRepo(source);
+    if (owner === "basilisk-labs" && repo === "agent-plane") {
+        return {
+            source: `https://github.com/${owner}/agentplane`,
+            owner,
+            repo: "agentplane",
+            migrated: true,
+        };
+    }
+    return { source: `https://github.com/${owner}/${repo}`, owner, repo, migrated: false };
+}
+export function resolveUpgradeDownloadFromRelease(opts) {
+    const assets = Array.isArray(opts.release.assets) ? opts.release.assets : [];
+    const asset = assets.find((a) => a?.name === opts.assetName);
+    const checksumAsset = assets.find((a) => a?.name === opts.checksumName);
+    if (asset?.browser_download_url && checksumAsset?.browser_download_url) {
+        return {
+            kind: "assets",
+            bundleUrl: asset.browser_download_url,
+            checksumUrl: checksumAsset.browser_download_url,
+        };
+    }
+    const tarballUrl = typeof opts.release.tarball_url === "string" ? opts.release.tarball_url : "";
+    if (!tarballUrl) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_NETWORK"),
+            code: "E_NETWORK",
+            message: `Upgrade assets not found in ${opts.owner}/${opts.repo} release`,
+        });
+    }
+    return { kind: "tarball", tarballUrl };
+}
+function buildCodeloadTarGzUrl(opts) {
+    const tag = opts.tag.trim();
+    if (!tag)
+        throw new Error("tag is required");
+    return `https://codeload.github.com/${opts.owner}/${opts.repo}/tar.gz/${encodeURIComponent(tag)}`;
+}
+export function resolveRepoTarballUrl(opts) {
+    const tag = (typeof opts.explicitTag === "string" && opts.explicitTag.trim()) ||
+        (typeof opts.release.tag_name === "string" && opts.release.tag_name.trim()) ||
+        "";
+    if (tag)
+        return buildCodeloadTarGzUrl({ owner: opts.owner, repo: opts.repo, tag });
+    const tarballUrl = typeof opts.release.tarball_url === "string" ? opts.release.tarball_url : "";
+    if (tarballUrl)
+        return tarballUrl;
+    throw new CliError({
+        exitCode: exitCodeForError("E_NETWORK"),
+        code: "E_NETWORK",
+        message: "GitHub release did not provide tag_name or tarball_url; cannot fall back to repo tarball.",
+    });
+}
+export async function resolveUpgradeRoot(extractedDir) {
+    const entries = await readdir(extractedDir, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+    if (files.length === 0 && dirs.length === 1) {
+        return path.join(extractedDir, dirs[0]);
+    }
+    return extractedDir;
+}

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

@@ -0,0 +1,31 @@
+export type GitHubRelease = {
+    tag_name?: string;
+    assets?: {
+        name?: string;
+        browser_download_url?: string;
+    }[];
+    tarball_url?: string;
+};
+export type FrameworkManifest = {
+    schema_version: 1;
+    files: FrameworkManifestEntry[];
+};
+export type FrameworkManifestEntry = {
+    path: string;
+    source_path?: string;
+    type: "markdown" | "json" | "text";
+    merge_strategy: "agents_policy_markdown" | "agent_json_3way" | "agent_json_merge";
+    required?: boolean;
+};
+export type UpgradeReviewRecord = {
+    relPath: string;
+    mergeStrategy: FrameworkManifestEntry["merge_strategy"];
+    hasBaseline: boolean;
+    changedCurrentVsBaseline: boolean | null;
+    changedIncomingVsBaseline: boolean | null;
+    currentDiffersFromIncoming: boolean;
+    needsSemanticReview: boolean;
+    mergeApplied: boolean;
+    mergePath: "none" | "markdownOverrides" | "3way" | "incomingWins" | "incomingWinsFallback" | "parseFailed" | "incidentsAppend";
+};
+//# sourceMappingURL=types.d.ts.map