@warpgogol/forge 5.2.3 → 5.3.0

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";
@@ -35,7 +37,7 @@ import { resolveForgeRoot, loadForgeConfig, resolveBinding, resolveTerminology,
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
 import { discoverWorkspaces } from "./workspace-discovery.ts";
 import { buildNestedAgentsMd, selectNestedTemplate } from "./nested-agents-templates.ts";
-import { readPackageInfo } from "./nested-agents-generate.ts";
+import { readPackageInfo, generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 import { TERMINOLOGY_DEFAULTS } from "../profiles/profile-schema.ts";
@@ -47,14 +49,21 @@ import type { ParsedKnowledgeFile } from "../knowledge/index.ts";
 import { computeLayerBudgets, resolveKnowledgeBudgets, DEFAULT_KNOWLEDGE_BUDGETS } from "../knowledge/budgets.ts";
 import { detectDuplicatePrinciples } from "../knowledge/index.ts";
 import type { DuplicatePair } from "../knowledge/index.ts";
-import { checkMemoryLayerHealth } from "./memory-scaffold.ts";
+import { checkMemoryLayerHealth, resolveMemoryBudget } from "./memory-scaffold.ts";
+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 {
+  check: string;
+  action: "fixed" | "skipped" | "failed";
+  detail: string;
+}
+
 interface DoctorCheck {
   name: string;
   status: "pass" | "fail" | "warn";
@@ -80,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 =
@@ -95,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) {
@@ -144,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;
@@ -163,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 {
@@ -175,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 {
@@ -219,6 +224,7 @@ async function validateBindings(workspaceRoot: string): Promise<BindingValidatio
 async function checkStaleKnowledgeFiles(
   workspaceRoot: string,
   forgeRoot: string,
+  io: WorkspaceIO,
 ): Promise<DoctorCheck> {
   const stale: string[] = [];
 
@@ -240,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.
@@ -272,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);
@@ -635,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);
@@ -651,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) {
@@ -681,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);
@@ -713,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`);
     }
@@ -732,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}'`);
       }
@@ -760,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);
@@ -813,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 {
@@ -826,7 +833,11 @@ async function checkNestedAgentsMd(
     };
   }
 
-  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const workspaces = discoverWorkspaces(
+    workspaceRoot,
+    workspaceTypes,
+    config.bindings?.workspaces?.skipDirs,
+  );
 
   if (workspaces.length === 0) {
     return {
@@ -840,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) {
@@ -852,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");
         }
@@ -874,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'`);
       }
@@ -895,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)` : ""}`,
   };
 }
