@warpgogol/forge 5.2.4 → 5.3.0

package/skills/shared/grilling/learned-principles.archive.md

@@ -1,7 +1,9 @@
 <!-- knowledge-layer: L2 -->
+
 # learned-principles.md (archive)
 
 Archived entries from learned-principles.md. Generated by forge.skill.knowledge.compact (RFC-0662).
+
 ### K-0001: Extend infrastructure before feature logic
 
 ```knowledge-entry
@@ -15,6 +17,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0002: Unknown is not green
 
 ```knowledge-entry
@@ -28,6 +31,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0003: Quality claims bind to immutable identity
 
 ```knowledge-entry
@@ -41,6 +45,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0004: Evaluation must not mutate its subject
 
 ```knowledge-entry
@@ -54,6 +59,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0004.
+
 ### K-0005: Immutable history and current health are separate
 
 ```knowledge-entry
@@ -67,6 +73,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0006: Migration complexity follows the real estate
 
 ```knowledge-entry
@@ -80,6 +87,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0007: Integrity requires an independent authority
 
 ```knowledge-entry
@@ -93,6 +101,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0002.
+
 ### K-0008: Historical verification preserves policy bytes
 
 ```knowledge-entry
@@ -106,6 +115,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0009: Distributed evidence uses authority order and immutable cuts
 
 ```knowledge-entry
@@ -119,6 +129,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0002.
+
 ### K-0010: Bootstrap safety does not create legacy authority
 
 ```knowledge-entry
@@ -132,6 +143,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0011: Documents are execution boundaries
 
 ```knowledge-entry
@@ -145,6 +157,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0005.
+
 ### K-0012: Supersede decision authority, preserve useful mechanisms deliberately
 
 ```knowledge-entry
@@ -158,6 +171,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0013: Deterministic aggregators need scale contracts
 
 ```knowledge-entry
@@ -171,6 +185,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0006.
+
 ### K-0014: Canonical identities require a closed snapshot boundary
 
 ```knowledge-entry
@@ -184,6 +199,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0007.
+
 ### K-0015: Permanent formats profile standards instead of imitating them
 
 ```knowledge-entry
@@ -197,6 +213,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0007.
+
 ### K-0016: Cutover enforcement starts after executor bootstrap
 
 ```knowledge-entry

package/skills/shared/grilling/learned-principles.md

@@ -10,4 +10,3 @@ Concrete principles distilled from past grilling sessions. Each principle has a
 - **confirmations:** <N>
 - **Added:** <date>
 -->
-

package/skills/shared/knowledge/learned-principles.md

@@ -18,6 +18,7 @@ status: active
 
 - **Condition:** A consequential durable decision depends on evidence, policy, or artifact state that may later change or become unavailable.
 - **Recommended answer:** Represent missing, stale, malformed, or unavailable evidence explicitly and fail closed. Bind the decision to immutable subject and policy bytes, preserve its evidence as append-only history, and calculate current health separately rather than rewriting the historical result.
+
 ### K-0002: Integrity requires authority ordering
 
 ```knowledge-entry
@@ -32,6 +33,7 @@ status: active
 
 - **Condition:** Evidence or events may be produced concurrently, retried, submitted by the artifact author, delivered out of order, or received after a decision closes.
 - **Recommended answer:** Admit evidence through a separate least-privilege authority that assigns a monotonic sequence and freezes every decision at an explicit evaluation cut. Producer timestamps never determine precedence, self-authored consistency is not authority, and late results create a new decision or incident instead of rewriting history.
+
 ### K-0003: Forward-only cutovers preserve recovery, not legacy authority
 
 ```knowledge-entry
@@ -46,6 +48,7 @@ status: active
 
 - **Condition:** A forward-only transition replaces an authority model, runtime, toolchain, or deployment contract while still requiring prerequisites and a recoverable first cutover.
 - **Recommended answer:** Provision and verify the required executor and infrastructure before activating enforcement. Then supersede the old authority through the smallest complete cutover that fits the real estate. Preserve useful old mechanisms only as explicitly non-authorizing infrastructure; permit a narrow, one-time rollback target with explicit closure conditions, never an indefinite compatibility path.
