@warpgogol/forge 5.3.3 → 6.0.0

package/os/rfc/verification-refresh.test.ts

@@ -105,15 +105,44 @@ async function setupWorkspace(opts: {
   };
 }
 
-function makeContext(workspaceRoot: string) {
+function makeContext(workspaceRoot: string, overrides: Record<string, unknown> = {}) {
   return {
     workspaceRoot,
     logger: { info: () => {} },
     outputFormat: "json" as const,
     commandRegistry: undefined,
+    dryRun: false,
+    ...overrides,
   };
 }
 
+/**
+ * RFC-1237: a minimal recording-style WorkspaceIO — writes land in `writes`,
+ * never on disk. Lets tests assert which writes the handler attempted through
+ * the port without touching fs.
+ */
+function makeSpyIo() {
+  const writes: string[] = [];
+  const io = {
+    readFile: (p: string) => fs.readFile(p, "utf8"),
+    writeFile: async (p: string) => {
+      writes.push(p);
+    },
+    mkdir: async (p: string) => {
+      writes.push(`mkdir:${p}`);
+    },
+    exists: async (p: string) => {
+      try {
+        await fs.stat(p);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+  return { io, writes };
+}
+
 beforeEach(() => {
   mockRunProbe.mockReset();
   mockCaptureGitContext.mockReset();
@@ -124,6 +153,53 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+describe("rfc.verification.refresh — sweep delta report", () => {
+  test("reports recovered (fail→pass) and regressed (pass→fail) transitions", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [
+        { id: "RFC-0100", status: "implemented" },
+        { id: "RFC-0101", status: "implemented" },
+        { id: "RFC-0102", status: "implemented" },
+      ],
+      envelopes: [
+        { id: "RFC-0100", overall: "fail" },
+        { id: "RFC-0101", overall: "pass" },
+        { id: "RFC-0102", overall: "fail" },
+      ],
+    });
+
+    try {
+      // RFC-0100: fail → pass (recovered); RFC-0101: pass → fail (regressed);
+      // RFC-0102: fail → fail (still failing — not a regression).
+      mockRunProbe
+        .mockResolvedValueOnce({ probe: PROBE, ok: true, detail: "exists" })
+        .mockResolvedValueOnce({ probe: PROBE, ok: false, detail: "missing" })
+        .mockResolvedValueOnce({ probe: PROBE, ok: false, detail: "missing" });
+
+      const result = await runRfcVerificationRefresh(
+        { flags: { all: true } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
+      );
+
+      expect(result.data!.delta).toEqual({
+        recovered: ["RFC-0100"],
+        regressed: ["RFC-0101"],
+      });
+      const entries = Object.fromEntries(result.data!.refreshed.map((r) => [r.rfcId, r]));
+      expect(entries["RFC-0100"]?.previousOverall).toBe("fail");
+      expect(entries["RFC-0101"]?.previousOverall).toBe("pass");
+      expect(entries["RFC-0102"]?.previousOverall).toBe("fail");
+      const r101Diag = result.data!.diagnostics.find((d) => d.file?.includes("rfc-0101"));
+      expect(r101Diag?.message).toContain("regressed: was pass");
+      const r102Diag = result.data!.diagnostics.find((d) => d.file?.includes("rfc-0102"));
+      expect(r102Diag?.message).not.toContain("regressed");
+      expect(result.summary).toContain("1 regressed, 1 recovered");
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
 describe("rfc.verification.refresh — AC-1: single-RFC refresh", () => {
   test("updates lastRefreshedAt, replaces probes[], preserves emittedAt", async () => {
     const { workspaceRoot, cleanup } = await setupWorkspace({
@@ -260,6 +336,151 @@ describe("rfc.verification.refresh — AC-4: --dry-run does not write files", ()
   });
 });
 
+describe("rfc.verification.refresh — RFC-1237 AC-1: context.dryRun (the real CLI path)", () => {
+  test("werkstatt run --dry-run consumes --dry-run into context.dryRun — zero writes", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100", emittedAt: "2026-01-01T00:00:00.000Z" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+      const before = await fs.readFile(envelopePath, "utf-8");
+
+      // The real CLI path: consumeCommonFlags strips --dry-run from argv into
+      // context.dryRun — input.flags carries no "dry-run" key at all.
+      const result = await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot, { dryRun: true }) as unknown as ForgeRuntimeContext,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(1);
+      expect(await fs.readFile(envelopePath, "utf-8")).toBe(before);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("recording-IO port sees zero write intents under context.dryRun", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+      const { io, writes } = makeSpyIo();
+
+      await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot, { dryRun: true, io }) as unknown as ForgeRuntimeContext,
+      );
+
+      expect(
+        writes,
+        "dry-run refresh must issue zero io writes — check the dryRun guard in runRfcVerificationRefresh",
+      ).toEqual([]);
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("rfc.verification.refresh — RFC-1237 AC-2: emit-canonical header", () => {
+  test("writes the emit-owned structured marker header, not a refresh-owned one", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+
+      await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
+      );
+
+      const raw = await fs.readFile(
+        path.join(workspaceRoot, "docs", "rfcs", "verification", "rfc-0100.generated.yaml"),
+        "utf-8",
+      );
+      // Structured marker keys — identical-by-construction to what emit writes.
+      expect(raw).toMatch(/^generatedMarker: GENERATED\./);
+      expect(raw).toContain("ownerCommand: rfc.verification.emit");
+      expect(raw).toContain("regenerateCommand: pnpm exec werkstatt run rfc.verification.emit");
+      // Refresh never stamps itself as owner — it is a conditional secondary writer.
+      expect(raw).not.toContain("rfc.verification.refresh");
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("legacy '#'-comment input header normalizes to the canonical key format", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+      await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
+      );
+
+      const raw = await fs.readFile(
+        path.join(workspaceRoot, "docs", "rfcs", "verification", "rfc-0100.generated.yaml"),
+        "utf-8",
+      );
+      // setupWorkspace wrote the legacy `# Generated by ...` comment header —
+      // refresh output must carry no comment lines at all.
+      expect(raw.split("\n").every((line) => !line.startsWith("#"))).toBe(true);
+      expect(raw).toMatch(/^generatedMarker: GENERATED\./);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("writes route through the resolved io port, not ambient fs", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100", emittedAt: "2026-01-01T00:00:00.000Z" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+      const { io, writes } = makeSpyIo();
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+
+      await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot, { io }) as unknown as ForgeRuntimeContext,
+      );
+
+      expect(writes).toEqual([envelopePath]);
+      // The spy io never touches disk — the on-disk file keeps its old content.
+      const raw = await fs.readFile(envelopePath, "utf-8");
+      expect(raw).not.toContain("lastRefreshedAt");
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
 describe("rfc.verification.refresh — AC-5: no evidence envelope", () => {
   test("skips RFC with reason 'no evidence envelope' and exits non-zero", async () => {
     const { workspaceRoot, cleanup } = await setupWorkspace({

package/os/rfc/verification-refresh.ts

@@ -14,6 +14,17 @@ lastRefreshedAt, replaces probes[] with fresh results. Supports --id,
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0999: initial implementation.</item>
+  <item>RFC-1237: dual-read dry-run (context.dryRun || flags["dry-run"]),
+io.writeFile port routing, emit-canonical generated header — refresh owns
+content freshness, never envelope identity (ownerCommand stays
+rfc.verification.emit).</item>
+  <item>Session-retro 2026-10-08: sweep delta report — previousOverall per
+envelope + recovered/regressed lists separate still-failing drift from fresh
+regressions without manual triage.</item>
+  <item>Session-retro 2026-10-08: --concurrency flag (default 1, garbage values
+warn + fall back to 1, >16 clamps) fans refresh out across RFC units via
+mapWithConcurrency while probes inside one RFC stay sequential — envelope
+ordering stays deterministic.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -24,14 +35,14 @@ import { parse as yamlParse } from "yaml";
 
 import { runProbe } from "./acceptance.ts";
 import { listRfcFiles, readAndParseRfc } from "./frontmatter-io.ts";
-import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
-import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
-import { stringify as yamlStringify } from "yaml";
 import {
   captureGitContext,
   getKernelVersion,
+  mapWithConcurrency,
+  resolveConcurrency,
   VERIFICATION_DIR,
   buildEvidenceEnvelope,
+  serializeEvidenceEnvelope,
 } from "./verification-evidence.ts";
 import { RFC_DIR } from "./types.ts";
 import type {
@@ -57,7 +68,10 @@ export async function runRfcVerificationRefresh(
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
   const targetId = input.flags["id"] as string | undefined;
   const allMode = input.flags["all"] === true;
-  const dryRun = input.flags["dry-run"] === true;
+  // RFC-1237: consumeCommonFlags strips --dry-run into context.dryRun before
+  // dispatch — the input.flags read stays for direct/programmatic callers.
+  const dryRun = context.dryRun === true || input.flags["dry-run"] === true;
+  const concurrency = resolveConcurrency(input.flags["concurrency"], (m) => logger.warn(m));
 
   if (!targetId && !allMode) {
     return {
@@ -82,19 +96,24 @@ export async function runRfcVerificationRefresh(
   const gitContext = await captureGitContext(workspaceRoot);
   const kernelVersion = await getKernelVersion(workspaceRoot);
 
-  for (const fileName of allFiles) {
+  const processFile = async (
+    fileName: string,
+  ): Promise<{
+    refreshedEntry?: NonNullable<RfcVerificationRefreshResult["refreshed"]>[number];
+    skippedEntry?: NonNullable<RfcVerificationRefreshResult["skipped"]>[number];
+    diagnostic?: Diagnostic;
+  }> => {
     const parsedFile = await readAndParseRfc(rfcDirPath, fileName);
-    if (!parsedFile) continue;
-    if ("error" in parsedFile) continue;
+    if (!parsedFile) return {};
+    if ("error" in parsedFile) return {};
     const fm = parsedFile.parsed.frontmatter;
     const rfcId = String(fm["id"] ?? "");
     const status = String(fm["status"] ?? "");
 
-    if (targetId && rfcId.toLowerCase() !== targetId.toLowerCase()) continue;
+    if (targetId && rfcId.toLowerCase() !== targetId.toLowerCase()) return {};
 
     if (status !== "implemented") {
-      skipped.push({ rfcId, reason: "not implemented" });
-      continue;
+      return { skippedEntry: { rfcId, reason: "not implemented" } };
     }
 
     const slug = rfcId.toLowerCase();
@@ -113,15 +132,9 @@ export async function runRfcVerificationRefresh(
       // file doesn't exist or can't be parsed
     }
 
-    if (!existingEnvelope) {
-      skipped.push({ rfcId, reason: "no evidence envelope" });
-      continue;
-    }
-
     const acceptance = fm["acceptance"];
-    if (!Array.isArray(acceptance) || acceptance.length === 0) {
-      skipped.push({ rfcId, reason: "no evidence envelope" });
-      continue;
+    if (!existingEnvelope || !Array.isArray(acceptance) || acceptance.length === 0) {
+      return { skippedEntry: { rfcId, reason: "no evidence envelope" } };
     }
 
     const probes = acceptance as AcceptanceProbe[];
@@ -156,33 +169,49 @@ export async function runRfcVerificationRefresh(
     envelope.lastRefreshedAt = now;
 
     if (!dryRun) {
-      const yamlContent = `${buildGeneratedHeader({ filePath: evidenceRelPath, ownerCommand: "rfc.verification.refresh" })}${yamlStringify(envelope)}\n`;
-      await writeFileAtomic(evidenceAbsPath, yamlContent);
+      // RFC-1237: emit-canonical serialization — emit owns these envelopes;
+      // refresh owns content freshness, never file identity (OWN-DUP-01).
+      // Port write routes through recording IO under kernel --dry-run.
+      await io.writeFile(evidenceAbsPath, serializeEvidenceEnvelope(envelope));
     }
 
     const probesFailed = probeRecords.filter((r) => !r.ok).length;
-    refreshed.push({
-      rfcId,
-      file: evidenceRelPath,
-      overall: envelope.overall,
-      probesTotal: probeRecords.length,
-      probesFailed,
-    });
-
-    if (envelope.overall === "fail") {
-      diagnostics.push({
-        ruleId: "RFC-REFRESH-01",
-        severity: "error",
-        file: evidenceRelPath,
-        message: `${rfcId}: refresh overall is "fail" — ${probesFailed}/${probeRecords.length} probe(s) failed.`,
-      });
-    }
+    const previousOverall = existingEnvelope.overall;
 
     if (outputFormat === "pretty") {
+      const drift = previousOverall !== envelope.overall ? `, was ${previousOverall}` : "";
       logger.info(
-        `[refresh] ${rfcId} → ${evidenceRelPath} (${envelope.overall}, ${probeRecords.length} probes${dryRun ? ", dry-run" : ""})`,
+        `[refresh] ${rfcId} → ${evidenceRelPath} (${envelope.overall}, ${probeRecords.length} probes${drift}${dryRun ? ", dry-run" : ""})`,
       );
     }
+
+    return {
+      refreshedEntry: {
+        rfcId,
+        file: evidenceRelPath,
+        overall: envelope.overall,
+        previousOverall,
+        probesTotal: probeRecords.length,
+        probesFailed,
+      },
+      ...(envelope.overall === "fail"
+        ? {
+            diagnostic: {
+              ruleId: "RFC-REFRESH-01",
+              severity: "error",
+              file: evidenceRelPath,
+              message: `${rfcId}: refresh overall is "fail" — ${probesFailed}/${probeRecords.length} probe(s) failed${previousOverall === "pass" ? " (regressed: was pass)" : ""}.`,
+            } satisfies Diagnostic,
+          }
+        : {}),
+    };
+  };
+
+  const results = await mapWithConcurrency(allFiles, concurrency, processFile);
+  for (const r of results) {
+    if (r.refreshedEntry) refreshed.push(r.refreshedEntry);
+    if (r.skippedEntry) skipped.push(r.skippedEntry);
+    if (r.diagnostic) diagnostics.push(r.diagnostic);
   }
 
   const passed = refreshed.filter((r) => r.overall === "pass").length;
@@ -190,6 +219,18 @@ export async function runRfcVerificationRefresh(
   const hasFailures = failed > 0;
   const hasSkippedNoEnvelope = skipped.some((s) => s.reason === "no evidence envelope");
   const status: RfcVerificationRefreshResult["status"] = hasFailures ? "fail" : "pass";
+  const delta = {
+    recovered: refreshed
+      .filter((r) => r.previousOverall === "fail" && r.overall === "pass")
+      .map((r) => r.rfcId),
+    regressed: refreshed
+      .filter((r) => r.previousOverall === "pass" && r.overall === "fail")
+      .map((r) => r.rfcId),
+  };
+  const deltaSummary =
+    delta.recovered.length + delta.regressed.length > 0
+      ? `, ${delta.regressed.length} regressed, ${delta.recovered.length} recovered`
+      : "";
 
   return {
     data: {
@@ -198,6 +239,7 @@ export async function runRfcVerificationRefresh(
       refreshed,
       skipped,
       diagnostics,
+      delta,
       summary: {
         total: refreshed.length,
         passed,
@@ -206,6 +248,6 @@ export async function runRfcVerificationRefresh(
       },
     },
     exitCode: hasFailures || hasSkippedNoEnvelope ? 1 : 0,
-    summary: `rfc.verification.refresh: ${refreshed.length} refreshed, ${skipped.length} skipped`,
+    summary: `rfc.verification.refresh: ${refreshed.length} refreshed, ${skipped.length} skipped${deltaSummary}`,
   };
 }

package/os/session/handlers/save.ts

@@ -19,6 +19,11 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>Session-retro 2026-10-08: raw-file claiming — each .atif is claimed via
+an atomic sibling `<name>.claim-<pid>-<token>` (io rename onto a nonexistent
+target) before read/process/delete; another session's claim skips the file,
+claims clean up in finally, dry-run creates none, keepRaw still preserves the
+raw input. Closes the parallel-session read/delete race.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -196,7 +201,9 @@ export async function runSessionSave(
   } else {
     try {
       const entries = await fs.readdir(rawDirPath);
-      rawFiles = entries.filter((e) => e.isFile).map((e) => e.name);
+      // Only *.atif files are processed — claimed intermediates
+      // (*.atif.claim-<pid>) and in-progress writer temp files are skipped.
+      rawFiles = entries.filter((e) => e.isFile && e.name.endsWith(".atif")).map((e) => e.name);
     } catch {
       rawFiles = [];
     }
@@ -234,9 +241,25 @@ export async function runSessionSave(
 
   for (const rawFileName of rawFiles) {
     const rawFilePath = path.join(rawDirPath, rawFileName);
+    // Atomic claim: rename before reading so two concurrent session.save runs
+    // (parallel agent sessions) can't process the same file — the losing
+    // rename sees ENOENT and skips. Dry-run stays read-only by design.
+    let claimedPath = rawFilePath;
+    if (!dryRun) {
+      claimedPath = `${rawFilePath}.claim-${process.pid}`;
+      try {
+        await fs.rename(rawFilePath, claimedPath);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          skipped.push({ rawFile: rawFileName, reason: "claimed by another process" });
+          continue;
+        }
+        throw err;
+      }
+    }
     let rawContent: string;
     try {
-      rawContent = await fs.readFile(rawFilePath);
+      rawContent = await fs.readFile(claimedPath);
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
         skipped.push({ rawFile: rawFileName, reason: "already processed by another process" });
@@ -279,12 +302,18 @@ export async function runSessionSave(
       // Delete raw file even when skipping — otherwise .atif files accumulate
       if (!dryRun && !keepRaw) {
         try {
-          await trashPath(rawFilePath);
+          await trashPath(claimedPath);
         } catch (err) {
           if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
             throw err;
           }
         }
+      } else if (!dryRun && claimedPath !== rawFilePath) {
+        try {
+          await fs.rename(claimedPath, rawFilePath);
+        } catch {
+          // best-effort restore
+        }
       }
       continue;
     } catch {
@@ -320,15 +349,22 @@ export async function runSessionSave(
         );
       }
 
-      // Delete raw file unless --keep-raw
+      // Delete raw file unless --keep-raw (then restore the original name —
+      // the claim suffix is an internal detail, not part of the file's name)
       if (!keepRaw) {
         try {
-          await trashPath(rawFilePath);
+          await trashPath(claimedPath);
         } catch (err) {
           if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
             throw err;
           }
         }
+      } else if (claimedPath !== rawFilePath) {
+        try {
+          await fs.rename(claimedPath, rawFilePath);
+        } catch {
+          // best-effort restore — the claimed name remains, still recoverable
+        }
       }
     }
 

package/os/session/session.module.ts

@@ -57,6 +57,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "session.archive",
+        coverage: "operator" as const,
         description:
           "Move session files older than --max-age-days (default 7) from " +
           "docs/sessions/ to docs/sessions/archive/. Bidirectional: files in " +
@@ -84,6 +85,8 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "session.validate",
+        coverage: "operator" as const,
+        coverageNote: "retrospective session-doc audit — pre-existing frontmatter debt",
         mutatesState: false,
         contract: "session",
         rules: [],
@@ -102,6 +105,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "session.list",
+        coverage: "operator" as const,
         mutatesState: false,
         description:
           "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
@@ -132,6 +136,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "metrics.aggregate",
+        coverage: "operator" as const,
         mutatesState: true,
         description:
           "Query and aggregate skill effectiveness metrics from docs/metrics/ files. " +