@@ -1209,13 +1233,15 @@ function checkPrerequisites(prerequisites: ProfilePrerequisite[]): DoctorCheck {
 export async function runDoctor(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
-): Promise<ForgeCommandResult<{ command: string; checks: DoctorCheck[]; allPass: boolean; forbiddenImports: ForbiddenImport[]; bindings: BindingValidation; domain?: DomainReport }>> {
-  const { workspaceRoot, logger, outputFormat } = context;
+): 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",
@@ -1225,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",
@@ -1235,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",
@@ -1245,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",
@@ -1255,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",
@@ -1265,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",
@@ -1374,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",
@@ -1385,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",
@@ -1396,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
@@ -1418,16 +1444,19 @@ export async function runDoctor(
   // RFC-0664: Check memory layer health (budget, gitignore coverage, leak risk)
   checks.push(checkMemoryLayer(workspaceRoot));
 
+  // RFC-1151: Check dist freshness — stale dist/ silently shadows src/ in source checkouts
+  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
@@ -1435,8 +1464,8 @@ export async function runDoctor(
   // RFC-0640 fix: previously gated by isSoftwareDomain, which skipped the check
   // entirely for non-software domains. Now runs for all domains — profile-driven
   // wsTypes replace hardcoded detection when present.
+  let wsTypes: ProfileWorkspaceType[] | undefined;
   {
-    let wsTypes: ProfileWorkspaceType[] | undefined;
     try {
       const config = loadForgeConfig(workspaceRoot);
       // RFC-0643: prefer config.profile (loaded by loadForgeConfig)
@@ -1455,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);
   }
 
@@ -1472,6 +1501,15 @@ export async function runDoctor(
   const allPass = finalChecks.every((c) => c.status === "pass");
   const hasFails = finalChecks.some((c) => c.status === "fail");
 
+  // RFC-1151: --fix applies registered safe remediations for warn/fail checks
+  const fixes: DoctorFixResult[] = [];
+  if (fix) {
+    for (const check of finalChecks) {
+      if (check.status === "pass") continue;
+      fixes.push(await applyDoctorRemediation(check, workspaceRoot, wsTypes, dryRun === true, fio));
+    }
+  }
+
   if (outputFormat === "pretty") {
     logger.section(`Forge Doctor — ${workspaceRoot}`);
     for (const check of finalChecks) {
@@ -1479,6 +1517,10 @@ export async function runDoctor(
       const fn = check.status === "pass" ? logger.success : check.status === "warn" ? logger.warn : logger.error;
       fn(`${icon} ${check.name}: ${check.message}`);
     }
+    for (const f of fixes) {
+      const fn = f.action === "fixed" ? logger.success : f.action === "failed" ? logger.error : logger.info;
+      fn(`  fix ${f.check}: ${f.action} — ${f.detail}`);
+    }
     if (allPass) {
       logger.success("All checks passed — forge is properly configured.");
     } else if (hasFails) {
@@ -1488,11 +1530,109 @@ export async function runDoctor(
     }
   }
 
+  const fixFailed = fixes.some((f) => f.action === "failed");
+
   return {
-    data: { command: "forge.doctor", checks: finalChecks, allPass, forbiddenImports, bindings: bindingsResult, domain: domainReport },
-    exitCode: hasFails ? 1 : 0,
+    data: { command: "forge.doctor", checks: finalChecks, allPass, forbiddenImports, bindings: bindingsResult, domain: domainReport, ...(fix ? { fixes } : {}) },
+    exitCode: hasFails || fixFailed ? 1 : 0,
     summary: allPass
       ? "forge.doctor: all checks passed"
-      : `forge.doctor: ${finalChecks.filter((c) => c.status === "fail").length} fail(s), ${finalChecks.filter((c) => c.status === "warn").length} warn(s)`,
+      : `forge.doctor: ${finalChecks.filter((c) => c.status === "fail").length} fail(s), ${finalChecks.filter((c) => c.status === "warn").length} warn(s)${fix ? `, ${fixes.filter((f) => f.action === "fixed").length} fixed` : ""}`,
   };
 }
+
+// RFC-1151: dist-freshness — a stale dist/ silently shadows src/ because
+// bin/cli.js prefers dist when present. Warn-only; rebuild is a pnpm script,
+// not forge's call. Pass (skip) when src/ or dist/ is absent — npm consumers
+// ship dist-only, so this activates only in source checkouts.
+function checkDistFreshness(forgeRoot: string): DoctorCheck {
+  const srcDir = join(forgeRoot, "src");
+  const distDir = join(forgeRoot, "dist");
+  if (!fs.existsSync(srcDir) || !fs.existsSync(distDir)) {
+    return {
+      name: "dist-freshness",
+      status: "pass",
+      message: "no src+dist pair — not a source checkout",
+    };
+  }
+  const newestSrc = newestMtime(srcDir);
+  const distMtime = fs.statSync(distDir).mtimeMs;
+  if (newestSrc > distMtime) {
+    return {
+      name: "dist-freshness",
+      status: "warn",
+      message: `dist/ older than newest src/ file — run 'pnpm run build' in ${forgeRoot}`,
+    };
+  }
+  return { name: "dist-freshness", status: "pass", message: "dist/ is fresh" };
+}
+
+function newestMtime(dir: string): number {
+  let newest = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    const m = fs.statSync(join(entry.parentPath, entry.name)).mtimeMs;
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+// RFC-1151: remediation dispatch — check name → safe fix action.
+// Remediations reuse existing generators; hand-written files are never touched
+// (generated-marker edit guard inside generateNestedAgentsMd).
+async function applyDoctorRemediation(
+  check: DoctorCheck,
+  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, io);
+        return {
+          check: check.name,
+          action: res.generated.length > 0 ? "fixed" : "skipped",
+          detail: `${res.generated.length} file(s) ${dryRun ? "would be " : ""}regenerated, ${res.skipped.length} skipped`,
+        };
+      } catch (err) {
+        return { check: check.name, action: "failed", detail: (err as Error).message };
+      }
+    }
+    case "memory-layer": {
+      try {
+        const memoryPath = join(workspaceRoot, ".agents", "memory", "MEMORY.md");
+        if (!(await io.exists(memoryPath))) {
+          return { check: check.name, action: "skipped", detail: "MEMORY.md absent" };
+        }
+        const content = await io.readFile(memoryPath);
+        const budget = resolveMemoryBudget(workspaceRoot);
+        const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+        if (!fitsBudget) {
+          return {
+            check: check.name,
+            action: "failed",
+            detail: "still over budget after Environment notes truncation — manual editorial compaction required",
+          };
+        }
+        if (removedLines.length === 0) {
+          return { check: check.name, action: "skipped", detail: "within budget" };
+        }
+        if (!dryRun) {
+          await io.writeFile(memoryPath, lines.join("\n"));
+        }
+        return {
+          check: check.name,
+          action: "fixed",
+          detail: `${dryRun ? "would remove" : "removed"} ${removedLines.length} bullet(s)`,
+        };
+      } catch (err) {
+        return { check: check.name, action: "failed", detail: (err as Error).message };
+      }
+    }
+    default:
+      return { check: check.name, action: "skipped", detail: "no-remediation" };
+  }
+}

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";