+
 ### K-0004: Evaluation must not mutate its subject
 
 ```knowledge-entry
@@ -60,6 +63,7 @@ status: active
 
 - **Condition:** A gate, evaluator, audit, review, or certification process discovers a defect in the artifact it judges.
 - **Recommended answer:** Keep evaluation read-only with respect to the judged artifact. Emit precise, anchored remediation tasks; apply fixes in a separate authoring flow that produces a new artifact identity and a new evidence chain.
+
 ### K-0005: Documents are executable boundaries
 
 ```knowledge-entry
@@ -74,6 +78,7 @@ status: active
 
 - **Condition:** A specification or implementation document will be executed by another agent—possibly less capable—in an isolated session.
 - **Recommended answer:** Decompose work into dependency-ordered documents that each define their inputs, outputs, forbidden shortcuts, acceptance evidence, and bounded validation. Every document must leave its affected scope internally consistent; use a final integration document for cross-module laws instead of relying on unstated context.
+
 ### K-0006: Deterministic mechanisms require scale contracts
 
 ```knowledge-entry
@@ -88,6 +93,7 @@ status: active
 
 - **Condition:** A deterministic evaluator, selector, validator, or aggregator processes potentially growing collections and may gate a consequential transition.
 - **Recommended answer:** Specify hard input limits, time and memory complexity, overflow behavior, and a deterministic stress fixture. Reject overflow explicitly without truncation or synthesized success, and forbid repeated full scans when an indexed or single-pass design is available.
+
 ### K-0007: Canonical identities use closed snapshots and named standards
 
 ```knowledge-entry

package/skills/shared/my-preferences/SKILL.md

@@ -7,6 +7,7 @@ concerns: document-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>my-preferences skill — Read, create, or edit the operator's preferences file at the repository root. Run when the operator wants to change language settings for AI conversations, grilling, or project documentation.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 # my-preferences
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing, create it using the semantics below.

package/skills/shared/windows-ai-tooling/SKILL.md

@@ -7,6 +7,7 @@ concerns: code-mutation
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>windows-ai-tooling skill — Bootstrap a Windows project for AI agents. Installs verified tools, generates .gitattributes, and emits a command allow-list for agent prompts. Run when starting a new project or when agents fail.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 # Windows AI Tooling
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.

package/skills/shared/writing-great-skills/SKILL.md

@@ -7,6 +7,7 @@ concerns: read-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>writing-great-skills skill — Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
 A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.

package/src/compass/contract-registry.ts

@@ -12,7 +12,7 @@
 </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 picomatch from "picomatch";

package/src/config/forge-config.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 { z } from "zod";
 import { parse as parseYaml } from "yaml";

package/src/knowledge/__tests__/sync.test.ts

@@ -24,8 +24,7 @@ afterEach(() => {
 });
 
 function entry(id: string, title: string, body: string, layer = "L0"): string {
-  const confirmations =
-    layer === "L2" ? `lastConfirmedAt: 2026-08-03\nconfirmations: 1\n` : "";
+  const confirmations = layer === "L2" ? `lastConfirmedAt: 2026-08-03\nconfirmations: 1\n` : "";
   return `### ${id}: ${title}\n\n\`\`\`knowledge-entry\nid: ${id}\nlayer: ${layer}\ncreated: 2026-08-03\n${confirmations}status: active\n\`\`\`\n\n${body}\n`;
 }
 
@@ -99,11 +98,7 @@ test("merges: local entries preserved, new source entries appended", () => {
 test("merge into empty template appends all source entries", () => {
   const src = join(tempDir, "qa-log.md");
   const dest = join(tempDir, "dest.md");
-  writeFileSync(
-    src,
-    knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]),
-    "utf8",
-  );
+  writeFileSync(src, knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]), "utf8");
   // Destination is the shipped empty template (layer marker, no entries)
   writeFileSync(dest, `<!-- knowledge-layer: L0 -->\n\n# Q&A Log (L0)\n`, "utf8");
 

