@warpgogol/forge 2.21.6 → 2.21.8

package/os/rfc/handlers/validate-rules.ts

@@ -10,11 +10,13 @@
   <item>RFC-0722: add RFC-DIR-01 directory structure warning rule for unsanctioned subdirectories.</item>
   <item>RFC-0755: add V-RFC-33 frontmatter YAML parseability check (checkFrontmatterYamlParse helper).</item>
   <item>RFC-0795: add V-33 dependsOn referential integrity/self-dependency/rejected-dependency and V-34 batch slug format rules.</item>
+  <item>RFC-0997: add V-35 probe→criterion referential integrity, V-36 criterion identifier discipline, V-37 evidence mechanism validity, and computeProbeCoverage for non-blocking coverage reports.</item>
+  <item>RFC-1006: add V-38 document readiness completeness, V-39 non-atomic criterion, V-40 unbounded quantity, V-41 weasel verb, V-42 criterion versioning annotation format. Add evaluateDocumentReadiness and extend evaluateAcceptanceCriteria with supersession tracking and reject-checklist scans.</item>
 </CHANGE_SUMMARY>
 */
 
 import path from "node:path";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { execFile } from "node:child_process";
 
 import { parse as yamlParse } from "yaml";
@@ -31,7 +33,10 @@ import {
   RFC_FULL_REQUIRED_SECTIONS,
   RFC_METADATA_CUTOFF,
   RFC_VERSION_BUMP_CUTOFF,
+  RFC_PROBE_BINDING_CUTOFF,
+  RFC_CRITERIA_CONTENT_CUTOFF,
 } from "../types.ts";
+import type { ProbeCoverageReport, AcceptanceProbe } from "../types.ts";
 import { DNA_DOCS, AP_DOCS } from "./shared.ts";
 
 const DNA_DOC = DNA_DOCS[0]!;
