agentplane 0.2.26 → 0.3.2

package/dist/commands/upgrade.js

@@ -11,10 +11,23 @@ import { invalidFieldMessage, invalidValueMessage, requiredFieldMessage, warnMes
 import { exitCodeForError } from "../cli/exit-codes.js";
 import { CliError } from "../shared/errors.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
+import { execFileAsync, gitEnv } from "./shared/git.js";
+import { getVersion } from "../meta/version.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;
+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";
+}
 async function safeRemovePath(targetPath) {
     try {
         await rm(targetPath, { recursive: true, force: true });
@@ -148,83 +161,22 @@ async function resolveUpgradeRoot(extractedDir) {
 function isAllowedUpgradePath(relPath) {
     if (relPath === "AGENTS.md")
         return true;
+    if (relPath === "CLAUDE.md")
+        return true;
     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 -->";
-function extractLocalOverridesBlock(text) {
-    const start = text.indexOf(LOCAL_OVERRIDES_START);
-    const end = text.indexOf(LOCAL_OVERRIDES_END);
-    if (start === -1 || end === -1 || end < start)
-        return null;
-    return text.slice(start + LOCAL_OVERRIDES_START.length, end).trim();
-}
-function withLocalOverridesBlock(base, localOverrides) {
-    const start = base.indexOf(LOCAL_OVERRIDES_START);
-    const end = base.indexOf(LOCAL_OVERRIDES_END);
-    if (start === -1 || end === -1 || end < start) {
-        const suffix = "\n\n## Local Overrides (preserved across upgrades)\n\n" +
-            `${LOCAL_OVERRIDES_START}\n` +
-            (localOverrides.trim() ? `${localOverrides.trim()}\n` : "") +
-            `${LOCAL_OVERRIDES_END}\n`;
-        return `${base.trimEnd()}${suffix}`;
-    }
-    const before = base.slice(0, start + LOCAL_OVERRIDES_START.length);
-    const after = base.slice(end);
-    return `${before}\n${localOverrides.trim() ? `${localOverrides.trim()}\n` : ""}${after}`;
-}
-function parseH2Sections(text) {
-    const lines = text.replaceAll("\r\n", "\n").split("\n");
-    const sections = new Map();
-    let current = null;
-    let buf = [];
-    const flush = () => {
-        if (!current)
-            return;
-        if (!sections.has(current)) {
-            sections.set(current, buf.join("\n").trimEnd());
-        }
-    };
-    for (const line of lines) {
-        const m = /^##\s+(.+?)\s*$/.exec(line);
-        if (m) {
-            flush();
-            current = (m[1] ?? "").trim();
-            buf = [];
-            continue;
-        }
-        if (current)
-            buf.push(line);
-    }
-    flush();
-    return sections;
-}
-function mergeAgentsPolicyMarkdown(incoming, current) {
-    const local = extractLocalOverridesBlock(current);
-    if (local !== null) {
-        return withLocalOverridesBlock(incoming, local);
-    }
-    // Fallback: if the user edited AGENTS.md without the local markers, preserve their changes by
-    // appending differing/extra sections into a dedicated local overrides block.
-    const incomingSections = parseH2Sections(incoming);
-    const currentSections = parseH2Sections(current);
-    const overrides = [];
-    for (const [title, body] of currentSections.entries()) {
-        const incomingBody = incomingSections.get(title);
-        if (incomingBody === undefined) {
-            overrides.push(`### Added section: ${title}\n\n${body.trim()}\n`);
-            continue;
-        }
-        if (incomingBody.trim() !== body.trim()) {
-            overrides.push(`### Local edits for: ${title}\n\n${body.trim()}\n`);
-        }
+    if (relPath.startsWith(".agentplane/policy/") &&
+        (relPath.endsWith(".md") ||
+            relPath.endsWith(".ts") ||
+            relPath.endsWith(".js") ||
+            relPath.endsWith(".mjs"))) {
+        return true;
     }
-    if (overrides.length === 0)
-        return incoming;
-    return withLocalOverridesBlock(incoming, overrides.join("\n"));
+    return false;
 }
+const INCIDENTS_POLICY_PATH = ".agentplane/policy/incidents.md";
+const INCIDENTS_APPEND_MARKER = "<!-- AGENTPLANE:UPGRADE-APPEND incidents.md -->";
+const CONFIG_REL_PATH = ".agentplane/config.json";
 function isJsonRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -262,127 +214,167 @@ function textChangedForType(opts) {
     }
     return opts.aText.trimEnd() !== opts.bText.trimEnd();
 }
-// 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 {
-        incoming = JSON.parse(incomingText);
-        current = JSON.parse(currentText);
+function parseIncidentEntryBlocks(entriesBody) {
+    const lines = entriesBody.replaceAll("\r\n", "\n").split("\n");
+    const starts = [];
+    for (const [index, line] of lines.entries()) {
+        if (/^\s*-\s*id:\s+/i.test(line ?? ""))
+            starts.push(index);
     }
-    catch {
-        return null;
+    const blocks = [];
+    for (const [idx, start] of starts.entries()) {
+        const end = starts.at(idx + 1) ?? lines.length;
+        const slice = lines.slice(start, end);
+        while (slice.length > 0 && !(slice[0] ?? "").trim())
+            slice.shift();
+        while (slice.length > 0 && !(slice.at(-1) ?? "").trim())
+            slice.pop();
+        const block = slice.join("\n").trim();
+        if (block)
+            blocks.push(block);
     }
-    if (!isJsonRecord(incoming) || !isJsonRecord(current))
+    return blocks;
+}
+function normalizeEntryBlock(block) {
+    return block
+        .replaceAll("\r\n", "\n")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .trim();
+}
+function splitEntriesSection(text) {
+    const lines = text.replaceAll("\r\n", "\n").split("\n");
+    const headingIndex = lines.findIndex((line) => /^\s*##\s+Entries\s*$/i.test(line));
+    if (headingIndex === -1)
         return null;
-    const out = { ...incoming };
-    for (const [k, curVal] of Object.entries(current)) {
-        const incVal = incoming[k];
-        if (incVal === undefined) {
-            out[k] = curVal;
-            continue;
-        }
-        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) {
-                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)) {
-            // Preserve user-only subkeys but let upstream win for conflicts.
-            out[k] = { ...curVal, ...incVal };
-            continue;
+    let nextHeadingIndex = lines.length;
+    for (let i = headingIndex + 1; i < lines.length; i++) {
+        if (/^\s*##\s+/.test(lines[i] ?? "")) {
+            nextHeadingIndex = i;
+            break;
         }
-        out[k] = incVal;
     }
-    return JSON.stringify(out, null, 2) + "\n";
+    return {
+        before: lines.slice(0, headingIndex + 1).join("\n"),
+        entriesBody: lines.slice(headingIndex + 1, nextHeadingIndex).join("\n"),
+        after: lines.slice(nextHeadingIndex).join("\n"),
+    };
 }
-function mergeAgentJson3Way(opts) {
-    let incoming;
-    let current;
-    let base;
-    try {
-        incoming = JSON.parse(opts.incomingText);
-        current = JSON.parse(opts.currentText);
-        base = JSON.parse(opts.baseText);
+function mergeIncidentsPolicy(opts) {
+    const incomingTrimmed = opts.incomingText.trim();
+    if (!incomingTrimmed)
+        return { nextText: opts.currentText, appended: false, appendedCount: 0 };
+    const incomingSection = splitEntriesSection(opts.incomingText);
+    const currentSection = splitEntriesSection(opts.currentText);
+    if (!incomingSection || !currentSection) {
+        return { nextText: opts.incomingText, appended: false, appendedCount: 0 };
     }
-    catch {
-        return null;
+    const incomingBlocks = parseIncidentEntryBlocks(incomingSection.entriesBody).map((block) => normalizeEntryBlock(block));
+    const currentBlocks = parseIncidentEntryBlocks(currentSection.entriesBody).map((block) => normalizeEntryBlock(block));
+    if (currentBlocks.length === 0) {
+        return { nextText: opts.incomingText, appended: false, appendedCount: 0 };
+    }
+    const baselineSection = opts.baselineText ? splitEntriesSection(opts.baselineText) : null;
+    const baselineBlocks = baselineSection
+        ? parseIncidentEntryBlocks(baselineSection.entriesBody).map((block) => normalizeEntryBlock(block))
+        : [];
+    const baselineSet = new Set(baselineBlocks);
+    const incomingSet = new Set(incomingBlocks);
+    const userAdded = currentBlocks.filter((block) => {
+        if (baselineSet.size > 0 && baselineSet.has(block))
+            return false;
+        return true;
+    });
+    const toAppend = userAdded.filter((block) => !incomingSet.has(block));
+    if (toAppend.length === 0) {
+        return { nextText: opts.incomingText, appended: false, appendedCount: 0 };
     }
-    if (!isJsonRecord(incoming) || !isJsonRecord(current) || !isJsonRecord(base))
+    const mergedBlocks = [...incomingBlocks, ...toAppend];
+    const renderedEntries = mergedBlocks.length > 0 ? `\n\n${mergedBlocks.join("\n\n")}\n` : "\n\n- None yet.\n";
+    const afterSuffix = incomingSection.after ? `\n${incomingSection.after.trimStart()}` : "";
+    const nextText = `${incomingSection.before.trimEnd()}` +
+        `${renderedEntries}` +
+        `${INCIDENTS_APPEND_MARKER}\n` +
+        `${afterSuffix}` +
+        `\n`;
+    return { nextText, appended: true, appendedCount: toAppend.length };
+}
+function normalizeUpgradeVersionLabel(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return "unknown";
+    if (/^v\d/i.test(trimmed))
+        return trimmed;
+    return `v${trimmed}`;
+}
+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")}`,
+    });
+}
+async function createUpgradeCommit(opts) {
+    const uniquePaths = [...new Set(opts.paths.filter(Boolean))];
+    if (uniquePaths.length === 0)
         return null;
-    const keys = new Set([...Object.keys(incoming), ...Object.keys(current), ...Object.keys(base)]);
-    const out = {};
-    for (const key of keys) {
-        const incVal = incoming[key];
-        const curVal = current[key];
-        const baseVal = base[key];
-        // 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 = !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) {
-                    const k = JSON.stringify(canonicalizeJson(item));
-                    if (!seen.has(k)) {
-                        merged.push(item);
-                        seen.add(k);
-                    }
-                }
-            }
-            out[key] = merged;
-            continue;
-        }
-        // Objects: shallow merge; for each subkey, prefer incoming unless user changed vs base.
-        if (isJsonRecord(incVal) && isJsonRecord(curVal) && isJsonRecord(baseVal)) {
-            const merged = { ...incVal };
-            const subKeys = new Set([
-                ...Object.keys(incVal),
-                ...Object.keys(curVal),
-                ...Object.keys(baseVal),
-            ]);
-            for (const sk of subKeys) {
-                const incSub = incVal[sk];
-                const curSub = curVal[sk];
-                const baseSub = baseVal[sk];
-                const userChanged = !jsonEqual(curSub, baseSub);
-                if (userChanged)
-                    merged[sk] = curSub;
-                else if (incSub !== undefined)
-                    merged[sk] = incSub;
-                else if (curSub !== undefined)
-                    merged[sk] = curSub;
-            }
-            out[key] = merged;
-            continue;
-        }
-        // Scalars: prefer incoming unless the user changed vs base.
-        if (!jsonEqual(curVal, baseVal)) {
-            if (curVal !== undefined)
-                out[key] = curVal;
-            else if (incVal !== undefined)
-                out[key] = incVal;
-            continue;
-        }
-        if (incVal !== undefined)
-            out[key] = incVal;
-        else if (curVal !== undefined)
-            out[key] = curVal;
+    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()}` : ""),
+        });
     }
-    return JSON.stringify(out, null, 2) + "\n";
+    const { stdout: hashOut } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+    });
+    return { hash: String(hashOut ?? "").trim(), subject };
 }
 export async function cmdUpgradeParsed(opts) {
     const flags = opts.flags;
@@ -400,6 +392,9 @@ export async function cmdUpgradeParsed(opts) {
         rootOverride: opts.rootOverride ?? null,
     });
     const loaded = await loadConfig(resolved.agentplaneDir);
+    if (flags.mode === "auto" && !flags.dryRun) {
+        await ensureCleanTrackedTreeForUpgrade(resolved.gitRoot);
+    }
     const upgradeStateDir = path.join(resolved.agentplaneDir, ".upgrade");
     const lockPath = path.join(upgradeStateDir, "lock.json");
     const statePath = path.join(upgradeStateDir, "state.json");
@@ -438,6 +433,7 @@ export async function cmdUpgradeParsed(opts) {
         let bundleLayout = "upgrade_bundle";
         let bundleRoot = "";
         let normalizedSourceToPersist = null;
+        let upgradeVersionLabel = normalizeUpgradeVersionLabel(getVersion());
         if (!hasBundle && !useRemote) {
             bundleLayout = "local_assets";
             bundleRoot = fileURLToPath(ASSETS_DIR_URL);
@@ -477,6 +473,12 @@ export async function cmdUpgradeParsed(opts) {
             const assetName = flags.asset ?? DEFAULT_UPGRADE_ASSET;
             const checksumName = flags.checksumAsset ?? DEFAULT_UPGRADE_CHECKSUM_ASSET;
             const release = (await fetchJson(releaseUrl, UPGRADE_RELEASE_METADATA_TIMEOUT_MS));
+            const releaseTag = (typeof release.tag_name === "string" && release.tag_name.trim()) ||
+                (typeof flags.tag === "string" && flags.tag.trim()) ||
+                "";
+            if (releaseTag) {
+                upgradeVersionLabel = normalizeUpgradeVersionLabel(releaseTag);
+            }
             const download = resolveUpgradeDownloadFromRelease({
                 release,
                 owner,
@@ -546,6 +548,14 @@ export async function cmdUpgradeParsed(opts) {
             ? fileURLToPath(new URL("../../assets/framework.manifest.json", import.meta.url))
             : path.join(bundleRoot, "framework.manifest.json");
         const manifest = await loadFrameworkManifestFromPath(manifestPath);
+        const modeLabel = flags.dryRun ? "dry-run" : flags.mode === "agent" ? "review" : "apply";
+        process.stdout.write(`Upgrade source: ${describeUpgradeSource({
+            bundleLayout,
+            hasExplicitBundle: hasBundle,
+            useRemote,
+        })}\n` +
+            `Upgrade version: ${upgradeVersionLabel}\n` +
+            `Upgrade mode: ${modeLabel}\n`);
         const additions = [];
         const updates = [];
         const skipped = [];
@@ -553,7 +563,7 @@ export async function cmdUpgradeParsed(opts) {
         const merged = [];
         const missingRequired = [];
         const reviewRecords = [];
-        const reviewSnapshots = new Map();
+        let incidentsAppendedCount = 0;
         const readBaselineText = async (baselineKey) => {
             try {
                 return await readFile(path.join(baselineDirNew, baselineKey), "utf8");
@@ -571,33 +581,46 @@ export async function cmdUpgradeParsed(opts) {
         const toBaselineKey = (rel) => {
             if (rel === "AGENTS.md")
                 return "AGENTS.md";
+            if (rel === "CLAUDE.md")
+                return "CLAUDE.md";
             if (rel.startsWith(".agentplane/"))
                 return rel.slice(".agentplane/".length);
             return null;
         };
+        const policyGatewayRel = (await fileExists(path.join(resolved.gitRoot, "AGENTS.md")))
+            ? "AGENTS.md"
+            : (await fileExists(path.join(resolved.gitRoot, "CLAUDE.md")))
+                ? "CLAUDE.md"
+                : "AGENTS.md";
+        const remapManagedGatewayRel = (rel) => {
+            if (rel === "AGENTS.md" && policyGatewayRel === "CLAUDE.md")
+                return "CLAUDE.md";
+            return rel;
+        };
         for (const entry of manifest.files) {
-            const rel = entry.path.replaceAll("\\", "/").trim();
-            if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+            const relRaw = entry.path.replaceAll("\\", "/").trim();
+            if (!relRaw || relRaw.startsWith("..") || path.isAbsolute(relRaw)) {
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
                     message: `Invalid manifest path: ${entry.path}`,
                 });
             }
-            if (isDeniedUpgradePath(rel)) {
+            if (isDeniedUpgradePath(relRaw)) {
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
-                    message: `Manifest includes a denied path: ${rel}`,
+                    message: `Manifest includes a denied path: ${relRaw}`,
                 });
             }
-            if (!isAllowedUpgradePath(rel)) {
+            if (!isAllowedUpgradePath(relRaw)) {
                 throw new CliError({
                     exitCode: 3,
                     code: "E_VALIDATION",
-                    message: `Manifest path not allowed: ${rel}`,
+                    message: `Manifest path not allowed: ${relRaw}`,
                 });
             }
+            const rel = remapManagedGatewayRel(relRaw);
             const destPath = path.join(resolved.gitRoot, rel);
             const kind = await getPathKind(destPath);
             if (kind === "dir") {
@@ -607,16 +630,27 @@ export async function cmdUpgradeParsed(opts) {
                     message: `Upgrade target is a directory: ${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;
+            {
+                const sourceRelRaw = (entry.source_path ?? entry.path).replaceAll("\\", "/").trim();
+                const mappedSourceRel = rel === "CLAUDE.md" && sourceRelRaw === "AGENTS.md" ? "CLAUDE.md" : sourceRelRaw;
+                const sourceCandidates = [...new Set([mappedSourceRel, sourceRelRaw])];
+                let loaded = null;
+                for (const candidate of sourceCandidates) {
+                    try {
+                        loaded = await readFile(path.join(bundleRoot, candidate));
+                        break;
+                    }
+                    catch {
+                        // try next candidate
+                    }
+                }
+                if (!loaded) {
+                    if (entry.required)
+                        missingRequired.push(rel);
+                    continue;
+                }
+                data = loaded;
             }
             let existingBuf = null;
             let existingText = null;
@@ -649,7 +683,7 @@ export async function cmdUpgradeParsed(opts) {
                     aText: currentTextForReview,
                     bText: incomingTextOriginal,
                 }) === false;
-            // Fast-path: if incoming already equals local, semantic merge/snapshots are unnecessary.
+            // Fast-path: incoming already equals local.
             if (currentTextForReview !== null && currentAndIncomingEqual) {
                 skipped.push(rel);
                 reviewRecords.push({
@@ -665,7 +699,7 @@ export async function cmdUpgradeParsed(opts) {
                 });
                 continue;
             }
-            // No local edits vs baseline: file can be safely replaced with incoming without semantic merge.
+            // No local edits vs baseline: file can be safely replaced with incoming.
             if (currentTextForReview !== null && changedCurrentVsBaseline === false) {
                 updates.push(rel);
                 fileContents.set(rel, data);
@@ -684,53 +718,24 @@ export async function cmdUpgradeParsed(opts) {
             }
             let mergeApplied = false;
             let mergePath = "none";
-            // 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");
+            // Simplified policy for upgrade:
+            // - All managed files are replaced with incoming bundle content.
+            // - incidents.md is append-only when local file already has content.
+            if (existingBuf && rel === INCIDENTS_POLICY_PATH) {
+                existingText = existingBuf.toString("utf8");
+                const mergedIncidents = mergeIncidentsPolicy({
+                    incomingText: data.toString("utf8"),
+                    currentText: existingText,
+                    baselineText,
+                });
+                data = Buffer.from(mergedIncidents.nextText, "utf8");
+                if (mergedIncidents.appended) {
                     merged.push(rel);
                     mergeApplied = true;
-                    mergePath = "markdownOverrides";
-                }
-                else if (entry.merge_strategy === "agent_json_3way" &&
-                    rel.startsWith(".agentplane/agents/") &&
-                    rel.endsWith(".json")) {
-                    existingText = existingBuf.toString("utf8");
-                    let mergedText = null;
-                    if (baselineText !== null) {
-                        try {
-                            mergedText = mergeAgentJson3Way({
-                                incomingText: data.toString("utf8"),
-                                currentText: existingText,
-                                baseText: baselineText,
-                            });
-                        }
-                        catch {
-                            mergedText = null;
-                        }
-                    }
-                    if (mergedText) {
-                        mergePath = "3way";
-                    }
-                    else {
-                        mergedText = mergeAgentJsonIncomingWins(data.toString("utf8"), existingText);
-                        if (mergedText) {
-                            mergePath = baselineText === null ? "incomingWins" : "incomingWinsFallback";
-                        }
-                    }
-                    if (mergedText) {
-                        data = Buffer.from(mergedText, "utf8");
-                        merged.push(rel);
-                        mergeApplied = true;
-                    }
-                    else {
-                        mergePath = "parseFailed";
-                    }
+                    mergePath = "incidentsAppend";
+                    incidentsAppendedCount += mergedIncidents.appendedCount;
                 }
             }
-            const proposedText = data.toString("utf8");
             const currentDiffersFromIncoming = currentTextForReview === null
                 ? false
                 : textChangedForType({
@@ -738,16 +743,7 @@ export async function cmdUpgradeParsed(opts) {
                     aText: currentTextForReview,
                     bText: incomingTextOriginal,
                 });
-            const baselineConflict = baselineText === null
-                ? false
-                : currentDiffersFromIncoming &&
-                    Boolean(changedCurrentVsBaseline) &&
-                    Boolean(changedIncomingVsBaseline);
-            const unresolvedLocalEditsConflict = baselineText === null
-                ? false
-                : currentDiffersFromIncoming && Boolean(changedCurrentVsBaseline) && !mergeApplied;
-            const parseFailedConflict = mergePath === "parseFailed";
-            const needsSemanticReview = baselineConflict || unresolvedLocalEditsConflict || parseFailedConflict;
+            const needsSemanticReview = false;
             reviewRecords.push({
                 relPath: rel,
                 mergeStrategy: entry.merge_strategy,
@@ -759,14 +755,6 @@ export async function cmdUpgradeParsed(opts) {
                 mergeApplied,
                 mergePath,
             });
-            if (flags.mode === "agent" && needsSemanticReview) {
-                reviewSnapshots.set(rel, {
-                    incomingText: incomingTextOriginal,
-                    currentText: currentTextForReview,
-                    baselineText,
-                    proposedText,
-                });
-            }
             fileContents.set(rel, data);
             if (kind === null)
                 additions.push(rel);
@@ -808,7 +796,7 @@ export async function cmdUpgradeParsed(opts) {
             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` +
+                `Mode: agent-assisted review (no files modified)\n\n` +
                 `## Summary\n\n` +
                 `- additions: ${additions.length}\n` +
                 `- updates: ${updates.length}\n` +
@@ -829,7 +817,7 @@ export async function cmdUpgradeParsed(opts) {
                 `\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` +
+                `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` +
@@ -841,7 +829,7 @@ export async function cmdUpgradeParsed(opts) {
                 `- .git/**\n\n` +
                 `## Notes\n\n` +
                 `- The upgrade bundle is validated against framework.manifest.json.\n` +
-                `- AGENTS.md is the canonical policy file at the workspace root.\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` +
@@ -862,30 +850,9 @@ export async function cmdUpgradeParsed(opts) {
                 },
                 files: reviewRecords,
             }, null, 2) + "\n", "utf8");
-            if (needsReview.length > 0) {
-                const snapshotsRoot = path.join(runDir, "snapshots");
-                for (const [rel, snap] of reviewSnapshots.entries()) {
-                    const variants = [
-                        ["current", snap.currentText],
-                        ["incoming", snap.incomingText],
-                        ["baseline", snap.baselineText],
-                        ["proposed", snap.proposedText],
-                    ];
-                    for (const [variant, text] of variants) {
-                        if (text === null)
-                            continue;
-                        const outPath = path.join(snapshotsRoot, variant, rel);
-                        await mkdir(path.dirname(outPath), { recursive: true });
-                        await writeFile(outPath, text, "utf8");
-                    }
-                }
-            }
             const relRunDir = path.relative(resolved.gitRoot, runDir);
             process.stdout.write(`Upgrade plan written: ${relRunDir}\n`);
-            process.stdout.write(`Prompt merge required: ${needsReview.length} files\n`);
-            if (needsReview.length > 0) {
-                process.stdout.write(`Hint: Create an UPGRADER task and attach ${relRunDir}\n`);
-            }
+            process.stdout.write(`Review-required files: ${needsReview.length}\n`);
             return 0;
         }
         for (const rel of [...additions, ...updates]) {
@@ -897,8 +864,8 @@ export async function cmdUpgradeParsed(opts) {
             await mkdir(path.dirname(destPath), { recursive: true });
             const data = fileContents.get(rel);
             if (data) {
-                if (rel === "AGENTS.md") {
-                    // If AGENTS.md is a symlink, avoid overwriting an arbitrary external target.
+                if (rel === "AGENTS.md" || rel === "CLAUDE.md") {
+                    // If policy gateway file is a symlink, avoid overwriting an arbitrary external target.
                     // This permits repo-internal symlinks (e.g. the agentplane repo itself) while
                     // keeping user workspaces safe.
                     try {
@@ -911,7 +878,7 @@ export async function cmdUpgradeParsed(opts) {
                                 throw new CliError({
                                     exitCode: exitCodeForError("E_VALIDATION"),
                                     code: "E_VALIDATION",
-                                    message: `Refusing to overwrite symlinked AGENTS.md target outside repo: ${linkTarget}. ` +
+                                    message: `Refusing to overwrite symlinked ${rel} target outside repo: ${linkTarget}. ` +
                                         "Replace the symlink with a regular file and retry.",
                                 });
                             }
@@ -933,12 +900,17 @@ export async function cmdUpgradeParsed(opts) {
                 await writeFile(baselinePath, data);
             }
         }
-        const raw = { ...loaded.raw };
-        if (normalizedSourceToPersist) {
-            setByDottedKey(raw, "framework.source", normalizedSourceToPersist);
+        const hasManagedMutations = additions.length > 0 || updates.length > 0;
+        const hasSourceMigration = normalizedSourceToPersist !== null;
+        const shouldMutateConfig = hasManagedMutations || hasSourceMigration;
+        if (shouldMutateConfig) {
+            const raw = { ...loaded.raw };
+            if (normalizedSourceToPersist) {
+                setByDottedKey(raw, "framework.source", normalizedSourceToPersist);
+            }
+            setByDottedKey(raw, "framework.last_update", new Date().toISOString());
+            await saveConfig(resolved.agentplaneDir, raw);
         }
-        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,
@@ -952,8 +924,24 @@ export async function cmdUpgradeParsed(opts) {
             },
             files: reviewRecords,
         }, null, 2) + "\n", "utf8");
+        const commitPaths = [
+            ...new Set([...additions, ...updates, ...(shouldMutateConfig ? [CONFIG_REL_PATH] : [])]),
+        ];
+        const commit = await createUpgradeCommit({
+            gitRoot: resolved.gitRoot,
+            paths: commitPaths,
+            versionLabel: upgradeVersionLabel,
+            source: bundleLayout,
+            additions: additions.length,
+            updates: updates.length,
+            unchanged: skipped.length,
+            incidentsAppendedCount,
+        });
         await cleanupAutoUpgradeArtifacts({ upgradeStateDir, createdBackups });
         process.stdout.write(`Upgrade applied: ${additions.length} add, ${updates.length} update, ${skipped.length} unchanged\n`);
+        if (commit) {
+            process.stdout.write(`Upgrade commit: ${commit.hash.slice(0, 12)} ${commit.subject}\n`);
+        }
         return 0;
     }
     finally {