@warpgogol/forge 5.2.4 → 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";

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-");
 });
@@ -427,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-fix.test.ts

@@ -83,10 +83,7 @@ test("doctor --fix regenerates stale nested AGENTS.md and subsequent run passes"
   expect(fixEntry).toBeDefined();
   expect(fixEntry!.action).toBe("fixed");
 
-  const regenerated = await readFile(
-    join(tempDir, "packages", "my-pkg", "AGENTS.md"),
-    "utf8",
-  );
+  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");
 

package/src/tests/doctor-nested-agents.test.ts

@@ -9,10 +9,13 @@ workspace discovery exclusions via bindings.workspaces.skipDirs (RFC-1150).</pur
 */
 
 import { test, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, mkdir, writeFile, appendFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runDoctor } from "../onboarding/doctor.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { buildGeneratedHeader } from "../utils/index.ts";
+import { loadForgeConfig } from "../config/forge-config.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
 
 let tempDir: string;
@@ -106,3 +109,52 @@ test("nested-AGENTS.md check reports artifact dir as missing without skipDirs",
   expect(check).toBeDefined();
   expect(check!.message).toContain("builds");
 });
+
+// RFC-1153: boundary-aware staleness -----------------------------------------
+
+test("AC-8: custom content below the forge:custom boundary reports in-sync, not stale", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "packages", "pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "pkg", "package.json"), '{"name":"pkg"}', "utf8");
+
+  const config = loadForgeConfig(tempDir);
+  await generateNestedAgentsMd(tempDir, config, false);
+
+  // Operator appends a custom section below the marker
+  await appendFile(
+    join(tempDir, "packages", "pkg", "AGENTS.md"),
+    "\n## Custom rules\n\n- workspace-specific note\n",
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(
+    check!.message,
+    "Below-boundary divergence must not count as stale — merge(expected, actual) compares only the head",
+  ).not.toContain("stale");
+});
+
+test("AC-6: divergent file without a resolvable boundary reports unmapped-customization", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "packages", "legacy"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "legacy", "package.json"), '{"name":"legacy"}', "utf8");
+  // Marker-bearing (isGenerated) file that diverges and lacks footer/forge:custom
+  await writeFile(
+    join(tempDir, "packages", "legacy", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("warn");
+  expect(check!.message).toContain("unmapped-customization");
+  expect(check!.message).not.toContain("stale");
+});

package/src/tests/editable-generated-region.test.ts