@@ -63,6 +68,123 @@ export interface AcceptanceCriteriaEvaluation {
   totalUnchecked: number;
   uncheckedLines: string[];
   checkedWithoutEvidence: string[];
+  criterionIds: string[];
+  duplicateCriterionIds: string[];
+  linesWithoutId: string[];
+  supersededIds: string[];
+  nonAtomicViolations: { line: string; acId: string }[];
+  unboundedQuantityViolations: { line: string; acId: string; trigger: string }[];
+  weaselVerbViolations: { line: string; acId: string; trigger: string }[];
+  malformedSupersessionAnnotations: string[];
+}
+
+export interface DocumentReadinessEvaluation {
+  totalChecked: number;
+  totalUnchecked: number;
+  uncheckedLines: string[];
+  criterionIds: string[];
+  linesWithoutId: string[];
+}
+
+// ─── RFC-1006: reject checklist constants ──────────────────────────────────
+
+const UNBOUNDED_QUANTITY_TRIGGERS = [
+  "fast",
+  "quick",
+  "scalable",
+  "reasonable load",
+  "most requests",
+  "efficiently",
+  "high performance",
+  "low latency",
+  "responsively",
+  "smoothly",
+] as const;
+
+const WEASEL_VERBS = [
+  "handle gracefully",
+  "behave correctly",
+  "as appropriate",
+  "robust",
+  "user-friendly",
+  "works correctly",
+  "is reliable",
+  "gracefully handle",
+  "correctly handle",
+  "properly handle",
+] as const;
+
+// Detects "SHALL <verb-phrase> and <verb-phrase>" — non-atomic criterion.
+// Conservative: only fires when "and" appears after SHALL/SHOULD/MUST and
+// is followed by a verb-like word (a-z, not a noun-phrase connector).
+const NON_ATOMIC_PATTERN =
+  /\b(?:SHALL|SHOULD|MUST)\s+\S[^()]*?\band\s+(?:return|report|exit|emit|write|read|create|delete|update|persist|validate|reject|accept|log|send|store|load|fetch|process|register|enqueue|schedule|trigger|notify|redirect|render|display|show|hide|enable|disable|start|stop|restart|check|verify|ensure|prevent|allow|block|deny|grant|revoke|parse|serialize|deserialize|encode|decode|compress|decompress|encrypt|decrypt|hash|sign|verify|transform|convert|map|filter|sort|group|aggregate|count|sum|average|min|max|find|search|resolve|lookup)\b/i;
+
+const SUPERSEDED_ANNOTATION_PATTERN =
+  /^>\s*Superseded\s+(AC-\d+)\s+\((\d{4}-\d{2}-\d{2})\):\s*(.+)$/;
+
+/**
+ * Strip fenced code blocks (``` ... ```) from a markdown body.
+ * Prevents section extractors from matching headings inside code block examples.
+ * Pure function — no I/O, no side effects.
+ */
+export function stripFencedCodeBlocks(body: string): string {
+  return body.replace(/```[\s\S]*?```/g, "");
+}
+
+/**
+ * Extract the raw document-readiness section text from an RFC body.
+ * Pure function — no I/O, no side effects.
+ */
+export function extractDocumentReadinessSection(body: string): string | null {
+  const stripped = stripFencedCodeBlocks(body);
+  const match = stripped.match(/## Document readiness\s*\n([\s\S]*?)(?=\n## |\n*$)/);
+  return match ? match[1]! : null;
+}
+
+/**
+ * Evaluate document-readiness checkboxes (RFC-1006).
+ * Pure function — no I/O, no side effects.
+ */
+export function evaluateDocumentReadiness(body: string): DocumentReadinessEvaluation {
+  const section = extractDocumentReadinessSection(body);
+  if (!section) {
+    return {
+      totalChecked: 0,
+      totalUnchecked: 0,
+      uncheckedLines: [],
+      criterionIds: [],
+      linesWithoutId: [],
+    };
+  }
+
+  const uncheckedLines = section
+    .split("\n")
+    .filter((line) => /^- \[ \]/.test(line))
+    .map((line) => line.trim());
+  const totalUnchecked = uncheckedLines.length;
+
+  const checkedLines = section.split("\n").filter((line) => /^- \[x\]/.test(line));
+
+  const checklistLines = section.split("\n").filter((line) => /^- \[[ x]\]/.test(line));
+  const criterionIds: string[] = [];
+  const linesWithoutId: string[] = [];
+  for (const line of checklistLines) {
+    const match = line.match(/^\s*- \[[ x]\]\s*DR-(\d+):/);
+    if (match) {
+      criterionIds.push(`DR-${match[1]}`);
+    } else {
+      linesWithoutId.push(line.trim());
+    }
+  }
+
+  return {
+    totalChecked: checkedLines.length,
+    totalUnchecked,
+    uncheckedLines,
+    criterionIds,
+    linesWithoutId,
+  };
 }
 
 /**
@@ -70,7 +192,8 @@ export interface AcceptanceCriteriaEvaluation {
  * Returns `undefined` when the section is absent.
  */
 export function extractAcceptanceCriteriaSection(body: string): string | undefined {
-  const match = body.match(/## Acceptance criteria\s*\n([\s\S]*?)(?=\n## |\n*$)/);
+  const stripped = stripFencedCodeBlocks(body);
+  const match = stripped.match(/## Acceptance criteria\s*\n([\s\S]*?)(?=\n## |\n*$)/);
   return match?.[1];
 }
 
@@ -87,6 +210,14 @@ export function evaluateAcceptanceCriteria(body: string): AcceptanceCriteriaEval
       totalUnchecked: 0,
       uncheckedLines: [],
       checkedWithoutEvidence: [],
+      criterionIds: [],
+      duplicateCriterionIds: [],
+      linesWithoutId: [],
+      supersededIds: [],
+      nonAtomicViolations: [],
+      unboundedQuantityViolations: [],
+      weaselVerbViolations: [],
+      malformedSupersessionAnnotations: [],
     };
   }
 
@@ -104,11 +235,149 @@ export function evaluateAcceptanceCriteria(body: string): AcceptanceCriteriaEval
     }
   }
 
