@warpgogol/forge 5.2.4 → 5.3.1

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

@@ -10,7 +10,7 @@ routing table, conditional extended layer, markers, and idempotency (RFC-0548, R
 */
 
 import { test, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile, mkdir, readFile, symlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -102,11 +102,33 @@ 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-");
 });
 
+test("agents-generate populates routing table rows in consumer layout (no packages/forge)", async () => {
+  await makeForgeYaml(tempDir);
+  // Consumer install: the package lives under node_modules — skills ship inside
+  // it. A symlinked node_modules/@warpgogol/forge mimics the npm layout.
+  const consumerPkg = join(tempDir, "node_modules", "@warpgogol", "forge");
+  await mkdir(join(consumerPkg, ".."), { recursive: true });
+  await symlink(FORGE_ROOT, consumerPkg, "junction");
+
+  // forgeRoot undefined → extraction must resolve via the consumer layout.
+  const result = await runAgentsGenerate(
+    { argv: [], flags: {} },
+    { ...makeContext(tempDir), forgeRoot: undefined },
+  );
+  expect(result.exitCode).toBe(0);
+
+  const agentsMd = await readFile(join(tempDir, "AGENTS.md"), "utf8");
+  // A quoted trigger phrase appears only in routing-table rows — the Skills
+  // table contains bare skill names, so this probes extraction end-to-end.
+  expect(agentsMd).toContain('"show RFC and ADR status"');
+});
+
 test("agents-generate includes fixed policy text sections", async () => {
   await makeForgeYaml(tempDir);
   const result = await runAgentsGenerate({ argv: [], flags: {} }, makeContext(tempDir));
@@ -427,9 +449,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/cli-flags.test.ts

@@ -0,0 +1,169 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for src/cli-flags.ts — schema-driven argv-to-flags
+resolution for the standalone forge CLI (strict KERNEL-FLAG-01/02/03 and
+KERNEL-ARG-01 diagnostics, legacy heuristic path for schema-less commands).</purpose>
+<non-goals>
+  <item>Do not test bin/cli.ts dispatch — these tests cover pure functions only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial cli-flags resolution tests — covers the `forge rfc.validate --id` crash regression (value-less declared string flag must produce KERNEL-FLAG-02, not a boolean).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, expect, test } from "vitest";
+import { parseCliArgs, resolveCliFlags } from "../cli-flags.ts";
+import type { ForgeCommandDefinition, ForgeFlagSpec } from "../types.ts";
+
+function command(flags?: Record<string, ForgeFlagSpec>): ForgeCommandDefinition {
+  return {
+    name: "test.command",
+    description: "test command",
+    scope: "workspace",
+    flags,
+    execute: () => {},
+  };
+}
+
+const errorRuleIds = (diagnostics: { ruleId: string; severity: string }[]) =>
+  diagnostics.filter((d) => d.severity === "error").map((d) => d.ruleId);
+
+describe("resolveCliFlags — strict (schema-carrying) path", () => {
+  const rfcValidate = command({
+    id: { kind: "string", description: "Target a single RFC by id." },
+  });
+
+  test("value-less declared string flag errors with KERNEL-FLAG-02 instead of becoming `true`", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id"], rfcValidate);
+    expect(flags["id"]).toBeUndefined();
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+    expect(diagnostics[0]!.message).toContain('Flag "--id"');
+    expect(diagnostics[0]!.message).toContain('"test.command"');
+  });
+
+  test("value-less declared string flag before another flag still errors", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id", "--json"], rfcValidate);
+    expect(flags["id"]).toBeUndefined();
+    expect(flags["json"]).toBe(true);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+  });
+
+  test("--id <value> and --id=<value> resolve to the string", () => {
+    for (const argv of [["--id", "RFC-0609"], ["--id=RFC-0609"]]) {
+      const { flags, diagnostics } = resolveCliFlags(argv, rfcValidate);
+      expect(flags["id"]).toBe("RFC-0609");
+      expect(errorRuleIds(diagnostics)).toEqual([]);
+    }
+  });
+
+  test("repeated single-value string flag errors instead of promoting to an array", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id", "RFC-1", "--id", "RFC-2"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+    expect(diagnostics[0]!.message).toContain("single value");
+    expect(flags["id"]).toEqual(["RFC-1", "RFC-2"]);
+  });
+
+  test("unknown flag errors with KERNEL-FLAG-01 listing valid flags", () => {
+    const { diagnostics } = resolveCliFlags(["--idd"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-01"]);
+    expect(diagnostics[0]!.message).toContain("id");
+  });
+
+  test("unknown flag followed by a bare token also flags the token as positional", () => {
+    const { diagnostics } = resolveCliFlags(["--idd", "RFC-1"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-01", "KERNEL-ARG-01"]);
+  });
+
+  test("required flag missing errors with KERNEL-FLAG-03", () => {
+    const cmd = command({
+      name: { kind: "string", required: true, description: "Required name." },
+    });
+    const { diagnostics } = resolveCliFlags([], cmd);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-03"]);
+  });
+
+  test("declared default applies when flag absent", () => {
+    const cmd = command({
+      mode: { kind: "string", default: "all", description: "Mode." },
+    });
+    const { flags, diagnostics } = resolveCliFlags([], cmd);
+    expect(flags["mode"]).toBe("all");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("positional token errors with KERNEL-ARG-01", () => {
+    const { diagnostics } = resolveCliFlags(["RFC-0609"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+
+  test("tokens after -- are positional errors", () => {
+    const { diagnostics } = resolveCliFlags(["--id", "RFC-1", "--", "extra"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+
+  test("universal flags accepted on commands with empty schema", () => {
+    const { flags, diagnostics } = resolveCliFlags(
+      ["--json", "--dry-run", "--help", "--site", "x"],
+      command({}),
+    );
+    expect(flags["json"]).toBe(true);
+    expect(flags["dry-run"]).toBe(true);
+    expect(flags["help"]).toBe(true);
+    expect(flags["site"]).toBe("x");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("universal boolean does not swallow the next flag's token", () => {
+    const cmd = command({ fix: { kind: "boolean", description: "Fix." } });
+    const { flags, diagnostics } = resolveCliFlags(["--json", "--fix"], cmd);
+    expect(flags["json"]).toBe(true);
+    expect(flags["fix"]).toBe(true);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("--flag=false on a declared boolean resolves to false", () => {
+    const cmd = command({ fix: { kind: "boolean", description: "Fix." } });
+    const { flags, diagnostics } = resolveCliFlags(["--fix=false"], cmd);
+    expect(flags["fix"]).toBe(false);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("string[] flag collects repeated values", () => {
+    const cmd = command({
+      files: { kind: "string[]", description: "Files." },
+    });
+    const { flags, diagnostics } = resolveCliFlags(["--files", "a", "--files", "b"], cmd);
+    expect(flags["files"]).toEqual(["a", "b"]);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+});
+
+describe("resolveCliFlags — legacy (schema-less) path", () => {
+  const schemaLess = command(undefined);
+
+  test("unknown flags still parse heuristically", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--anything", "v"], schemaLess);
+    expect(flags["anything"]).toBe("v");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("known boolean switches do not consume the next token", () => {
+    const { flags } = resolveCliFlags(["--json", "v"], schemaLess);
+    expect(flags["json"]).toBe(true);
+  });
+
+  test("positional token errors with KERNEL-ARG-01", () => {
+    const { diagnostics } = resolveCliFlags(["positional"], schemaLess);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+});
+
+describe("parseCliArgs", () => {
+  test("--key=value and --key value forms both resolve", () => {
+    const { flags } = parseCliArgs(["--a=1", "--b", "2", "--json"]);
+    expect(flags["a"]).toBe("1");
+    expect(flags["b"]).toBe("2");
+    expect(flags["json"]).toBe(true);
+  });
+});

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