@warpgogol/forge 5.2.4 → 5.3.1

package/src/tests/prettierignore-manage.test.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the RFC-1154 managed .prettierignore block:
+root-only prettier detection, delimited-block reconcile preserving operator
+content, marker-driven skill entries, and the skipped contract for
+prettier-free consumers.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial prettierignore plan/apply tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  planPrettierignore,
+  applyPrettierignore,
+  reconcilePrettierignoreContent,
+  PRETTIERIGNORE_BLOCK_BEGIN,
+  PRETTIERIGNORE_BLOCK_END,
+} from "../onboarding/prettierignore.ts";
+import { SKILL_MARKER_FILE } from "../onboarding/skill-markers.ts";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "prettierignore-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function withPrettier(root: string): Promise<void> {
+  await writeFile(join(root, ".prettierrc"), "{}\n");
+}
+
+test("detects prettier via root .prettierrc", async () => {
+  await withPrettier(tmpDir);
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via package.json prettier key", async () => {
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({ prettier: {} }));
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via prettier devDependency", async () => {
+  await writeFile(
+    join(tmpDir, "package.json"),
+    JSON.stringify({ devDependencies: { prettier: "^3" } }),
+  );
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via existing .prettierignore alone", async () => {
+  await writeFile(join(tmpDir, ".prettierignore"), "dist/\n");
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("AC-4: no prettier markers — plan does not apply, apply writes nothing", async () => {
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(false);
+  const result = await applyPrettierignore(tmpDir, plan);
+  expect(result).toBe("skipped");
+  expect(existsSync(join(tmpDir, ".prettierignore"))).toBe(false);
+});
+
+test("AC-2: block contains generated.yaml glob, sessions, metrics, queues entries", async () => {
+  await withPrettier(tmpDir);
+  const plan = await planPrettierignore(tmpDir);
+  const result = await applyPrettierignore(tmpDir, plan);
+  expect(result).toBe("written");
+  const content = await readFile(join(tmpDir, ".prettierignore"), "utf8");
+  expect(content).toContain(PRETTIERIGNORE_BLOCK_BEGIN);
+  expect(content).toContain("**/*.generated.yaml");
+  expect(content).toContain("docs/sessions/");
+  expect(content).toContain("docs/metrics/");
+  expect(content).toContain("docs/queues/session-*.yaml");
+  expect(content).toContain(PRETTIERIGNORE_BLOCK_END);
+});
+
+test("skill entries enumerate only marker-carrying dirs (AC-9)", async () => {
+  await withPrettier(tmpDir);
+  const skillsDir = join(tmpDir, ".agents", "skills");
+  await mkdir(join(skillsDir, "fo-idea"), { recursive: true });
+  await writeFile(join(skillsDir, "fo-idea", SKILL_MARKER_FILE), '{"files":["SKILL.md"]}');
+  await mkdir(join(skillsDir, "my-own-skill"), { recursive: true }); // unmarked — consumer-owned
+
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.entries).toContain(".agents/skills/fo-idea/");
+  expect(plan.entries).not.toContain(".agents/skills/my-own-skill/");
+});
+
+test("reconcile preserves operator content outside the block", async () => {
+  const existing = `dist/\nnode_modules/\n${PRETTIERIGNORE_BLOCK_BEGIN}\nold-entry/\n${PRETTIERIGNORE_BLOCK_END}\ncustom/\n`;
+  const { next, changed } = reconcilePrettierignoreContent(existing, ["a/", "b/"]);
+  expect(changed).toBe("updated");
+  expect(next).toContain("dist/\nnode_modules/\n");
+  expect(next).toContain("custom/\n");
+  expect(next).not.toContain("old-entry/");
+  expect(next).toContain("a/\nb/");
+});
+
+test("unbalanced markers treat the file as operator-owned and append a fresh block", async () => {
+  const existing = `dist/\n${PRETTIERIGNORE_BLOCK_BEGIN}\nstray/\n`; // no END marker
+  const { next, changed } = reconcilePrettierignoreContent(existing, ["x/"]);
+  expect(changed).toBe("updated");
+  expect(next).toContain("dist/\n");
+  // Original content preserved verbatim — forge does not merge into a
+  // corrupted region; a fresh block is appended.
+  expect(next.indexOf(PRETTIERIGNORE_BLOCK_BEGIN)).toBeLessThan(
+    next.lastIndexOf(PRETTIERIGNORE_BLOCK_BEGIN),
+  );
+});
+
+test("repeated apply is idempotent", async () => {
+  await withPrettier(tmpDir);
+  await writeFile(join(tmpDir, ".prettierignore"), "dist/\n");
+  const plan = await planPrettierignore(tmpDir);
+  const first = await applyPrettierignore(tmpDir, plan);
+  expect(first).toBe("updated");
+  const second = await applyPrettierignore(tmpDir, await planPrettierignore(tmpDir));
+  expect(second, "second apply must be unchanged — check reconcile block boundaries").toBe(
+    "unchanged",
+  );
+});