+  const checklistLines = section.split("\n").filter((line) => /^- \[[ x]\]/.test(line));
+  const criterionIds: string[] = [];
+  const seenIds = new Set<string>();
+  const duplicateCriterionIds: string[] = [];
+  const linesWithoutId: string[] = [];
+  for (const line of checklistLines) {
+    const match = line.match(/^\s*- \[[ x]\]\s*AC-(\d+):/);
+    if (match) {
+      const id = `AC-${match[1]}`;
+      if (seenIds.has(id)) {
+        duplicateCriterionIds.push(id);
+      } else {
+        seenIds.add(id);
+        criterionIds.push(id);
+      }
+    } else {
+      linesWithoutId.push(line.trim());
+    }
+  }
+
+  // RFC-1006: detect supersession annotations and exclude superseded criteria
+  const sectionLines = section.split("\n");
+  const supersededIds: string[] = [];
+  const supersededSet = new Set<string>();
+  const malformedSupersessionAnnotations: string[] = [];
+
+  for (let i = 0; i < sectionLines.length; i++) {
+    const line = sectionLines[i]!;
+    const annMatch = line.match(SUPERSEDED_ANNOTATION_PATTERN);
+    if (annMatch) {
+      const acId = annMatch[1]!;
+      const dateStr = annMatch[2]!;
+      supersededIds.push(acId);
+      supersededSet.add(acId);
+      // Validate date format (already captured by regex, but check range)
+      const date = new Date(dateStr);
+      if (isNaN(date.getTime())) {
+        malformedSupersessionAnnotations.push(line.trim());
+      }
+    } else if (
+      /^>\s*Superseded\s+AC-/.test(line.trim()) &&
+      !SUPERSEDED_ANNOTATION_PATTERN.test(line.trim())
+    ) {
+      // Line starts with supersession annotation pattern but doesn't match full format
+      malformedSupersessionAnnotations.push(line.trim());
+    }
+  }
+
+  // Remove superseded criteria from unchecked count
+  const effectiveUncheckedLines = uncheckedLines.filter((line) => {
+    const match = line.match(/^\s*- \[ \]\s*AC-(\d+):/);
+    if (match) {
+      return !supersededSet.has(`AC-${match[1]}`);
+    }
+    return true;
+  });
+
+  // RFC-1006: reject checklist scans on criterion text
+  const nonAtomicViolations: { line: string; acId: string }[] = [];
+  const unboundedQuantityViolations: { line: string; acId: string; trigger: string }[] = [];
+  const weaselVerbViolations: { line: string; acId: string; trigger: string }[] = [];
+
+  for (const line of checklistLines) {
+    const acMatch = line.match(/^\s*- \[[ x]\]\s*(AC-\d+):/);
+    if (!acMatch) continue;
+    const acId = acMatch[1]!;
+    if (supersededSet.has(acId)) continue;
+
+    const text = line.toLowerCase();
+
+    // V-39: non-atomic criterion
+    if (NON_ATOMIC_PATTERN.test(line)) {
+      nonAtomicViolations.push({ line: line.trim(), acId });
+    }
+
+    // V-40: unbounded quantity
+    for (const trigger of UNBOUNDED_QUANTITY_TRIGGERS) {
+      if (text.includes(trigger)) {
+        unboundedQuantityViolations.push({ line: line.trim(), acId, trigger });
+      }
+    }
+
+    // V-41: weasel verbs
+    for (const trigger of WEASEL_VERBS) {
+      if (text.includes(trigger)) {
+        weaselVerbViolations.push({ line: line.trim(), acId, trigger });
+      }
+    }
+  }
+
   return {
     totalChecked: checkedLines.length,
-    totalUnchecked,
-    uncheckedLines,
+    totalUnchecked: effectiveUncheckedLines.length,
+    uncheckedLines: effectiveUncheckedLines,
     checkedWithoutEvidence,
+    criterionIds,
+    duplicateCriterionIds,
+    linesWithoutId,
+    supersededIds,
+    nonAtomicViolations,
+    unboundedQuantityViolations,
+    weaselVerbViolations,
+    malformedSupersessionAnnotations,
+  };
+}
+
+// ─── RFC-0997: probe-criterion binding and coverage ────────────────────────
+
+/**
+ * Compute a non-blocking probe coverage report for an RFC.
+ * Pure function — no I/O, no side effects.
+ */
+export function computeProbeCoverage(
+  criterionIds: string[],
+  acceptance: unknown,
+): ProbeCoverageReport {
+  const probes = Array.isArray(acceptance) ? (acceptance as AcceptanceProbe[]) : [];
+  const probeBackedCriteria = new Set<string>();
+  const unboundProbes: string[] = [];
+
+  for (const probe of probes) {
+    const criterion = probe.criterion;
+    if (typeof criterion === "string" && /^AC-\d+$/.test(criterion)) {
+      if (criterionIds.includes(criterion)) {
+        probeBackedCriteria.add(criterion);
+      } else {
+        unboundProbes.push(criterion);
+      }
+    } else {
+      unboundProbes.push(String(criterion ?? "(missing)"));
+    }
+  }
+
+  const uncoveredCriteria = criterionIds.filter((id) => !probeBackedCriteria.has(id));
+  const totalCriteria = criterionIds.length;
+  const probeBackedCount = probeBackedCriteria.size;
+
+  return {
+    totalCriteria,
+    probeBackedCriteria: probeBackedCount,
+    coverageRatio: totalCriteria > 0 ? probeBackedCount / totalCriteria : 0,
+    unboundProbes,
+    uncoveredCriteria,
   };
 }
 
