@warpgogol/forge 5.2.3 → 5.3.0

package/src/onboarding/workspace-discovery.ts

@@ -15,7 +15,7 @@ workspace type (app, service, package) by content markers.</purpose>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { hasGeneratedMarker } from "../utils/index.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
@@ -36,6 +36,13 @@ const SKIP_DIRS = new Set([
   ".turbo",
   ".cache",
   ".agents",
+  // Pipeline-managed mission workpieces and archives — their AGENTS.md is
+  // generated by the site pipeline, not by forge.agents.generate.
+  "missions",
+  // Test fixture workshops — not real project workspaces.
+  "test-fixtures",
+  // Stryker mutation-testing sandboxes — transient temp dirs.
+  ".stryker-tmp",
 ]);
 
 export function detectWorkspaceType(
@@ -110,8 +117,15 @@ function matchesWorkspaceType(dirPath: string, wt: ProfileWorkspaceType): boolea
 export function discoverWorkspaces(
   workspaceRoot: string,
   workspaceTypes?: ProfileWorkspaceType[],
+  extraSkipDirs?: readonly string[],
 ): WorkspaceDir[] {
   const results: WorkspaceDir[] = [];
+  // RFC-1150: consumer-declared exclusions (bindings.workspaces.skipDirs)
+  // merge over the SKIP_DIRS defaults.
+  const skipDirs =
+    extraSkipDirs && extraSkipDirs.length > 0
+      ? new Set([...SKIP_DIRS, ...extraSkipDirs])
+      : SKIP_DIRS;
 
   function scanDir(dirPath: string, depth: number): void {
     if (depth > 5) return;
@@ -125,7 +139,7 @@ export function discoverWorkspaces(
 
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      if (SKIP_DIRS.has(entry.name)) continue;
+      if (skipDirs.has(entry.name)) continue;
 
       const childPath = path.join(dirPath, entry.name);
       const type = detectWorkspaceType(childPath, workspaceTypes);

package/src/pipeline-status.test.ts

@@ -116,10 +116,7 @@ describe("deriveQueueItemStatus — derivation matrix (RFC-1140)", () => {
 
   test("audit file only → in-progress/enhance", async () => {
     await writeRfc("RFC-1107", "status: draft\n");
-    await fs.writeFile(
-      path.join(tmpDir, "docs/audits/audit-rfc-1107-test.md"),
-      "# audit\n",
-    );
+    await fs.writeFile(path.join(tmpDir, "docs/audits/audit-rfc-1107-test.md"), "# audit\n");
     const r = await deriveQueueItemStatus(tmpDir, "RFC-1107");
     expect(r?.status).toBe("in-progress");
     expect(r?.pipelineStep).toBe("enhance");

package/src/pipeline-status.ts

@@ -25,8 +25,9 @@ Add pipeline-status.test.ts (derivation matrix, order, next selection, ADR, skip
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
 import path from "node:path";
+import type { WorkspaceIO } from "./types.ts";
+import { resolveIo } from "./utils/io.ts";
 import YAML from "yaml";
 
 // ---------------------------------------------------------------------------
@@ -75,10 +76,12 @@ export function parseFrontmatter(source: string): ParsedDocument {
 export async function findAuditFile(
   workspaceRoot: string,
   docId: string,
+  io?: WorkspaceIO,
 ): Promise<string | undefined> {
+  const fio = resolveIo(io);
   const auditsDir = path.join(workspaceRoot, "docs/audits");
   try {
-    const entries = await fs.readdir(auditsDir);
+    const entries = (await fio.readdir(auditsDir)).map((e) => e.name);
     const prefix = `audit-${docId.toLowerCase()}`;
     const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
     return match ? path.join("docs/audits", match) : undefined;
@@ -90,10 +93,12 @@ export async function findAuditFile(
 export async function findPlanFile(
   workspaceRoot: string,
   docId: string,
+  io?: WorkspaceIO,
 ): Promise<string | undefined> {
+  const fio = resolveIo(io);
   const plansDir = path.join(workspaceRoot, "docs/plans");
   try {
-    const entries = await fs.readdir(plansDir);
+    const entries = (await fio.readdir(plansDir)).map((e) => e.name);
     const prefix = `plan-${docId.toLowerCase()}`;
     const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
     return match ? path.join("docs/plans", match) : undefined;
@@ -122,20 +127,26 @@ async function scanForDocument(
   dirPath: string,
   relativePrefix: string,
   idLower: string,
+  io: WorkspaceIO,
 ): Promise<string | undefined> {
   let entries;
   try {
-    entries = await fs.readdir(dirPath, { withFileTypes: true });
+    entries = await io.readdir(dirPath);
   } catch {
     return undefined;
   }
   for (const entry of entries) {
     const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      const found = await scanForDocument(path.join(dirPath, entry.name), relativePath, idLower);
+    if (entry.isDirectory) {
+      const found = await scanForDocument(
+        path.join(dirPath, entry.name),
+        relativePath,
+        idLower,
+        io,
+      );
       if (found) return found;
     } else if (
-      entry.isFile() &&
+      entry.isFile &&
       entry.name.endsWith(".md") &&
       entry.name.toLowerCase().startsWith(idLower)
     ) {
@@ -153,19 +164,21 @@ async function scanForDocument(
 export async function resolveDocument(
   workspaceRoot: string,
   docId: string,
+  io?: WorkspaceIO,
 ): Promise<ResolvedDocument | undefined> {
+  const fio = resolveIo(io);
   const idMatch = DOC_ID_PATTERN.exec(docId.trim());
   if (!idMatch) return undefined;
   const kind: QueueDocumentKind = idMatch[1]!.toUpperCase() === "ADR" ? "adr" : "rfc";
   const baseDir = kind === "adr" ? "docs/adrs" : "docs/rfcs";
   const idLower = docId.toLowerCase();
 
-  const found = await scanForDocument(path.join(workspaceRoot, baseDir), "", idLower);
+  const found = await scanForDocument(path.join(workspaceRoot, baseDir), "", idLower, fio);
   if (!found) return undefined;
 
   let source: string;
   try {
-    source = await fs.readFile(path.join(workspaceRoot, baseDir, found), "utf-8");
+    source = await fio.readFile(path.join(workspaceRoot, baseDir, found));
   } catch {
     return undefined;
   }
@@ -242,8 +255,10 @@ export interface QueueItemReport {
 export async function deriveQueueItemStatus(
   workspaceRoot: string,
   docId: string,
+  io?: WorkspaceIO,
 ): Promise<QueueItemReport | undefined> {
-  const doc = await resolveDocument(workspaceRoot, docId);
+  const fio = resolveIo(io);
+  const doc = await resolveDocument(workspaceRoot, docId, fio);
   if (!doc) return undefined;
 
   const fm = doc.frontmatter;
@@ -268,8 +283,8 @@ export async function deriveQueueItemStatus(
   }
 
   const enhancedAt = fm["enhancedAt"] ? String(fm["enhancedAt"]) : undefined;
-  const auditFile = await findAuditFile(workspaceRoot, doc.id);
-  const planFile = await findPlanFile(workspaceRoot, doc.id);
+  const auditFile = await findAuditFile(workspaceRoot, doc.id, fio);
+  const planFile = await findPlanFile(workspaceRoot, doc.id, fio);
 
   const stages = computeRfcPipelineStages({
     status,
@@ -306,10 +321,12 @@ export interface QueueReport {
 export async function deriveQueueReport(
   workspaceRoot: string,
   itemIds: string[],
+  io?: WorkspaceIO,
 ): Promise<QueueReport> {
+  const fio = resolveIo(io);
   const items: QueueItemReport[] = [];
   for (const id of itemIds) {
-    const report = await deriveQueueItemStatus(workspaceRoot, id);
+    const report = await deriveQueueItemStatus(workspaceRoot, id, fio);
     // Unresolvable ids are reported by the manifest validator; the resolver
     // skips them here so a partial report stays usable.
     if (report) items.push(report);

package/src/profiles/stack-profile.ts

@@ -20,7 +20,7 @@ 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 { z } from "zod";
 import { parse as parseYaml } from "yaml";

package/src/registry.ts

@@ -19,7 +19,7 @@ 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 { parse as parseYaml } from "yaml";
 import type { ForgeConfig } from "./config/forge-config.ts";
@@ -38,7 +38,7 @@ export interface ForgeSkillEntry {
   dependsOn: string[];
   path: string;
   knowledge?: string[];
-  triggers?: string[];
+  triggerPhrases?: string[];
 }
 
 /**
@@ -191,9 +191,9 @@ function discoverForgeSkills(skillsRoot: string): ForgeSkillEntry[] {
               ),
             }
           : {}),
-        ...(Array.isArray(fm["triggers"])
+        ...(Array.isArray(fm["triggerPhrases"])
           ? {
-              triggers: (fm["triggers"] as unknown[]).filter(
+              triggerPhrases: (fm["triggerPhrases"] as unknown[]).filter(
                 (v): v is string => typeof v === "string",
               ),
             }

package/src/skill-schema.ts

@@ -31,7 +31,10 @@ export const skillFrontmatterSchema = z.object({
     })
     .optional(),
   knowledge: z.array(z.string()).optional(),
-  triggers: z.array(z.string().min(5).max(100)).max(5).optional(),
+  // Named triggerPhrases, not triggers — agent-IDE skill loaders (Devin CLI,
+  // Windsurf) reserve `triggers` for invocation modes (user/model); a list of
+  // phrases parses to zero valid modes and the skill is dropped entirely.
+  triggerPhrases: z.array(z.string().min(5).max(100)).max(5).optional(),
 });
 
 export type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;

package/src/tests/acceptance-probe-kinds.test.ts

@@ -36,17 +36,13 @@ describe("validateAcceptanceShape — test probe", () => {
   });
 
   it("rejects a test probe missing file", () => {
-    const issues = validateAcceptanceShape([
-      { probe: "test", expect: { exitCode: 0 } },
-    ]);
+    const issues = validateAcceptanceShape([{ probe: "test", expect: { exitCode: 0 } }]);
     expect(issues).toHaveLength(1);
     expect(issues[0].message).toContain('requires a string "file"');
   });
 
   it("rejects a test probe missing expect.exitCode", () => {
-    const issues = validateAcceptanceShape([
-      { probe: "test", file: "src/test.ts" },
-    ]);
+    const issues = validateAcceptanceShape([{ probe: "test", file: "src/test.ts" }]);
     expect(issues).toHaveLength(1);
     expect(issues[0].message).toContain("requires expect: { exitCode");
   });
@@ -108,9 +104,7 @@ describe("validateAcceptanceShape — existing probe kinds (regression)", () =>
   });
 
   it("accepts well-formed file-exists probe", () => {
-    const issues = validateAcceptanceShape([
-      { probe: "file-exists", path: "src/index.ts" },
-    ]);
+    const issues = validateAcceptanceShape([{ probe: "file-exists", path: "src/index.ts" }]);
     expect(issues).toEqual([]);
   });
 
@@ -122,16 +116,12 @@ describe("validateAcceptanceShape — existing probe kinds (regression)", () =>
   });
 
   it("accepts well-formed command-registered probe", () => {
-    const issues = validateAcceptanceShape([
-      { probe: "command-registered", name: "rfc.validate" },
-    ]);
+    const issues = validateAcceptanceShape([{ probe: "command-registered", name: "rfc.validate" }]);
     expect(issues).toEqual([]);
   });
 
   it("accepts well-formed page probe", () => {
-    const issues = validateAcceptanceShape([
-      { probe: "page", path: "/about" },
-    ]);
+    const issues = validateAcceptanceShape([{ probe: "page", path: "/about" }]);
     expect(issues).toEqual([]);
   });
 });

package/src/tests/agents-generate.test.ts

@@ -102,7 +102,8 @@ test("agents-generate includes intent-to-skill routing table", async () => {
 
   const agentsMd = await readFile(join(tempDir, "AGENTS.md"), "utf8");
   expect(agentsMd).toContain("### Intent-to-skill routing");
-  expect(agentsMd).toContain("| Operator says something like | Skill |");
+  // RFC-1154: header cells are padded to column width — match via regex
+  expect(agentsMd).toMatch(/\| Operator says something like +\| Skill +\|/);
   // Should contain at least one skill name from the registry
   expect(agentsMd).toContain("fo-");
 });
@@ -224,13 +225,36 @@ test("agents-generate is idempotent — running twice produces the same content"
   expect(second).toBe(first);
 });
 
-test("agents-generate refuses to overwrite hand-written AGENTS.md", async () => {
+// RFC-1150: hand-written root guard is non-fatal — skip root, continue nested
+
+test("agents-generate skips hand-written root and still generates nested", async () => {
   await makeForgeYaml(tempDir);
   await writeFile(join(tempDir, "AGENTS.md"), "# Hand-written\nNo marker.\n", "utf8");
+  await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "package.json"),
+    JSON.stringify({ name: "@test/my-pkg" }),
+  );
 
   const result = await runAgentsGenerate({ argv: [], flags: {} }, makeContext(tempDir));
-  expect(result.exitCode).toBe(1);
-  expect(result.data?.status).toBe("fail");
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.status).toBe("pass");
+  expect(result.data?.rootSkipped).toBe(true);
+  expect(result.data?.rootSkipReason).toBe("hand-written");
+  expect(result.data?.skipped).toContain("AGENTS.md (hand-written)");
+  expect(result.data?.generated).toContain("packages/my-pkg/AGENTS.md");
+});
+
+test("agents-generate does not modify hand-written root AGENTS.md", async () => {
+  await makeForgeYaml(tempDir);
+  const original = "# Hand-written\nNo marker.\n";
+  await writeFile(join(tempDir, "AGENTS.md"), original, "utf8");
+
+  const result = await runAgentsGenerate({ argv: [], flags: {} }, makeContext(tempDir));
+  expect(result.exitCode).toBe(0);
+
+  const after = await readFile(join(tempDir, "AGENTS.md"), "utf8");
+  expect(after).toBe(original);
 });
 
 // RFC-0611: nested AGENTS.md generation tests
@@ -404,9 +428,10 @@ test("agents-generate nested renders entry points from exports map", async () =>
 
   const nested = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
   expect(nested).toContain("## Entry points");
-  expect(nested).toContain("| `@test/my-pkg` | `./src/index.ts` |");
-  expect(nested).toContain("| `@test/my-pkg/port` | `./src/port.ts` |");
-  expect(nested).toContain("| `@test/my-pkg/client` | `./src/client.ts` |");
+  // RFC-1154: cells are padded to column width — match via regex
+  expect(nested).toMatch(/\| `@test\/my-pkg` +\| `\.\/src\/index\.ts` +\|/);
+  expect(nested).toMatch(/\| `@test\/my-pkg\/port` +\| `\.\/src\/port\.ts` +\|/);
+  expect(nested).toMatch(/\| `@test\/my-pkg\/client` +\| `\.\/src\/client\.ts` +\|/);
 });
 
 test("agents-generate nested separates workspace and external dependencies", async () => {

package/src/tests/contract-registry.test.ts

@@ -41,11 +41,15 @@ describe("contract-registry (RFC-0943)", () => {
 
   describe("fileMatchesGlobs", () => {
     test("matches a simple glob pattern", () => {
-      expect(fileMatchesGlobs("packages/my-pack/src/index.ts", ["packages/my-pack/**/*.ts"])).toBe(true);
+      expect(fileMatchesGlobs("packages/my-pack/src/index.ts", ["packages/my-pack/**/*.ts"])).toBe(
+        true,
+      );
     });
 
     test("does not match when glob does not match", () => {
-      expect(fileMatchesGlobs("packages/other-pack/src/index.ts", ["packages/my-pack/**/*.ts"])).toBe(false);
+      expect(
+        fileMatchesGlobs("packages/other-pack/src/index.ts", ["packages/my-pack/**/*.ts"]),
+      ).toBe(false);
     });
 
     test("matches any of multiple globs", () => {
@@ -58,7 +62,9 @@ describe("contract-registry (RFC-0943)", () => {
     });
 
     test("handles dot files with dot option", () => {
-      expect(fileMatchesGlobs("packages/my-pack/.env.example", ["packages/**/*.example"])).toBe(true);
+      expect(fileMatchesGlobs("packages/my-pack/.env.example", ["packages/**/*.example"])).toBe(
+        true,
+      );
     });
   });
 
@@ -86,7 +92,7 @@ describe("contract-registry (RFC-0943)", () => {
         const packDir = join(ws, "my-pack");
         writeManifest(
           packDir,
-          "id: my-pack\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: api-contract\n          requiredFor:\n            - \"packages/my-pack/**/*.ts\"\n          requiredTags:\n            - name: endpoints\n              minWords: 5\n",
+          'id: my-pack\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: api-contract\n          requiredFor:\n            - "packages/my-pack/**/*.ts"\n          requiredTags:\n            - name: endpoints\n              minWords: 5\n',
         );
 
         const config: ForgeConfig = {
@@ -111,11 +117,11 @@ describe("contract-registry (RFC-0943)", () => {
       try {
         writeManifest(
           join(ws, "pack-a"),
-          "id: pack-a\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: shared-block\n          requiredFor:\n            - \"packages/**/*.ts\"\n",
+          'id: pack-a\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: shared-block\n          requiredFor:\n            - "packages/**/*.ts"\n',
         );
         writeManifest(
           join(ws, "pack-b"),
-          "id: pack-b\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: shared-block\n          requiredFor:\n            - \"services/**/*.ts\"\n",
+          'id: pack-b\nversion: 1.0.0\nextensionPoints:\n  compass:\n    contract:\n      blocks:\n        - blockId: shared-block\n          requiredFor:\n            - "services/**/*.ts"\n',
         );
 
         const config: ForgeConfig = {

package/src/tests/doctor-dist-freshness.test.ts

@@ -0,0 +1,110 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the dist-freshness doctor check — warns when a forge
+source checkout's dist/ is older than the newest src/ file (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial dist-freshness tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-dist-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    // forgeRoot falls back to <workspaceRoot>/packages/forge when unresolvable
+    forgeRoot: join(tempDir, "packages", "forge"),
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+const FORGE_YAML = `schema: "forge/config@1"
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+`;
+
+async function makeForgeCheckout(srcMtime: Date, distMtime: Date): Promise<void> {
+  const forgeRoot = join(tempDir, "packages", "forge");
+  await mkdir(join(forgeRoot, "src"), { recursive: true });
+  await mkdir(join(forgeRoot, "dist"), { recursive: true });
+  await writeFile(join(forgeRoot, "package.json"), JSON.stringify({ name: "@warpgogol/forge" }));
+  await writeFile(join(forgeRoot, "src", "index.ts"), "export {};\n");
+  await writeFile(join(forgeRoot, "dist", "index.js"), "export {};\n");
+  await utimes(join(forgeRoot, "src", "index.ts"), srcMtime, srcMtime);
+  await utimes(join(forgeRoot, "dist"), distMtime, distMtime);
+}
+
+test("dist-freshness warns when dist is older than newest src file", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const old = new Date("2026-01-01T00:00:00Z");
+  const recent = new Date("2026-09-01T00:00:00Z");
+  await makeForgeCheckout(recent, old);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("warn");
+  expect(check!.message).toContain("pnpm run build");
+});
+
+test("dist-freshness passes when dist is absent (npm consumer layout)", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  // No packages/forge at all — forgeRoot fallback dir doesn't exist
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("pass");
+});
+
+test("dist-freshness passes when dist is newer than src", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const old = new Date("2026-01-01T00:00:00Z");
+  const recent = new Date("2026-09-01T00:00:00Z");
+  await makeForgeCheckout(old, recent);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("pass");
+  expect(check!.message).toContain("fresh");
+});

package/src/tests/doctor-fix.test.ts

@@ -0,0 +1,142 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge doctor --fix — safe remediations for warn/fail
+checks: nested-AGENTS.md regeneration and memory-layer compaction (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial doctor --fix tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-fix-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun,
+    outputFormat: "json",
+  };
+}
+
+const FORGE_YAML = `schema: "forge/config@1"
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+`;
+
+const GENERATED_MARKER =
+  "<!--\n  GENERATED. Do not change this line unless the file contains project specific changes.\n-->\n";
+
+async function makeStaleWorkspace(): Promise<void> {
+  await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "package.json"),
+    JSON.stringify({ name: "@test/my-pkg" }),
+  );
+  // Generated marker + outdated content → stale
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "AGENTS.md"),
+    `${GENERATED_MARKER}# Old content\n`,
+    "utf8",
+  );
+}
+
+test("doctor --fix regenerates stale nested AGENTS.md and subsequent run passes", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await makeStaleWorkspace();
+
+  const fixInput: ForgeCommandInput = { argv: [], flags: { fix: true } };
+  const fixResult = await runDoctor(fixInput, makeContext());
+
+  const fixEntry = fixResult.data!.fixes?.find((f) => f.check === "nested-AGENTS.md");
+  expect(fixEntry).toBeDefined();
+  expect(fixEntry!.action).toBe("fixed");
+
+  const regenerated = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
+  expect(regenerated).toContain("`@test/my-pkg` — Agent Guide");
+  expect(regenerated).not.toContain("Old content");
+
+  // Subsequent doctor run: nested-AGENTS.md no longer reports this file stale
+  const verifyResult = await runDoctor({ argv: [], flags: {} }, makeContext());
+  const check = verifyResult.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check!.message).not.toContain("my-pkg/AGENTS.md stale");
+});
+
+test("doctor --fix does not modify hand-written nested AGENTS.md", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "package.json"),
+    JSON.stringify({ name: "@test/my-pkg" }),
+  );
+  const handwritten = "# Custom\nNo marker.\n";
+  await writeFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), handwritten, "utf8");
+
+  const result = await runDoctor({ argv: [], flags: { fix: true } }, makeContext());
+  expect(result.data!.fixes).toBeDefined();
+
+  const after = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
+  expect(after).toBe(handwritten);
+});
+
+test("doctor --fix compacts over-budget MEMORY.md", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, ".agents", "memory"), { recursive: true });
+  const env = Array.from({ length: 30 }, (_, i) => `- env ${i} ${"x".repeat(200)}`).join("\n");
+  await writeFile(
+    join(tempDir, ".agents", "memory", "MEMORY.md"),
+    `# Project Memory\n\n## Current focus\n\n- keep\n\n## Environment notes\n\n${env}\n`,
+    "utf8",
+  );
+
+  const result = await runDoctor({ argv: [], flags: { fix: true } }, makeContext());
+  const fixEntry = result.data!.fixes?.find((f) => f.check === "memory-layer");
+  expect(fixEntry).toBeDefined();
+  expect(fixEntry!.action).toBe("fixed");
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after.length).toBeLessThanOrEqual(4096);
+  expect(after).toContain("- keep");
+});
+
+test("doctor without --fix produces no fixes array and does not mutate", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await makeStaleWorkspace();
+
+  const result = await runDoctor({ argv: [], flags: {} }, makeContext());
+  expect(result.data!.fixes).toBeUndefined();
+
+  const after = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
+  expect(after).toContain("Old content");
+});