@warpgogol/forge 5.3.4 → 6.2.0

package/os/spec/live-spec-idempotency.pbt.test.ts

@@ -0,0 +1,222 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Property-based test for the spec.live.merge idempotency law (RFC-1230,
+AC-10 / DNA-101): merge(merge(spec, rfc), rfc) ≡ merge(spec, rfc) — a second
+merge of the same RFC is already-merged and byte-identical — and
+force∘force ≡ force — a forced re-merge stabilizes after one application.</purpose>
+<non-goals>
+  <item>Do not test rebuild or validate — covered by their own test files.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1230: initial PBT for the merge idempotency law.</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>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, test, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import fc from "fast-check";
+import { runSpecLiveMerge } from "./live-spec-merge.ts";
+import { escapeRegex } from "./live-spec-shared.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",
+  };
+}
+
+// Heading text: single-line, non-empty after trim, never carrying an (RFC-XXXX)
+// marker — namespaceHeadings leaves already-marked headings alone, which would
+// make sections belong to a different RFC id.
+const headingTextArb = fc
+  .string({
+    unit: fc.constantFrom(
+      ..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -_".split(""),
+    ),
+    minLength: 1,
+    maxLength: 40,
+  })
+  .filter((s) => s.trim().length > 0 && !/\(RFC-\d{4}\)/.test(s));
+
+const bodyLineArb = fc
+  .string({
+    unit: fc.constantFrom(
+      ..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -_.,;:!?()[]".split(""),
+    ),
+    maxLength: 80,
+  })
+  .filter((s) => !s.trimStart().startsWith("#"));
+
+const sectionArb = fc.record({
+  heading: headingTextArb,
+  body: fc.array(bodyLineArb, { maxLength: 6 }).map((lines) => lines.join("\n")),
+});
+
+function rfcSource(id: string, design: string): string {
+  return `---
+id: ${id}
+title: "PBT 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: true
+packagesImpacted:
+  - packages/forge
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# ${id}
+
+## Design
+
+${design}
+
+## Rollout
+
+Done.
+`;
+}
+
+describe("spec.live.merge idempotency law (AC-10)", () => {
+  test("merge(merge(spec, rfc), rfc) ≡ merge(spec, rfc)", async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.array(sectionArb, { minLength: 1, maxLength: 6 }),
+        fc.boolean(), // seed a spec via a different RFC first → exercise the existing-spec path
+        async (sections, seedWithOther) => {
+          const design = sections
+            .map((s) => `### ${s.heading}\n\n${s.body}`)
+            .join("\n\n");
+
+          const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-pbt-"));
+          try {
+            const rfcDir = path.join(tmpDir, "docs/rfcs");
+            await fs.mkdir(rfcDir, { recursive: true });
+            await fs.writeFile(
+              path.join(rfcDir, "rfc-9001-pbt.md"),
+              rfcSource("RFC-9001", design),
+            );
+            if (seedWithOther) {
+              await fs.writeFile(
+                path.join(rfcDir, "rfc-9002-seed.md"),
+                rfcSource("RFC-9002", "### Seed\n\nseed body."),
+              );
+              await runSpecLiveMerge(
+                { argv: [], flags: { id: "RFC-9002" } },
+                makeContext(tmpDir),
+              );
+            }
+
+            const mergeInput = { argv: [], flags: { id: "RFC-9001" } };
+            const first = await runSpecLiveMerge(mergeInput, makeContext(tmpDir));
+            const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+            const afterFirst = await fs.readFile(specFile, "utf-8");
+
+            const second = await runSpecLiveMerge(mergeInput, makeContext(tmpDir));
+            const afterSecond = await fs.readFile(specFile, "utf-8");
+
+            expect(first.exitCode).toBe(0);
+            expect(second.exitCode).toBe(0);
+            expect(second.data?.operation).toBe("already-merged");
+            expect(second.data?.deltas).toEqual([]);
+            expect(afterSecond).toBe(afterFirst);
+          } finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+          }
+        },
+      ),
+      { numRuns: 30 },
+    );
+  });
+
+  test("force(force(spec)) ≡ force(spec) — forced re-merge stabilizes", async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.array(sectionArb, { minLength: 1, maxLength: 6 }),
+        async (sections) => {
+          const design = sections
+            .map((s) => `### ${s.heading}\n\n${s.body}`)
+            .join("\n\n");
+
+          const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-pbt-"));
+          try {
+            const rfcDir = path.join(tmpDir, "docs/rfcs");
+            await fs.mkdir(rfcDir, { recursive: true });
+            await fs.writeFile(
+              path.join(rfcDir, "rfc-9001-pbt.md"),
+              rfcSource("RFC-9001", design),
+            );
+
+            await runSpecLiveMerge(
+              { argv: [], flags: { id: "RFC-9001" } },
+              makeContext(tmpDir),
+            );
+            const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+
+            const forceInput = {
+              argv: [],
+              flags: { id: "RFC-9001", force: true },
+            };
+            const force1 = await runSpecLiveMerge(forceInput, makeContext(tmpDir));
+            const afterForce1 = await fs.readFile(specFile, "utf-8");
+
+            const force2 = await runSpecLiveMerge(forceInput, makeContext(tmpDir));
+            const afterForce2 = await fs.readFile(specFile, "utf-8");
+
+            expect(force1.exitCode).toBe(0);
+            expect(force2.exitCode).toBe(0);
+            expect(force1.data?.operation).toBe("modified");
+            expect(force2.data?.operation).toBe("modified");
+            // Exactly one namespaced section set per heading and one history entry.
+            expect(afterForce2).toBe(afterForce1);
+            // Each namespaced heading occurs exactly as often as the RFC's
+            // design repeats that heading text (headings are trimmed on parse).
+            // Count heading lines — substring matching would let "a (RFC-9001)"
+            // match inside "aa (RFC-9001)".
+            for (const s of sections) {
+              const namespaced = `${s.heading.trim()} (RFC-9001)`;
+              const occurrences = (afterForce2.match(
+                new RegExp(`^### ${escapeRegex(namespaced)}$`, "gm"),
+              ) ?? []).length;
+              const expected = sections.filter(
+                (x) => x.heading.trim() === s.heading.trim(),
+              ).length;
+              expect(occurrences).toBe(expected);
+            }
+          } finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+          }
+        },
+      ),
+      { numRuns: 30 },
+    );
+  });
+});

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

