agentplane 0.2.3 → 0.2.5

package/dist/commands/upgrade.js

@@ -1,6 +1,7 @@
-import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readdir, readFile, readlink, rm, symlink, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConfig, resolveProject, saveConfig, setByDottedKey } from "@agentplaneorg/core";
 import { backupPath, fileExists, getPathKind } from "../cli/fs-utils.js";
 import { downloadToFile, fetchJson } from "../cli/http.js";
@@ -13,6 +14,39 @@ import { ensureNetworkApproved } from "./shared/network-approval.js";
 const DEFAULT_UPGRADE_ASSET = "agentplane-upgrade.tar.gz";
 const DEFAULT_UPGRADE_CHECKSUM_ASSET = "agentplane-upgrade.tar.gz.sha256";
 const UPGRADE_DOWNLOAD_TIMEOUT_MS = 60_000;
+const UPGRADE_RELEASE_METADATA_TIMEOUT_MS = 15_000;
+const ASSETS_DIR_URL = new URL("../../assets/", import.meta.url);
+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 isDeniedUpgradePath(relPath) {
+    if (relPath === ".agentplane/config.json")
+        return true;
+    if (relPath === ".agentplane/tasks.json")
+        return true;
+    if (relPath.startsWith(".agentplane/backends/"))
+        return true;
+    if (relPath.startsWith(".agentplane/worktrees/"))
+        return true;
+    if (relPath.startsWith(".agentplane/recipes/"))
+        return true;
+    if (relPath.startsWith(".agentplane/tasks/"))
+        return true;
+    if (relPath.startsWith(".agentplane/.upgrade/"))
+        return true;
+    if (relPath === ".git" || relPath.startsWith(".git/"))
+        return true;
+    return false;
+}
 function parseGitHubRepo(source) {
     const trimmed = source.trim();
     if (!trimmed)
@@ -64,6 +98,29 @@ export function resolveUpgradeDownloadFromRelease(opts) {
     }
     return { kind: "tarball", tarballUrl };
 }
+function buildCodeloadTarGzUrl(opts) {
+    // Prefer codeload over api.github.com tarball_url. It is less brittle and does not require
+    // GitHub API-specific behavior/rate limits.
+    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.",
+    });
+}
 async function resolveUpgradeRoot(extractedDir) {
     const entries = await readdir(extractedDir, { withFileTypes: true });
     const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
@@ -73,24 +130,12 @@ async function resolveUpgradeRoot(extractedDir) {
     }
     return extractedDir;
 }
-async function listFilesRecursive(rootDir) {
-    const out = [];
-    const entries = await readdir(rootDir, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = path.join(rootDir, entry.name);
-        if (entry.isDirectory()) {
-            out.push(...(await listFilesRecursive(fullPath)));
-        }
-        else if (entry.isFile()) {
-            out.push(fullPath);
-        }
-    }
-    return out;
-}
 function isAllowedUpgradePath(relPath) {
     if (relPath === "AGENTS.md")
         return true;
-    return relPath.startsWith(".agentplane/");
+    if (relPath.startsWith(".agentplane/agents/") && relPath.endsWith(".json"))
+        return true;
+    return false;
 }
 const LOCAL_OVERRIDES_START = "<!-- AGENTPLANE:LOCAL-START -->";
 const LOCAL_OVERRIDES_END = "<!-- AGENTPLANE:LOCAL-END -->";
