@warpgogol/forge 5.2.4 → 5.3.1

package/src/onboarding/doctor.ts

@@ -21,8 +21,10 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import { readFile, readdir, stat } from "node:fs/promises";
-import { readFileSync, existsSync } from "node:fs";
+import type { WorkspaceIO } from "../types.ts";
+import { resolveIo } from "../utils/io.ts";
+import { hasEditableGeneratedMarker, mergeEditableGenerated } from "../utils/index.ts";
+import { readFileSync, existsSync } from "../utils/sync-fs.ts";
 import { join, relative, dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { forgePluginManifestSchema } from "../plugin/forge-plugin-manifest.ts";
@@ -52,8 +54,8 @@ import { compactMemoryMd } from "./memory-compact.ts";
 import { checkInvariants } from "./invariant-engine.ts";
 import type { InvariantViolation } from "./invariant-engine.ts";
 import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
-import { execSync } from "node:child_process";
-import fs from "node:fs";
+import { execSync } from "../utils/sync-fs.ts";
+import * as fs from "../utils/sync-fs.ts";
 import type { ProfilePrerequisite } from "../profiles/profile-schema.ts";
 
 interface DoctorFixResult {
@@ -87,13 +89,8 @@ interface BindingNotice {
   suggestion: string;
 }
 
-async function pathExists(target: string): Promise<boolean> {
-  try {
-    await stat(target);
-    return true;
-  } catch {
-    return false;
-  }
+async function pathExists(target: string, io: WorkspaceIO): Promise<boolean> {
+  return io.exists(target);
 }
 
 const FORBIDDEN_IMPORT_PATTERN =
@@ -102,19 +99,20 @@ const FORBIDDEN_IMPORT_PATTERN =
 async function scanForForbiddenImports(
   dir: string,
   workspaceRoot: string,
+  io: WorkspaceIO,
 ): Promise<ForbiddenImport[]> {
   const violations: ForbiddenImport[] = [];
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const entries = await io.readdir(dir).catch(() => []);
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
 
-    if (entry.isDirectory()) {
+    if (entry.isDirectory) {
       if (entry.name === "node_modules" || entry.name === "tests") continue;
-      const sub = await scanForForbiddenImports(fullPath, workspaceRoot);
+      const sub = await scanForForbiddenImports(fullPath, workspaceRoot, io);
       violations.push(...sub);
     } else if (entry.name.endsWith(".ts")) {
-      const content = await readFile(fullPath, "utf8").catch(() => "");
+      const content = await io.readFile(fullPath).catch(() => "");
       let match: RegExpExecArray | null;
       const pattern = new RegExp(FORBIDDEN_IMPORT_PATTERN.source, "g");
       while ((match = pattern.exec(content)) !== null) {
@@ -151,7 +149,7 @@ const BINDING_COMMAND_KEYS = [
   "commands.sessionSave",
 ];
 
-async function validateBindings(workspaceRoot: string): Promise<BindingValidation> {
+async function validateBindings(workspaceRoot: string, io: WorkspaceIO): Promise<BindingValidation> {
   const result: BindingValidation = { resolved: [], absent: [], invalid: [], notices: [] };
 
   let config;
@@ -170,7 +168,7 @@ async function validateBindings(workspaceRoot: string): Promise<BindingValidatio
     if (value === null) {
       result.absent.push(key);
     } else if (typeof value === "string") {
-      const exists = await pathExists(join(workspaceRoot, value));
+      const exists = await pathExists(join(workspaceRoot, value), io);
       if (exists) {
         result.resolved.push(key);
       } else {
@@ -182,7 +180,7 @@ async function validateBindings(workspaceRoot: string): Promise<BindingValidatio
   const compassDocs = resolveBinding(config, "paths.compassDocs");
   if (Array.isArray(compassDocs) && compassDocs.length > 0) {
     for (const docPath of compassDocs) {
-      const exists = await pathExists(join(workspaceRoot, docPath));
+      const exists = await pathExists(join(workspaceRoot, docPath), io);
       if (exists) {
         result.resolved.push(`paths.compassDocs[${docPath}]`);
       } else {
@@ -226,6 +224,7 @@ async function validateBindings(workspaceRoot: string): Promise<BindingValidatio
 async function checkStaleKnowledgeFiles(
   workspaceRoot: string,
   forgeRoot: string,
+  io: WorkspaceIO,
 ): Promise<DoctorCheck> {
   const stale: string[] = [];
 
@@ -247,8 +246,8 @@ async function checkStaleKnowledgeFiles(
       const srcPath = join(skillSrcDir, kf);
       const destPath = join(agentsSkillsDir, skill.name, kf);
 
-      const srcExists = await pathExists(srcPath);
-      const destExists = await pathExists(destPath);
+      const srcExists = await pathExists(srcPath, io);
+      const destExists = await pathExists(destPath, io);
 
       if (srcExists && destExists) {
         // Append-only contract: local copies legitimately accumulate entries.
@@ -279,8 +278,8 @@ async function checkStaleKnowledgeFiles(
       const srcPath = join(skillSrcDir, kf);
       const destPath = join(agentsSkillsDir, skill.name, kf);
 
-      const srcExists = await pathExists(srcPath);
-      const destExists = await pathExists(destPath);
+      const srcExists = await pathExists(srcPath, io);
+      const destExists = await pathExists(destPath, io);
 
       if (srcExists && destExists) {
         const plan = planKnowledgeSync(srcPath, destPath);
@@ -642,7 +641,7 @@ function checkSharedKnowledgeFile(
 // Independent version packages diagnostics (RFC-0704)
 // ---------------------------------------------------------------------------
 
-async function checkIndependentVersionPackages(workspaceRoot: string): Promise<DoctorCheck> {
+async function checkIndependentVersionPackages(workspaceRoot: string, io: WorkspaceIO): Promise<DoctorCheck> {
   let config;
   try {
     config = loadForgeConfig(workspaceRoot);
@@ -658,8 +657,8 @@ async function checkIndependentVersionPackages(workspaceRoot: string): Promise<D
   let validCount = 0;
 
   for (const pkgPath of config.independentVersionPackages) {
-    const dirExists = await pathExists(join(workspaceRoot, pkgPath));
-    const pkgJsonExists = await pathExists(join(workspaceRoot, pkgPath, "package.json"));
+    const dirExists = await pathExists(join(workspaceRoot, pkgPath), io);
+    const pkgJsonExists = await pathExists(join(workspaceRoot, pkgPath, "package.json"), io);
     if (!dirExists) {
       issues.push(`path '${pkgPath}' does not exist`);
     } else if (!pkgJsonExists) {
@@ -688,7 +687,7 @@ async function checkIndependentVersionPackages(workspaceRoot: string): Promise<D
 // Pack skill diagnostics (RFC-0539)
 // ---------------------------------------------------------------------------
 
-async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
+async function checkPackSkills(workspaceRoot: string, io: WorkspaceIO): Promise<DoctorCheck> {
   let config;
   try {
     config = loadForgeConfig(workspaceRoot);
@@ -720,7 +719,7 @@ async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
     }
     dirs.add(pack.dir);
 
-    const packDirExists = await pathExists(join(workspaceRoot, pack.dir));
+    const packDirExists = await pathExists(join(workspaceRoot, pack.dir), io);
     if (!packDirExists) {
       issues.push(`pack dir '${pack.dir}' does not exist`);
     }
@@ -739,12 +738,12 @@ async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
     const srcPath = join(workspaceRoot, skill.dir, skill.path);
     const destPath = join(agentsSkillsDir, skill.name, "SKILL.md");
 
-    const srcExists = await pathExists(srcPath);
-    const destExists = await pathExists(destPath);
+    const srcExists = await pathExists(srcPath, io);
+    const destExists = await pathExists(destPath, io);
 
     if (srcExists && destExists) {
-      const srcContent = await readFile(srcPath, "utf8").catch(() => "");
-      const destContent = await readFile(destPath, "utf8").catch(() => "");
+      const srcContent = await io.readFile(srcPath).catch(() => "");
+      const destContent = await io.readFile(destPath).catch(() => "");
       if (srcContent !== destContent) {
         issues.push(`stale copy of '${skill.name}'`);
       }
@@ -767,7 +766,7 @@ async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
 // Pack manifest diagnostics (RFC-0941)
 // ---------------------------------------------------------------------------
 
-async function checkPackManifests(workspaceRoot: string): Promise<DoctorCheck> {
+async function checkPackManifests(workspaceRoot: string, _io: WorkspaceIO): Promise<DoctorCheck> {
   let config;
   try {
     config = loadForgeConfig(workspaceRoot);
@@ -820,7 +819,8 @@ async function checkPackManifests(workspaceRoot: string): Promise<DoctorCheck> {
 
 async function checkNestedAgentsMd(
   workspaceRoot: string,
-  workspaceTypes?: ProfileWorkspaceType[],
+  workspaceTypes: ProfileWorkspaceType[] | undefined,
+  io: WorkspaceIO,
 ): Promise<DoctorCheck> {
   let config;
   try {
@@ -851,6 +851,7 @@ async function checkNestedAgentsMd(
   let missing = 0;
   let stale = 0;
   let handwritten = 0;
+  let unmapped = 0;
 
   for (const ws of workspaces) {
     if (!ws.hasAgentsMd) {
@@ -863,7 +864,7 @@ async function checkNestedAgentsMd(
       handwritten++;
       const suggestions: string[] = [];
       try {
-        const content = await readFile(join(workspaceRoot, ws.path, "AGENTS.md"), "utf8");
+        const content = await io.readFile(join(workspaceRoot, ws.path, "AGENTS.md"));
         if (!content.includes("AGENTS.md")) {
           suggestions.push("reference root AGENTS.md");
         }
@@ -885,8 +886,19 @@ async function checkNestedAgentsMd(
       const terminology = resolveAllTerminology(config, profile);
       const wsType = workspaceTypes?.find((wt) => wt.id === ws.type);
       const expected = selectNestedTemplate(wsType, profile, terminology, fallback);
-      const actual = await readFile(join(workspaceRoot, ws.path, "AGENTS.md"), "utf8");
-      if (expected !== actual) {
+      const actual = await io.readFile(join(workspaceRoot, ws.path, "AGENTS.md"));
+      // RFC-1153: boundary-aware staleness — merge(expected, actual) compares
+      // only the generated head; content below the forge:custom boundary (or
+      // the canonical footer fallback) is preserved, not drift. Files bearing
+      // the restrictive GENERATED marker are generator-owned (RFC-0081) — any
+      // divergence is plain staleness, never unmapped-customization.
+      const merged = mergeEditableGenerated(expected, actual, `${ws.path}/AGENTS.md`);
+      if (merged === null && hasEditableGeneratedMarker(actual)) {
+        unmapped++;
+        issues.push(
+          `${ws.path}/AGENTS.md has custom content but no resolvable boundary — add <!-- forge:custom --> manually`,
+        );
+      } else if (merged === null || merged !== actual.replace(/\r\n/g, "\n")) {
         stale++;
         issues.push(`${ws.path}/AGENTS.md stale — run 'forge agents generate'`);
       }
@@ -906,11 +918,12 @@ async function checkNestedAgentsMd(
   const parts: string[] = [];
   if (missing > 0) parts.push(`${missing} missing`);
   if (stale > 0) parts.push(`${stale} stale`);
+  if (unmapped > 0) parts.push(`${unmapped} unmapped-customization`);
   if (handwritten > 0) parts.push(`${handwritten} hand-written`);
 
   return {
     name: "nested-AGENTS.md",
-    status: stale > 0 ? "warn" : "pass",
+    status: stale > 0 || unmapped > 0 ? "warn" : "pass",
     message: `${parts.join(", ")} — ${issues.slice(0, 3).join("; ")}${issues.length > 3 ? ` (+${issues.length - 3} more)` : ""}`,
   };
 }
@@ -1222,12 +1235,13 @@ export async function runDoctor(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<{ command: string; checks: DoctorCheck[]; allPass: boolean; forbiddenImports: ForbiddenImport[]; bindings: BindingValidation; domain?: DomainReport; fixes?: DoctorFixResult[] }>> {
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
   const strict = input.flags["strict"] === true;
   const fix = input.flags["fix"] === true;
   const checks: DoctorCheck[] = [];
 
   // Check forge.yaml
-  const forgeYamlExists = await pathExists(join(workspaceRoot, "forge.yaml"));
+  const forgeYamlExists = await pathExists(join(workspaceRoot, "forge.yaml"), fio);
   checks.push({
     name: "forge.yaml",
     status: forgeYamlExists ? "pass" : "warn",
@@ -1237,7 +1251,7 @@ export async function runDoctor(
   });
 
   // Check AGENTS.md
-  const agentsMdExists = await pathExists(join(workspaceRoot, "AGENTS.md"));
+  const agentsMdExists = await pathExists(join(workspaceRoot, "AGENTS.md"), fio);
   checks.push({
     name: "AGENTS.md",
     status: agentsMdExists ? "pass" : "warn",
@@ -1247,7 +1261,7 @@ export async function runDoctor(
   });
 
   // Check PREFERENCES.md
-  const preferencesExists = await pathExists(join(workspaceRoot, "PREFERENCES.md"));
+  const preferencesExists = await pathExists(join(workspaceRoot, "PREFERENCES.md"), fio);
   checks.push({
     name: "PREFERENCES.md",
     status: preferencesExists ? "pass" : "warn",
@@ -1257,7 +1271,7 @@ export async function runDoctor(
   });
 
   // Check .agents/skills/
-  const skillsDirExists = await pathExists(join(workspaceRoot, ".agents", "skills"));
+  const skillsDirExists = await pathExists(join(workspaceRoot, ".agents", "skills"), fio);
   checks.push({
     name: ".agents/skills/",
     status: skillsDirExists ? "pass" : "fail",
@@ -1267,7 +1281,7 @@ export async function runDoctor(
   });
 
   // Check docs/rfcs/
-  const rfcsDirExists = await pathExists(join(workspaceRoot, "docs", "rfcs"));
+  const rfcsDirExists = await pathExists(join(workspaceRoot, "docs", "rfcs"), fio);
   checks.push({
     name: "docs/rfcs/",
     status: rfcsDirExists ? "pass" : "warn",
@@ -1277,7 +1291,7 @@ export async function runDoctor(
   });
 
   // Check docs/adrs/
-  const adrsDirExists = await pathExists(join(workspaceRoot, "docs", "adrs"));
+  const adrsDirExists = await pathExists(join(workspaceRoot, "docs", "adrs"), fio);
   checks.push({
     name: "docs/adrs/",
     status: adrsDirExists ? "pass" : "warn",
@@ -1386,7 +1400,7 @@ export async function runDoctor(
         : `${invalidProfiles.length} profile(s) invalid (advisory): ${invalidProfiles.map((p) => p.id).join(", ")}`,
   });
 
-  const forbiddenImports = await scanForForbiddenImports(forgeRoot, workspaceRoot);
+  const forbiddenImports = await scanForForbiddenImports(forgeRoot, workspaceRoot, fio);
   checks.push({
     name: "autonomy-guard",
     status: forbiddenImports.length === 0 ? "pass" : "fail",
@@ -1397,7 +1411,7 @@ export async function runDoctor(
   });
 
   // Check bindings contract (RFC-0393)
-  const bindingsResult = await validateBindings(workspaceRoot);
+  const bindingsResult = await validateBindings(workspaceRoot, fio);
   checks.push({
     name: "bindings",
     status: bindingsResult.invalid.length === 0 ? "pass" : "fail",
@@ -1408,7 +1422,7 @@ export async function runDoctor(
   });
 
   // Check stale knowledge files (RFC-0524, RFC-0539)
-  const staleCheck = await checkStaleKnowledgeFiles(workspaceRoot, forgeRoot);
+  const staleCheck = await checkStaleKnowledgeFiles(workspaceRoot, forgeRoot, fio);
   checks.push(staleCheck);
 
   // RFC-0660: Check legacy sections in knowledge files
@@ -1434,15 +1448,15 @@ export async function runDoctor(
   checks.push(checkDistFreshness(forgeRoot));
 
   // RFC-0539: Check pack skills — stale/missing copies and config validation
-  const packCheck = await checkPackSkills(workspaceRoot);
+  const packCheck = await checkPackSkills(workspaceRoot, fio);
   checks.push(packCheck);
 
   // RFC-0941: Check pack manifests — forge.plugin.yaml existence and validity
-  const packManifestCheck = await checkPackManifests(workspaceRoot);
+  const packManifestCheck = await checkPackManifests(workspaceRoot, fio);
   checks.push(packManifestCheck);
 
   // RFC-0704: Check independent version packages — paths must exist and contain package.json
-  const independentCheck = await checkIndependentVersionPackages(workspaceRoot);
+  const independentCheck = await checkIndependentVersionPackages(workspaceRoot, fio);
   checks.push(independentCheck);
 
   // RFC-0611: Check nested AGENTS.md — missing, stale, hand-written
@@ -1470,7 +1484,7 @@ export async function runDoctor(
     } catch {
       // profiles not loadable
     }
-    const nestedCheck = await checkNestedAgentsMd(workspaceRoot, wsTypes);
+    const nestedCheck = await checkNestedAgentsMd(workspaceRoot, wsTypes, fio);
     checks.push(nestedCheck);
   }
 
@@ -1492,7 +1506,7 @@ export async function runDoctor(
   if (fix) {
     for (const check of finalChecks) {
       if (check.status === "pass") continue;
-      fixes.push(await applyDoctorRemediation(check, workspaceRoot, wsTypes, dryRun === true));
+      fixes.push(await applyDoctorRemediation(check, workspaceRoot, wsTypes, dryRun === true, fio));
     }
   }
 
@@ -1571,12 +1585,13 @@ async function applyDoctorRemediation(
   workspaceRoot: string,
   workspaceTypes: ProfileWorkspaceType[] | undefined,
   dryRun: boolean,
+  io: WorkspaceIO,
 ): Promise<DoctorFixResult> {
   switch (check.name) {
     case "nested-AGENTS.md": {
       try {
         const config = loadForgeConfig(workspaceRoot);
-        const res = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes);
+        const res = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes, io);
         return {
           check: check.name,
           action: res.generated.length > 0 ? "fixed" : "skipped",
@@ -1589,10 +1604,10 @@ async function applyDoctorRemediation(
     case "memory-layer": {
       try {
         const memoryPath = join(workspaceRoot, ".agents", "memory", "MEMORY.md");
-        if (!fs.existsSync(memoryPath)) {
+        if (!(await io.exists(memoryPath))) {
           return { check: check.name, action: "skipped", detail: "MEMORY.md absent" };
         }
-        const content = fs.readFileSync(memoryPath, "utf8");
+        const content = await io.readFile(memoryPath);
         const budget = resolveMemoryBudget(workspaceRoot);
         const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
         if (!fitsBudget) {
@@ -1606,7 +1621,7 @@ async function applyDoctorRemediation(
           return { check: check.name, action: "skipped", detail: "within budget" };
         }
         if (!dryRun) {
-          fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+          await io.writeFile(memoryPath, lines.join("\n"));
         }
         return {
           check: check.name,

package/src/onboarding/init.ts

@@ -20,11 +20,13 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { stringify as stringifyYaml, parse as parseYaml } from "yaml";
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
 import { syncKnowledgeFile } from "../knowledge/index.ts";
+import { writeSkillMarkerSync } from "./skill-markers.ts";
+import { planPrettierignoreSync, applyPrettierignoreSync } from "./prettierignore.ts";
 import { defaultForgeConfig, loadForgeConfig, resolveForgeRoot, type ForgeConfig } from "../config/forge-config.ts";
 import { listStackProfiles, detectStack } from "../profiles/stack-profile.ts";
 
@@ -280,6 +282,11 @@ export function runInit(
     fs.writeFileSync(destPath, content, "utf8");
     created.push(`${config.paths.skillsDir}/${skillName}/SKILL.md`);
 
+    // RFC-1154: marker manifest lists SKILL.md + knowledge files whose content
+    // is purely forge's (copied/unchanged); merged/skipped files carry consumer
+    // entries and stay out of the manifest so prune never deletes them.
+    const markerFiles = ["SKILL.md"];
+
     // RFC-0524: sync declared knowledge files
     const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (fmMatch) {
@@ -298,6 +305,9 @@ export function runInit(
               if (syncResult.action === "copied" || syncResult.action === "merged") {
                 created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
               }
+              if (syncResult.action === "copied" || syncResult.action === "unchanged") {
+                markerFiles.push(kf);
+              }
             } else {
               errors.push(`Knowledge file '${kf}' declared in ${skillName} but not found in source`);
             }
@@ -307,6 +317,7 @@ export function runInit(
         // Frontmatter parse error — SKILL-01 will catch this in validation
       }
     }
+    writeSkillMarkerSync(destDir, markerFiles);
   }
 
   // RFC-0539: Copy declared pack skills to .agents/skills/<name>/ for IDE discovery
@@ -352,6 +363,9 @@ export function runInit(
     fs.writeFileSync(destPath, content, "utf8");
     created.push(`${config.paths.skillsDir}/${skillName}/SKILL.md`);
 
+    // RFC-1154: same marker rule as forge skills.
+    const markerFiles = ["SKILL.md"];
+
     // RFC-0524: sync declared knowledge files for pack skills
     const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (fmMatch) {
@@ -370,6 +384,9 @@ export function runInit(
               if (syncResult.action === "copied" || syncResult.action === "merged") {
                 created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
               }
+              if (syncResult.action === "copied" || syncResult.action === "unchanged") {
+                markerFiles.push(kf);
+              }
             } else {
               errors.push(`Knowledge file '${kf}' declared in ${skillName} but not found in source`);
             }
@@ -379,6 +396,7 @@ export function runInit(
         // Frontmatter parse error — SKILL-01 will catch this in validation
       }
     }
+    writeSkillMarkerSync(destDir, markerFiles);
   }
 
   // RFC-0663: Sync shared knowledge layer to .agents/skills/shared-knowledge/
@@ -391,6 +409,25 @@ export function runInit(
     if (syncResult.action === "copied" || syncResult.action === "merged") {
       created.push(`${config.paths.skillsDir}/shared-knowledge/learned-principles.md`);
     }
+    // RFC-1154: marker lists the file only when its content is purely forge's.
+    writeSkillMarkerSync(
+      sharedKnowledgeDestDir,
+      syncResult.action === "copied" || syncResult.action === "unchanged"
+        ? ["learned-principles.md"]
+        : [],
+    );
+  }
+
+  // RFC-1154: reconcile the forge-managed .prettierignore block (prettier
+  // consumers only; additive + idempotent, no-op otherwise). Non-fatal —
+  // a prettierignore write failure must not fail init.
+  try {
+    applyPrettierignoreSync(
+      workspaceRoot,
+      planPrettierignoreSync(workspaceRoot, config.paths.skillsDir),
+    );
+  } catch (err) {
+    errors.push(`.prettierignore reconcile failed: ${(err as Error).message}`);
   }
 
   // 4. Create docs directories from config paths

package/src/onboarding/invariant-engine.ts

@@ -20,7 +20,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { StackProfile } from "../profiles/stack-profile.ts";

package/src/onboarding/memory-compact.ts

@@ -14,7 +14,7 @@ Invoked standalone and by forge doctor --fix for the memory-layer check (RFC-115
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import { resolveIo } from "../utils/io.ts";
 import path from "node:path";
 import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
 import { resolveMemoryBudget } from "./memory-scaffold.ts";
@@ -100,6 +100,7 @@ export async function runMemoryCompact(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<MemoryCompactResult>> {
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
   const memoryPath = path.join(workspaceRoot, MEMORY_MD_PATH);
   const budget = resolveMemoryBudget(workspaceRoot);
 
@@ -116,7 +117,7 @@ export async function runMemoryCompact(
     summary: `forge.memory.compact: failed — ${msg}`,
   });
 
-  if (!fs.existsSync(memoryPath)) {
+  if (!(await fio.exists(memoryPath))) {
     return {
       data: {
         command: "forge.memory.compact",
@@ -131,7 +132,7 @@ export async function runMemoryCompact(
     };
   }
 
-  const content = fs.readFileSync(memoryPath, "utf8");
+  const content = await fio.readFile(memoryPath);
   if (content.length <= budget) {
     return {
       data: {
@@ -158,7 +159,7 @@ export async function runMemoryCompact(
   }
 
   if (!dryRun) {
-    fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+    await fio.writeFile(memoryPath, lines.join("\n"));
   }
 
   if (outputFormat === "pretty") {

package/src/onboarding/memory-scaffold.ts

@@ -12,7 +12,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { loadForgeConfig } from "../config/forge-config.ts";
 

package/src/onboarding/nested-agents-generate.ts

@@ -23,19 +23,29 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { writeFileIfChanged } from "../utils/index.ts";
+import {
+  canonicalFooterOf,
+  hasEditableGeneratedMarker,
+  mergeEditableGenerated,
+  splitEditableGenerated,
+  writeFileIfChanged,
+} from "../utils/index.ts";
+import { resolveIo } from "../utils/io.ts";
 import { discoverWorkspaces } from "./workspace-discovery.ts";
 import { buildNestedAgentsMd, selectNestedTemplate, type PackageInfo } from "./nested-agents-templates.ts";
 import type { ForgeConfig } from "../config/forge-config.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
 import type { StackProfile } from "../profiles/stack-profile.ts";
+import type { WorkspaceIO } from "../types.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 
 export interface NestedGenerateResult {
   generated: string[];
   skipped: string[];
+  /** RFC-1153: files merged with a carried custom tail below the boundary. */
+  preserved: string[];
   renderedFiles: { [relPath: string]: string };
   workspaceTypeMap?: { [relPath: string]: string };
 }
@@ -55,6 +65,7 @@ export async function generateNestedAgentsMd(
   config: ForgeConfig,
   dryRun: boolean,
   workspaceTypes?: ProfileWorkspaceType[],
+  io?: WorkspaceIO,
 ): Promise<NestedGenerateResult> {
   const workspaces = discoverWorkspaces(
     workspaceRoot,
@@ -63,7 +74,9 @@ export async function generateNestedAgentsMd(
   );
   const generated: string[] = [];
   const skipped: string[] = [];
+  const preserved: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};
+  const fio = resolveIo(io);
   const workspaceTypeMap: { [relPath: string]: string } = {};
 
   // RFC-0643: resolve terminology from config + profile for nested template substitution
@@ -90,12 +103,40 @@ export async function generateNestedAgentsMd(
       continue;
     }
 
-    await writeFileIfChanged(agentsMdPath, content);
+    // RFC-1153: merge instead of overwrite — the `forge:custom` boundary marks
+    // the split between the generator-owned head and the preserved custom tail.
+    let existing: string | null = null;
+    if (ws.hasAgentsMd) {
+      try {
+        existing = await fio.readFile(agentsMdPath);
+      } catch {
+        // Unreadable — treat as absent; merge will emit a fresh file.
+      }
+    }
+    let merged = mergeEditableGenerated(content, existing, relPath);
+    if (merged === null && existing !== null && !hasEditableGeneratedMarker(existing)) {
+      // RFC-0081/RFC-1153: restrictive-marker file is fully generator-owned —
+      // upgrade it to the editable boundary contract (fresh render + marker).
+      merged = mergeEditableGenerated(content, null, relPath);
+    }
+    if (merged === null) {
+      skipped.push(`${relPath} (unmapped-customization)`);
+      continue;
+    }
+
+    await writeFileIfChanged(agentsMdPath, merged, fio);
     generated.push(relPath);
     workspaceTypeMap[relPath] = ws.type;
+    const footer = canonicalFooterOf(content);
+    if (
+      existing !== null &&
+      splitEditableGenerated(existing, relPath, footer ?? undefined).customTail !== null
+    ) {
+      preserved.push(relPath);
+    }
   }
 
-  return { generated, skipped, renderedFiles, workspaceTypeMap };
+  return { generated, skipped, preserved, renderedFiles, workspaceTypeMap };
 }
 
 export { discoverWorkspaces, type WorkspaceDir, type WorkspaceType } from "./workspace-discovery.ts";