@warpgogol/forge 5.2.4 → 5.3.0

package/src/tests/skill-sync-marker.test.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-1154 skill markers: .forge-managed manifests
+recorded on sync, and the stale-dir prune under the subset-of-manifest rule
+(keeps dirs with consumer files or corrupt markers, never touches unmarked
+dirs).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial marker + prune tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  SKILL_MARKER_FILE,
+  writeSkillMarker,
+  writeSkillMarkerSync,
+  pruneStaleSkillDirs,
+} from "../onboarding/skill-markers.ts";
+
+let tmpDir: string;
+let skillsDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "skill-marker-"));
+  skillsDir = join(tmpDir, ".agents", "skills");
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function makeSkillDir(name: string, files: string[]): Promise<void> {
+  const dir = join(skillsDir, name);
+  await mkdir(dir, { recursive: true });
+  for (const f of files) {
+    const filePath = join(dir, f);
+    await mkdir(join(filePath, ".."), { recursive: true });
+    await writeFile(filePath, `content of ${f}\n`);
+  }
+}
+
+test("AC-7: writeSkillMarker records the exact file list", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  await writeSkillMarker(dir, ["SKILL.md", "qa-log.md"]);
+  const raw = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  expect(JSON.parse(raw)).toEqual({ files: ["SKILL.md", "qa-log.md"] });
+});
+
+test("marker write is idempotent (identical content on repeat)", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  const first = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  expect(await readFile(join(dir, SKILL_MARKER_FILE), "utf8")).toBe(first);
+  expect(JSON.parse(first).files).toEqual(["a.md", "b.md"]); // sorted, deterministic
+});
+
+test("AC-8: prunes a stale marked dir whose contents match the manifest", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["other-skill"]));
+  expect(result.pruned).toEqual(["old-skill"]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("AC-8: keeps a stale marked dir containing consumer files", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md", "my-notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("old-skill");
+  expect(result.keptWithConsumerFiles[0]).toContain("my-notes.md");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("AC-9: unmarked dirs are never pruned", async () => {
+  const dir = join(skillsDir, "consumer-skill");
+  await makeSkillDir("consumer-skill", ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("dirs still in the sync set are kept regardless of marker", async () => {
+  const dir = join(skillsDir, "current-skill");
+  await makeSkillDir("current-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["current-skill"]));
+  expect(result.pruned).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("corrupt marker disables prune for that dir (fail-safe keep)", async () => {
+  const dir = join(skillsDir, "broken-skill");
+  await makeSkillDir("broken-skill", ["SKILL.md"]);
+  await writeFile(join(dir, SKILL_MARKER_FILE), "not json {{{");
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("corrupt marker");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("nested manifest files are matched recursively", async () => {
+  const dir = join(skillsDir, "nested-skill");
+  await makeSkillDir("nested-skill", ["SKILL.md", "knowledge/notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md", "knowledge/notes.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual(["nested-skill"]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("missing skills dir returns empty result", async () => {
+  const result = await pruneStaleSkillDirs(join(tmpDir, "nonexistent"), new Set());
+  expect(result).toEqual({ pruned: [], keptWithConsumerFiles: [] });
+});

package/src/tests/skill-validate.test.ts

@@ -78,14 +78,14 @@ describe("RFC-0539: Pack skill validation (SKILL-14, SKILL-15)", () => {
   });
 });
 
-describe("RFC-0548: SKILL-16 triggers field validation", () => {
-  test("SKILL-16: real workspace fo-skills have valid triggers (no violations)", () => {
+describe("RFC-0548: SKILL-16 triggerPhrases field validation", () => {
+  test("SKILL-16: real workspace fo-skills have valid triggerPhrases (no violations)", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const skill16Violations = result.violations.filter((v) => v.rule === "SKILL-16");
     expect(skill16Violations).toEqual([]);
   });
 
-  test("SKILL-16: triggers are only on fo-category skills", () => {
+  test("SKILL-16: triggerPhrases are only on fo-category skills", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const skill16Violations = result.violations.filter(
       (v) => v.rule === "SKILL-16" && v.message.includes("only allowed on fo-category"),
@@ -93,13 +93,20 @@ describe("RFC-0548: SKILL-16 triggers field validation", () => {
     expect(skill16Violations).toEqual([]);
   });
 
-  test("SKILL-16: no pack skills declare triggers", () => {
+  test("SKILL-16: no pack skills declare triggerPhrases", () => {
     const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
     const packTriggerViolations = result.violations.filter(
-      (v) => v.rule === "SKILL-16" && v.message.includes("pack skills may not declare triggers"),
+      (v) =>
+        v.rule === "SKILL-16" && v.message.includes("pack skills may not declare triggerPhrases"),
     );
     expect(packTriggerViolations).toEqual([]);
   });
+
+  test("SKILL-22: no skill declares the reserved `triggers` key", () => {
+    const result = runSkillValidate({}, { workspaceRoot: process.cwd() });
+    const skill22Violations = result.violations.filter((v) => v.rule === "SKILL-22");
+    expect(skill22Violations).toEqual([]);
+  });
 });
 
 describe("RFC-0553: SKILL-17 platform reference prohibition", () => {

package/src/tests/upgrade.test.ts

@@ -9,11 +9,15 @@
 */
 
 import { test, expect, beforeEach, afterEach, vi } from "vitest";
-import { mkdtemp, mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, rm, readFile, appendFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runUpgrade } from "../onboarding/upgrade.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { ambientIo } from "../utils/io.ts";
+import { buildGeneratedHeader } from "../utils/index.ts";
+import type { WorkspaceIO } from "@warpgogol/werkstatt-shared/kernel/workspace-io";
 import { runInit } from "../onboarding/init.ts";
 import {
   loadForgeConfig,
@@ -163,7 +167,9 @@ test("forge.upgrade with syncedVersion matching installed version returns noop",
   expect(result.data?.status).toBe("noop");
   expect(result.data?.fromVersion).toBe("0.2.0");
   expect(result.data?.toVersion).toBe("0.2.0");
-  expect(result.data?.skillsUpdated).toEqual([]);
+  // RFC-1154: the reconcile pass still runs on a same-version noop — skills it
+  // re-synced are reported in skillsUpdated.
+  expect(result.data?.skillsUpdated).toContain("fo-idea");
   expect(result.exitCode).toBe(0);
 });
 
@@ -358,66 +364,40 @@ test("forge.upgrade --update-npm attempts npm install for npm consumer", async (
   await setupNpmConsumerForge(tempDir, "0.2.0");
   await setupConsumerForgeYaml(tempDir, null);
 
-  // Mock execSync to avoid real npm install
-  const execSyncMock = vi.fn(() => "");
-  vi.resetModules();
-  vi.doMock("node:child_process", () => ({
-    execSync: execSyncMock,
-    exec: vi.fn(),
-    execFile: vi.fn(),
-    spawn: vi.fn(),
-    fork: vi.fn(),
-  }));
-
-  // Re-import with mock
-  const { runUpgrade: runUpgradeMocked } = await import("../onboarding/upgrade.ts");
-
-  const result = await runUpgradeMocked(
+  // RFC-1152: inject a fake WorkspaceIO — exec is the port seam; real fs stays.
+  const execMock = vi.fn(async () => ({ exitCode: 0, stdout: "", stderr: "" }));
+  const io = { ...ambientIo, exec: execMock } as WorkspaceIO;
+
+  const result = await runUpgrade(
     { argv: [], flags: { "update-npm": true } },
-    makeContext(tempDir, false),
+    { ...makeContext(tempDir, false), io },
   );
 
   expect(result.data?.status).toBe("pass");
-  expect(execSyncMock).toHaveBeenCalled();
+  expect(execMock).toHaveBeenCalled();
   expect(result.data?.npmUpdated).toBe(true);
   expect(result.data?.npmUpdateSkipped).toBe(null);
-
-  vi.doUnmock("node:child_process");
-  vi.resetModules();
 });
 
 test("forge.upgrade --update-npm reports failure when npm install throws", async () => {
   await setupNpmConsumerForge(tempDir, "0.2.0");
   await setupConsumerForgeYaml(tempDir, null);
 
-  // Mock execSync to throw (simulates network error / registry unavailable)
-  const execSyncMock = vi.fn(() => {
-    throw new Error("network error");
-  });
-  vi.resetModules();
-  vi.doMock("node:child_process", () => ({
-    execSync: execSyncMock,
-    exec: vi.fn(),
-    execFile: vi.fn(),
-    spawn: vi.fn(),
-    fork: vi.fn(),
-  }));
-
-  const { runUpgrade: runUpgradeMocked } = await import("../onboarding/upgrade.ts");
+  // RFC-1152: fake io.exec fails — simulates network error / registry unavailable
+  const execMock = vi.fn(async () => ({ exitCode: 1, stdout: "", stderr: "network error" }));
+  const io = { ...ambientIo, exec: execMock } as WorkspaceIO;
 
-  const result = await runUpgradeMocked(
+  const result = await runUpgrade(
     { argv: [], flags: { "update-npm": true } },
-    makeContext(tempDir, false),
+    { ...makeContext(tempDir, false), io },
   );
 
   expect(result.data?.status).toBe("pass");
-  expect(execSyncMock).toHaveBeenCalled();
+  expect(execMock).toHaveBeenCalled();
   expect(result.data?.npmUpdated).toBe(false);
   expect(result.data?.npmUpdateSkipped).toBe(
     "install failed (network error or registry unavailable)",
   );
-
-  vi.doUnmock("node:child_process");
   vi.resetModules();
 });
 
@@ -432,6 +412,72 @@ test("forge.upgrade without --update-npm does not attempt npm install", async ()
   expect(result.data?.npmUpdateSkipped).toBe(null);
 });
 
+// RFC-1153: dry-run preview of the nested-AGENTS.md merge --------------------
+
+test("AC-7: forge.upgrade --dry-run reports nestedAgentsPlanned and nestedAgentsSkipped", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // Workspace with no AGENTS.md — merged output would be written → planned
+  await mkdir(join(tempDir, "packages", "newpkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "newpkg", "package.json"), '{"name":"newpkg"}', "utf8");
+
+  // Marker-bearing file that diverges with no resolvable boundary → skipped
+  await mkdir(join(tempDir, "packages", "unmapped"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "unmapped", "package.json"),
+    '{"name":"unmapped"}',
+    "utf8",
+  );
+  await writeFile(
+    join(tempDir, "packages", "unmapped", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const result = await runUpgrade(
+    { argv: [], flags: { "dry-run": true } },
+    makeContext(tempDir, true),
+  );
+
+  expect(result.data?.status).toBe("pass");
+  const planned = result.data?.nestedAgentsPlanned ?? [];
+  const skipped = result.data?.nestedAgentsSkipped ?? [];
+
+  expect(
+    planned,
+    "planned must contain exactly the guides whose merged output differs from disk",
+  ).toContain(join("packages", "newpkg", "AGENTS.md"));
+  expect(skipped.some((s) => s.includes("unmapped") && s.includes("unmapped-customization"))).toBe(
+    true,
+  );
+  // No files written under dry-run
+  expect(existsSync(join(tempDir, "packages", "newpkg", "AGENTS.md"))).toBe(false);
+});
+
+test("forge.upgrade executing path reports nestedAgentsPreserved for carried tails", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // First run materializes the nested guide with the boundary marker
+  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);
+  await appendFile(
+    join(tempDir, "packages", "pkg", "AGENTS.md"),
+    "\n## Custom rules\n\n- keep me\n",
+    "utf8",
+  );
+
+  const result = await runUpgrade({ argv: [], flags: {} }, makeContext(tempDir, false));
+
+  expect(result.data?.status).toBe("pass");
+  expect(result.data?.nestedAgentsPreserved).toContain(join("packages", "pkg", "AGENTS.md"));
+  const merged = await readFile(join(tempDir, "packages", "pkg", "AGENTS.md"), "utf8");
+  expect(merged).toContain("- keep me");
+});
+
 function qaLog(entries: { id: string; title: string; body: string }[]): string {
   const blocks = entries.map(
     (e) =>

package/src/types.ts

@@ -20,6 +20,101 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
+// RFC-1152: WorkspaceIO port types — declared locally so the standalone npm
+// build needs no @warpgogol/* package (ADR-0019). Structurally identical to
+// @warpgogol/werkstatt-shared/kernel/workspace-io — kernel callers passing a
+// real WorkspaceIO (context.io) are assignable both ways.
+
+export interface ExecOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  /** Extra environment variables merged over `process.env` for the child. */
+  env?: Record<string, string>;
+}
+
+export interface ExecResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * A directory entry in a port-neutral shape — no `node:fs` `Dirent` leaks
+ * through the port, so command modules never need to import `node:fs` just to
+ * type a listing. `isFile`/`isDirectory` are plain booleans (not methods).
+ */
+export interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+}
+
+/** Port-neutral `stat` result — no `node:fs` `Stats` leaks through the port. */
+export interface FileStat {
+  isFile: boolean;
+  isDirectory: boolean;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface WorkspaceIO {
+  readFile(path: string): Promise<string>;
+  readFileBytes(path: string): Promise<Uint8Array>;
+  exists(path: string): Promise<boolean>;
+  glob(pattern: string, opts?: { cwd?: string }): Promise<string[]>;
+  /** List a directory's immediate entries. Read-only; throws if the path is not a directory. */
+  readdir(path: string): Promise<DirEntry[]>;
+  /** File metadata in a port-neutral shape. Throws when the path does not exist. */
+  stat(path: string): Promise<FileStat>;
+  /** Resolve symlinks to the canonical absolute path. Read-only. */
+  realpath(path: string): Promise<string>;
+  /** Atomic by contract (rfc-0258). */
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  /** Append content to a file, creating it (and parent dirs) when absent. */
+  appendFile(path: string, content: string | Uint8Array): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  rm(path: string, opts?: { recursive?: boolean }): Promise<void>;
+  rename(src: string, dst: string): Promise<void>;
+  copyFile(src: string, dst: string): Promise<void>;
+  /** Create a unique temporary directory under `prefix`; returns its path. */
+  mkdtemp(prefix: string): Promise<string>;
+  exec(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+  /**
+   * RFC-1176: `true` only on the read-only adapter (`mutatesState: false`
+   * commands). Best-effort bookkeeping writes must be skipped with
+   * `if (!io.readonly)` instead of attempting a mutation that throws
+   * KERNEL-META-01 — the throw stays as the enforcement floor for
+   * undeclared mutations. Undefined on real and recording adapters.
+   */
+  readonly readonly?: boolean;
+}
+
+/**
+ * RFC-0960: Declared generated artifact specification on a kernel command.
+ * Lives on `ForgeCommandMetadata.generates[]` and is the source of truth
+ * for the derived generator ownership map.
+ */
+export interface GeneratedArtifactSpec {
+  /** Workpiece-relative path or glob, e.g. "src/content/system-health.generated.yaml". */
+  path: string;
+  /** Skip absence checks (RFC-0636 semantics) — e.g. produced only in build.post. */
+  conditional?: boolean;
+  /** Pipeline phase that produces it: informs which validator phase may assert existence. */
+  phase: "build.prepare" | "build.post" | "on-demand";
+  /**
+   * Override the default markerPolicy derivation. Default: public/** → "registry-only",
+   * everything else → "embedded". Set explicitly only for edge cases (e.g. .cache/pdf/**).
+   */
+  markerPolicy?: "embedded" | "registry-only";
+  /**
+   * Committed bytes contain non-deterministic fields (Ed25519 proofs, real-time
+   * created/generatedAt timestamps, build durations) — byte-compare against a
+   * dryRun render can never pass. generated.drift.validate skips volatile
+   * artifacts; existence/staleness/signature checks still apply elsewhere.
+   */
+  volatile?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Command input / output
 // ---------------------------------------------------------------------------
@@ -71,6 +166,24 @@ export interface ForgeCommandMetadata {
   description: string;
   scope: ForgeCommandScope;
   mutatesState?: boolean;
+  /**
+   * RFC-1176: permits `io.exec` on the read-only adapter — the command
+   * declares `mutatesState: false` but legitimately shells out for
+   * read-only probes. Structurally mirrors KernelCommandMetadata.
+   */
+  execOnReadOnly?: boolean;
+  /**
+   * RFC-1176: flag names whose truthy presence upgrades this invocation to
+   * a real (or `--dry-run` recording) adapter. Structurally mirrors
+   * KernelCommandMetadata.
+   */
+  mutatingFlags?: string[];
+  /**
+   * RFC-0960/0810: repo-relative path to the implementing module file —
+   * propagated into generator ownership entries (OWN-XCHECK-03 requires it
+   * on every command that declares generates[]).
+   */
+  modulePath?: string;
   requiresNetwork?: boolean;
   supportsAllSites?: boolean;
   /** RFC-0963: validation contract this command belongs to (e.g. "content", "seo"). */
@@ -118,6 +231,8 @@ export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];
   writes?: string[];
+  /** RFC-0960 generated-artifact declarations (on-demand generators). */
+  generates?: GeneratedArtifactSpec[];
   hidden?: boolean;
 }
 
@@ -126,6 +241,8 @@ export interface ForgeCommandDefinition<TData = unknown> extends ForgeCommandMet
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];
   writes?: string[];
+  /** RFC-0960 generated-artifact declarations (on-demand generators). */
+  generates?: GeneratedArtifactSpec[];
   execute(
     input: ForgeCommandInput,
     context: ForgeRuntimeContext,
@@ -227,4 +344,10 @@ export interface ForgeRuntimeContext {
    * use this instead of calling resolveForgeRoot(workspaceRoot).
    */
   forgeRoot?: string;
+  /**
+   * RFC-1152: optional WorkspaceIO port — populated when a kernel invokes the
+   * command (writes flow through the recording adapter); absent under the
+   * standalone `forge` CLI, where helpers fall back to the ambient adapter.
+   */
+  io?: WorkspaceIO;
 }

package/src/utils/editable-region.ts

@@ -0,0 +1,156 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-1153: preservation-boundary split/merge for editable generated
+files. Pure, no I/O — callers read the existing file and write the merged
+result through WorkspaceIO. The `forge:custom` marker line bounds the
+generator-owned head; everything below it is carried over verbatim.</purpose>
+<non-goals>
+  <item>Do not perform file I/O — operates on in-memory content strings only.</item>
+  <item>Do not apply to non-editable generated files — GENERATED_MARKER files
+  keep the RFC-0081 binary semantics (marker present = overwrite, absent = skip).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>forge:custom marker bounds the generated head; canonical footer is the fallback boundary when absent.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1153: initial — splitEditableGenerated + mergeEditableGenerated with
+  forge:custom marker boundary and canonical-footer (last non-empty render line) fallback.</item>
+</CHANGE_SUMMARY>
+*/
+
+import {
+  CUSTOM_BOUNDARY_HINTS,
+  CUSTOM_BOUNDARY_MARKERS,
+  CUSTOM_BOUNDARY_TOKEN,
+  commentStyleForPath,
+} from "./generated-marker.ts";
+
+export interface EditableRegionSplit {
+  /** Content up to and including the boundary line (marker or footer). */
+  generatedHead: string;
+  /** Content after the boundary line, verbatim. null when empty. */
+  customTail: string | null;
+  boundary: "marker" | "footer" | "none";
+}
+
+/** DNA-58 rule: boundary and footer matching normalize CRLF to LF. */
+function normalizeNewlines(text: string): string {
+  return text.replace(/\r\n/g, "\n");
+}
+
+/**
+ * Canonical footer of a render — its last non-empty line. Callers that need
+ * the boundary value separately (doctor staleness, preserved-tail detection)
+ * derive it from the same render they pass to the merge.
+ */
+export function canonicalFooterOf(rendered: string): string | null {
+  const lines = normalizeNewlines(rendered).split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (line !== undefined && line.trim() !== "") return line;
+  }
+  return null;
+}
+
+/**
+ * Split an existing editable generated file at its preservation boundary.
+ *
+ * Priority:
+ * 1. First line containing the `forge:custom` token (comment-style agnostic —
+ *    a token in prose is a documented, deliberate-looking boundary hazard).
+ *    The marker line and an immediately following canonical hint line belong
+ *    to the generated head.
+ * 2. `footerLine` (canonical template footer, derived by callers from the
+ *    render as its last non-empty line) — first occurrence is the boundary.
+ * 3. `"none"` — no resolvable boundary.
+ */
+export function splitEditableGenerated(
+  content: string,
+  filePath: string,
+  footerLine?: string,
+): EditableRegionSplit {
+  const text = normalizeNewlines(content);
+  const style = commentStyleForPath(filePath);
+  const hint = CUSTOM_BOUNDARY_HINTS[style];
+  const lines = text.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== undefined && line.includes(CUSTOM_BOUNDARY_TOKEN)) {
+      let headEnd = i + 1;
+      if (lines[headEnd] === hint) headEnd += 1;
+      const tail = lines.slice(headEnd).join("\n");
+      return {
+        generatedHead: lines.slice(0, headEnd).join("\n"),
+        customTail: tail.trim() === "" ? null : tail,
+        boundary: "marker",
+      };
+    }
+  }
+
+  if (footerLine !== undefined) {
+    // lastIndexOf: the canonical footer is the template's last line — the
+    // trailingmost occurrence is the correct boundary even when an operator
+    // copied the line into a mid-file section.
+    const idx = lines.lastIndexOf(footerLine);
+    if (idx >= 0) {
+      const tail = lines.slice(idx + 1).join("\n");
+      return {
+        generatedHead: lines.slice(0, idx + 1).join("\n"),
+        customTail: tail.trim() === "" ? null : tail,
+        boundary: "footer",
+      };
+    }
+  }
+
+  return { generatedHead: text, customTail: null, boundary: "none" };
+}
+
+/**
+ * Merge a fresh render with an existing editable generated file.
+ *
+ * The canonical footer is derived internally as the last non-empty line of
+ * `rendered` — no per-file-kind footer registry exists; when a template tail
+ * changes, the boundary follows the new render automatically.
+ *
+ * Merge contract:
+ * - `existing === null` (new file): rendered + boundary marker + hint.
+ * - marker boundary: head = fresh render + marker + hint; tail verbatim.
+ * - footer boundary (legacy marker-less file): head = fresh render + marker +
+ *   hint (marker introduced now); tail = content after the legacy footer line.
+ * - none + identical content: clean regeneration, marker + hint appended.
+ * - none + divergent content: returns null — caller must skip and warn
+ *   (`unmapped-customization`), never overwrite.
+ *
+ * The result is LF-normalized; callers write through `writeFileIfChanged`.
+ */
+export function mergeEditableGenerated(
+  rendered: string,
+  existing: string | null,
+  filePath: string,
+): string | null {
+  const render = normalizeNewlines(rendered);
+  const style = commentStyleForPath(filePath);
+  const marker = CUSTOM_BOUNDARY_MARKERS[style];
+  const hint = CUSTOM_BOUNDARY_HINTS[style];
+  const boundaryBlock = `${marker}\n${hint}\n`;
+
+  if (existing === null) {
+    return `${render}${boundaryBlock}`;
+  }
+
+  const text = normalizeNewlines(existing);
+  const footer = canonicalFooterOf(render);
+  const split = splitEditableGenerated(text, filePath, footer ?? undefined);
+
+  if (split.boundary === "marker" || split.boundary === "footer") {
+    return `${render}${boundaryBlock}${split.customTail ?? ""}`;
+  }
+
+  if (text === render || text === `${render}${boundaryBlock}`) {
+    return `${render}${boundaryBlock}`;
+  }
+
+  return null;
+}