package/src/tests/skill-agents-sync.test.ts

@@ -0,0 +1,168 @@
+/*
+<MODULE_CONTRACT>
+<purpose>CI gate: every forge/pack skill source must be fully propagated to
+`.agents/skills/` (IDE discovery copy written by forge.init/forge.upgrade).
+SKILL.md syncs verbatim; declared knowledge files follow the append-only
+syncKnowledgeFile contract — in the canonical repo a resync must be a no-op,
+otherwise source and copy have drifted apart.</purpose>
+<non-goals>
+  <item>Do not validate skill content/schema — forge.skill.validate owns that.</item>
+  <item>Do not flag unmarked dirs — a missing .forge-managed marker means
+    consumer-owned (RFC-1154), e.g. `_shared/`.</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>planKnowledgeSync is reused so the gate encodes the exact merge
+    semantics of the syncer — only "unchanged" is a pass; "merged" (source has
+    entries the copy lacks), "copied" (copy missing), and "skipped"
+    (non-mergeable divergence = hand-edited copy) all fail.</item>
+  <item>Runs on the real repo — this is a drift gate, not a fixture test.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>Initial version — covers FORGE_SKILLS, declared pack skills
+    (discoverPackSkills), and the shared-knowledge layer.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { loadForgeConfig } from "../config/forge-config.ts";
+import { planKnowledgeSync } from "../knowledge/index.ts";
+import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
+
+const forgeRoot = path.resolve(import.meta.dirname, "../..");
+const workspaceRoot = path.resolve(import.meta.dirname, "../../../..");
+
+interface SkillSource {
+  name: string;
+  srcDir: string;
+  knowledge: string[];
+}
+
+function collectSkillSources(): SkillSource[] {
+  const sources: SkillSource[] = [];
+  for (const skill of FORGE_SKILLS) {
+    sources.push({
+      name: skill.name,
+      srcDir: path.dirname(path.join(forgeRoot, skill.path)),
+      knowledge: skill.knowledge ?? [],
+    });
+  }
+  const config = loadForgeConfig(workspaceRoot);
+  for (const skill of discoverPackSkills(workspaceRoot, config)) {
+    sources.push({
+      name: skill.name,
+      srcDir: path.dirname(path.join(workspaceRoot, skill.dir, skill.path)),
+      knowledge: skill.knowledge ?? [],
+    });
+  }
+  return sources;
+}
+
+// Skipped in the standalone package repo — the gate needs a forge-managed
+// workspace root (forge.yaml + synced skillsDir), which only exists for the
+// monorepo and consumer projects, not for the published forge source tree.
+const hasForgeWorkspace = fs.existsSync(path.join(workspaceRoot, "forge.yaml"));
+describe.runIf(hasForgeWorkspace)(
+  ".agents/skills sync gate (forge.init/forge.upgrade parity)",
+  () => {
+    // describe callbacks still run during collection even when runIf is false,
+    // so initializers must tolerate the absent forge.yaml themselves.
+    const config = hasForgeWorkspace ? loadForgeConfig(workspaceRoot) : null;
+    const skillsDir = config ? path.join(workspaceRoot, config.paths.skillsDir) : "";
+    const sources = config ? collectSkillSources() : [];
+
+    it("every forge + pack skill has a synced copy in .agents/skills/", () => {
+      const missing = sources
+        .filter((s) => !fs.existsSync(path.join(skillsDir, s.name, "SKILL.md")))
+        .map((s) => `${s.name} (src ${path.relative(workspaceRoot, s.srcDir)})`);
+      expect(
+        missing,
+        `skills never synced — run \`forge init\`/\`forge upgrade\` to populate ${path.relative(workspaceRoot, skillsDir)}`,
+      ).toEqual([]);
+    });
+
+    it("SKILL.md copies are byte-identical to their sources", () => {
+      const drifted: string[] = [];
+      for (const s of sources) {
+        const src = path.join(s.srcDir, "SKILL.md");
+        const dest = path.join(skillsDir, s.name, "SKILL.md");
+        if (!fs.existsSync(dest)) continue; // reported by the presence test
+        if (fs.readFileSync(src, "utf8") !== fs.readFileSync(dest, "utf8")) {
+          drifted.push(s.name);
+        }
+      }
+      expect(
+        drifted,
+        "SKILL.md drift — edit the pack source and re-sync, never edit .agents/skills/ directly",
+      ).toEqual([]);
+    });
+
+    it("declared knowledge files are in sync (append-only merge would be a no-op)", () => {
+      const stale: string[] = [];
+      for (const s of sources) {
+        for (const kf of s.knowledge) {
+          const src = path.join(s.srcDir, kf);
+          const dest = path.join(skillsDir, s.name, kf);
+          if (!fs.existsSync(src)) {
+            stale.push(`${s.name}/${kf} — declared but missing in source`);
+            continue;
+          }
+          if (!fs.existsSync(dest)) {
+            stale.push(`${s.name}/${kf} — missing in .agents/skills (run forge upgrade)`);
+            continue;
+          }
+          const plan = planKnowledgeSync(src, dest);
+          if (plan.action === "merged") {
+            stale.push(`${s.name}/${kf} — source has entries the copy lacks`);
+          } else if (plan.action === "skipped") {
+            stale.push(`${s.name}/${kf} — copy diverged non-mergeably (hand-edited .agents copy)`);
+          }
+        }
+      }
+      expect(stale).toEqual([]);
+    });
+
+    it("undeclared aux files in the copy still match their sources", () => {
+      // The syncer writes SKILL.md + declared knowledge files only. Aux files
+      // (references, templates, placeholder dirs) that exist in BOTH trees are
+      // hand-copied and silently diverge — a same-named pair must stay identical,
+      // and a copy-only orphan can never resync.
+      const flagged: string[] = [];
+      for (const s of sources) {
+        const destDir = path.join(skillsDir, s.name);
+        if (!fs.existsSync(destDir)) continue;
+        const declared = new Set(["SKILL.md", ".forge-managed", ...s.knowledge]);
+        for (const entry of fs.readdirSync(destDir)) {
+          if (declared.has(entry)) continue;
+          const srcEntry = path.join(s.srcDir, entry);
+          const destEntry = path.join(destDir, entry);
+          if (fs.statSync(destEntry).isDirectory()) {
+            if (!fs.existsSync(srcEntry))
+              flagged.push(`${s.name}/${entry}/ — dir absent in source`);
+            continue;
+          }
+          if (!fs.existsSync(srcEntry)) {
+            flagged.push(`${s.name}/${entry} — absent in source, copy can never resync`);
+          } else if (fs.readFileSync(srcEntry, "utf8") !== fs.readFileSync(destEntry, "utf8")) {
+            flagged.push(`${s.name}/${entry} — diverged from source`);
+          }
+        }
+      }
+      expect(
+        flagged,
+        "aux-file drift — declare aux files via `knowledge:` in SKILL.md or keep copies identical to source",
+      ).toEqual([]);
+    });
+
+    it("shared-knowledge layer is synced", () => {
+      const src = path.join(forgeRoot, "skills", "shared", "knowledge", "learned-principles.md");
+      const dest = path.join(skillsDir, "shared-knowledge", "learned-principles.md");
+      if (!fs.existsSync(src)) return; // layer absent — nothing to gate
+      expect(fs.existsSync(dest), "shared-knowledge/learned-principles.md not synced").toBe(true);
+      const plan = planKnowledgeSync(src, dest);
+      expect(plan.action, `shared-knowledge drift (sync action: ${plan.action})`).toBe("unchanged");
+    });
+  },
+);

package/src/tests/skill-sync-marker.test.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-1154 skill markers: .forge-managed manifests
+recorded on sync, and the stale-dir prune under the subset-of-manifest rule
+(keeps dirs with consumer files or corrupt markers, never touches unmarked
+dirs).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial marker + prune tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  SKILL_MARKER_FILE,
+  writeSkillMarker,
+  writeSkillMarkerSync,
+  pruneStaleSkillDirs,
+} from "../onboarding/skill-markers.ts";
+
+let tmpDir: string;
+let skillsDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "skill-marker-"));
+  skillsDir = join(tmpDir, ".agents", "skills");
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function makeSkillDir(name: string, files: string[]): Promise<void> {
+  const dir = join(skillsDir, name);
+  await mkdir(dir, { recursive: true });
+  for (const f of files) {
+    const filePath = join(dir, f);
+    await mkdir(join(filePath, ".."), { recursive: true });
+    await writeFile(filePath, `content of ${f}\n`);
+  }
+}
+
+test("AC-7: writeSkillMarker records the exact file list", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  await writeSkillMarker(dir, ["SKILL.md", "qa-log.md"]);
+  const raw = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  expect(JSON.parse(raw)).toEqual({ files: ["SKILL.md", "qa-log.md"] });
+});
+
+test("marker write is idempotent (identical content on repeat)", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  const first = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  expect(await readFile(join(dir, SKILL_MARKER_FILE), "utf8")).toBe(first);
+  expect(JSON.parse(first).files).toEqual(["a.md", "b.md"]); // sorted, deterministic
+});
+
+test("AC-8: prunes a stale marked dir whose contents match the manifest", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["other-skill"]));
+  expect(result.pruned).toEqual(["old-skill"]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("AC-8: keeps a stale marked dir containing consumer files", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md", "my-notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("old-skill");
+  expect(result.keptWithConsumerFiles[0]).toContain("my-notes.md");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("AC-9: unmarked dirs are never pruned", async () => {
+  const dir = join(skillsDir, "consumer-skill");
+  await makeSkillDir("consumer-skill", ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("dirs still in the sync set are kept regardless of marker", async () => {
+  const dir = join(skillsDir, "current-skill");
+  await makeSkillDir("current-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["current-skill"]));
+  expect(result.pruned).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("corrupt marker disables prune for that dir (fail-safe keep)", async () => {
+  const dir = join(skillsDir, "broken-skill");
+  await makeSkillDir("broken-skill", ["SKILL.md"]);
+  await writeFile(join(dir, SKILL_MARKER_FILE), "not json {{{");
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("corrupt marker");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("nested manifest files are matched recursively", async () => {
+  const dir = join(skillsDir, "nested-skill");
+  await makeSkillDir("nested-skill", ["SKILL.md", "knowledge/notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md", "knowledge/notes.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual(["nested-skill"]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("missing skills dir returns empty result", async () => {
+  const result = await pruneStaleSkillDirs(join(tmpDir, "nonexistent"), new Set());
+  expect(result).toEqual({ pruned: [], keptWithConsumerFiles: [] });
+});

package/src/tests/skill-validate.test.ts

@@ -78,14 +78,14 @@ describe("RFC-0539: Pack skill validation (SKILL-14, SKILL-15)", () => {
   });
 });
 
-describe("RFC-0548: SKILL-16 triggers field validation", () => {
-  test("SKILL-16: real workspace fo-skills have valid triggers (no violations)", () => {
+describe("RFC-0548: SKILL-16 triggerPhrases field validation", () => {
+  test("SKILL-16: real workspace fo-skills have valid triggerPhrases (no violations)", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const skill16Violations = result.violations.filter((v) => v.rule === "SKILL-16");
     expect(skill16Violations).toEqual([]);
   });
 
-  test("SKILL-16: triggers are only on fo-category skills", () => {
+  test("SKILL-16: triggerPhrases are only on fo-category skills", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const skill16Violations = result.violations.filter(
       (v) => v.rule === "SKILL-16" && v.message.includes("only allowed on fo-category"),
@@ -93,13 +93,20 @@ describe("RFC-0548: SKILL-16 triggers field validation", () => {
     expect(skill16Violations).toEqual([]);
   });
 
-  test("SKILL-16: no pack skills declare triggers", () => {
+  test("SKILL-16: no pack skills declare triggerPhrases", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const packTriggerViolations = result.violations.filter(
-      (v) => v.rule === "SKILL-16" && v.message.includes("pack skills may not declare triggers"),
+      (v) =>
+        v.rule === "SKILL-16" && v.message.includes("pack skills may not declare triggerPhrases"),
     );
     expect(packTriggerViolations).toEqual([]);
   });
+
+  test("SKILL-22: no skill declares the reserved `triggers` key", () => {
+    const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
+    const skill22Violations = result.violations.filter((v) => v.rule === "SKILL-22");
+    expect(skill22Violations).toEqual([]);
+  });
 });
 
 describe("RFC-0553: SKILL-17 platform reference prohibition", () => {

package/src/tests/upgrade.test.ts

@@ -9,11 +9,15 @@
 */
 
 import { test, expect, beforeEach, afterEach, vi } from "vitest";
