@warpgogol/forge 5.2.3 → 5.2.4

package/src/config/forge-config.ts

@@ -83,6 +83,13 @@ export const forgeBindingsSchema = z.object({
       budget: z.number().int().positive().default(4096),
     })
     .optional(),
+  // RFC-1150: consumer-declared directory names excluded from workspace
+  // discovery (merged over the SKIP_DIRS defaults in workspace-discovery.ts).
+  workspaces: z
+    .object({
+      skipDirs: z.array(z.string()).default([]),
+    })
+    .optional(),
 });
 
 export interface ForgeBindings {
@@ -126,6 +133,10 @@ export interface ForgeBindings {
   memory?: {
     budget: number;
   };
+  // RFC-1150: consumer-declared workspace discovery exclusions
+  workspaces?: {
+    skipDirs: string[];
+  };
 }
 
 // ---------------------------------------------------------------------------

package/src/onboarding/agents-generate.ts

@@ -2,7 +2,7 @@
 <MODULE_CONTRACT>
 <purpose>forge.agents.generate — regenerates AGENTS.md deterministically from forge.yaml + skill registry. Carries the standard generated-file marker.</purpose>
 <non-goals>
-  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — refuse with exit 1.</item>
+  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — skip with warning, continue nested (RFC-1150).</item>
   <item>Do not read or modify forge.yaml — only read it via loadForgeConfig.</item>
 </non-goals>
 </MODULE_CONTRACT>
@@ -215,6 +215,9 @@ interface AgentsGenerateResult {
   errors: string[];
   renderedFiles?: { [relPath: string]: string };
   details?: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }>;
+  // RFC-1150: set when the root AGENTS.md was skipped (hand-written, no marker)
+  rootSkipped?: boolean;
+  rootSkipReason?: string;
 }
 
 export async function runAgentsGenerate(
@@ -247,26 +250,18 @@ export async function runAgentsGenerate(
 
   const agentsMdPath = path.join(workspaceRoot, "AGENTS.md");
 
-  // Edit guard: refuse to overwrite a hand-written AGENTS.md (skipped in dryRun)
+  // Edit guard: never overwrite a hand-written AGENTS.md — skip the root file
+  // with a warning and continue to nested generation (RFC-1150, non-fatal).
+  let rootSkipped = false;
   if (!dryRun && fs.existsSync(agentsMdPath)) {
     const existing = fs.readFileSync(agentsMdPath, "utf8");
     if (!hasGeneratedMarker(existing)) {
-      const msg = `AGENTS.md exists without a generated marker — refusing to overwrite a hand-written file. Delete or rename it first, then re-run forge.agents.generate.`;
+      rootSkipped = true;
       if (outputFormat === "pretty") {
-        logger.error(msg);
+        logger.warn(
+          "AGENTS.md exists without a generated marker — skipping root file (hand-written). Nested AGENTS.md generation continues.",
+        );
       }
-      return {
-        data: {
-          command: "forge.agents.generate",
-          status: "fail",
-          configPath: "forge.yaml",
-          generated: [],
-          skipped: [],
-          errors: [msg],
-        },
-        exitCode: 1,
-        summary: `forge.agents.generate: failed — hand-written AGENTS.md`,
-      };
     }
   }
 
@@ -371,7 +366,7 @@ export async function runAgentsGenerate(
   const resolvedTerminology = resolveAllTerminology(config, profile);
   content = substituteTemplate(content, resolvedTerminology);
 
-  const generated: string[] = ["AGENTS.md"];
+  const generated: string[] = [];
   const skipped: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};
   const details: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }> = [];
@@ -383,8 +378,12 @@ export async function runAgentsGenerate(
 
   if (dryRun) {
     renderedFiles["AGENTS.md"] = content;
+    generated.push("AGENTS.md");
+  } else if (rootSkipped) {
+    skipped.push("AGENTS.md (hand-written)");
   } else {
     await writeFileIfChanged(agentsMdPath, content);
+    generated.push("AGENTS.md");
     if (outputFormat === "pretty") {
       logger.success(`Generated ${path.relative(workspaceRoot, agentsMdPath)}`);
     }
@@ -443,11 +442,12 @@ export async function runAgentsGenerate(
       skipped,
       errors: [],
       details,
+      ...(rootSkipped ? { rootSkipped: true, rootSkipReason: "hand-written" } : {}),
       ...(dryRun ? { renderedFiles } : {}),
     },
     exitCode: 0,
     summary: dryRun
       ? `forge.agents.generate: [dry-run] would generate ${generated.length} file(s), skip ${skipped.length}`
-      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped`,
+      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped${rootSkipped ? " (root AGENTS.md hand-written — skipped)" : ""}`,
   };
 }

package/src/onboarding/doctor.ts

@@ -35,7 +35,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,7 +47,8 @@ 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";
@@ -55,6 +56,12 @@ import { execSync } from "node:child_process";
 import fs from "node:fs";
 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";
@@ -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 {
@@ -1209,9 +1220,10 @@ 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 strict = input.flags["strict"] === true;
+  const fix = input.flags["fix"] === true;
   const checks: DoctorCheck[] = [];
 
   // Check forge.yaml
@@ -1418,6 +1430,9 @@ 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);
   checks.push(packCheck);
@@ -1435,8 +1450,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)
@@ -1472,6 +1487,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));
+    }
+  }
+
   if (outputFormat === "pretty") {
     logger.section(`Forge Doctor — ${workspaceRoot}`);
     for (const check of finalChecks) {
@@ -1479,6 +1503,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 +1516,108 @@ 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,
+): Promise<DoctorFixResult> {
+  switch (check.name) {
+    case "nested-AGENTS.md": {
+      try {
+        const config = loadForgeConfig(workspaceRoot);
+        const res = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes);
+        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 (!fs.existsSync(memoryPath)) {
+          return { check: check.name, action: "skipped", detail: "MEMORY.md absent" };
+        }
+        const content = fs.readFileSync(memoryPath, "utf8");
+        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) {
+          fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+        }
+        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/memory-compact.ts

@@ -0,0 +1,188 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge memory.compact — mechanically enforce the MEMORY.md character budget
+(RFC-0664) by removing oldest Environment notes bullets until the file fits.
+Invoked standalone and by forge doctor --fix for the memory-layer check (RFC-1151).</purpose>
+<non-goals>
+  <item>Never touch "## Current focus" or "## Decisions in flight" — those need editorial judgment.</item>
+  <item>No semantic rewriting — bullets are removed whole, never edited or merged.</item>
+  <item>No archiving into daily/ logs — removed content is recoverable via git history.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial memory.compact — oldest-first Environment notes truncation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
+import { resolveMemoryBudget } from "./memory-scaffold.ts";
+
+const MEMORY_MD_PATH = path.join(".agents", "memory", "MEMORY.md");
+const COMPACT_SECTION = "## Environment notes";
+const PROTECTED_SECTIONS = new Set(["## Current focus", "## Decisions in flight"]);
+
+export interface MemoryCompactResult {
+  command: "forge.memory.compact";
+  status: "pass" | "fail";
+  removed: number;
+  remainingChars: number;
+  budget: number;
+  removedLines?: string[];
+  errors: string[];
+}
+
+interface Section {
+  header: string;
+  start: number; // line index of the "## ..." header
+  end: number; // line index one past the section's last line
+}
+
+function parseSections(lines: string[]): Section[] {
+  const sections: Section[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      if (sections.length > 0) sections[sections.length - 1].end = i;
+      sections.push({ header: lines[i].trim(), start: i, end: lines.length });
+    }
+  }
+  return sections;
+}
+
+function isBullet(line: string): boolean {
+  return /^\s*-\s+/.test(line);
+}
+
+/**
+ * Remove oldest bullets from `## Environment notes` until the file fits the
+ * budget. Returns the new line list and the removed bullet lines.
+ * Exported for reuse by `forge doctor --fix` (RFC-1151).
+ */
+export function compactMemoryMd(
+  content: string,
+  budget: number,
+): { lines: string[]; removedLines: string[]; fitsBudget: boolean } {
+  if (content.length <= budget) {
+    return { lines: content.split("\n"), removedLines: [], fitsBudget: true };
+  }
+
+  const lines = content.split("\n");
+  const sections = parseSections(lines);
+  const target = sections.find((s) => s.header === COMPACT_SECTION);
+
+  const removedLines: string[] = [];
+  if (target) {
+    // Sanity: never remove from protected sections even if headers drift.
+    if (PROTECTED_SECTIONS.has(target.header)) {
+      return { lines, removedLines, fitsBudget: false };
+    }
+    // Remove bullet lines oldest-first (document order) within the section.
+    let i = target.start + 1;
+    while (i < target.end && lines.join("\n").length > budget) {
+      if (isBullet(lines[i])) {
+        removedLines.push(lines[i]);
+        lines.splice(i, 1);
+        target.end--;
+        // Recompute section ends after splice — only the target shrinks.
+      } else {
+        i++;
+      }
+    }
+  }
+
+  const fitsBudget = lines.join("\n").length <= budget;
+  return { lines, removedLines, fitsBudget };
+}
+
+export async function runMemoryCompact(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MemoryCompactResult>> {
+  const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const memoryPath = path.join(workspaceRoot, MEMORY_MD_PATH);
+  const budget = resolveMemoryBudget(workspaceRoot);
+
+  const fail = (msg: string): ForgeCommandResult<MemoryCompactResult> => ({
+    data: {
+      command: "forge.memory.compact",
+      status: "fail",
+      removed: 0,
+      remainingChars: 0,
+      budget,
+      errors: [msg],
+    },
+    exitCode: 1,
+    summary: `forge.memory.compact: failed — ${msg}`,
+  });
+
+  if (!fs.existsSync(memoryPath)) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: 0,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: "forge.memory.compact: OK — MEMORY.md absent, nothing to compact",
+    };
+  }
+
+  const content = fs.readFileSync(memoryPath, "utf8");
+  if (content.length <= budget) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: content.length,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: `forge.memory.compact: OK — already within budget (${content.length}/${budget} chars)`,
+    };
+  }
+
+  const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+  const remainingChars = lines.join("\n").length;
+
+  if (!fitsBudget) {
+    return fail(
+      `still over budget after removing ${removedLines.length} Environment notes bullet(s) ` +
+        `(${remainingChars}/${budget} chars) — manual editorial compaction required`,
+    );
+  }
+
+  if (!dryRun) {
+    fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+  }
+
+  if (outputFormat === "pretty") {
+    for (const line of removedLines) {
+      logger.info(`removed: ${line.slice(0, 80)}`);
+    }
+    logger.success(
+      `${dryRun ? "[dry-run] would remove" : "removed"} ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`,
+    );
+  }
+
+  return {
+    data: {
+      command: "forge.memory.compact",
+      status: "pass",
+      removed: removedLines.length,
+      remainingChars,
+      budget,
+      removedLines: dryRun ? removedLines : undefined,
+      errors: [],
+    },
+    exitCode: 0,
+    summary: dryRun
+      ? `forge.memory.compact: [dry-run] would remove ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`
+      : `forge.memory.compact: OK — removed ${removedLines.length} bullet(s), ${remainingChars}/${budget} chars`,
+  };
+}

package/src/onboarding/memory-scaffold.ts

@@ -138,7 +138,7 @@ export function scaffoldMemoryLayer(workspaceRoot: string): MemoryScaffoldResult
 // Health check
 // ---------------------------------------------------------------------------
 
-function resolveMemoryBudget(workspaceRoot: string): number {
+export function resolveMemoryBudget(workspaceRoot: string): number {
   try {
     const config = loadForgeConfig(workspaceRoot);
     if (config.bindings?.memory?.budget !== undefined && config.bindings?.memory?.budget !== null) {

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

@@ -56,7 +56,11 @@ export async function generateNestedAgentsMd(
   dryRun: boolean,
   workspaceTypes?: ProfileWorkspaceType[],
 ): Promise<NestedGenerateResult> {
-  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const workspaces = discoverWorkspaces(
+    workspaceRoot,
+    workspaceTypes,
+    config.bindings?.workspaces?.skipDirs,
+  );
   const generated: string[] = [];
   const skipped: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};

package/src/onboarding/workspace-discovery.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/tests/agents-generate.test.ts

@@ -224,13 +224,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