@@ -0,0 +1,231 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the RFC-1153 preservation boundary — splitEditableGenerated
+and mergeEditableGenerated (forge:custom marker + canonical-footer fallback),
+plus an integration pass through generateNestedAgentsMd on a temp workspace.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1153: initial boundary merge tests — marker, footer fallback, fail-closed, comment styles, CRLF, integration.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile, readFile, appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  splitEditableGenerated,
+  mergeEditableGenerated,
+  canonicalFooterOf,
+} from "../utils/editable-region.ts";
+import {
+  CUSTOM_BOUNDARY_HINTS,
+  CUSTOM_BOUNDARY_MARKERS,
+  buildGeneratedHeader,
+} from "../utils/generated-marker.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { loadForgeConfig } from "../config/forge-config.ts";
+
+const MD = "AGENTS.md";
+const MD_MARKER = CUSTOM_BOUNDARY_MARKERS["block-html"]; // <!-- forge:custom -->
+const MD_HINT = CUSTOM_BOUNDARY_HINTS["block-html"];
+
+const FOOTER = "See the root `AGENTS.md` for project-wide rules, skills, and capabilities.";
+
+function render(body: string): string {
+  return `${buildGeneratedHeader({ filePath: MD, ownerCommand: "forge.agents.generate", editable: true })}\n${body}\n\n${FOOTER}\n`;
+}
+
+test("AC-1: content below the forge:custom marker is preserved byte-identical", () => {
+  const tail = "\n## Workspace rules\n\n- always run pnpm test first\n- custom note\n";
+  const existing = `${render("old body v1")}${MD_MARKER}\n${MD_HINT}\n${tail}`;
+  const merged = mergeEditableGenerated(render("fresh body v2"), existing, MD);
+  expect(merged).not.toBeNull();
+  // Fresh head regenerated, tail below the marker verbatim
+  expect(merged).toContain("fresh body v2");
+  expect(merged).not.toContain("old body v1");
+  expect(
+    merged!.endsWith(tail.trimStart() === tail ? tail : `\n${tail}`) || merged!.includes(tail),
+  ).toBe(true);
+  expect(merged).toContain(MD_MARKER);
+});
+
+test("marker line itself belongs to the generated head — operator-placed marker also merges", () => {
+  const tail = "everything below survives\n";
+  const existing = `hand-tuned intro\n${MD_MARKER}\n${tail}`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged).toBe(`${render("body")}${MD_MARKER}\n${MD_HINT}\n${tail}`);
+});
+
+test("AC-2: footer fallback preserves text below the canonical template footer", () => {
+  const tail = "\noperator-appended rules\n";
+  const existing = `${render("stale body")}${tail}`; // marker-less, ends with footer + tail
+  const merged = mergeEditableGenerated(render("new body"), existing, MD);
+  expect(merged).not.toBeNull();
+  expect(merged!.endsWith(tail)).toBe(true);
+});
+
+test("AC-3: footer-fallback merge introduces the forge:custom marker as the new boundary", () => {
+  const existing = `${render("body")}\ncustom tail\n`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged).toContain(MD_MARKER);
+  expect(merged).toContain(MD_HINT);
+});
+
+test("AC-5: footer-less marker-less divergent content returns null — caller must skip", () => {
+  const existing = `${buildGeneratedHeader({ filePath: MD, ownerCommand: "forge.agents.generate", editable: true })}\n# Custom\n\ntotally divergent, no footer\n`;
+  expect(mergeEditableGenerated(render("body"), existing, MD)).toBeNull();
+});
+
+test("identical content is a clean regeneration — marker appended for future runs", () => {
+  const r = render("body");
+  const merged = mergeEditableGenerated(r, r, MD);
+  expect(merged).toBe(`${r}${MD_MARKER}\n${MD_HINT}\n`);
+});
+
+test("new file (existing null) gains the boundary marker and hint", () => {
+  const merged = mergeEditableGenerated(render("body"), null, MD);
+  expect(merged).toBe(`${render("body")}${MD_MARKER}\n${MD_HINT}\n`);
+});
+
+test("AC-4: boundary marker is emitted in the comment style of the target file", () => {
+  for (const [file, style] of [
+    ["AGENTS.md", "block-html"],
+    ["config.ts", "line-slash"],
+    ["data.yaml", "line-hash"],
+    ["styles.css", "block-css"],
+  ] as const) {
+    const merged = mergeEditableGenerated("content\n", null, file);
+    expect(merged, `marker for ${file} must use ${style} comment syntax`).toContain(
+      CUSTOM_BOUNDARY_MARKERS[style],
+    );
+  }
+});
+
+test("CRLF input normalizes to LF and still resolves the marker boundary", () => {
+  const tail = "preserved tail\n";
+  const existing = `a\r\nb\r\n${MD_MARKER}\r\n${tail}`;
+  const merged = mergeEditableGenerated("fresh\n", existing, MD);
+  expect(merged).toBe(`fresh\n${MD_MARKER}\n${MD_HINT}\n${tail}`);
+  expect(merged).not.toContain("\r\n");
+});
+
+test("mid-file marker freezes everything below the first occurrence", () => {
+  const tail = "mid doc\nfrozen rules\n";
+  const existing = `intro\n${MD_MARKER}\n${tail}`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged!.endsWith(tail)).toBe(true);
+});
+
+test("forge:custom token in prose is treated as a boundary (first occurrence wins)", () => {
+  const existing = `notes on the forge:custom feature\nkept anyway\n`;
+  const split = splitEditableGenerated(existing, MD);
+  expect(split.boundary).toBe("marker");
+  expect(split.customTail).toBe("kept anyway\n");
+});
+
+test("boundary none: split returns whole content as head", () => {
+  const split = splitEditableGenerated("plain\nfile\n", MD, FOOTER);
+  expect(split.boundary).toBe("none");
+  expect(split.customTail).toBeNull();
+});
+
+test("canonicalFooterOf returns the last non-empty line", () => {
+  expect(canonicalFooterOf("a\nb\n\n\n")).toBe("b");
+  expect(canonicalFooterOf("x\n")).toBe("x");
+});
+
+// --- Integration through the real write path -----------------------------
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "editable-region-it-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+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
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+`;
+
+test("generateNestedAgentsMd regenerates the head and preserves the custom tail", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "pkg", "package.json"), '{"name":"pkg"}', "utf8");
+
+  const config = loadForgeConfig(tempDir);
+
+  // First run — fresh file gains the marker + hint
+  const first = await generateNestedAgentsMd(tempDir, config, false);
+  expect(first.generated).toContain(join("packages", "pkg", "AGENTS.md"));
+  const agentsPath = join(tempDir, "packages", "pkg", "AGENTS.md");
+  const initial = await readFile(agentsPath, "utf8");
+  expect(initial).toContain(MD_MARKER);
+  expect(initial).toContain(MD_HINT);
+
+  // Operator appends a custom section below the boundary
+  await appendFile(agentsPath, "\n## Workspace rules\n\n- never touch dist/\n", "utf8");
+
+  // Second run — head regenerated, tail preserved verbatim
+  const second = await generateNestedAgentsMd(tempDir, config, false);
+  expect(second.preserved).toContain(join("packages", "pkg", "AGENTS.md"));
+  const merged = await readFile(agentsPath, "utf8");
+  expect(merged).toContain("## Workspace rules");
+  expect(merged).toContain("- never touch dist/");
+  // Boundary sits between generated head and custom tail
+  expect(merged.indexOf(MD_MARKER)).toBeLessThan(merged.indexOf("## Workspace rules"));
+});
+
+test("generateNestedAgentsMd skips a divergent file without a resolvable boundary", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "legacy"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "legacy", "package.json"), '{"name":"legacy"}', "utf8");
+  // Marker-bearing (isGenerated) file whose body diverges and lacks the footer
+  await writeFile(
+    join(tempDir, "packages", "legacy", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const config = loadForgeConfig(tempDir);
+  const result = await generateNestedAgentsMd(tempDir, config, false);
+  const skippedEntry = result.skipped.find((s) => s.includes("legacy"));
+  expect(
+    skippedEntry,
+    "Divergent file without forge:custom/footer boundary must be skipped as unmapped-customization",
+  ).toContain("unmapped-customization");
+  // File untouched
+  const content = await readFile(join(tempDir, "packages", "legacy", "AGENTS.md"), "utf8");
+  expect(content).toContain("divergent body");
+});