-import { mkdtemp, mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, rm, readFile, appendFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runUpgrade } from "../onboarding/upgrade.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { ambientIo } from "../utils/io.ts";
+import { buildGeneratedHeader } from "../utils/index.ts";
+import type { WorkspaceIO } from "@warpgogol/werkstatt-shared/kernel/workspace-io";
 import { runInit } from "../onboarding/init.ts";
 import {
   loadForgeConfig,
@@ -163,7 +167,9 @@ test("forge.upgrade with syncedVersion matching installed version returns noop",
   expect(result.data?.status).toBe("noop");
   expect(result.data?.fromVersion).toBe("0.2.0");
   expect(result.data?.toVersion).toBe("0.2.0");
-  expect(result.data?.skillsUpdated).toEqual([]);
+  // RFC-1154: the reconcile pass still runs on a same-version noop — skills it
+  // re-synced are reported in skillsUpdated.
+  expect(result.data?.skillsUpdated).toContain("fo-idea");
   expect(result.exitCode).toBe(0);
 });
 
@@ -358,66 +364,40 @@ test("forge.upgrade --update-npm attempts npm install for npm consumer", async (
   await setupNpmConsumerForge(tempDir, "0.2.0");
   await setupConsumerForgeYaml(tempDir, null);
 
-  // Mock execSync to avoid real npm install
-  const execSyncMock = vi.fn(() => "");
-  vi.resetModules();
-  vi.doMock("node:child_process", () => ({
-    execSync: execSyncMock,
-    exec: vi.fn(),
-    execFile: vi.fn(),
-    spawn: vi.fn(),
-    fork: vi.fn(),
-  }));
-
-  // Re-import with mock
-  const { runUpgrade: runUpgradeMocked } = await import("../onboarding/upgrade.ts");
-
-  const result = await runUpgradeMocked(
+  // RFC-1152: inject a fake WorkspaceIO — exec is the port seam; real fs stays.
+  const execMock = vi.fn(async () => ({ exitCode: 0, stdout: "", stderr: "" }));
+  const io = { ...ambientIo, exec: execMock } as WorkspaceIO;
+
+  const result = await runUpgrade(
     { argv: [], flags: { "update-npm": true } },
-    makeContext(tempDir, false),
+    { ...makeContext(tempDir, false), io },
   );
 
   expect(result.data?.status).toBe("pass");
-  expect(execSyncMock).toHaveBeenCalled();
+  expect(execMock).toHaveBeenCalled();
   expect(result.data?.npmUpdated).toBe(true);
   expect(result.data?.npmUpdateSkipped).toBe(null);
-
-  vi.doUnmock("node:child_process");
-  vi.resetModules();
 });
 
 test("forge.upgrade --update-npm reports failure when npm install throws", async () => {
   await setupNpmConsumerForge(tempDir, "0.2.0");
   await setupConsumerForgeYaml(tempDir, null);
 
-  // Mock execSync to throw (simulates network error / registry unavailable)
-  const execSyncMock = vi.fn(() => {
-    throw new Error("network error");
-  });
-  vi.resetModules();
-  vi.doMock("node:child_process", () => ({
-    execSync: execSyncMock,
-    exec: vi.fn(),
-    execFile: vi.fn(),
-    spawn: vi.fn(),
-    fork: vi.fn(),
-  }));
-
-  const { runUpgrade: runUpgradeMocked } = await import("../onboarding/upgrade.ts");
+  // RFC-1152: fake io.exec fails — simulates network error / registry unavailable
+  const execMock = vi.fn(async () => ({ exitCode: 1, stdout: "", stderr: "network error" }));
+  const io = { ...ambientIo, exec: execMock } as WorkspaceIO;
 
-  const result = await runUpgradeMocked(
+  const result = await runUpgrade(
     { argv: [], flags: { "update-npm": true } },
-    makeContext(tempDir, false),
+    { ...makeContext(tempDir, false), io },
   );
 
   expect(result.data?.status).toBe("pass");
-  expect(execSyncMock).toHaveBeenCalled();
+  expect(execMock).toHaveBeenCalled();
   expect(result.data?.npmUpdated).toBe(false);
   expect(result.data?.npmUpdateSkipped).toBe(
     "install failed (network error or registry unavailable)",
   );
-
-  vi.doUnmock("node:child_process");
   vi.resetModules();
 });
 
@@ -432,6 +412,72 @@ test("forge.upgrade without --update-npm does not attempt npm install", async ()
   expect(result.data?.npmUpdateSkipped).toBe(null);
 });
 
+// RFC-1153: dry-run preview of the nested-AGENTS.md merge --------------------
+
+test("AC-7: forge.upgrade --dry-run reports nestedAgentsPlanned and nestedAgentsSkipped", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // Workspace with no AGENTS.md — merged output would be written → planned
+  await mkdir(join(tempDir, "packages", "newpkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "newpkg", "package.json"), '{"name":"newpkg"}', "utf8");
+
+  // Marker-bearing file that diverges with no resolvable boundary → skipped
+  await mkdir(join(tempDir, "packages", "unmapped"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "unmapped", "package.json"),
+    '{"name":"unmapped"}',
+    "utf8",
+  );
+  await writeFile(
+    join(tempDir, "packages", "unmapped", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const result = await runUpgrade(
+    { argv: [], flags: { "dry-run": true } },
+    makeContext(tempDir, true),
+  );
+
+  expect(result.data?.status).toBe("pass");
+  const planned = result.data?.nestedAgentsPlanned ?? [];
+  const skipped = result.data?.nestedAgentsSkipped ?? [];
+
+  expect(
+    planned,
+    "planned must contain exactly the guides whose merged output differs from disk",
+  ).toContain(join("packages", "newpkg", "AGENTS.md"));
+  expect(skipped.some((s) => s.includes("unmapped") && s.includes("unmapped-customization"))).toBe(
+    true,
+  );
+  // No files written under dry-run
+  expect(existsSync(join(tempDir, "packages", "newpkg", "AGENTS.md"))).toBe(false);
+});
+
+test("forge.upgrade executing path reports nestedAgentsPreserved for carried tails", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // First run materializes the nested guide with the boundary marker
+  await mkdir(join(tempDir, "packages", "pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "pkg", "package.json"), '{"name":"pkg"}', "utf8");
+  const config = loadForgeConfig(tempDir);
+  await generateNestedAgentsMd(tempDir, config, false);
+  await appendFile(
+    join(tempDir, "packages", "pkg", "AGENTS.md"),
+    "\n## Custom rules\n\n- keep me\n",
+    "utf8",
+  );
+
+  const result = await runUpgrade({ argv: [], flags: {} }, makeContext(tempDir, false));
+
+  expect(result.data?.status).toBe("pass");
+  expect(result.data?.nestedAgentsPreserved).toContain(join("packages", "pkg", "AGENTS.md"));
+  const merged = await readFile(join(tempDir, "packages", "pkg", "AGENTS.md"), "utf8");
+  expect(merged).toContain("- keep me");
+});
+
 function qaLog(entries: { id: string; title: string; body: string }[]): string {
   const blocks = entries.map(
     (e) =>