@@ -431,9 +700,9 @@ export async function validateSingleRfc(
   }
 
   // V-14: acceptance criteria must have at least 3 checklist items
-  const acceptanceMatch = body.match(/## Acceptance criteria\s*\n([\s\S]*?)(?=\n## |\n*$)/);
-  if (acceptanceMatch) {
-    const checklistItems = acceptanceMatch[1]!.match(/^- \[[ x]\]/gm);
+  const acceptanceSection = extractAcceptanceCriteriaSection(body);
+  if (acceptanceSection) {
+    const checklistItems = acceptanceSection.match(/^- \[[ x]\]/gm);
     const count = checklistItems?.length ?? 0;
     if (count < 3) {
       addViolation(
@@ -449,8 +718,8 @@ export async function validateSingleRfc(
   // V-26: implemented RFCs must have all acceptance criteria checked (RFC-0463)
   // V-27: every checked criterion must carry inline (evidence: ...) annotation (RFC-0463)
   // RFC-0476: both use the shared evaluateAcceptanceCriteria function.
-  if (acceptanceMatch) {
-    const criteriaEval = evaluateAcceptanceCriteria(body);
+  const criteriaEval = evaluateAcceptanceCriteria(body);
+  if (acceptanceSection) {
     if (status === "implemented" && criteriaEval.totalUnchecked > 0 && !isArchived) {
       addViolation(
         rfcId,
@@ -468,6 +737,178 @@ export async function validateSingleRfc(
         `checked acceptance criterion lacks inline (evidence: ...) annotation: "${line}"`,
       );
     }
+
+    // V-35/V-36/V-37: probe-criterion binding rules (RFC-0997, post-cutoff only)
+    const isPostCutoff = createdAt >= RFC_PROBE_BINDING_CUTOFF && !isArchived;
+    if (isPostCutoff) {
+      const acceptance = fm["acceptance"];
+      const probes = Array.isArray(acceptance) ? (acceptance as AcceptanceProbe[]) : [];
+
+      // V-35: every probe SHALL declare criterion referencing an existing AC-N id
+      for (let i = 0; i < probes.length; i++) {
+        const probe = probes[i]!;
+        const criterion = probe.criterion;
+        if (criterion === undefined || criterion === null) {
+          addViolation(
+            rfcId,
+            relFile,
+            "V-35",
+            `acceptance probe ${i} ("${probe.probe}") lacks required "criterion" field (post-cutoff RFCs must bind probes to AC-N criteria per RFC-0997)`,
+          );
+        } else if (typeof criterion !== "string" || !/^AC-\d+$/.test(criterion)) {
+          addViolation(
+            rfcId,
+            relFile,
+            "V-35",
+            `acceptance probe ${i} ("${probe.probe}") has criterion "${String(criterion)}" which does not match format "AC-N"`,
+          );
+        } else if (!criteriaEval.criterionIds.includes(criterion)) {
+          addViolation(
+            rfcId,
+            relFile,
+            "V-35",
+            `acceptance probe ${i} ("${probe.probe}") declares criterion "${criterion}" which does not exist in acceptance criteria`,
+          );
+        }
+      }
+
+      // V-36: every top-level checklist line SHALL start with a unique AC-N: identifier
+      for (const line of criteriaEval.linesWithoutId) {
+        addViolation(
+          rfcId,
+          relFile,
+          "V-36",
+          `acceptance criterion checklist line lacks "AC-N:" identifier: "${line}"`,
+        );
+      }
+      for (const dupId of criteriaEval.duplicateCriterionIds) {
+        addViolation(
+          rfcId,
+          relFile,
+          "V-36",
+          `duplicate acceptance criterion identifier "${dupId}" — each AC-N must be unique`,
+        );
+      }
+
+      // V-37: checked criteria evidence SHALL resolve
+      if (acceptanceSection) {
+        const checkedLines = acceptanceSection
+          .split("\n")
+          .filter((line: string) => /^- \[x\]/.test(line));
+        for (const line of checkedLines) {
+          const evidenceMatch = line.match(/\(evidence:\s*(.+?)\)/);
+          if (!evidenceMatch) continue;
+          const evidence = evidenceMatch[1]!.trim();
+
+          if (evidence.startsWith("probe:")) {
+            const refId = evidence.slice("probe:".length).trim();
+            const hasProbe = probes.some((p) => p.criterion === refId);
+            if (!criteriaEval.criterionIds.includes(refId)) {
+              addViolation(
+                rfcId,
+                relFile,
+                "V-37",
+                `evidence "probe:${refId}" references a criterion that does not exist in acceptance criteria`,
+              );
+            } else if (!hasProbe) {
+              addViolation(
+                rfcId,
+                relFile,
+                "V-37",
+                `evidence "probe:${refId}" references a criterion with no bound probe`,
+              );
+            }
+          } else if (evidence.startsWith("test:")) {
+            const testPath = evidence.slice("test:".length).trim();
+            try {
+              await stat(path.join(workspaceRoot, testPath));
+            } catch {
+              addViolation(
+                rfcId,
+                relFile,
+                "V-37",
+                `evidence "test:${testPath}" references a file that does not exist`,
+              );
+            }
+          } else if (/^[^:]+:\d+$/.test(evidence)) {
+            const lastColon = evidence.lastIndexOf(":");
+            const filePath = evidence.slice(0, lastColon).trim();
+            try {
+              await stat(path.join(workspaceRoot, filePath));
+            } catch {
+              addViolation(
+                rfcId,
+                relFile,
+                "V-37",
+                `evidence "${evidence}" references a file that does not exist`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // V-38..V-42: criteria content rules (RFC-1006, post-cutoff only)
+  const isCriteriaPostCutoff = createdAt >= RFC_CRITERIA_CONTENT_CUTOFF && !isArchived;
+  if (isCriteriaPostCutoff) {
+    const severity: "error" | "warning" = status === "draft" ? "warning" : "error";
+
+    // V-38: document readiness completeness for accepted+ RFCs
+    const drEval = evaluateDocumentReadiness(body);
+    if (drEval.totalUnchecked > 0 && (status === "accepted" || status === "implemented")) {
+      addViolation(
+        rfcId,
+        relFile,
+        "V-38",
+        `status is "${status}" but ${drEval.totalUnchecked} document readiness criteria are unchecked in "## Document readiness" section.`,
+        severity,
+      );
+    }
+
+    // V-39: non-atomic criterion
+    for (const v of criteriaEval.nonAtomicViolations) {
+      addViolation(
+        rfcId,
+        relFile,
+        "V-39",
+        `acceptance criterion ${v.acId} is non-atomic (contains "and" joining two behaviors): "${v.line}". Split into separate criteria.`,
+        severity,
+      );
+    }
+
+    // V-40: unbounded quantity
+    for (const v of criteriaEval.unboundedQuantityViolations) {
+      addViolation(
+        rfcId,
+        relFile,
+        "V-40",
+        `acceptance criterion ${v.acId} contains unbounded quantity "${v.trigger}": state a specific number or reference the decision that will set it.`,
+        severity,
+      );
+    }
+
+    // V-41: weasel verb
+    for (const v of criteriaEval.weaselVerbViolations) {
+      addViolation(
+        rfcId,
+        relFile,
+        "V-41",
+        `acceptance criterion ${v.acId} contains weasel verb "${v.trigger}": replace with a specific observable behavior.`,
+        severity,
+      );
+    }
+
+    // V-42: malformed supersession annotation
+    for (const line of criteriaEval.malformedSupersessionAnnotations) {
+      addViolation(
+        rfcId,
+        relFile,
+        "V-42",
+        `malformed criterion supersession annotation (expected "> Superseded AC-N (YYYY-MM-DD): <reason>"): "${line}"`,
+        "error",
+      );
+    }
   }
 
   // V-15: title consistency

package/os/rfc/handlers/validate.ts

@@ -24,10 +24,16 @@ import type {
   ForgeCommandResult,
   ForgeRuntimeContext,
 } from "../../../src/types.ts";
-import type { RfcValidationViolation, RfcValidationResult, Marker } from "../types.ts";
-import { RFC_DIR, RFC_KNOWN_KEYS } from "../types.ts";
+import type {
+  RfcValidationViolation,
+  RfcValidationResult,
+  Marker,
+  ProbeCoverageReport,
+} from "../types.ts";
+import { RFC_DIR, RFC_KNOWN_KEYS, RFC_PROBE_BINDING_CUTOFF } from "../types.ts";
 import { DNA_DOCS, AP_DOCS, loadInvariantIds } from "./shared.ts";
 import { collectRfcCommandLifecycleViolations } from "./lifecycle.ts";
+import { evaluateAcceptanceCriteria, computeProbeCoverage } from "./validate-rules.ts";
 import { validateSingleRfc, checkFrontmatterYamlParse } from "./validate-rules.ts";
 
 export async function runRfcValidate(
@@ -60,6 +66,7 @@ export async function runRfcValidate(
 
   const violations: RfcValidationViolation[] = [];
   const allMarkers: Marker[] = [];
+  const coverage: Array<{ rfcId: string; report: ProbeCoverageReport }> = [];
 
   function addViolation(
     rfcId: string,
@@ -108,6 +115,16 @@ export async function runRfcValidate(
       seenFilenameNumbers,
     );
     allMarkers.push(...markers);
+
+    const fm = result.parsed.frontmatter;
+    const rfcId = String(fm["id"] ?? "");
+    const createdAt = String(fm["createdAt"] ?? "");
+    const isArchived = fileName.startsWith("archive/");
+    if (createdAt >= RFC_PROBE_BINDING_CUTOFF && !isArchived) {
+      const criteriaEval = evaluateAcceptanceCriteria(result.parsed.body);
+      const report = computeProbeCoverage(criteriaEval.criterionIds, fm["acceptance"]);
+      coverage.push({ rfcId, report });
+    }
   }
 
   const lifecycle = await collectRfcCommandLifecycleViolations(
@@ -161,6 +178,7 @@ export async function runRfcValidate(
       count: filesToValidate.length,
       violations,
       markers: allMarkers,
+      coverage: coverage.length > 0 ? coverage : undefined,
     },
     exitCode: hasErrors ? 1 : 0,
     summary: hasErrors

package/os/rfc/rfc-0000-template.md

@@ -57,14 +57,18 @@ nonGoals: []
 # automatically inside build pipelines).
 # acceptance:
 #   - probe: run
+#     criterion: AC-1
 #     command: "pnpm exec forge some.command.validate"
 #     expect:
 #       exitCode: 0
 #   - probe: file-exists
+#     criterion: AC-2
 #     path: "packages/my-package/src/some-new-module.ts"
 #   - probe: command-registered
+#     criterion: AC-3
 #     name: "some.new.command"
 #   - probe: file-contains
+#     criterion: AC-4
 #     path: "AGENTS.md"
 #     pattern: "Some new governance paragraph"
 ---
@@ -194,16 +198,28 @@ interface ExampleResult {
      Include: performance impact, false positive rate, maintenance burden,
      risk of agents misinterpreting this RFC. -->
 
+## Document readiness
+
+<!-- Optional (RFC-1006). RFC-phase criteria: document quality gates that verify
+     the RFC itself is ready for acceptance. These are NOT EARS statements about
+     system behavior — they are checks that the document is complete.
+     Use DR-N: identifiers. V-38 enforces completeness for accepted+ post-cutoff RFCs.
+
+- [ ] DR-1: Every considered alternative has a stated reason for rejection (evidence: file: <path:line>)
+- [ ] DR-2: The RFC enumerates every existing artifact it touches (evidence: file: <path:line>)
+- [ ] DR-3: The RFC states whether the decision is reversible and at what cost
+-->
+
 ## Acceptance criteria
 
-- [ ] TypeScript types and interfaces defined in the relevant package
-- [ ] CLI command registered with correct name and scope
-- [ ] `--json` output format documented and stable
-- [ ] Integrated into appropriate pipeline (`build.check` or standalone)
-- [ ] Existing apps pass without changes (or migration path is documented)
-- [ ] `AGENTS.md` updated where agent behavior rules changed
-- [ ] Relevant Architecture DNA or spec docs link to this RFC
-- [ ] `rfc.validate` passes on this file before merging
+<!-- Authoring standard: see packages/forge/skills/fo/fo-idea-create-rfc/acceptance-criteria-standard.md (RFC-0996).
+     Each criterion is a falsifiable claim about an observable artifact, written in EARS form with a stable AC-N: identifier.
+     Required mix: behavior, contract, negative, sync. 3–10 items. One claim = one checking mechanism. -->
+
+- [ ] AC-1: WHEN `<command> --json` is invoked, THE command SHALL return a JSON object matching the documented output schema (evidence: probe:AC-1 or test: <path>)
+- [ ] AC-2: THE `<command>` SHALL be registered in the kernel module with the correct name and scope (evidence: file: <module-path>)
+- [ ] AC-3: IF `<command>` receives invalid input, THEN THE command SHALL report a blocking error and exit non-zero (evidence: test: <path/to/test>)
+- [ ] AC-4: THE relevant `AGENTS.md` SHALL reference this RFC where agent behavior rules changed (evidence: file: <path:line>)
 
 ## Implementation notes for agents
 

package/os/rfc/rfc.module.ts

@@ -34,6 +34,7 @@ export const forgeRfcModule: ForgeModule = {
     } = await import("./handlers.ts");
     const { runRfcAcceptanceRun } = await import("./acceptance.ts");
     const { runRfcVerificationEmit } = await import("./verification-evidence.ts");
+    const { runRfcVerificationRefresh } = await import("./verification-refresh.ts");
     const { runRfcDnaTraceValidate, runRfcDnaTraceGenerate } = await import("./dna-trace.ts");
     const { runRfcDecisionLogGenerate } = await import("./decision-log.ts");
     const { runRfcSupersedePropose } = await import("./handlers/supersede-propose.ts");
@@ -259,6 +260,33 @@ export const forgeRfcModule: ForgeModule = {
       execute: runRfcVerificationEmit,
     });
 
+    // ── rfc.verification.refresh ────────────────────────────────────────────
+    registry.registerCommand({
+      name: "rfc.verification.refresh",
+      description:
+        "RFC-0999: re-run acceptance probes for implemented RFC(s) and update verification " +
+        "evidence envelopes in-place. Preserves emittedAt, adds lastRefreshedAt, replaces " +
+        "probes[] with fresh results. Requires --id <rfc-id> or --all. Use --dry-run to " +
+        "run probes without writing envelope files.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/rfcs/verification/*.generated.yaml"],
+      reads: ["docs/rfcs/**/*.md", "docs/rfcs/verification/*.generated.yaml"],
+      cacheable: false,
+      flags: {
+        id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0330)." },
+        all: {
+          kind: "boolean",
+          description: "Refresh all implemented RFCs with existing evidence envelopes.",
+        },
+        "dry-run": {
+          kind: "boolean",
+          description: "Run probes and report results without writing envelope files.",
+        },
+      },
+      execute: runRfcVerificationRefresh,
+    });
+
     // ── rfc.dna.trace.validate ───────────────────────────────────────────────
     registry.registerCommand({
       name: "rfc.dna.trace.validate",