@warpgogol/forge 5.2.3 → 5.3.0

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/tests/workspace-discovery.test.ts

@@ -104,6 +104,34 @@ test("discoverWorkspaces skips node_modules, .git, dist, .turbo, .cache, .agents
   expect(workspaces).toHaveLength(0);
 });
 
+test("discoverWorkspaces skips missions, test-fixtures, .stryker-tmp", async () => {
+  // Pipeline-managed workpieces/archives, fixture workshops, and mutation-testing
+  // sandboxes are not project workspaces — their AGENTS.md is owned elsewhere.
+  for (const skip of ["missions", "test-fixtures", ".stryker-tmp"]) {
+    await mkdir(join(tempDir, skip, "sub"), { recursive: true });
+    await writeFile(join(tempDir, skip, "sub", "package.json"), "{}");
+  }
+
+  const workspaces = discoverWorkspaces(tempDir);
+  expect(workspaces).toHaveLength(0);
+});
+
+// RFC-1150: consumer-declared exclusions (bindings.workspaces.skipDirs)
+
+test("discoverWorkspaces honors extraSkipDirs for consumer artifact dirs", async () => {
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+  await mkdir(join(tempDir, "packages", "real-pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "real-pkg", "package.json"), "{}");
+
+  const without = discoverWorkspaces(tempDir);
+  expect(without.map((w) => w.path)).toContain(join("builds", "out"));
+
+  const withSkip = discoverWorkspaces(tempDir, undefined, ["builds"]);
+  expect(withSkip.map((w) => w.path)).not.toContain(join("builds", "out"));
+  expect(withSkip.map((w) => w.path)).toContain(join("packages", "real-pkg"));
+});
+
 test("discoverWorkspaces detects generated AGENTS.md", async () => {
   await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
   await writeFile(join(tempDir, "packages", "my-pkg", "package.json"), "{}");

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;
+}

package/src/utils/fs-idempotent.ts

@@ -27,28 +27,34 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
-import { writeFileAtomic } from "./fs-atomic.ts";
+import type { WorkspaceIO } from "../types.ts";
+import { resolveIo } from "./io.ts";
 
+// Forge-autonomy boundary (ADR-0019 / FORGE-AUTONOMY-01): `io` is optional and
+// TYPE-ONLY — forge's standalone CLI has no kernel context, so `resolveIo`
+// falls back to the ambient adapter. Kernel callers pass context.io so the
+// read-compare-write goes through the recording adapter.
 export async function writeFileIfChanged(
   filePath: string,
   content: string | Uint8Array,
+  io?: WorkspaceIO,
 ): Promise<"written" | "unchanged"> {
+  const fio = resolveIo(io);
   try {
     if (typeof content === "string") {
-      const existing = await readFile(filePath, "utf8");
+      const existing = await fio.readFile(filePath);
       if (existing === content) {
         return "unchanged";
       }
     } else {
-      const existing = await readFile(filePath);
-      if (Buffer.compare(existing, Buffer.from(content)) === 0) {
+      const existing = await fio.readFileBytes(filePath);
+      if (Buffer.compare(Buffer.from(existing), Buffer.from(content)) === 0) {
         return "unchanged";
       }
     }
   } catch {
     // File does not exist — proceed to write.
   }
-  await writeFileAtomic(filePath, content);
+  await fio.writeFile(filePath, content);
   return "written";
 }

package/src/utils/generated-marker.ts

@@ -20,6 +20,31 @@ export const GENERATED_MARKER =
 export const EDITABLE_GENERATED_MARKER =
   "GENERATED. Safe to edit — project-specific changes are expected and encouraged.";
 
+/**
+ * RFC-1153: preservation boundary marker for editable generated files.
+ * Everything below the marker line is carried over verbatim on regeneration;
+ * everything above (including the marker line itself) is generator-owned.
+ * Emitted in the file's comment style — see CUSTOM_BOUNDARY_MARKERS.
+ */
+export const CUSTOM_BOUNDARY_TOKEN = "forge:custom";
+
+export const CUSTOM_BOUNDARY_MARKERS: Record<GeneratedHeaderCommentStyle, string> = {
+  "line-slash": "// forge:custom",
+  "line-hash": "# forge:custom",
+  "block-html": "<!-- forge:custom -->",
+  "block-css": "/* forge:custom */",
+};
+
+const CUSTOM_BOUNDARY_HINT_TEXT =
+  "Add workspace-specific guidance below this line. Everything below is preserved on regeneration.";
+
+export const CUSTOM_BOUNDARY_HINTS: Record<GeneratedHeaderCommentStyle, string> = {
+  "line-slash": `// ${CUSTOM_BOUNDARY_HINT_TEXT}`,
+  "line-hash": `# ${CUSTOM_BOUNDARY_HINT_TEXT}`,
+  "block-html": `<!-- ${CUSTOM_BOUNDARY_HINT_TEXT} -->`,
+  "block-css": `/* ${CUSTOM_BOUNDARY_HINT_TEXT} */`,
+};
+
 const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
 const SAFE_TO_EDIT_LINE =
   "This file is generated but editable — your changes are preserved on regeneration.";
@@ -28,6 +53,15 @@ export function hasGeneratedMarker(content: string): boolean {
   return content.includes(GENERATED_MARKER) || content.includes(EDITABLE_GENERATED_MARKER);
 }
 
+/**
+ * RFC-1153: true only for files carrying the editable marker. A file bearing
+ * just GENERATED_MARKER is fully generator-owned (RFC-0081) — the merge
+ * upgrades it to the editable boundary contract instead of skipping it.
+ */
+export function hasEditableGeneratedMarker(content: string): boolean {
+  return content.includes(EDITABLE_GENERATED_MARKER);
+}
+
 export interface StripGeneratedMarkerResult {
   changed: boolean;
   content: string;
@@ -112,9 +146,9 @@ export interface GeneratedHeaderInput {
   editable?: boolean;
 }
 
-type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
+export type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
 
-function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
+export function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
   const lower = filePath.toLowerCase().replace(/\\/g, "/");
   const base = lower.slice(lower.lastIndexOf("/") + 1);
   if (