@warpgogol/forge 5.2.4 → 5.3.1

package/src/onboarding/upgrade.ts

@@ -24,9 +24,11 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import type { WorkspaceIO } from "../types.ts";
+import { resolveIo } from "../utils/io.ts";
+import { hasGeneratedMarker, mergeEditableGenerated } from "../utils/index.ts";
 import path from "node:path";
-import { execSync } from "node:child_process";
+
 import { stringify as stringifyYaml, parse as parseYaml } from "yaml";
 import {
   FORGE_CLI_BINDING_DEFAULTS,
@@ -40,6 +42,13 @@ import {
 } from "../config/forge-config.ts";
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
 import { syncKnowledgeFile } from "../knowledge/index.ts";
+import { writeFileIfChanged } from "../utils/fs-idempotent.ts";
+import { writeSkillMarker, pruneStaleSkillDirs, type PruneResult } from "./skill-markers.ts";
+import {
+  planPrettierignore,
+  applyPrettierignore,
+  type PrettierignoreResult,
+} from "./prettierignore.ts";
 import { generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { scaffoldMemoryLayer } from "./memory-scaffold.ts";
 import type { SkippedSkill } from "./init.ts";
@@ -54,68 +63,80 @@ export interface UpgradeResult {
   bindingsAdded: { key: string; value: string }[];
   skippedSkills: SkippedSkill[];
   nestedAgentsGenerated: string[];
+  /** RFC-1153: dry-run only — nested guides whose merged output differs from disk. */
+  nestedAgentsPlanned: string[];
+  /** RFC-1153: files merged with a carried custom tail below the boundary. */
+  nestedAgentsPreserved: string[];
+  /** RFC-1153: hand-written or unmapped files skipped by the merge. */
+  nestedAgentsSkipped: string[];
   memoryScaffold: { created: string[]; gitignoreUpdated: boolean; skipped: string[] };
   npmUpdated: boolean;
   npmUpdateSkipped: string | null;
   latestNpmVersion: string | null;
   npmVersionWarning: string | null;
   doctorReport: unknown;
+  // RFC-1154: reconcile phase results (runs on every upgrade incl. noop).
+  skillsPruned: string[];
+  skillsKeptWithConsumerFiles: string[];
+  prettierignore: PrettierignoreResult;
 }
 
-function isMonorepoForge(workspaceRoot: string): boolean {
-  return fs.existsSync(path.join(workspaceRoot, "packages", "forge", "package.json"));
+async function isMonorepoForge(workspaceRoot: string, io: WorkspaceIO): Promise<boolean> {
+  return io.exists(path.join(workspaceRoot, "packages", "forge", "package.json"));
 }
 
-function updateNpmPackage(
+async function updateNpmPackage(
   workspaceRoot: string,
   config: ForgeConfig,
   isDryRun: boolean,
-): { updated: boolean; skipped: string | null } {
-  if (isMonorepoForge(workspaceRoot)) {
+  io: WorkspaceIO,
+): Promise<{ updated: boolean; skipped: string | null }> {
+  if (await isMonorepoForge(workspaceRoot, io)) {
     return { updated: false, skipped: "monorepo (local package, not npm-installed)" };
   }
 
   const pm = config.project.packageManager;
   const installCmd = resolvePmInstall(pm);
-  const fullCmd = `${installCmd} @warpgogol/forge@latest`;
+  const installArgs = installCmd.split(/\s+/);
 
   if (isDryRun) {
     return { updated: false, skipped: "dry-run" };
   }
 
-  try {
-    execSync(fullCmd, {
+  const result = await io
+    .exec(installArgs[0]!, [...installArgs.slice(1), "@warpgogol/forge@latest"], {
       cwd: workspaceRoot,
-      stdio: "pipe",
-      timeout: 120_000,
-    });
+      timeoutMs: 120_000,
+    })
+    .catch(() => null);
+  if (result && result.exitCode === 0) {
     return { updated: true, skipped: null };
-  } catch {
-    return { updated: false, skipped: "install failed (network error or registry unavailable)" };
   }
+  return { updated: false, skipped: "install failed (network error or registry unavailable)" };
 }
 
-function readForgePackageVersion(forgeRoot: string): string {
+async function readForgePackageVersion(forgeRoot: string, io: WorkspaceIO): Promise<string> {
   const pkgPath = path.join(forgeRoot, "package.json");
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as { version?: string };
+  const pkg = JSON.parse(await io.readFile(pkgPath)) as { version?: string };
   return pkg.version ?? "0.0.0-unknown";
 }
 
-function checkLatestNpmVersion(
+async function checkLatestNpmVersion(
   workspaceRoot: string,
   installedVersion: string,
   isMonorepo: boolean,
-): { latest: string | null; warning: string | null } {
+  io: WorkspaceIO,
+): Promise<{ latest: string | null; warning: string | null }> {
   if (isMonorepo) {
     return { latest: null, warning: null };
   }
   try {
-    const latest = execSync("npm view @warpgogol/forge version", {
+    const result = await io.exec("npm", ["view", "@warpgogol/forge", "version"], {
       cwd: workspaceRoot,
-      stdio: "pipe",
-      timeout: 15_000,
-      encoding: "utf8",
-    }).trim();
+      timeoutMs: 15_000,
+    });
+    if (result.exitCode !== 0) throw new Error(result.stderr || "npm view failed");
+    const latest = result.stdout.trim();
     if (!latest || !/^\d+\.\d+\.\d+/.test(latest)) {
       return { latest: null, warning: null };
     }
@@ -139,28 +160,34 @@ function checkLatestNpmVersion(
   }
 }
 
-function syncForgeSkills(
+async function syncForgeSkills(
   workspaceRoot: string,
   forgeRoot: string,
   skillsDir: string,
   dryRun: boolean,
-): { updated: string[]; knowledgeConflicts: string[] } {
+  io: WorkspaceIO,
+): Promise<{ updated: string[]; knowledgeConflicts: string[] }> {
   const updated: string[] = [];
   const knowledgeConflicts: string[] = [];
   const agentsSkillsDir = path.join(workspaceRoot, skillsDir);
 
   for (const skill of FORGE_SKILLS) {
     const srcPath = path.join(forgeRoot, skill.path);
-    if (!fs.existsSync(srcPath)) continue;
+    if (!(await io.exists(srcPath))) continue;
 
     const skillName = skill.name;
     const destDir = path.join(agentsSkillsDir, skillName);
     const destPath = path.join(destDir, "SKILL.md");
 
     if (!dryRun) {
-      fs.mkdirSync(destDir, { recursive: true });
-      const content = fs.readFileSync(srcPath, "utf8");
-      fs.writeFileSync(destPath, content, "utf8");
+      await io.mkdir(destDir);
+      const content = await io.readFile(srcPath);
+      await writeFileIfChanged(destPath, content, io);
+
+      // RFC-1154: marker manifest lists SKILL.md + knowledge files that carry
+      // pure forge content. Merged/skipped knowledge files hold consumer
+      // entries — excluded so a stale dir is kept rather than deleted.
+      const markerFiles = ["SKILL.md"];
 
       // Sync knowledge files (append-only — never overwrite local entries)
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -174,11 +201,14 @@ function syncForgeSkills(
               if (typeof kf !== "string") continue;
               const kfSrcPath = path.join(skillSrcDir, kf);
               const kfDestPath = path.join(destDir, kf);
-              if (fs.existsSync(kfSrcPath)) {
+              if (await io.exists(kfSrcPath)) {
                 const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
                 for (const id of syncResult.conflicts) {
                   knowledgeConflicts.push(`${skillName}/${kf}#${id}`);
                 }
+                if (syncResult.action === "copied" || syncResult.action === "unchanged") {
+                  markerFiles.push(kf);
+                }
               }
             }
           }
@@ -186,6 +216,7 @@ function syncForgeSkills(
           // Frontmatter parse error — SKILL-01 will catch in validation
         }
       }
+      await writeSkillMarker(destDir, markerFiles, io);
     }
     updated.push(skillName);
   }
@@ -193,37 +224,45 @@ function syncForgeSkills(
   return { updated, knowledgeConflicts };
 }
 
-function syncSharedKnowledge(
+async function syncSharedKnowledge(
   workspaceRoot: string,
   forgeRoot: string,
   skillsDir: string,
   dryRun: boolean,
-): { updated: string[]; knowledgeConflicts: string[] } {
+  io: WorkspaceIO,
+): Promise<{ updated: string[]; knowledgeConflicts: string[] }> {
   const updated: string[] = [];
   const knowledgeConflicts: string[] = [];
   const srcPath = path.join(forgeRoot, "skills", "shared", "knowledge", "learned-principles.md");
-  if (!fs.existsSync(srcPath)) return { updated, knowledgeConflicts };
+  if (!(await io.exists(srcPath))) return { updated, knowledgeConflicts };
 
   const destDir = path.join(workspaceRoot, skillsDir, "shared-knowledge");
   const destPath = path.join(destDir, "learned-principles.md");
 
   if (!dryRun) {
-    fs.mkdirSync(destDir, { recursive: true });
+    await io.mkdir(destDir);
     const syncResult = syncKnowledgeFile(srcPath, destPath);
     for (const id of syncResult.conflicts) {
       knowledgeConflicts.push(`shared-knowledge/learned-principles.md#${id}`);
     }
+    // RFC-1154: marker lists the file only when its content is purely forge's.
+    const markerFiles =
+      syncResult.action === "copied" || syncResult.action === "unchanged"
+        ? ["learned-principles.md"]
+        : [];
+    await writeSkillMarker(destDir, markerFiles, io);
   }
   updated.push("shared-knowledge");
   return { updated, knowledgeConflicts };
 }
 
-function syncPackSkills(
+async function syncPackSkills(
   workspaceRoot: string,
   config: ForgeConfig,
   skillsDir: string,
   dryRun: boolean,
-): { updated: string[]; skipped: SkippedSkill[]; knowledgeConflicts: string[] } {
+  io: WorkspaceIO,
+): Promise<{ updated: string[]; skipped: SkippedSkill[]; knowledgeConflicts: string[] }> {
   const updated: string[] = [];
   const skipped: SkippedSkill[] = [];
   const knowledgeConflicts: string[] = [];
@@ -238,7 +277,7 @@ function syncPackSkills(
 
   for (const skill of packSkills) {
     const srcPath = path.join(workspaceRoot, skill.dir, skill.path);
-    if (!fs.existsSync(srcPath)) continue;
+    if (!(await io.exists(srcPath))) continue;
 
     const skillName = skill.name;
 
@@ -251,9 +290,13 @@ function syncPackSkills(
     const destPath = path.join(destDir, "SKILL.md");
 
     if (!dryRun) {
-      fs.mkdirSync(destDir, { recursive: true });
-      const content = fs.readFileSync(srcPath, "utf8");
-      fs.writeFileSync(destPath, content, "utf8");
+      await io.mkdir(destDir);
+      const content = await io.readFile(srcPath);
+      await writeFileIfChanged(destPath, content, io);
+
+      // RFC-1154: same marker rule as forge skills — merged/skipped knowledge
+      // files carry consumer entries and are excluded from the manifest.
+      const markerFiles = ["SKILL.md"];
 
       // Sync knowledge files (append-only — never overwrite local entries)
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -267,11 +310,14 @@ function syncPackSkills(
               if (typeof kf !== "string") continue;
               const kfSrcPath = path.join(skillSrcDir, kf);
               const kfDestPath = path.join(destDir, kf);
-              if (fs.existsSync(kfSrcPath)) {
+              if (await io.exists(kfSrcPath)) {
                 const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
                 for (const id of syncResult.conflicts) {
                   knowledgeConflicts.push(`${skillName}/${kf}#${id}`);
                 }
+                if (syncResult.action === "copied" || syncResult.action === "unchanged") {
+                  markerFiles.push(kf);
+                }
               }
             }
           }
@@ -279,6 +325,7 @@ function syncPackSkills(
           // Frontmatter parse error
         }
       }
+      await writeSkillMarker(destDir, markerFiles, io);
     }
     updated.push(skillName);
   }
@@ -286,6 +333,94 @@ function syncPackSkills(
   return { updated, skipped, knowledgeConflicts };
 }
 
+/**
+ * RFC-1154 reconcile phase — runs on every forge upgrade, including the
+ * same-version noop path: markers for synced dirs, prune stale marked dirs,
+ * managed .prettierignore block. Idempotent; dry-run passes through.
+ */
+async function reconcileGeneratedSurface(
+  workspaceRoot: string,
+  forgeRoot: string,
+  config: ForgeConfig,
+  dryRun: boolean,
+  io: WorkspaceIO,
+): Promise<{
+  updated: string[];
+  knowledgeConflicts: string[];
+  skipped: SkippedSkill[];
+  prune: PruneResult;
+  prettierignore: PrettierignoreResult;
+  /** Non-fatal reconcile failures — surface as warnings, never block upgrade. */
+  warnings: string[];
+}> {
+  const forgeSkillsResult = await syncForgeSkills(
+    workspaceRoot,
+    forgeRoot,
+    config.paths.skillsDir,
+    dryRun,
+    io,
+  );
+  const packResult = await syncPackSkills(workspaceRoot, config, config.paths.skillsDir, dryRun, io);
+  const sharedKnowledgeResult = await syncSharedKnowledge(
+    workspaceRoot,
+    forgeRoot,
+    config.paths.skillsDir,
+    dryRun,
+    io,
+  );
+
+  const currentSyncSet = new Set([
+    ...forgeSkillsResult.updated,
+    ...packResult.updated,
+    ...sharedKnowledgeResult.updated,
+  ]);
+
+  const warnings: string[] = [];
+
+  let prune: PruneResult = { pruned: [], keptWithConsumerFiles: [] };
+  if (!dryRun) {
+    try {
+      prune = await pruneStaleSkillDirs(
+        path.join(workspaceRoot, config.paths.skillsDir),
+        currentSyncSet,
+        io,
+      );
+    } catch (err) {
+      warnings.push(`stale skill dir prune failed: ${(err as Error).message}`);
+    }
+  }
+
+  let prettierignore: PrettierignoreResult = "skipped";
+  if (!dryRun) {
+    try {
+      prettierignore = await applyPrettierignore(
+        workspaceRoot,
+        await planPrettierignore(workspaceRoot, config.paths.skillsDir, io),
+        io,
+      );
+    } catch (err) {
+      warnings.push(`.prettierignore reconcile failed: ${(err as Error).message}`);
+    }
+  }
+
+  return {
+    updated: [
+      ...forgeSkillsResult.updated,
+      ...packResult.updated,
+      ...sharedKnowledgeResult.updated,
+    ],
+    knowledgeConflicts: [
+      ...forgeSkillsResult.knowledgeConflicts,
+      ...packResult.knowledgeConflicts,
+      ...sharedKnowledgeResult.knowledgeConflicts,
+    ],
+    skipped: packResult.skipped,
+    prune,
+    prettierignore,
+    warnings,
+  };
+}
+
 function addMissingBindingDefaults(
   config: ForgeConfig,
   dryRun: boolean,
@@ -313,12 +448,13 @@ function addMissingBindingDefaults(
   return added;
 }
 
-function updateSyncedVersion(
+async function updateSyncedVersion(
   workspaceRoot: string,
   config: ForgeConfig,
   version: string,
   dryRun: boolean,
-): void {
+  io: WorkspaceIO,
+): Promise<void> {
   if (dryRun) return;
 
   // Set the syncedVersion on the in-memory config (bindings already updated)
@@ -328,7 +464,7 @@ function updateSyncedVersion(
   // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
   // never the resolved StackProfile object, never drops an unresolvable id.
   const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
-  fs.writeFileSync(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)), "utf8");
+  await io.writeFile(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)));
 }
 
 export async function runUpgrade(
@@ -336,12 +472,13 @@ export async function runUpgrade(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<UpgradeResult>> {
   const { workspaceRoot, dryRun } = context;
+  const fio = resolveIo(context.io);
   const isDryRun = dryRun || input.flags["dry-run"] === true;
   const isUpdateNpm = input.flags["update-npm"] === true;
 
   // Step 0: Check forge.yaml exists
   const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
-  if (!fs.existsSync(forgeYamlPath)) {
+  if (!(await fio.exists(forgeYamlPath))) {
     return {
       data: {
         command: "forge.upgrade",
@@ -352,12 +489,18 @@ export async function runUpgrade(
         bindingsAdded: [],
         skippedSkills: [],
         nestedAgentsGenerated: [],
+        nestedAgentsPlanned: [],
+        nestedAgentsPreserved: [],
+        nestedAgentsSkipped: [],
         memoryScaffold: { created: [], gitignoreUpdated: false, skipped: [] },
         npmUpdated: false,
         npmUpdateSkipped: null,
         latestNpmVersion: null,
         npmVersionWarning: null,
         doctorReport: null,
+        skillsPruned: [],
+        skillsKeptWithConsumerFiles: [],
+        prettierignore: "skipped",
       },
       nextSteps: [{ action: "Run 'forge create' to create forge.yaml first", kind: "required" }],
       exitCode: 1,
@@ -375,7 +518,7 @@ export async function runUpgrade(
     } catch {
       configForNpm = { project: { packageManager: "npm" } } as unknown as ForgeConfig;
     }
-    const npmResult = updateNpmPackage(workspaceRoot, configForNpm, isDryRun);
+    const npmResult = await updateNpmPackage(workspaceRoot, configForNpm, isDryRun, fio);
     npmUpdated = npmResult.updated;
     npmUpdateSkipped = npmResult.skipped;
   }
@@ -385,7 +528,7 @@ export async function runUpgrade(
   let toVersion: string;
   try {
     forgeRoot = context.forgeRoot ?? resolveForgeRoot(workspaceRoot);
-    toVersion = readForgePackageVersion(forgeRoot);
+    toVersion = await readForgePackageVersion(forgeRoot, fio);
   } catch (err) {
     return {
       data: {
@@ -397,12 +540,18 @@ export async function runUpgrade(
         bindingsAdded: [],
         skippedSkills: [],
         nestedAgentsGenerated: [],
+        nestedAgentsPlanned: [],
+        nestedAgentsPreserved: [],
+        nestedAgentsSkipped: [],
         memoryScaffold: { created: [], gitignoreUpdated: false, skipped: [] },
         npmUpdated: false,
         npmUpdateSkipped: null,
         latestNpmVersion: null,
         npmVersionWarning: null,
         doctorReport: null,
+        skillsPruned: [],
+        skillsKeptWithConsumerFiles: [],
+        prettierignore: "skipped",
       },
       nextSteps: [
         { action: "Install @warpgogol/forge first: npm install @warpgogol/forge", kind: "required" },
@@ -413,7 +562,7 @@ export async function runUpgrade(
   }
 
   // Step 1.5: Check npm for newer version (non-fatal)
-  const npmCheck = checkLatestNpmVersion(workspaceRoot, toVersion, isMonorepoForge(workspaceRoot));
+  const npmCheck = await checkLatestNpmVersion(workspaceRoot, toVersion, await isMonorepoForge(workspaceRoot, fio), fio);
   if (npmCheck.warning && context.outputFormat === "pretty") {
     context.logger.warn(`⚠ ${npmCheck.warning}`);
   }
@@ -433,12 +582,18 @@ export async function runUpgrade(
         bindingsAdded: [],
         skippedSkills: [],
         nestedAgentsGenerated: [],
+        nestedAgentsPlanned: [],
+        nestedAgentsPreserved: [],
+        nestedAgentsSkipped: [],
         memoryScaffold: { created: [], gitignoreUpdated: false, skipped: [] },
         npmUpdated: false,
         npmUpdateSkipped: null,
         latestNpmVersion: npmCheck.latest,
         npmVersionWarning: npmCheck.warning,
         doctorReport: null,
+        skillsPruned: [],
+        skillsKeptWithConsumerFiles: [],
+        prettierignore: "skipped",
       },
       nextSteps: [
         { action: `Fix forge.yaml: ${(err as Error).message}`, kind: "required" },
@@ -451,23 +606,43 @@ export async function runUpgrade(
   const fromVersion = config.forge?.syncedVersion ?? null;
 
   if (fromVersion === toVersion) {
-    // Noop — versions match
+    // Noop version-wise — but the RFC-1154 reconcile (markers, stale-dir prune,
+    // managed .prettierignore) still runs so a same-version upgrade fixes lint debt.
+    const reconcile = await reconcileGeneratedSurface(
+      workspaceRoot,
+      forgeRoot,
+      config,
+      isDryRun,
+      fio,
+    );
+    for (const kept of reconcile.prune.keptWithConsumerFiles) {
+      context.logger.warn(`forge.upgrade: kept stale skill dir ${kept}`);
+    }
+    for (const warn of reconcile.warnings) {
+      context.logger.warn(`forge.upgrade: ${warn}`);
+    }
     return {
       data: {
         command: "forge.upgrade",
         status: "noop",
         fromVersion,
         toVersion,
-        skillsUpdated: [],
+        skillsUpdated: reconcile.updated,
         bindingsAdded: [],
-        skippedSkills: [],
+        skippedSkills: reconcile.skipped,
         nestedAgentsGenerated: [],
+        nestedAgentsPlanned: [],
+        nestedAgentsPreserved: [],
+        nestedAgentsSkipped: [],
         memoryScaffold: { created: [], gitignoreUpdated: false, skipped: [] },
         npmUpdated: npmUpdated,
         npmUpdateSkipped: npmUpdateSkipped,
         latestNpmVersion: npmCheck.latest,
         npmVersionWarning: npmCheck.warning,
         doctorReport: null,
+        skillsPruned: reconcile.prune.pruned,
+        skillsKeptWithConsumerFiles: reconcile.prune.keptWithConsumerFiles,
+        prettierignore: reconcile.prettierignore,
       },
       nextSteps: npmCheck.warning
         ? [{ action: npmCheck.warning, kind: "optional" }]
@@ -479,40 +654,26 @@ export async function runUpgrade(
     };
   }
 
-  // Step 3: Sync forge skills
-  const forgeSkillsResult = syncForgeSkills(
+  // Step 3: RFC-1154 reconcile — sync forge+pack skills + shared knowledge,
+  // write .forge-managed markers, prune stale marked dirs, reconcile the
+  // managed .prettierignore block.
+  const reconcile = await reconcileGeneratedSurface(
     workspaceRoot,
     forgeRoot,
-    config.paths.skillsDir,
-    isDryRun,
-  );
-
-  // Step 3b: Sync pack skills
-  const packResult = syncPackSkills(
-    workspaceRoot,
     config,
-    config.paths.skillsDir,
     isDryRun,
+    fio,
   );
 
-  // Step 3c: Sync shared knowledge layer (RFC-0663)
-  const sharedKnowledgeResult = syncSharedKnowledge(
-    workspaceRoot,
-    forgeRoot,
-    config.paths.skillsDir,
-    isDryRun,
-  );
-
-  const skillsUpdated = [
-    ...forgeSkillsResult.updated,
-    ...packResult.updated,
-    ...sharedKnowledgeResult.updated,
-  ];
-  const knowledgeConflicts = [
-    ...forgeSkillsResult.knowledgeConflicts,
-    ...packResult.knowledgeConflicts,
-    ...sharedKnowledgeResult.knowledgeConflicts,
-  ];
+  const skillsUpdated = reconcile.updated;
+  const knowledgeConflicts = reconcile.knowledgeConflicts;
+  const packSkipped = reconcile.skipped;
+  for (const kept of reconcile.prune.keptWithConsumerFiles) {
+    context.logger.warn(`forge.upgrade: kept stale skill dir ${kept}`);
+  }
+  for (const warn of reconcile.warnings) {
+    context.logger.warn(`forge.upgrade: ${warn}`);
+  }
   if (knowledgeConflicts.length > 0) {
     context.logger.warn(
       `forge.upgrade: ${knowledgeConflicts.length} knowledge entr${knowledgeConflicts.length === 1 ? "y" : "ies"} ` +
@@ -528,18 +689,47 @@ export async function runUpgrade(
 
   // Step 5: Update forge.syncedVersion
   if (!isDryRun) {
-    updateSyncedVersion(workspaceRoot, config, toVersion, false);
+    await updateSyncedVersion(workspaceRoot, config, toVersion, false, fio);
   }
 
-  // Step 5b: Generate nested AGENTS.md (RFC-0611)
+  // Step 5b: Generate nested AGENTS.md (RFC-0611). RFC-1153: the write path
+  // merges at the forge:custom boundary, and --dry-run previews which guides
+  // would be rewritten vs. skipped (the destructive step is no longer silent).
   let nestedAgentsGenerated: string[] = [];
-  if (!isDryRun) {
-    try {
-      const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, false);
+  const nestedAgentsPlanned: string[] = [];
+  let nestedAgentsPreserved: string[] = [];
+  const nestedAgentsSkipped: string[] = [];
+  try {
+    const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, isDryRun, undefined, fio);
+    if (isDryRun) {
+      for (const [relPath, rendered] of Object.entries(nestedResult.renderedFiles)) {
+        const absPath = path.join(workspaceRoot, relPath);
+        let existing: string | null = null;
+        if (await fio.exists(absPath)) {
+          try {
+            existing = await fio.readFile(absPath);
+          } catch {
+            // Unreadable — treat as absent; merge will emit a fresh file.
+          }
+        }
+        if (existing !== null && !hasGeneratedMarker(existing)) {
+          nestedAgentsSkipped.push(`${relPath} (hand-written)`);
+          continue;
+        }
+        const merged = mergeEditableGenerated(rendered, existing, relPath);
+        if (merged === null) {
+          nestedAgentsSkipped.push(`${relPath} (unmapped-customization)`);
+        } else if (merged !== existing) {
+          nestedAgentsPlanned.push(relPath);
+        }
+      }
+    } else {
       nestedAgentsGenerated = nestedResult.generated;
-    } catch {
-      // Nested generation failure is non-fatal
+      nestedAgentsPreserved = nestedResult.preserved;
+      nestedAgentsSkipped.push(...nestedResult.skipped);
     }
+  } catch {
+    // Nested generation failure is non-fatal
   }
 
   // Step 6: Run doctor
@@ -578,19 +768,25 @@ export async function runUpgrade(
       toVersion,
       skillsUpdated,
       bindingsAdded,
-      skippedSkills: packResult.skipped,
+      skippedSkills: packSkipped,
       nestedAgentsGenerated,
+      nestedAgentsPlanned,
+      nestedAgentsPreserved,
+      nestedAgentsSkipped,
       memoryScaffold,
       npmUpdated,
       npmUpdateSkipped,
       latestNpmVersion: npmCheck.latest,
       npmVersionWarning: npmCheck.warning,
       doctorReport,
+      skillsPruned: reconcile.prune.pruned,
+      skillsKeptWithConsumerFiles: reconcile.prune.keptWithConsumerFiles,
+      prettierignore: reconcile.prettierignore,
     },
     nextSteps,
     exitCode: 0,
     summary: isDryRun
-      ? `[dry-run] forge.upgrade: would sync ${skillsUpdated.length} skill(s), add ${bindingsAdded.length} binding(s), update syncedVersion to ${toVersion}`
+      ? `[dry-run] forge.upgrade: would sync ${skillsUpdated.length} skill(s), add ${bindingsAdded.length} binding(s), update syncedVersion to ${toVersion}, rewrite ${nestedAgentsPlanned.length} nested AGENTS.md file(s)`
       : npmCheck.warning
         ? `[forge.upgrade] OK — ${skillsUpdated.length} skill(s) synced, ${bindingsAdded.length} binding(s) added, syncedVersion → ${toVersion} — ⚠ ${npmCheck.warning}`
         : `[forge.upgrade] OK — ${skillsUpdated.length} skill(s) synced, ${bindingsAdded.length} binding(s) added, syncedVersion → ${toVersion}` +