@@ -7,6 +7,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0711: initial unit tests for spec.live.list and spec.live.validate.</item>
+  <item>RFC-1234: zero-violations fixture now produced by runSpecLiveMerge so the spec is byte-canonical under the V-LS-09 replay check; RFC-9001 fixture gained liveSpec: true.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -17,6 +18,7 @@ import os from "node:os";
 import { runSpecLiveList } from "./live-spec-list.ts";
 import { runSpecLiveShow } from "./live-spec-show.ts";
 import { runSpecLiveValidate } from "./live-spec-validate.ts";
+import { runSpecLiveMerge } from "./live-spec-merge.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
 
 function makeContext(workspaceRoot: string): ForgeRuntimeContext {
@@ -157,7 +159,9 @@ createdAt: 2026-08-06
 updatedAt: 2026-08-06
 implementedAt: 2026-08-06
 versionBump: patch
-packagesImpacted: []
+liveSpec: true
+packagesImpacted:
+  - packages/forge
 commands:
   proposed: []
   added: []
@@ -184,13 +188,13 @@ Content.
   });
 
   it("passes with zero violations on a valid living spec", async () => {
-    await fs.writeFile(
-      path.join(tmpDir, "docs/specs/live/forge.md"),
-      VALID_SPEC,
-    );
+    // V-LS-09 (RFC-1234) byte-compares against the canonical replay — the
+    // fixture spec is produced by the real merge writer, not hand-written.
+    const ctx = makeContext(tmpDir);
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, ctx);
 
     const input: ForgeCommandInput = { argv: [], flags: {} };
-    const result = await runSpecLiveValidate(input, makeContext(tmpDir));
+    const result = await runSpecLiveValidate(input, ctx);
 
     expect(result.exitCode).toBe(0);
     expect(result.data?.status).toBe("pass");

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

@@ -1,13 +1,17 @@
 /*
 <MODULE_CONTRACT>
 <purpose>Unit tests for spec.live.merge handler — covers creation, modification,
-conflict detection, dry-run, no-op cases (RFC-0711).</purpose>
+idempotent already-merged skip, --force re-merge, conflict detection, dry-run,
+no-op cases (RFC-0711, RFC-1230).</purpose>
 <non-goals>
   <item>Do not test docs.archive integration — covered separately.</item>
+  <item>Do not test spec.live.rebuild — covered by live-spec-rebuild.test.ts.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0711: initial unit tests for spec.live.merge.</item>
+  <item>RFC-1230: updated re-merge expectations to already-merged; added --force surgical re-merge and byte-identity cases.</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>
 </CHANGE_SUMMARY>
 */
 
@@ -201,6 +205,57 @@ Different types from RFC-9004.
 Some rollout.
 `;
 
+const SAMPLE_RFC_FENCED = `---
+id: RFC-9005
+title: "RFC with fenced heading-like lines"
+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: true
+packagesImpacted:
+  - packages/forge
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# RFC-9005: RFC with fenced heading-like lines
+
+## Design
+
+### CLI surface
+
+\`\`\`sh
+### this is a shell comment, not a heading
+werkstatt run spec.live.merge --id RFC-9005
+\`\`\`
+
+### TypeScript contracts
+
+~~~text
+### markdown-looking line inside tilde fence
+~~~
+
+Real text.
+
+## Rollout
+
+Done.
+`;
+
 async function setupWorkspace(): Promise<string> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-test-"));
   const rfcDir = path.join(tmpDir, "docs/rfcs");
@@ -209,6 +264,7 @@ async function setupWorkspace(): Promise<string> {
   await fs.writeFile(path.join(rfcDir, "rfc-9002-test-rfc-without-livespec.md"), SAMPLE_RFC_NO_LIVE_SPEC);
   await fs.writeFile(path.join(rfcDir, "rfc-9003-rejected-rfc-with-livespec.md"), SAMPLE_RFC_REJECTED);
   await fs.writeFile(path.join(rfcDir, "rfc-9004-second-rfc-with-same-headings.md"), SAMPLE_RFC_9004);
+  await fs.writeFile(path.join(rfcDir, "rfc-9005-rfc-with-fenced-heading-like-lines.md"), SAMPLE_RFC_FENCED);
   return tmpDir;
 }
 
@@ -243,18 +299,61 @@ describe("spec.live.merge", () => {
     expect(content).toContain("lastMergedRfc: RFC-9001");
   });
 
-  it("modifies an existing living spec", async () => {
+  it("skips an already-merged RFC and leaves the spec byte-identical (AC-1)", async () => {
     // First merge creates the spec
     const input1: ForgeCommandInput = { argv: [], flags: { id: "RFC-9001" } };
     await runSpecLiveMerge(input1, makeContext(tmpDir));
 
-    // Second merge modifies it
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+    const before = await fs.readFile(specFile, "utf-8");
+
+    // Second merge of the same RFC is a no-op
     const input2: ForgeCommandInput = { argv: [], flags: { id: "RFC-9001" } };
     const result = await runSpecLiveMerge(input2, makeContext(tmpDir));
 
     expect(result.exitCode).toBe(0);
-    expect(result.data?.operation).toBe("modified");
+    expect(result.data?.operation).toBe("already-merged");
     expect(result.data?.domain).toBe("forge");
+    expect(result.data?.deltas).toEqual([]);
+
+    const after = await fs.readFile(specFile, "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it("re-merges an already-merged RFC surgically with --force (AC-2)", async () => {
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9004" } }, makeContext(tmpDir));
+
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+
+    // Simulate prior corruption: a duplicated RFC-9001 section + history entry.
+    const corrupted = (await fs.readFile(specFile, "utf-8"))
+      .replace(
+        "### TypeScript contracts (RFC-9001)\n\nSome types.",
+        "### TypeScript contracts (RFC-9001)\n\nSome types.\n\n### CLI surface (RFC-9001)\n\nDuplicated stale section.",
+      )
+      .replace(
+        "  - rfc: RFC-9004",
+        "  - rfc: RFC-9001\n    mergedAt: 2026-08-07\n    operation: modified\n  - rfc: RFC-9004",
+      );
+    await fs.writeFile(specFile, corrupted);
+
+    const result = await runSpecLiveMerge(
+      { argv: [], flags: { id: "RFC-9001", force: true } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.operation).toBe("modified");
+
+    const after = await fs.readFile(specFile, "utf-8");
+    // Exactly one section set for RFC-9001 remains; stale duplicate is gone.
+    expect(after.match(/\(RFC-9001\)/g)?.length).toBe(3);
+    expect(after).not.toContain("Duplicated stale section.");
+    // Exactly one history entry for RFC-9001.
+    expect(after.match(/rfc: RFC-9001/g)?.length).toBe(1);
+    // RFC-9004 sections untouched.
+    expect(after).toContain("CLI surface (RFC-9004)");
   });
 
   it("skips RFCs without liveSpec field (no-op)", async () => {
@@ -323,15 +422,96 @@ describe("spec.live.merge", () => {
     expect(content).toContain("CLI surface (RFC-9004)");
   });
 
-  it("re-merges namespaced headings without conflicts on subsequent docs.archive runs", async () => {
+  it("reports already-merged on re-run instead of duplicating sections (RFC-1230)", async () => {
     // Initial merges
     await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
     await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9004" } }, makeContext(tmpDir));
 
-    // Re-merge RFC-9001 (simulates docs.archive re-running all merges)
+    // Re-merge RFC-9001 (simulates a repeated caller) — idempotent no-op
     const result = await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
 
     expect(result.exitCode).toBe(0);
-    expect(result.data?.conflicts.length).toBe(0);
+    expect(result.data?.operation).toBe("already-merged");
+    expect(result.data?.deltas).toEqual([]);
+  });
+
+  it("writes nothing under --dry-run on an existing spec (AC-9)", async () => {
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+    const before = await fs.readFile(specFile, "utf-8");
+
+    const ctx = makeContext(tmpDir);
+    ctx.dryRun = true;
+    const result = await runSpecLiveMerge(
+      { argv: [], flags: { id: "RFC-9001", force: true, "dry-run": true } },
+      ctx,
+    );
+
+    expect(result.data?.dryRun).toBe(true);
+    const after = await fs.readFile(specFile, "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it("does not namespace-rewrite ### lines inside ``` and ~~~ fences (RFC-1232 AC-1/AC-5)", async () => {
+    const result = await runSpecLiveMerge(
+      { argv: [], flags: { id: "RFC-9005" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+
+    const content = await fs.readFile(path.join(tmpDir, "docs/specs/live/forge.md"), "utf-8");
+    // Fence-interior ### lines pass through verbatim — no namespacing suffix.
+    expect(content).toContain("### this is a shell comment, not a heading\n");
+    expect(content).toContain("### markdown-looking line inside tilde fence\n");
+    expect(content).not.toContain("shell comment, not a heading (RFC-9005)");
+    expect(content).not.toContain("inside tilde fence (RFC-9005)");
+    // Real headings still get namespaced.
+    expect(content).toContain("### CLI surface (RFC-9005)");
+    expect(content).toContain("### TypeScript contracts (RFC-9005)");
+  });
+
+  it("--force re-merge preserves fence-interior ### (RFC-NNNN) lines outside the RFC's sections", async () => {
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9005" } }, makeContext(tmpDir));
+
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+    const before = await fs.readFile(specFile, "utf-8");
+    // A fenced block carrying a phantom namespaced heading inside Overview —
+    // the pre-RFC-1232 scanner would slice from this line to the next real
+    // heading, deleting Overview tail content and leaving a stray fence.
+    await fs.writeFile(
+      specFile,
+      before.replace(
+        "## Overview\n",
+        "## Overview\n\n```md\n### Phantom (RFC-9005)\n```\n",
+      ),
+    );
+
+    const result = await runSpecLiveMerge(
+      { argv: [], flags: { id: "RFC-9005", force: true } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    const after = await fs.readFile(specFile, "utf-8");
+    expect(after).toContain("### Phantom (RFC-9005)");
+    expect(after.match(/### CLI surface \(RFC-9005\)/g)?.length).toBe(1);
+    expect(after.match(/### TypeScript contracts \(RFC-9005\)/g)?.length).toBe(1);
+  });
+
+  it("fails instead of overwriting a spec with unparseable frontmatter", async () => {
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+    await fs.mkdir(path.dirname(specFile), { recursive: true });
+    const corrupt = "# Living Spec: forge\n\nno frontmatter — orphaned content\n";
+    await fs.writeFile(specFile, corrupt);
+
+    const result = await runSpecLiveMerge(
+      { argv: [], flags: { id: "RFC-9001" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(1);
+    expect(result.summary).toContain("valid frontmatter");
+    expect(await fs.readFile(specFile, "utf-8")).toBe(corrupt);
   });
 });