package/src/knowledge/budgets.ts

@@ -13,7 +13,7 @@
 */
 
 import path from "node:path";
-import { readFileSync } from "node:fs";
+import { readFileSync } from "../utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import type { ParsedKnowledgeFile, KnowledgeLayer } from "./schema.ts";
 

package/src/knowledge/compact.ts

@@ -13,7 +13,7 @@
 </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 { ParsedKnowledgeFile, KnowledgeEntry, KnowledgeEntryMeta } from "./schema.ts";

package/src/knowledge/parse.ts

@@ -11,7 +11,7 @@
 </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 {

package/src/knowledge/sync.ts

@@ -12,11 +12,11 @@ the synced copy with the package version.</purpose>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>2026-09-24: initial append-only knowledge sync — merge by entry-ID union, local wins conflicts, skip divergent non-cumulative files, recurse into declared directories.</item>
+  <item>RFC-0660: initial append-only knowledge sync — merge by entry-ID union, local wins conflicts, skip divergent non-cumulative files, recurse into declared directories.</item>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parseKnowledgeFile } from "./parse.ts";
 import { serializeKnowledgeFile } from "./serialize.ts";
@@ -80,9 +80,7 @@ function planFileSync(srcPath: string, destPath: string): KnowledgeSyncPlan {
   if (isCumulative(srcParsed) && isCumulative(destParsed)) {
     const destIds = new Set(destParsed.entries.map((e) => e.meta.id));
     const appendedEntries = srcParsed.entries.filter((e) => !destIds.has(e.meta.id));
-    const conflicts = srcParsed.entries
-      .filter((e) => destIds.has(e.meta.id))
-      .map((e) => e.meta.id);
+    const conflicts = srcParsed.entries.filter((e) => destIds.has(e.meta.id)).map((e) => e.meta.id);
 
     const destLegacyTexts = new Set(destParsed.legacySections.map((l) => l.text.trim()));
     const appendedLegacy = srcParsed.legacySections.filter(

package/src/migration-adapters/git-utils.ts

@@ -17,9 +17,9 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync } from "../utils/sync-fs.ts";
 import { trashSync } from "../utils/fs-trash-sync.ts";
 import type { AdapterAnalysis } from "./types.ts";
 

package/src/migration-adapters/ignored-files.ts

@@ -16,9 +16,9 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync } from "../utils/sync-fs.ts";
 
 export type IgnoredFileCategoryId = "config" | "data" | "runtime-state" | "cache" | "other";
 

package/src/migration-adapters/node-typescript-pnpm/index.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../utils/sync-fs.ts";
 import path from "node:path";
 import type { MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict } from "../types.ts";
 import { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "../types.ts";

package/src/migration-adapters/phaser-pnpm/index.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../utils/sync-fs.ts";
 import path from "node:path";
 import type { MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict } from "../types.ts";
 import { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "../types.ts";

package/src/onboarding/agents-generate.ts

@@ -20,13 +20,14 @@ 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 { resolveIo } from "../utils/io.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { loadForgeConfig, resolveBinding, resolveForgePackageRoot, resolveForgeRoot } from "../config/forge-config.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 import { FORGE_SKILLS } from "../registry.ts";
-import { buildGeneratedHeader, hasGeneratedMarker, writeFileIfChanged } from "../utils/index.ts";
+import { alignMarkdownTable, buildGeneratedHeader, hasEditableGeneratedMarker, hasGeneratedMarker, mergeEditableGenerated, writeFileIfChanged } from "../utils/index.ts";
 import { generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { listStackProfiles } from "../profiles/stack-profile.ts";
 import type { StackProfile } from "../profiles/stack-profile.ts";
@@ -140,9 +141,11 @@ function readRegister(workspaceRoot: string): BehavioralRegister {
   return "business";
 }
 
-function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers: string[] }> {
+function extractTriggerPhrases(
+  workspaceRoot: string,
+): Array<{ name: string; triggerPhrases: string[] }> {
   const forgeRoot = path.join(workspaceRoot, "packages", "forge");
-  const result: Array<{ name: string; triggers: string[] }> = [];
+  const result: Array<{ name: string; triggerPhrases: string[] }> = [];
   for (const skill of FORGE_SKILLS) {
     if (skill.category !== "fo") continue;
     const skillPath = path.join(forgeRoot, skill.path);
@@ -151,10 +154,12 @@ function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers:
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
       if (!fmMatch) continue;
       const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
-      if (Array.isArray(fm["triggers"])) {
+      if (Array.isArray(fm["triggerPhrases"])) {
         result.push({
           name: skill.name,
-          triggers: (fm["triggers"] as unknown[]).filter((v): v is string => typeof v === "string"),
+          triggerPhrases: (fm["triggerPhrases"] as unknown[]).filter(
+            (v): v is string => typeof v === "string",
+          ),
         });
       }
     } catch {
@@ -164,21 +169,28 @@ function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers:
   return result;
 }
 
-function generateTriggersTable(triggers: Array<{ name: string; triggers: string[] }>): string {
-  const rows: string[] = [];
-  for (const { name, triggers: skillTriggers } of triggers) {
+// RFC-1154: emits the full aligned table (header + separator + rows) since
+// column widths depend on substituted trigger rows — the template carries only
+// the {{triggersTable}} placeholder, no static header lines.
+function generateTriggersTable(
+  triggerPhrases: Array<{ name: string; triggerPhrases: string[] }>,
+): string {
+  const rows: string[][] = [];
+  for (const { name, triggerPhrases: skillTriggers } of triggerPhrases) {
     if (skillTriggers.length === 0) continue;
     const display = skillTriggers.map((t) => `"${t}"`).join(", ");
-    rows.push(`| ${display} | \`${name}\` |`);
+    rows.push([display, `\`${name}\``]);
   }
-  return rows.length > 0 ? rows.join("\n") + "\n" : "";
+  // Always emit the header + separator — even with zero trigger rows the
+  // section documents the routing contract (matches pre-RFC-1154 behavior).
+  return alignMarkdownTable(["Operator says something like", "Skill"], rows) + "\n";
 }
 
 function generateBehavioralLayer(
   workspaceRoot: string,
   register: BehavioralRegister,
 ): string {
-  const triggers = extractTriggers(workspaceRoot);
+  const triggerPhrases = extractTriggerPhrases(workspaceRoot);
 
   let template: string;
   try {
@@ -187,7 +199,7 @@ function generateBehavioralLayer(
     return "";
   }
 
-  const triggersTable = generateTriggersTable(triggers);
+  const triggersTable = generateTriggersTable(triggerPhrases);
 
   let extendedLayer = "";
   if (register === "creative") {
@@ -225,6 +237,7 @@ export async function runAgentsGenerate(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<AgentsGenerateResult>> {
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
 
   let config;
   try {
@@ -253,8 +266,8 @@ export async function runAgentsGenerate(
   // 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 (!dryRun && (await fio.exists(agentsMdPath))) {
+    const existing = await fio.readFile(agentsMdPath);
     if (!hasGeneratedMarker(existing)) {
       rootSkipped = true;
       if (outputFormat === "pretty") {
@@ -279,14 +292,15 @@ export async function runAgentsGenerate(
   // Build dynamic sections (skills table, capabilities, behavioral layer)
   const dynamicLines: string[] = [];
 
-  // Skills table
+  // Skills table (RFC-1154: emitted prettier-normal via alignMarkdownTable)
   dynamicLines.push("## Skills");
   dynamicLines.push("");
-  dynamicLines.push("| Name | Category | Invocation | Concerns |");
-  dynamicLines.push("| --- | --- | --- | --- |");
-  for (const skill of FORGE_SKILLS) {
-    dynamicLines.push(`| ${skill.name} | ${skill.category} | ${skill.invocation} | ${skill.concerns} |`);
-  }
+  dynamicLines.push(
+    alignMarkdownTable(
+      ["Name", "Category", "Invocation", "Concerns"],
+      FORGE_SKILLS.map((skill) => [skill.name, skill.category, skill.invocation, skill.concerns]),
+    ),
+  );
   dynamicLines.push("");
 
   // Capabilities section (RFC-0393)
@@ -295,8 +309,6 @@ export async function runAgentsGenerate(
     dynamicLines.push("");
     dynamicLines.push("Bindings resolved from `forge.yaml`:");
     dynamicLines.push("");
-    dynamicLines.push("| Key | Status | Value |");
-    dynamicLines.push("| --- | --- | --- |");
 
     const bindingKeys = [
       "commands.validateRfc",
@@ -312,21 +324,23 @@ export async function runAgentsGenerate(
       "paths.sessionsDir",
     ];
 
-    for (const key of bindingKeys) {
+    const capabilityRows: string[][] = bindingKeys.map((key) => {
       const value = resolveBinding(config, key);
       const status = value === null ? "absent" : "resolved";
       const display = value === null ? "—" : typeof value === "string" ? `\`${value}\`` : String(value);
-      dynamicLines.push(`| ${key} | ${status} | ${display} |`);
-    }
+      return [key, status, display];
+    });
 
     // compassDocs array
     const compassDocs = resolveBinding(config, "paths.compassDocs");
     if (Array.isArray(compassDocs) && compassDocs.length > 0) {
-      dynamicLines.push(`| paths.compassDocs | resolved | ${compassDocs.map((d) => `\`${d}\``).join(", ")} |`);
+      capabilityRows.push(["paths.compassDocs", "resolved", compassDocs.map((d) => `\`${d}\``).join(", ")]);
     } else {
-      dynamicLines.push(`| paths.compassDocs | absent | — |`);
+      capabilityRows.push(["paths.compassDocs", "absent", "—"]);
     }
 
+    dynamicLines.push(alignMarkdownTable(["Key", "Status", "Value"], capabilityRows));
+
     // terminology
     if (config.bindings.terminology && Object.keys(config.bindings.terminology).length > 0) {
       dynamicLines.push("");
@@ -382,10 +396,37 @@ export async function runAgentsGenerate(
   } 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)}`);
+    // RFC-1153: merge instead of overwrite — preserve the custom tail below
+    // the forge:custom boundary; fail-closed skip when no boundary resolves.
+    let existing: string | null = null;
+    if (await fio.exists(agentsMdPath)) {
+      try {
+        existing = await fio.readFile(agentsMdPath);
+      } catch {
+        // Unreadable — treat as absent; merge will emit a fresh file.
+      }
+    }
+    let merged = mergeEditableGenerated(content, existing, "AGENTS.md");
+    if (merged === null) {
+      if (existing !== null && !hasEditableGeneratedMarker(existing)) {
+        // RFC-0081/RFC-1153: restrictive-marker file is fully generator-owned —
+        // upgrade it to the editable boundary contract (fresh render + marker).
+        merged = mergeEditableGenerated(content, null, "AGENTS.md");
+      } else {
+        skipped.push("AGENTS.md (unmapped-customization)");
+        if (outputFormat === "pretty") {
+          logger.warn(
+            "AGENTS.md has custom content but no resolvable boundary — skipping root file (unmapped-customization). Add <!-- forge:custom --> to set the boundary.",
+          );
+        }
+      }
+    }
+    if (merged !== null) {
+      await writeFileIfChanged(agentsMdPath, merged, fio);
+      generated.push("AGENTS.md");
+      if (outputFormat === "pretty") {
+        logger.success(`Generated ${path.relative(workspaceRoot, agentsMdPath)}`);
+      }
     }
   }
 
@@ -410,7 +451,7 @@ export async function runAgentsGenerate(
       // forge root not resolvable — fallback to hardcoded detection
     }
   }
-  const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes);
+  const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes, fio);
   generated.push(...nestedResult.generated);
   skipped.push(...nestedResult.skipped);
   Object.assign(renderedFiles, nestedResult.renderedFiles);