@warpgogol/forge 5.3.4 → 6.2.0

package/os/spec/live-spec-validate.test.ts

@@ -0,0 +1,317 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for spec.live.validate — V-LS-06 (duplicate namespaced
+headings), V-LS-07 (duplicate history RFCs), V-LS-08 (archive coverage) on
+synthetic living-spec fixtures (RFC-1230).</purpose>
+<non-goals>
+  <item>Do not re-test V-LS-01..05 semantics beyond fixtures needed for isolation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1230: initial unit tests for V-LS-06/07/08.</item>
+  <item>RFC-1230: review findings — scoped droppedSections to namespaced headings, warn on unreadable spec, fail-fast merge on corrupt frontmatter, CHANGE_SUMMARY dedupe</item>
+  <item>RFC-1234: V-LS-09 drift fixtures (AC-1..3); clean/fence fixtures now produced by runSpecLiveMerge so spec bytes are canonical under replay comparison.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { runSpecLiveValidate } from "./live-spec-validate.ts";
+import { runSpecLiveMerge } from "./live-spec-merge.ts";
+import type { ForgeRuntimeContext } from "../../src/types.ts";
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      section: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      success: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+function archivedRfc(id: string, liveSpec = true, design = "### Section\n\nBody.") {
+  return `---
+id: ${id}
+title: "Archived RFC ${id}"
+status: implemented
+kind: architecture
+scope: workspace
+owners:
+  - architecture
+reviewers:
+  - human:test
+createdAt: 2026-08-06
+updatedAt: 2026-08-06
+implementedAt: 2026-08-06
+versionBump: patch
+${liveSpec ? "liveSpec: true\n" : ""}packagesImpacted:
+  - packages/forge
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# ${id}
+
+## Design
+
+${design}
+`;
+}
+
+function specFixture(opts: {
+  domain: string;
+  historyEntries: string;
+  lastMergedRfc: string;
+  sections: string;
+}) {
+  return `---
+domain: ${opts.domain}
+title: "Living Spec: ${opts.domain}"
+lastMergedRfc: ${opts.lastMergedRfc}
+updatedAt: 2026-08-06
+createdAt: 2026-08-06
+history:
+${opts.historyEntries}---
+
+# Living Spec: ${opts.domain}
+
+## Overview
+
+${opts.sections}
+`;
+}
+
+const ENTRY_9001 = "  - rfc: RFC-9001\n    mergedAt: 2026-08-06\n    operation: created\n";
+
+async function setupWorkspace(): Promise<string> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-validate-"));
+  const rfcDir = path.join(tmpDir, "docs/rfcs/archive/implemented");
+  await fs.mkdir(rfcDir, { recursive: true });
+  await fs.writeFile(path.join(rfcDir, "rfc-9001-merged.md"), archivedRfc("RFC-9001"));
+  await fs.writeFile(path.join(rfcDir, "rfc-9002-unmerged.md"), archivedRfc("RFC-9002"));
+  await fs.mkdir(path.join(tmpDir, "docs/specs/live"), { recursive: true });
+  return tmpDir;
+}
+
+describe("spec.live.validate (V-LS-06/07/08)", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await setupWorkspace();
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("emits V-LS-06 per extra occurrence of a duplicated namespaced heading", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/specs/live/forge.md"),
+      specFixture({
+        domain: "forge",
+        lastMergedRfc: "RFC-9001",
+        historyEntries: ENTRY_9001,
+        sections: [
+          "### Alpha (RFC-9001)\n\na.",
+          "### Alpha (RFC-9001)\n\nstale.",
+          "### Alpha (RFC-9001)\n\nstalest.",
+        ].join("\n\n"),
+      }),
+    );
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v6 = result.data?.violations.filter((v) => v.rule === "V-LS-06") ?? [];
+    // 3 occurrences → 2 "extra occurrence" diagnostics.
+    expect(v6.length).toBe(2);
+    expect(v6[0]?.message).toContain("Alpha (RFC-9001)");
+    expect(v6[0]?.message).toContain("spec.live.rebuild");
+  });
+
+  it("emits V-LS-07 once per duplicated history rfc", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/specs/live/forge.md"),
+      specFixture({
+        domain: "forge",
+        lastMergedRfc: "RFC-9001",
+        historyEntries:
+          "  - rfc: RFC-9001\n    mergedAt: 2026-08-06\n    operation: created\n" +
+          "  - rfc: RFC-9001\n    mergedAt: 2026-08-07\n    operation: modified\n",
+        sections: "### Alpha (RFC-9001)\n\na.",
+      }),
+    );
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v7 = result.data?.violations.filter((v) => v.rule === "V-LS-07") ?? [];
+    expect(v7.length).toBe(1);
+    expect(v7[0]?.message).toContain("RFC-9001");
+    expect(v7[0]?.message).toContain("spec.live.rebuild");
+  });
+
+  it("emits V-LS-08 when an archived implemented liveSpec RFC is absent from history", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/specs/live/forge.md"),
+      specFixture({
+        domain: "forge",
+        lastMergedRfc: "RFC-9001",
+        historyEntries: ENTRY_9001,
+        sections: "### Alpha (RFC-9001)\n\na.",
+      }),
+    );
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v8 = result.data?.violations.filter((v) => v.rule === "V-LS-08") ?? [];
+    // RFC-9002 is archived+implemented+liveSpec but never merged into forge.md.
+    expect(v8.length).toBe(1);
+    expect(v8[0]?.message).toContain("RFC-9002");
+    expect(v8[0]?.message).toContain("spec.live.merge --id RFC-9002");
+  });
+
+  it("emits V-LS-08 when the domain spec file is missing entirely", async () => {
+    // No spec file at all — both RFCs lack coverage for domain "forge".
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v8 = result.data?.violations.filter((v) => v.rule === "V-LS-08") ?? [];
+    expect(v8.length).toBe(2);
+    expect(v8[0]?.message).toContain("does not exist");
+  });
+
+  it("does not emit V-LS-06 for ### (RFC-NNNN) lines inside fenced blocks (RFC-1232 AC-2)", async () => {
+    // The spec is produced by the real merge writer so V-LS-09 sees a
+    // byte-canonical file — fence-interior ### lines come from RFC-9001's
+    // Design and replay identically.
+    const fencedDesign = [
+      "### Alpha",
+      "",
+      "a.",
+      "",
+      "```md",
+      "### Alpha (RFC-9001)",
+      "### Alpha (RFC-9001)",
+      "```",
+      "",
+      "~~~",
+      "### Beta (RFC-9002)",
+      "~~~",
+    ].join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9001-merged.md"),
+      archivedRfc("RFC-9001", true, fencedDesign),
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9002-unmerged.md"),
+      archivedRfc("RFC-9002", true, "### Beta\n\nb."),
+    );
+
+    const ctx = makeContext(tmpDir);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, ctx);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9002" } }, ctx);
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, ctx);
+    const v6 = result.data?.violations.filter((v) => v.rule === "V-LS-06") ?? [];
+    // Fence-interior occurrences do not count — both real headings are unique.
+    expect(v6).toEqual([]);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("produces no V-LS-06/07/08 on a clean spec", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9001-merged.md"),
+      archivedRfc("RFC-9001", true, "### Alpha\n\na."),
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9002-unmerged.md"),
+      archivedRfc("RFC-9002", true, "### Beta\n\nb."),
+    );
+    const ctx = makeContext(tmpDir);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, ctx);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9002" } }, ctx);
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, ctx);
+    const dupOrGap = result.data?.violations.filter((v) =>
+      ["V-LS-06", "V-LS-07", "V-LS-08"].includes(v.rule),
+    ) ?? [];
+    expect(dupOrGap).toEqual([]);
+    expect(result.exitCode).toBe(0);
+  });
+});
+
+describe("spec.live.validate (V-LS-09 content drift — RFC-1234)", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await setupWorkspace();
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9001-merged.md"),
+      archivedRfc("RFC-9001", true, "### Alpha\n\na."),
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9002-unmerged.md"),
+      archivedRfc("RFC-9002", true, "### Beta\n\nb."),
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function mergedSpec(): Promise<string> {
+    const ctx = makeContext(tmpDir);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, ctx);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9002" } }, ctx);
+    return path.join(tmpDir, "docs/specs/live/forge.md");
+  }
+
+  it("AC-1: emits a V-LS-09 error naming the domain and repair path on drift", async () => {
+    const specPath = await mergedSpec();
+    await fs.appendFile(specPath, "\nStale hand edit.\n");
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v9 = result.data?.violations.filter((v) => v.rule === "V-LS-09") ?? [];
+    expect(v9.length).toBe(1);
+    expect(v9[0]?.severity).toBe("error");
+    expect(v9[0]?.message).toContain("forge.md");
+    expect(v9[0]?.message).toContain("spec.live.rebuild --domain forge");
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("AC-2: emits no V-LS-09 when the spec matches its replay", async () => {
+    await mergedSpec();
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v9 = result.data?.violations.filter((v) => v.rule === "V-LS-09") ?? [];
+    expect(v9).toEqual([]);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("AC-3: warns on an unreadable history RFC and still runs the drift comparison", async () => {
+    await mergedSpec();
+    // Deleting the RFC file leaves history[] pointing at an unreadable id —
+    // replay skips it, so the spec's RFC-9002 sections are unreproducible.
+    await fs.rm(path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-9002-unmerged.md"));
+
+    const result = await runSpecLiveValidate({ argv: [], flags: {} }, makeContext(tmpDir));
+    const v9warn = result.data?.violations.filter(
+      (v) => v.rule === "V-LS-09" && v.severity === "warning",
+    ) ?? [];
+    expect(v9warn.length).toBe(1);
+    expect(v9warn[0]?.message).toContain("RFC-9002");
+    // The drift comparison still ran — the un-replayable body diverges.
+    const v9err = result.data?.violations.filter(
+      (v) => v.rule === "V-LS-09" && v.severity === "error",
+    ) ?? [];
+    expect(v9err.length).toBe(1);
+    expect(result.exitCode).toBe(1);
+  });
+});

package/os/spec/live-spec-validate.ts

@@ -1,13 +1,18 @@
 /*
 <MODULE_CONTRACT>
 <purpose>spec.live.validate handler — validates all living specs in docs/specs/live/
-with rules V-LS-01..05 (RFC-0711).</purpose>
+with rules V-LS-01..09 (RFC-0711, RFC-1230, RFC-1234). Detection layer only — repair routes
+to spec.live.rebuild (V-LS-06/07/09) or spec.live.merge --id (V-LS-08), never hand-edits.</purpose>
 <non-goals>
   <item>Do not merge or list — use spec.live.merge / spec.live.list.</item>
+  <item>Do not repair — validators are read-only; spec.live.rebuild is the repair path.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0711: initial spec.live.validate handler with V-LS-01..05 rules.</item>
+  <item>RFC-1230: added V-LS-06 (duplicate namespaced headings), V-LS-07 (duplicate history RFCs), V-LS-08 (archive coverage — implemented liveSpec RFC absent from spec history).</item>
+  <item>RFC-1230: review findings — scoped droppedSections to namespaced headings, warn on unreadable spec, fail-fast merge on corrupt frontmatter, CHANGE_SUMMARY dedupe</item>
+  <item>RFC-1234: V-LS-09 content-drift rule — replays each spec's deduplicated history via the extracted projectLiveSpec core and compares committed bytes modulo updatedAt; LivingSpecViolation gains a severity channel (error findings drive the exit code, warning findings report unreadable history RFCs without failing the run).</item>
 </CHANGE_SUMMARY>
 */
 
@@ -27,6 +32,8 @@ import type {
   SpecLiveValidateResult,
   LivingSpecHistoryEntry,
 } from "./live-spec-types.ts";
+import { deriveDomain, parseHeadings } from "./live-spec-shared.ts";
+import { projectLiveSpec } from "./live-spec-rebuild.ts";
 
 const LIVE_SPECS_DIR = "docs/specs/live";
 
@@ -44,8 +51,10 @@ export async function runSpecLiveValidate(
   let specsChecked = 0;
 
   const domains = new Set<string>();
+  const specsByDomain = new Map<string, { file: string; historyRfcIds: Set<string> }>();
 
   const archivedRfcIds = new Set<string>();
+  const archivedImplementedLiveSpecRfcs: Array<{ id: string; domain: string }> = [];
   const rfcFiles = await listRfcFiles(rfcDir);
   for (const file of rfcFiles) {
     const parsed = await readAndParseRfc(rfcDir, file);
@@ -55,6 +64,14 @@ export async function runSpecLiveValidate(
       if (id && (status === "implemented" || status === "rejected" || status === "superseded")) {
         archivedRfcIds.add(id);
       }
+      // V-LS-08 tracks only RFCs physically under archive/implemented/ — an
+      // implemented-but-not-yet-archived RFC must not fire a false positive.
+      if (id && file.startsWith("archive/implemented/") && parsed.parsed.frontmatter["liveSpec"]) {
+        const liveSpecDomain = deriveDomain(parsed.parsed.frontmatter);
+        if (liveSpecDomain) {
+          archivedImplementedLiveSpecRfcs.push({ id, domain: liveSpecDomain });
+        }
+      }
     }
   }
 
@@ -78,6 +95,8 @@ export async function runSpecLiveValidate(
   const files = (await fs.readdir(liveSpecsDir)).map((e) => e.name);
   const specFiles = files.filter((f) => f.endsWith(".md") && f !== "README.md");
 
+  const parsedSpecPaths: Array<{ file: string; filePath: string; domain: string }> = [];
+
   for (const file of specFiles) {
     specsChecked++;
     const filePath = path.join(liveSpecsDir, file);
@@ -119,6 +138,7 @@ export async function runSpecLiveValidate(
     }
 
     const history = Array.isArray(fm["history"]) ? (fm["history"] as LivingSpecHistoryEntry[]) : [];
+    const historyRfcIds = new Set<string>();
     for (const entry of history) {
       if (entry.rfc && !archivedRfcIds.has(entry.rfc)) {
         violations.push({
@@ -127,6 +147,44 @@ export async function runSpecLiveValidate(
           domain,
         });
       }
+      if (entry.rfc) historyRfcIds.add(entry.rfc);
+    }
+
+    // V-LS-06: duplicate RFC-namespaced headings (###+ ending in ` (RFC-XXXX)`)
+    // — one diagnostic per extra occurrence. Full namespaced text is compared,
+    // so distinct RFCs never collide.
+    const headingCounts = new Map<string, number>();
+    for (const h of parseHeadings(content.slice(match[0].length))) {
+      if (!/\(RFC-\d{4}\)$/.test(h.text)) continue;
+      const seen = (headingCounts.get(h.text) ?? 0) + 1;
+      headingCounts.set(h.text, seen);
+      if (seen > 1) {
+        violations.push({
+          rule: "V-LS-06",
+          message: `${file}: duplicate section "${h.text}" (occurrence ${seen}) — repair via spec.live.rebuild`,
+          domain,
+        });
+      }
+    }
+
+    // V-LS-07: duplicate history[].rfc — one diagnostic per duplicated id.
+    const rfcCounts = new Map<string, number>();
+    for (const entry of history) {
+      if (!entry.rfc) continue;
+      rfcCounts.set(entry.rfc, (rfcCounts.get(entry.rfc) ?? 0) + 1);
+    }
+    for (const [rfcId, count] of rfcCounts) {
+      if (count > 1) {
+        violations.push({
+          rule: "V-LS-07",
+          message: `${file}: history contains ${count} entries for "${rfcId}" — repair via spec.live.rebuild`,
+          domain,
+        });
+      }
+    }
+
+    if (domain) {
+      specsByDomain.set(domain, { file, historyRfcIds });
     }
 
     if (domain) {
@@ -138,10 +196,56 @@ export async function runSpecLiveValidate(
         });
       }
       domains.add(domain);
+      parsedSpecPaths.push({ file, filePath, domain });
+    }
+  }
+
+  // V-LS-08 (coverage): every archived implemented RFC carrying liveSpec must
+  // appear in the history[] of its domain's living spec — also fires when that
+  // domain's spec file does not exist. Repair: spec.live.merge --id <rfc>.
+  for (const { id, domain } of archivedImplementedLiveSpecRfcs) {
+    const spec = specsByDomain.get(domain);
+    if (!spec) {
+      violations.push({
+        rule: "V-LS-08",
+        message: `${id}: living spec for domain "${domain}" does not exist — repair via spec.live.merge --id ${id}`,
+        domain,
+      });
+    } else if (!spec.historyRfcIds.has(id)) {
+      violations.push({
+        rule: "V-LS-08",
+        message: `${spec.file}: archived RFC "${id}" (liveSpec) is absent from history[] — repair via spec.live.merge --id ${id}`,
+        domain,
+      });
+    }
+  }
+
+  // V-LS-09 (content drift): replay each spec's deduplicated history via the
+  // same projection core rebuild uses, compare against committed bytes modulo
+  // updatedAt (RFC-1234 — DNA-58 closure for living specs). Specs that failed
+  // frontmatter parse are already fail-closed via V-LS-01 and skip here.
+  for (const { file, filePath, domain } of parsedSpecPaths) {
+    const proj = await projectLiveSpec(filePath, domain, rfcFiles, rfcDir);
+    if (proj.kind !== "projected") continue;
+    for (const rfcId of proj.unreadableRfcs) {
+      violations.push({
+        rule: "V-LS-09",
+        severity: "warning",
+        message: `${file}: history entry "${rfcId}" unreadable, not implemented, or lacks ## Design — excluded from replay`,
+        domain,
+      });
+    }
+    if (proj.projection !== proj.content) {
+      violations.push({
+        rule: "V-LS-09",
+        severity: "error",
+        message: `${file}: spec content diverges from replay of history[] — repair via spec.live.rebuild --domain ${domain}`,
+        domain,
+      });
     }
   }
 
-  const hasFailures = violations.length > 0;
+  const hasFailures = violations.some((v) => v.severity !== "warning");
   const result: SpecLiveValidateResult = {
     command: "spec.live.validate",
     status: hasFailures ? "fail" : "pass",

package/os/spec/spec-materialize.test.ts

@@ -0,0 +1,192 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Prove consumer-aware dependsOn filtering in spec.materialize (RFC-1240): foreign-owned nodes are excluded from the front and satisfy dependents; same-consumer and undeclared-identity nodes keep local gating.</purpose>
+<non-goals><item>Do not duplicate spec.validate rule coverage — that lives in spec-validate.test.ts.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-1240: initial coverage — foreign dep satisfaction, same-consumer gating, identity-missing skip, --consumer flag precedence, legacy snapshot compatibility.</item></CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ForgeRuntimeContext } from "../../src/types.ts";
+import { runSpecMaterialize } from "./spec-materialize.ts";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+async function makeWorkspace(opts: { consumer?: string } = {}): Promise<string> {
+  const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-materialize-"));
+  roots.push(workspaceRoot);
+  await fs.mkdir(path.join(workspaceRoot, "docs/rfcs"), { recursive: true });
+  if (opts.consumer !== undefined) {
+    await fs.writeFile(
+      path.join(workspaceRoot, "forge.yaml"),
+      `schema: forge/config@1\nproject:\n  name: test-ws\n  consumer: ${opts.consumer}\npaths: {}\n`,
+    );
+  }
+  return workspaceRoot;
+}
+
+async function writeSpec(workspaceRoot: string, id: string, rfcs: string): Promise<void> {
+  const specDir = path.join(workspaceRoot, "docs/specs", id);
+  await fs.mkdir(specDir, { recursive: true });
+  await fs.writeFile(path.join(specDir, "forge-spec.yaml"), `schema: forge/spec@1
+id: ${id}
+title: ${id}
+version: 1.0.0
+status: accepted
+reviewers: []
+sourceNote: test fixture
+vendoredAt: 2026-10-09
+documents: {}
+decisions: []
+rfcs:
+${rfcs}waves:
+  - id: 1
+    name: Test
+    goal: Exercise consumer filtering
+`);
+}
+
+const MULTI_SPEC = `  - id: V02
+    title: Consumer scoped node
+    dependsOn: []
+    wave: 1
+    sources: []
+    consumers:
+      - personal-agent
+  - id: V04
+    title: Dependent node
+    dependsOn:
+      - V02
+    wave: 1
+    sources: []
+  - id: V05
+    title: Pinned node
+    dependsOn: []
+    wave: 1
+    sources: []
+    materializedAs: RFC-9001
+`;
+
+function ctx(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    dryRun: false,
+    outputFormat: "json",
+    logger: { section() {}, info() {}, warn() {}, error() {}, success() {} },
+  } as ForgeRuntimeContext;
+}
+
+describe("spec.materialize consumer filtering (RFC-1240)", () => {
+  it("treats a foreign-consumer dependency as satisfied and excludes the foreign node from the front", async () => {
+    const workspaceRoot = await makeWorkspace({ consumer: "werkstatt" });
+    await writeSpec(workspaceRoot, "multi", MULTI_SPEC);
+    const result = await runSpecMaterialize({ argv: [], flags: { spec: "multi" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(0);
+    const data = result.data as {
+      created: Array<{ node: string; rfc: string }>;
+      front: string[];
+      foreignOwned: string[];
+    };
+    expect(data.created).toHaveLength(1);
+    expect(data.created[0]!.node).toBe("V04");
+    expect(data.created[0]!.rfc).toBe("RFC-0001");
+    expect(data.foreignOwned).toEqual(["V02"]);
+    expect(data.front).toEqual([]);
+    // AC-5: pre-existing materializedAs pins survive the write-back untouched.
+    const rewritten = await fs.readFile(
+      path.join(workspaceRoot, "docs/specs/multi/forge-spec.yaml"), "utf8");
+    expect(rewritten).toContain("materializedAs: RFC-9001");
+    expect(rewritten).toContain("materializedAs: RFC-0001");
+  });
+
+  it("keeps same-consumer dependencies blocking until implemented", async () => {
+    const workspaceRoot = await makeWorkspace({ consumer: "werkstatt" });
+    await writeSpec(workspaceRoot, "same", `  - id: V02
+    title: Locally owned node
+    dependsOn: []
+    wave: 1
+    sources: []
+    consumers:
+      - werkstatt
+  - id: V04
+    title: Dependent node
+    dependsOn:
+      - V02
+    wave: 1
+    sources: []
+`);
+    const result = await runSpecMaterialize({ argv: [], flags: { spec: "same", nodes: "V04" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(1);
+    const data = result.data as { skipped: Array<{ node: string; reason: string }> };
+    expect(data.skipped).toEqual([{ node: "V04", reason: "blocked by V02" }]);
+  });
+
+  it("reports 'consumer identity not configured' when consumers are declared without a local identity", async () => {
+    const workspaceRoot = await makeWorkspace();
+    await writeSpec(workspaceRoot, "noidentity", MULTI_SPEC);
+    const result = await runSpecMaterialize({ argv: [], flags: { spec: "noidentity", nodes: "V02" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(1);
+    const data = result.data as {
+      skipped: Array<{ node: string; reason: string }>;
+      foreignOwned: string[];
+    };
+    expect(data.skipped).toEqual([{ node: "V02", reason: "consumer identity not configured" }]);
+    expect(data.foreignOwned).toEqual(["V02"]);
+  });
+
+  it("lets --consumer override forge.yaml and claims the node as locally owned", async () => {
+    const workspaceRoot = await makeWorkspace({ consumer: "werkstatt" });
+    await writeSpec(workspaceRoot, "flagwin", MULTI_SPEC);
+    const result = await runSpecMaterialize(
+      { argv: [], flags: { spec: "flagwin", consumer: "personal-agent" } },
+      ctx(workspaceRoot),
+    );
+    expect(result.exitCode).toBe(0);
+    const data = result.data as {
+      created: Array<{ node: string }>;
+      foreignOwned: string[];
+    };
+    expect(data.created.map((c) => c.node)).toEqual(["V02"]);
+    expect(data.foreignOwned).toEqual([]);
+  });
+
+  it("reports 'foreign-owned by <consumers>' when the local identity is set but not a member", async () => {
+    const workspaceRoot = await makeWorkspace({ consumer: "werkstatt" });
+    await writeSpec(workspaceRoot, "foreign", MULTI_SPEC);
+    const result = await runSpecMaterialize({ argv: [], flags: { spec: "foreign", nodes: "V02" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(1);
+    const data = result.data as { skipped: Array<{ node: string; reason: string }> };
+    expect(data.skipped).toEqual([{ node: "V02", reason: "foreign-owned by personal-agent" }]);
+  });
+
+  it("keeps consumer-free snapshots fully backward compatible", async () => {
+    const workspaceRoot = await makeWorkspace();
+    await writeSpec(workspaceRoot, "legacy", `  - id: V01
+    title: Plain node
+    dependsOn: []
+    wave: 1
+    sources: []
+  - id: V02
+    title: Dependent plain node
+    dependsOn:
+      - V01
+    wave: 1
+    sources: []
+`);
+    const result = await runSpecMaterialize({ argv: [], flags: { spec: "legacy" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(0);
+    const data = result.data as {
+      created: Array<{ node: string }>;
+      foreignOwned: string[];
+    };
+    expect(data.created.map((c) => c.node)).toEqual(["V01"]);
+    expect(data.foreignOwned).toEqual([]);
+  });
+});