@warpgogol/forge 2.21.6 → 2.21.7

package/os/rfc/types.ts

@@ -17,6 +17,8 @@
   <item>RFC-0478: added versionBump field to RfcFrontmatter interface and RFC_KNOWN_KEYS array for platform versioning enforcement.</item>
   <item>RFC-0480: added breaksC field to RfcFrontmatter interface and RFC_KNOWN_KEYS array for Layer C protection.</item>
   <item>RFC-0795: added dependsOn, batch fields to RfcFrontmatter and RFC_KNOWN_KEYS; added RFC-IMP-07 to RfcImplementStampRule; added batch/dependsOn to RfcListEntry.</item>
+  <item>RFC-0998: added TestProbe and JsonSchemaProbe to AcceptanceProbe union for test and json-schema acceptance probe kinds.</item>
+  <item>RFC-0999: added lastRefreshedAt to VerificationEvidence; added RfcVerificationRefreshResult interface.</item>
 </CHANGE_SUMMARY>
  ***************************************************************/
 
@@ -265,10 +267,10 @@ export interface RfcFrontmatter {
  * arbitrary shell, keeping the probe surface auditable and platform-independent.
  */
 export type AcceptanceProbe =
-  | { probe: "run"; command: string; expect: { exitCode: number } }
-  | { probe: "file-exists"; path: string }
-  | { probe: "file-contains"; path: string; pattern: string }
-  | { probe: "command-registered"; name: string }
+  | { probe: "run"; command: string; expect: { exitCode: number }; criterion?: string }
+  | { probe: "file-exists"; path: string; criterion?: string }
+  | { probe: "file-contains"; path: string; pattern: string; criterion?: string }
+  | { probe: "command-registered"; name: string; criterion?: string }
   // RFC-0333: black-box expectation against the rendered site. Executed
   // ONLY by qa.independent.run (needs a built dist); rfc.acceptance.run
   // reports it as skipped.
@@ -279,6 +281,22 @@ export type AcceptanceProbe =
       selector?: string;
       textPattern?: string;
       allowConsoleErrors?: boolean;
+      criterion?: string;
+    }
+  // RFC-0998: run a specific vitest file or test name and check exit code.
+  | {
+      probe: "test";
+      file: string;
+      testName?: string;
+      expect: { exitCode: number };
+      criterion?: string;
+    }
+  // RFC-0998: validate a JSON/YAML artifact against an inline JSON Schema using Ajv.
+  | {
+      probe: "json-schema";
+      artifact: string;
+      schemaInline: Record<string, unknown>;
+      criterion?: string;
     };
 
 export interface ProbeResult {
@@ -292,7 +310,7 @@ export interface RfcAcceptanceRunResult {
   command: "rfc.acceptance.run";
   status: "pass" | "fail";
   diagnostics: Diagnostic[];
-  results: Array<{ rfcId: string; probeResults: ProbeResult[] }>;
+  results: Array<{ rfcId: string; probeResults: ProbeResult[]; coverage?: ProbeCoverageReport }>;
 } // ─── RFC-0330: verification evidence ─────────────────────────────────────────
 export interface VerificationEvidenceProbeRecord {
   probe: AcceptanceProbe;
@@ -306,6 +324,7 @@ export interface VerificationEvidence {
   title: string;
   rfcStatus: RfcStatus;
   emittedAt: string;
+  lastRefreshedAt?: string;
   commit: string;
   workingTreeDirty: boolean;
   kernelVersion: string;
@@ -322,6 +341,21 @@ export interface RfcVerificationEmitResult {
   emitted: Array<{ rfcId: string; file: string; overall: "pass" | "fail" }>;
   skipped: Array<{ rfcId: string; reason: "no-probes" }>;
   diagnostics: Diagnostic[];
+}
+
+export interface RfcVerificationRefreshResult {
+  command: "rfc.verification.refresh";
+  status: "pass" | "fail";
+  refreshed: Array<{
+    rfcId: string;
+    file: string;
+    overall: "pass" | "fail";
+    probesTotal: number;
+    probesFailed: number;
+  }>;
+  skipped: Array<{ rfcId: string; reason: "no evidence envelope" | "not implemented" }>;
+  diagnostics: Diagnostic[];
+  summary: { total: number; passed: number; failed: number; skipped: number };
 } // ─── Validation ──────────────────────────────────────────────────────────────
 export interface RfcValidationViolation {
   rfcId: string;
@@ -343,6 +377,7 @@ export interface RfcValidationResult {
   count: number;
   violations: RfcValidationViolation[];
   markers?: Marker[];
+  coverage?: Array<{ rfcId: string; report: ProbeCoverageReport }>;
 } // ─── Command results ─────────────────────────────────────────────────────────
 
 export interface RfcCommandLifecycleDiagnosticData {
@@ -515,7 +550,8 @@ export type RfcImplementStampRule =
   | "RFC-IMP-04"
   | "RFC-IMP-05"
   | "RFC-IMP-06"
-  | "RFC-IMP-07";
+  | "RFC-IMP-07"
+  | "RFC-IMP-08";
 
 export interface RfcImplementStampViolation {
   rule: RfcImplementStampRule;
@@ -594,3 +630,33 @@ export const RFC_METADATA_CUTOFF = "2026-07-07";
  * a versionBump field. RFCs created before are exempt.
  */
 export const RFC_VERSION_BUMP_CUTOFF = "2026-07-21";
+
+/**
+ * RFC-0997: cutoff date for probe-criterion binding rules.
+ * RFCs created on or after this date are subject to V-35 (probe→criterion
+ * referential integrity), V-36 (criterion identifier discipline), V-37
+ * (evidence mechanism validity), and RFC-IMP-08 (minimum-one-probe stamp gate).
+ * RFCs created before are exempt.
+ */
+export const RFC_PROBE_BINDING_CUTOFF = "2026-09-01";
+
+/**
+ * RFC-1006: cutoff date for criteria content rules (phase separation, reject
+ * checklist, criterion versioning). RFCs created on or after this date are
+ * subject to V-38 (document readiness completeness), V-39 (non-atomic
+ * criterion), V-40 (unbounded quantity), V-41 (weasel verb), and V-42
+ * (criterion versioning annotation format). RFCs created before are exempt.
+ */
+export const RFC_CRITERIA_CONTENT_CUTOFF = "2026-09-03";
+
+/**
+ * RFC-0997: non-blocking probe coverage report per RFC.
+ * Emitted in `rfc.validate --json` and `rfc.acceptance.run` outputs.
+ */
+export interface ProbeCoverageReport {
+  totalCriteria: number;
+  probeBackedCriteria: number;
+  coverageRatio: number;
+  unboundProbes: string[];
+  uncoveredCriteria: string[];
+}

package/os/rfc/verification-evidence.ts

@@ -13,6 +13,7 @@ a JSON evidence envelope to docs/rfcs/verification/<slug>.generated.yaml.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0330: initial implementation.</item>
+  <item>RFC-0999: exported captureGitContext, getKernelVersion, byteHashHex, VERIFICATION_DIR for reuse by verification-refresh.ts.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -42,7 +43,7 @@ import type {
   ForgeRuntimeContext,
 } from "../../src/types.ts";
 
-const VERIFICATION_DIR = join(RFC_DIR, "verification");
+export const VERIFICATION_DIR = join(RFC_DIR, "verification");
 const HASH_PREFIX = "sha" + "256:";
 
 function execGit(workspaceRoot: string, args: string[]): Promise<string> {
@@ -57,7 +58,7 @@ function execGit(workspaceRoot: string, args: string[]): Promise<string> {
   });
 }
 
-async function captureGitContext(
+export async function captureGitContext(
   workspaceRoot: string,
 ): Promise<{ commit: string; workingTreeDirty: boolean }> {
   const [commitOutput, statusOutput] = await Promise.all([
@@ -70,7 +71,7 @@ async function captureGitContext(
   };
 }
 
-async function getKernelVersion(workspaceRoot: string): Promise<string> {
+export async function getKernelVersion(workspaceRoot: string): Promise<string> {
   try {
     const pkgPath = join(workspaceRoot, "packages", "os", "site-kernel", "package.json");
     const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
@@ -80,7 +81,7 @@ async function getKernelVersion(workspaceRoot: string): Promise<string> {
   }
 }
 
-function byteHashHex(content: string): string {
+export function byteHashHex(content: string): string {
   return byteHash(content).slice(HASH_PREFIX.length);
 }
 

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

@@ -0,0 +1,320 @@
+// @vitest-environment node
+import { test, expect, describe, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { stringify as yamlStringify } from "yaml";
+
+import { runRfcVerificationRefresh } from "./verification-refresh.ts";
+
+const { mockRunProbe, mockCaptureGitContext, mockGetKernelVersion } = vi.hoisted(() => ({
+  mockRunProbe: vi.fn(),
+  mockCaptureGitContext: vi.fn(),
+  mockGetKernelVersion: vi.fn(),
+}));
+
+vi.mock("./acceptance.ts", () => ({
+  runProbe: mockRunProbe,
+}));
+
+vi.mock("./verification-evidence.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./verification-evidence.ts")>();
+  return {
+    ...actual,
+    captureGitContext: mockCaptureGitContext,
+    getKernelVersion: mockGetKernelVersion,
+  };
+});
+
+const RFC_FRONTMATTER = (id: string, status: string, probes: unknown[] = []) => {
+  const probeYaml = probes
+    .map(
+      (p) =>
+        `  - probe: ${(p as any).probe}\n    path: ${(p as any).path ?? ""}\n    criterion: ${(p as any).criterion ?? ""}`,
+    )
+    .join("\n");
+  return `---\nid: ${id}\ntitle: "Test ${id}"\nstatus: ${status}\nkind: command\nscope: workspace\nowners:\n  - architecture\ncreatedAt: 2026-01-01\nupdatedAt: 2026-01-01\nacceptance:\n${probeYaml}\n---\n\n# ${id}\n## Context\nTest.\n`;
+};
+
+const PROBE = { probe: "file-exists", path: "src/index.ts", criterion: "AC-1" };
+
+function makeEnvelope(
+  rfcId: string,
+  emittedAt: string,
+  overall: "pass" | "fail" = "pass",
+): Record<string, unknown> {
+  return {
+    rfcId,
+    title: `Test ${rfcId}`,
+    rfcStatus: "implemented",
+    emittedAt,
+    commit: "abc123",
+    workingTreeDirty: false,
+    kernelVersion: "1.0.0",
+    rfcFileHash: "hash123",
+    acceptanceHash: "accHash123",
+    probes: [
+      {
+        probe: PROBE,
+        ok: overall === "pass",
+        detail: overall === "pass" ? "exists" : "does not exist",
+        durationMs: 5,
+      },
+    ],
+    overall,
+  };
+}
+
+async function setupWorkspace(opts: {
+  rfcs: Array<{ id: string; status: string; probes?: unknown[] }>;
+  envelopes?: Array<{ id: string; emittedAt?: string; overall?: "pass" | "fail" }>;
+}): Promise<{ workspaceRoot: string; cleanup: () => Promise<void> }> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-refresh-test-"));
+  const rfcDir = path.join(tmpDir, "docs", "rfcs");
+  const verificationDir = path.join(rfcDir, "verification");
+  await fs.mkdir(verificationDir, { recursive: true });
+
+  for (const rfc of opts.rfcs) {
+    const slug = rfc.id.toLowerCase();
+    const probes = rfc.probes ?? [PROBE];
+    await fs.writeFile(
+      path.join(rfcDir, `${slug}-test.md`),
+      RFC_FRONTMATTER(rfc.id, rfc.status, probes),
+    );
+  }
+
+  for (const env of opts.envelopes ?? []) {
+    const slug = env.id.toLowerCase();
+    const envelope = makeEnvelope(env.id, env.emittedAt ?? "2026-01-01T00:00:00.000Z", env.overall);
+    const header = `# Generated by rfc.verification.emit\n# Do not edit by hand.\n`;
+    await fs.writeFile(
+      path.join(verificationDir, `${slug}.generated.yaml`),
+      header + yamlStringify(envelope) + "\n",
+    );
+  }
+
+  mockCaptureGitContext.mockResolvedValue({ commit: "abc123", workingTreeDirty: false });
+  mockGetKernelVersion.mockResolvedValue("1.0.0");
+
+  return {
+    workspaceRoot: tmpDir,
+    cleanup: async () => {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    },
+  };
+}
+
+function makeContext(workspaceRoot: string) {
+  return {
+    workspaceRoot,
+    logger: { info: () => {} },
+    outputFormat: "json" as const,
+    commandRegistry: undefined,
+  };
+}
+
+beforeEach(() => {
+  mockRunProbe.mockReset();
+  mockCaptureGitContext.mockReset();
+  mockGetKernelVersion.mockReset();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("rfc.verification.refresh — AC-1: single-RFC refresh", () => {
+  test("updates lastRefreshedAt, replaces probes[], preserves emittedAt", 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 result = await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(1);
+      expect(result.data!.refreshed[0].rfcId).toBe("RFC-0100");
+      expect(result.data!.refreshed[0].overall).toBe("pass");
+      expect(result.exitCode).toBe(0);
+
+      // Verify envelope was written with lastRefreshedAt
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+      const raw = await fs.readFile(envelopePath, "utf-8");
+      expect(raw).toContain("lastRefreshedAt");
+      expect(raw).toContain("emittedAt: 2026-01-01T00:00:00.000Z");
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("rfc.verification.refresh — AC-2: --all mode", () => {
+  test("iterates over all implemented RFCs with evidence envelopes", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [
+        { id: "RFC-0100", status: "implemented" },
+        { id: "RFC-0200", status: "implemented" },
+        { id: "RFC-0300", status: "accepted" },
+      ],
+      envelopes: [{ id: "RFC-0100" }, { id: "RFC-0200" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+
+      const result = await runRfcVerificationRefresh(
+        { flags: { all: true } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(2);
+      expect(result.data!.skipped).toHaveLength(1);
+      expect(result.data!.skipped[0].reason).toBe("not implemented");
+      expect(result.exitCode).toBe(0);
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("rfc.verification.refresh — AC-3: probe failure still writes envelope", () => {
+  test("writes envelope with overall: fail and exits non-zero", async () => {
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100" }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: false, detail: "does not exist" });
+
+      const result = await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(1);
+      expect(result.data!.refreshed[0].overall).toBe("fail");
+      expect(result.data!.refreshed[0].probesFailed).toBe(1);
+      expect(result.exitCode).toBe(1);
+
+      // Envelope was still written
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+      const raw = await fs.readFile(envelopePath, "utf-8");
+      expect(raw).toContain("overall: fail");
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("rfc.verification.refresh — AC-4: --dry-run does not write files", () => {
+  test("runs probes but does not write envelope files", 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 result = await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100", "dry-run": true } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(1);
+      expect(result.data!.refreshed[0].overall).toBe("pass");
+
+      // Envelope file should still have the old content (no lastRefreshedAt)
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+      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({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+
+      const result = await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      expect(result.data!.refreshed).toHaveLength(0);
+      expect(result.data!.skipped).toHaveLength(1);
+      expect(result.data!.skipped[0].reason).toBe("no evidence envelope");
+      expect(result.exitCode).toBe(1);
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("rfc.verification.refresh — AC-6: emittedAt preservation", () => {
+  test("emittedAt is preserved across refreshes", async () => {
+    const originalEmittedAt = "2026-01-01T00:00:00.000Z";
+    const { workspaceRoot, cleanup } = await setupWorkspace({
+      rfcs: [{ id: "RFC-0100", status: "implemented" }],
+      envelopes: [{ id: "RFC-0100", emittedAt: originalEmittedAt }],
+    });
+
+    try {
+      mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
+
+      await runRfcVerificationRefresh(
+        { flags: { id: "RFC-0100" } } as any,
+        makeContext(workspaceRoot) as any,
+      );
+
+      const envelopePath = path.join(
+        workspaceRoot,
+        "docs",
+        "rfcs",
+        "verification",
+        "rfc-0100.generated.yaml",
+      );
+      const raw = await fs.readFile(envelopePath, "utf-8");
+      expect(raw).toContain(`emittedAt: ${originalEmittedAt}`);
+      // lastRefreshedAt should be different (set to now)
+      expect(raw).toContain("lastRefreshedAt:");
+      // lastRefreshedAt should not equal emittedAt
+      expect(raw).not.toMatch(/lastRefreshedAt: 2026-01-01T00:00:00\.000Z/);
+    } finally {
+      await cleanup();
+    }
+  });
+});