@@ -168,7 +213,26 @@ function mergeAgentsPolicyMarkdown(incoming, current) {
 function isJsonRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function mergeAgentJson(incomingText, currentText) {
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map((v) => canonicalizeJson(v));
+    if (isJsonRecord(value)) {
+        const out = {};
+        for (const k of Object.keys(value).toSorted()) {
+            out[k] = canonicalizeJson(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+function jsonEqual(a, b) {
+    const ca = JSON.stringify(canonicalizeJson(a)) ?? "__undefined__";
+    const cb = JSON.stringify(canonicalizeJson(b)) ?? "__undefined__";
+    return ca === cb;
+}
+// Used as a fallback for 3-way merges when no baseline is available. Incoming (upstream) values
+// win for scalar/object conflicts, while user-added keys and array items are preserved.
+function mergeAgentJsonIncomingWins(incomingText, currentText) {
     let incoming;
     let current;
     try {
@@ -189,19 +253,22 @@ function mergeAgentJson(incomingText, currentText) {
         }
         if (Array.isArray(incVal) && Array.isArray(curVal)) {
             const merged = [...incVal];
+            const seen = new Set();
+            for (const x of merged)
+                seen.add(JSON.stringify(canonicalizeJson(x)));
             for (const item of curVal) {
-                if (!merged.some((x) => JSON.stringify(x) === JSON.stringify(item)))
+                const key = JSON.stringify(canonicalizeJson(item));
+                if (!seen.has(key)) {
                     merged.push(item);
+                    seen.add(key);
+                }
             }
             out[k] = merged;
             continue;
         }
         if (isJsonRecord(incVal) && isJsonRecord(curVal)) {
-            out[k] = { ...incVal, ...curVal };
-            continue;
-        }
-        if (curVal !== incVal && curVal !== null && curVal !== "") {
-            out[k] = curVal;
+            // Preserve user-only subkeys but let upstream win for conflicts.
+            out[k] = { ...curVal, ...incVal };
             continue;
         }
         out[k] = incVal;
@@ -231,11 +298,17 @@ function mergeAgentJson3Way(opts) {
         // Arrays: always take incoming as base; if user changed vs base, append user-only items.
         if (Array.isArray(incVal) && Array.isArray(curVal) && Array.isArray(baseVal)) {
             const merged = [...incVal];
-            const userChanged = JSON.stringify(curVal) !== JSON.stringify(baseVal);
+            const userChanged = !jsonEqual(curVal, baseVal);
             if (userChanged) {
+                const seen = new Set();
+                for (const x of merged)
+                    seen.add(JSON.stringify(canonicalizeJson(x)));
                 for (const item of curVal) {
-                    if (!merged.some((x) => JSON.stringify(x) === JSON.stringify(item)))
+                    const k = JSON.stringify(canonicalizeJson(item));
+                    if (!seen.has(k)) {
                         merged.push(item);
+                        seen.add(k);
+                    }
                 }
             }
             out[key] = merged;
@@ -253,7 +326,7 @@ function mergeAgentJson3Way(opts) {
                 const incSub = incVal[sk];
                 const curSub = curVal[sk];
                 const baseSub = baseVal[sk];
-                const userChanged = JSON.stringify(curSub) !== JSON.stringify(baseSub);
+                const userChanged = !jsonEqual(curSub, baseSub);
                 if (userChanged)
                     merged[sk] = curSub;
                 else if (incSub !== undefined)
@@ -265,7 +338,7 @@ function mergeAgentJson3Way(opts) {
             continue;
         }
         // Scalars: prefer incoming unless the user changed vs base.
-        if (JSON.stringify(curVal) !== JSON.stringify(baseVal)) {
+        if (!jsonEqual(curVal, baseVal)) {
             if (curVal !== undefined)
                 out[key] = curVal;
             else if (incVal !== undefined)
@@ -295,13 +368,21 @@ export async function cmdUpgradeParsed(opts) {
         rootOverride: opts.rootOverride ?? null,
     });
     const loaded = await loadConfig(resolved.agentplaneDir);
-    const sourceFromFlags = typeof flags.source === "string" && flags.source.trim().length > 0;
-    const originalSource = flags.source ?? loaded.config.framework.source;
-    const normalized = normalizeFrameworkSourceForUpgrade(originalSource);
-    const source = normalized.source;
-    if (normalized.migrated) {
-        process.stderr.write(`${warnMessage(`config.framework.source uses deprecated repo basilisk-labs/agent-plane; using ${source}`)}\n`);
+    const upgradeStateDir = path.join(resolved.agentplaneDir, ".upgrade");
+    const lockPath = path.join(upgradeStateDir, "lock.json");
+    const statePath = path.join(upgradeStateDir, "state.json");
+    const baselineDirNew = path.join(upgradeStateDir, "baseline");
+    const baselineDirLegacy = path.join(resolved.agentplaneDir, "upgrade", "baseline");
+    await mkdir(upgradeStateDir, { recursive: true });
+    if (await fileExists(lockPath)) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: `Upgrade is locked (found ${path.relative(resolved.gitRoot, lockPath)})`,
+        });
     }
+    await writeFile(lockPath, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }, null, 2) + "\n", "utf8");
+    let lockAcquired = true;
     let networkApproved = false;
     const ensureApproved = async (reason) => {
         if (networkApproved)
@@ -309,16 +390,26 @@ export async function cmdUpgradeParsed(opts) {
         await ensureNetworkApproved({ config: loaded.config, yes: flags.yes, reason });
         networkApproved = true;
     };
+    const hasBundle = Boolean(flags.bundle);
+    const hasRemoteHints = Boolean(flags.source) ||
+        Boolean(flags.tag) ||
+        Boolean(flags.asset) ||
+        Boolean(flags.checksumAsset);
+    const useRemote = flags.remote === true || hasRemoteHints;
     let tempRoot = null;
     let extractRoot = null;
     try {
         tempRoot = await mkdtemp(path.join(os.tmpdir(), "agentplane-upgrade-"));
         let bundlePath = "";
         let checksumPath = "";
-        // GitHub release tarballs contain the full repository. When we fall back to tarball_url,
-        // we must ignore non-upgrade paths instead of failing validation.
-        let allowNonUpgradePaths = false;
-        if (flags.bundle) {
+        let bundleLayout = "upgrade_bundle";
+        let bundleRoot = "";
+        let normalizedSourceToPersist = null;
+        if (!hasBundle && !useRemote) {
+            bundleLayout = "local_assets";
+            bundleRoot = fileURLToPath(ASSETS_DIR_URL);
+        }
+        else if (flags.bundle) {
             const isUrl = flags.bundle.startsWith("http://") || flags.bundle.startsWith("https://");
             bundlePath = isUrl ? path.join(tempRoot, "bundle.tar.gz") : path.resolve(flags.bundle);
             if (isUrl) {
@@ -336,6 +427,15 @@ export async function cmdUpgradeParsed(opts) {
             }
         }
         else {
+            const sourceFromFlags = typeof flags.source === "string" && flags.source.trim().length > 0;
+            const originalSource = flags.source ?? loaded.config.framework.source;
+            const normalized = normalizeFrameworkSourceForUpgrade(originalSource);
+            if (!sourceFromFlags && normalized.migrated) {
+                normalizedSourceToPersist = normalized.source;
+            }
+            if (normalized.migrated) {
+                process.stderr.write(`${warnMessage(`config.framework.source uses deprecated repo basilisk-labs/agent-plane; using ${normalized.source}`)}\n`);
+            }
             const { owner, repo } = normalized;
             const releaseUrl = flags.tag
                 ? `https://api.github.com/repos/${owner}/${repo}/releases/tags/${flags.tag}`
@@ -343,7 +443,7 @@ export async function cmdUpgradeParsed(opts) {
             await ensureApproved("upgrade fetches release metadata and downloads assets from the network");
             const assetName = flags.asset ?? DEFAULT_UPGRADE_ASSET;
             const checksumName = flags.checksumAsset ?? DEFAULT_UPGRADE_CHECKSUM_ASSET;
-            const release = (await fetchJson(releaseUrl));
+            const release = (await fetchJson(releaseUrl, UPGRADE_RELEASE_METADATA_TIMEOUT_MS));
             const download = resolveUpgradeDownloadFromRelease({
                 release,
                 owner,
@@ -358,14 +458,28 @@ export async function cmdUpgradeParsed(opts) {
                 await downloadToFile(download.checksumUrl, checksumPath, UPGRADE_DOWNLOAD_TIMEOUT_MS);
             }
             else {
-                process.stderr.write(`${warnMessage(`upgrade release does not include ${assetName}/${checksumName}; falling back to tarball_url without checksum verification`)}\n`);
-                allowNonUpgradePaths = true;
+                if (!flags.allowTarball) {
+                    throw new CliError({
+                        exitCode: exitCodeForError("E_NETWORK"),
+                        code: "E_NETWORK",
+                        message: `Upgrade assets ${assetName}/${checksumName} not found in ${owner}/${repo} release. ` +
+                            "Publish the upgrade bundle assets, or re-run with --allow-tarball to download a repo tarball (no checksum verification).",
+                    });
+                }
+                process.stderr.write(`${warnMessage(`upgrade release does not include ${assetName}/${checksumName}; falling back to repo tarball without checksum verification`)}\n`);
+                bundleLayout = "repo_tarball";
                 bundlePath = path.join(tempRoot, "source.tar.gz");
-                await downloadToFile(download.tarballUrl, bundlePath, UPGRADE_DOWNLOAD_TIMEOUT_MS);
+                const tarballUrl = resolveRepoTarballUrl({
+                    release,
+                    owner,
+                    repo,
+                    explicitTag: flags.tag,
+                });
+                await downloadToFile(tarballUrl, bundlePath, UPGRADE_DOWNLOAD_TIMEOUT_MS);
                 checksumPath = "";
             }
         }
-        if (checksumPath) {
+        if (bundleLayout !== "local_assets" && checksumPath) {
             const expected = parseSha256Text(await readFile(checksumPath, "utf8"));
             if (!expected) {
                 throw new CliError({
@@ -383,19 +497,42 @@ export async function cmdUpgradeParsed(opts) {
                 });
             }
         }
-        extractRoot = await mkdtemp(path.join(os.tmpdir(), "agentplane-upgrade-extract-"));
-        await extractArchive({
-            archivePath: bundlePath,
-            destDir: extractRoot,
-        });
-        const bundleRoot = await resolveUpgradeRoot(extractRoot);
-        const files = await listFilesRecursive(bundleRoot);
+        if (bundleLayout !== "local_assets") {
+            extractRoot = await mkdtemp(path.join(os.tmpdir(), "agentplane-upgrade-extract-"));
+            await extractArchive({
+                archivePath: bundlePath,
+                destDir: extractRoot,
+            });
+            const extractedRoot = await resolveUpgradeRoot(extractRoot);
+            bundleRoot =
+                bundleLayout === "repo_tarball"
+                    ? path.join(extractedRoot, "packages", "agentplane", "assets")
+                    : extractedRoot;
+        }
+        const manifestPath = bundleLayout === "local_assets"
+            ? fileURLToPath(new URL("../../assets/framework.manifest.json", import.meta.url))
+            : path.join(bundleRoot, "framework.manifest.json");
+        const manifest = await loadFrameworkManifestFromPath(manifestPath);
         const additions = [];
         const updates = [];
         const skipped = [];
         const fileContents = new Map();
         const merged = [];
-        const baselineDir = path.join(resolved.agentplaneDir, "upgrade", "baseline");
+        const missingRequired = [];
+        const readBaselineText = async (baselineKey) => {
+            try {
+                return await readFile(path.join(baselineDirNew, baselineKey), "utf8");
+            }
+            catch {
+                // Back-compat: older upgrades wrote baselines under .agentplane/upgrade/baseline.
+                try {
+                    return await readFile(path.join(baselineDirLegacy, baselineKey), "utf8");
+                }
+                catch {
+                    return null;
+                }
+            }
+        };
         const toBaselineKey = (rel) => {
             if (rel === "AGENTS.md")
                 return "AGENTS.md";
@@ -403,63 +540,76 @@ export async function cmdUpgradeParsed(opts) {
                 return rel.slice(".agentplane/".length);
             return null;
         };
-        for (const filePath of files) {
-            let rel = path.relative(bundleRoot, filePath).replaceAll("\\", "/");
+        for (const entry of manifest.files) {
+            const rel = entry.path.replaceAll("\\", "/").trim();
             if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
-                    message: `Invalid bundle path: ${filePath}`,
+                    message: `Invalid manifest path: ${entry.path}`,
                 });
             }
-            if (rel === ".git" || rel.startsWith(".git/")) {
+            if (isDeniedUpgradePath(rel)) {
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
-                    message: `Upgrade bundle cannot write to .git (${rel})`,
+                    message: `Manifest includes a denied path: ${rel}`,
                 });
             }
             if (!isAllowedUpgradePath(rel)) {
-                if (allowNonUpgradePaths) {
-                    continue;
-                }
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
-                    message: `Upgrade bundle path not allowed: ${rel}`,
+                    message: `Manifest path not allowed: ${rel}`,
                 });
             }
             const destPath = path.join(resolved.gitRoot, rel);
             const kind = await getPathKind(destPath);
             if (kind === "dir") {
                 throw new CliError({
-                    exitCode: 5,
+                    exitCode: exitCodeForError("E_IO"),
                     code: "E_IO",
                     message: `Upgrade target is a directory: ${rel}`,
                 });
             }
-            if (rel === ".agentplane/config.json") {
-                // Never overwrite local config during upgrade.
-                skipped.push(rel);
+            const sourceRel = (entry.source_path ?? entry.path).replaceAll("\\", "/").trim();
+            const sourcePath = path.join(bundleRoot, sourceRel);
+            let data;
+            try {
+                data = await readFile(sourcePath);
+            }
+            catch {
+                if (entry.required)
+                    missingRequired.push(rel);
                 continue;
             }
-            let data = await readFile(filePath);
+            let existingBuf = null;
+            let existingText = null;
             if (kind !== null) {
-                const existing = await readFile(destPath, "utf8");
-                if (rel === "AGENTS.md") {
-                    const mergedText = mergeAgentsPolicyMarkdown(data.toString("utf8"), existing);
+                existingBuf = await readFile(destPath);
+            }
+            // Merge logic only needs text for a small subset of managed files.
+            if (existingBuf) {
+                if (entry.merge_strategy === "agents_policy_markdown" && rel === "AGENTS.md") {
+                    existingText = existingBuf.toString("utf8");
+                    const mergedText = mergeAgentsPolicyMarkdown(data.toString("utf8"), existingText);
                     data = Buffer.from(mergedText, "utf8");
                     merged.push(rel);
                 }
-                else if (rel.startsWith(".agentplane/agents/") && rel.endsWith(".json")) {
+                else if (entry.merge_strategy === "agent_json_3way" &&
+                    rel.startsWith(".agentplane/agents/") &&
+                    rel.endsWith(".json")) {
+                    existingText = existingBuf.toString("utf8");
                     const baselineKey = toBaselineKey(rel);
                     let mergedText = null;
                     if (baselineKey) {
                         try {
-                            const baselineText = await readFile(path.join(baselineDir, baselineKey), "utf8");
+                            const baselineText = await readBaselineText(baselineKey);
+                            if (!baselineText)
+                                throw new Error("missing baseline");
                             mergedText = mergeAgentJson3Way({
                                 incomingText: data.toString("utf8"),
-                                currentText: existing,
+                                currentText: existingText,
                                 baseText: baselineText,
                             });
                         }
@@ -467,7 +617,7 @@ export async function cmdUpgradeParsed(opts) {
                             mergedText = null;
                         }
                     }
-                    mergedText ??= mergeAgentJson(data.toString("utf8"), existing);
+                    mergedText ??= mergeAgentJsonIncomingWins(data.toString("utf8"), existingText);
                     if (mergedText) {
                         data = Buffer.from(mergedText, "utf8");
                         merged.push(rel);
@@ -475,24 +625,18 @@ export async function cmdUpgradeParsed(opts) {
                 }
             }
             fileContents.set(rel, data);
-            if (kind === null) {
+            if (kind === null)
                 additions.push(rel);
-            }
-            else {
-                const existingBuf = await readFile(destPath);
-                if (Buffer.compare(existingBuf, data) === 0) {
-                    skipped.push(rel);
-                }
-                else {
-                    updates.push(rel);
-                }
-            }
+            else if (existingBuf && Buffer.compare(existingBuf, data) === 0)
+                skipped.push(rel);
+            else
+                updates.push(rel);
         }
-        if (fileContents.size === 0) {
+        if (missingRequired.length > 0) {
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "Upgrade bundle contains no applicable files (expected AGENTS.md and/or .agentplane/).",
+                message: `Upgrade bundle is missing required managed files: ${missingRequired.join(", ")}`,
             });
         }
         if (flags.dryRun) {
@@ -507,8 +651,61 @@ export async function cmdUpgradeParsed(opts) {
                 process.stdout.write(`MERGE ${rel}\n`);
             return 0;
         }
-        if (skipped.includes(".agentplane/config.json")) {
-            process.stderr.write(`${warnMessage("upgrade bundle includes .agentplane/config.json; skipping to preserve local configuration")}\n`);
+        if (flags.mode === "agent") {
+            const agentDir = path.join(upgradeStateDir, "agent");
+            const runId = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+            const runDir = path.join(agentDir, runId);
+            await mkdir(runDir, { recursive: true });
+            const managedFiles = manifest.files.map((f) => f.path.replaceAll("\\", "/").trim());
+            const planMd = `# agentplane upgrade plan (${runId})\n\n` +
+                `Mode: agent-assisted (no files modified)\n\n` +
+                `## Summary\n\n` +
+                `- additions: ${additions.length}\n` +
+                `- updates: ${updates.length}\n` +
+                `- unchanged: ${skipped.length}\n` +
+                `- merged (auto-safe transforms already applied to incoming): ${merged.length}\n\n` +
+                `## Managed files (manifest)\n\n` +
+                managedFiles.map((p) => `- ${p}`).join("\n") +
+                `\n\n` +
+                `## Proposed changes\n\n` +
+                additions.map((p) => `- ADD ${p}`).join("\n") +
+                (additions.length > 0 ? "\n" : "") +
+                updates.map((p) => `- UPDATE ${p}`).join("\n") +
+                (updates.length > 0 ? "\n" : "") +
+                merged.map((p) => `- MERGE ${p}`).join("\n") +
+                (merged.length > 0 ? "\n" : "") +
+                skipped.map((p) => `- SKIP ${p}`).join("\n") +
+                (skipped.length > 0 ? "\n" : "") +
+                `\n` +
+                `## Next steps\n\n` +
+                `1. Review the proposed changes list.\n` +
+                `2. Apply changes manually or re-run with \`agentplane upgrade --auto\` 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` +
+                `- AGENTS.md is managed under .agentplane/AGENTS.md and workspace-root AGENTS.md is a symlink.\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, updates, skipped, merged }, null, 2) + "\n", "utf8");
+            process.stdout.write(`Upgrade plan written: ${path.relative(resolved.gitRoot, runDir)}\n`);
+            return 0;
         }
         for (const rel of [...additions, ...updates]) {
             const destPath = path.join(resolved.gitRoot, rel);
@@ -517,22 +714,58 @@ export async function cmdUpgradeParsed(opts) {
             }
             await mkdir(path.dirname(destPath), { recursive: true });
             const data = fileContents.get(rel);
-            if (data)
-                await writeFile(destPath, data);
+            if (data) {
+                if (rel === "AGENTS.md") {
+                    // Write the managed copy under .agentplane/ and keep the workspace-root policy path
+                    // as a symlink to it.
+                    const managedPath = path.join(resolved.agentplaneDir, "AGENTS.md");
+                    await mkdir(path.dirname(managedPath), { recursive: true });
+                    await writeFile(managedPath, data);
+                    // Replace AGENTS.md with a symlink if needed.
+                    const relTarget = path.relative(resolved.gitRoot, managedPath);
+                    try {
+                        const st = await lstat(destPath);
+                        if (st.isSymbolicLink()) {
+                            const currentTarget = await readlink(destPath);
+                            if (currentTarget !== relTarget) {
+                                await rm(destPath, { force: true });
+                            }
+                        }
+                        else {
+                            // If it's a regular file, remove it (backup already happened above when enabled).
+                            await rm(destPath, { force: true });
+                        }
+                    }
+                    catch {
+                        // destPath doesn't exist
+                    }
+                    if (!(await fileExists(destPath))) {
+                        await symlink(relTarget, destPath);
+                    }
+                }
+                else {
+                    await writeFile(destPath, data);
+                }
+            }
             // Record a baseline copy for future three-way merges.
             const baselineKey = toBaselineKey(rel);
             if (baselineKey && data) {
-                const baselinePath = path.join(baselineDir, baselineKey);
+                const baselinePath = path.join(baselineDirNew, baselineKey);
                 await mkdir(path.dirname(baselinePath), { recursive: true });
                 await writeFile(baselinePath, data);
             }
         }
         const raw = { ...loaded.raw };
-        if (!sourceFromFlags && normalized.migrated) {
-            setByDottedKey(raw, "framework.source", source);
+        if (normalizedSourceToPersist) {
+            setByDottedKey(raw, "framework.source", normalizedSourceToPersist);
         }
         setByDottedKey(raw, "framework.last_update", new Date().toISOString());
         await saveConfig(resolved.agentplaneDir, raw);
+        await writeFile(statePath, JSON.stringify({
+            applied_at: new Date().toISOString(),
+            source: bundleLayout,
+            updated: { add: additions.length, update: updates.length, unchanged: skipped.length },
+        }, null, 2) + "\n", "utf8");
         process.stdout.write(`Upgrade applied: ${additions.length} add, ${updates.length} update, ${skipped.length} unchanged\n`);
         return 0;
     }
@@ -541,5 +774,13 @@ export async function cmdUpgradeParsed(opts) {
             await rm(extractRoot, { recursive: true, force: true });
         if (tempRoot)
             await rm(tempRoot, { recursive: true, force: true });
+        if (lockAcquired) {
+            try {
+                await rm(lockPath, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
     }
 }

package/dist/policy/engine.d.ts

@@ -0,0 +1,21 @@
+import type { AgentplaneConfig } from "@agentplaneorg/core";
+import type { PolicyAction, PolicyContext, PolicyProblem } from "./types.js";
+export type PolicyDecision = {
+    ok: boolean;
+    violations: PolicyViolation[];
+};
+export type PolicyViolation = {
+    level: "error" | "warning";
+    code: PolicyProblem["code"];
+    exitCode: number;
+    message: string;
+};
+export type ActionId = PolicyAction | "task_list" | "task_new" | "upgrade_apply" | "doctor_fix" | (string & {});
+export type PolicyEngineContext = Omit<PolicyContext, "action"> & {
+    action: ActionId;
+    config: AgentplaneConfig;
+};
+export declare class PolicyEngine {
+    evaluate(ctx: PolicyEngineContext): PolicyDecision;
+}
+//# sourceMappingURL=engine.d.ts.map