@warpgogol/forge 5.3.4 → 6.2.0

package/os/queue/queue-validate.test.ts

@@ -117,6 +117,309 @@ describe("loadQueueManifest — validation rules (RFC-1140)", () => {
   });
 });
 
+async function writeLedger(manifestName: string, body: string): Promise<void> {
+  await fs.writeFile(path.join(tmpDir, `docs/queues/${manifestName}.decisions.yaml`), body);
+}
+
+const LEDGER_HEADER = (id: string) => `id: ${id}.decisions\nqueue: ${id}\ncreatedAt: 2026-10-09\n`;
+
+describe("runQueueValidate — decision ledger (RFC-1250)", () => {
+  test("implement-stage item with open entry → QUEUE-07 + exitCode 1 (AC-2)", async () => {
+    await writeRfc("RFC-1500", "status: accepted\n");
+    const file = await writeManifest(
+      "block-q7",
+      "id: block-q7\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1500\n",
+    );
+    await writeLedger(
+      "block-q7",
+      `${LEDGER_HEADER("block-q7")}items:\n  - id: Q-1\n    doc: RFC-1500\n    stage: plan\n    question: which scope?\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.exitCode).toBe(1);
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(true);
+    expect(result?.data?.items[0]?.decisions?.open).toBe(1);
+  });
+
+  test("no QUEUE-07 when entries are answered/auto-resolved/deferred (AC-3)", async () => {
+    await writeRfc("RFC-1501", "status: accepted\n");
+    const file = await writeManifest(
+      "block-q7b",
+      "id: block-q7b\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1501\n",
+    );
+    await writeLedger(
+      "block-q7b",
+      `${LEDGER_HEADER("block-q7b")}items:\n  - id: Q-1\n    doc: RFC-1501\n    stage: plan\n    question: a\n    resolutionPath: none\n    status: answered\n    answer: scope A\n  - id: Q-2\n    doc: RFC-1501\n    stage: implement\n    question: b\n    resolutionPath: convention\n    status: auto-resolved\n    answer: option B\n  - id: Q-3\n    doc: RFC-1501\n    stage: review\n    question: c\n    resolutionPath: none\n    status: deferred\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(false);
+    expect(result?.data?.status).toBe("pass");
+    const d = result?.data?.items[0]?.decisions;
+    expect(d?.open).toBe(0);
+    expect(d?.deferred).toBe(1);
+    expect(d?.autoResolved).toBe(1);
+    expect(result?.data?.decisions).toEqual({
+      open: 0,
+      answered: 1,
+      deferred: 1,
+      autoResolved: 1,
+    });
+  });
+
+  test("no ledger sibling → no QUEUE-07 (AC-4)", async () => {
+    await writeRfc("RFC-1502", "status: accepted\n");
+    const file = await writeManifest(
+      "block-q7c",
+      "id: block-q7c\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1502\n",
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.errors).toEqual([]);
+    expect(result?.data?.items[0]?.decisions).toBeUndefined();
+  });
+
+  test("open entries on pre-implement stages stay legal — no QUEUE-07", async () => {
+    await writeRfc("RFC-1503"); // status: draft, no artifacts → pending
+    const file = await writeManifest(
+      "block-q7d",
+      "id: block-q7d\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1503\n",
+    );
+    await writeLedger(
+      "block-q7d",
+      `${LEDGER_HEADER("block-q7d")}items:\n  - id: Q-1\n    doc: RFC-1503\n    stage: enhance\n    question: q\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(false);
+    expect(result?.data?.status).toBe("pass");
+  });
+
+  test("pending ADR with open entry → QUEUE-07", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/adrs/adr-1504-test.md"),
+      "---\nid: ADR-1504\nstatus: proposed\n---\n# ADR-1504\n",
+    );
+    const file = await writeManifest(
+      "block-q7e",
+      "id: block-q7e\ncreatedAt: 2026-10-09\nitems:\n  - id: ADR-1504\n",
+    );
+    await writeLedger(
+      "block-q7e",
+      `${LEDGER_HEADER("block-q7e")}items:\n  - id: Q-1\n    doc: ADR-1504\n    stage: implement\n    question: which adapter?\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(true);
+    expect(result?.exitCode).toBe(1);
+  });
+
+  test("next skips deferred and parked items, dependsOn cascades (AC-5)", async () => {
+    await writeRfc("RFC-1510", "status: accepted\n");
+    await writeRfc("RFC-1511", "status: draft\ndependsOn:\n  - RFC-1510\n");
+    await writeRfc("RFC-1512");
+    const file = await writeManifest(
+      "block-park",
+      "id: block-park\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1510\n  - id: RFC-1511\n  - id: RFC-1512\n",
+    );
+    // RFC-1510 operator-deferred → parked; RFC-1511 dependsOn it → cascade-parked;
+    // next must be RFC-1512.
+    await writeLedger(
+      "block-park",
+      `${LEDGER_HEADER("block-park")}items:\n  - id: Q-1\n    doc: RFC-1510\n    stage: implement\n    question: park it\n    resolutionPath: none\n    status: deferred\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.next).toBe("RFC-1512");
+  });
+
+  test("open+parked entry parks the item — no QUEUE-07, next skips, batch stays green", async () => {
+    await writeRfc("RFC-1520", "status: accepted\n");
+    await writeRfc("RFC-1521");
+    const file = await writeManifest(
+      "block-park2",
+      "id: block-park2\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1520\n  - id: RFC-1521\n",
+    );
+    await writeLedger(
+      "block-park2",
+      `${LEDGER_HEADER("block-park2")}items:\n  - id: Q-1\n    doc: RFC-1520\n    stage: implement\n    question: destructive op\n    resolutionPath: none\n    status: open\n    parked: true\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    // A parked open is already execution-gated — QUEUE-07 must not fire on
+    // it (the park is the containment); the item just drops out of `next`.
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(false);
+    expect(result?.data?.next).toBe("RFC-1521");
+    expect(result?.data?.items[0]?.decisions?.open).toBe(1);
+  });
+
+  test("un-parked open on implementable item blocks it — QUEUE-07 + next skips it", async () => {
+    await writeRfc("RFC-1530", "status: accepted\n");
+    await writeRfc("RFC-1531");
+    const file = await writeManifest(
+      "block-q7-skip",
+      "id: block-q7-skip\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1530\n  - id: RFC-1531\n",
+    );
+    await writeLedger(
+      "block-q7-skip",
+      `${LEDGER_HEADER("block-q7-skip")}items:\n  - id: Q-1\n    doc: RFC-1530\n    stage: plan\n    question: pending answer\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(true);
+    // QUEUE-07-blocked items are not executable — `next` must not name one.
+    expect(result?.data?.next).toBe("RFC-1531");
+  });
+
+  test("ledger bound to a different manifest → QUEUE-02 error", async () => {
+    await writeRfc("RFC-1540", "status: accepted\n");
+    const file = await writeManifest(
+      "block-bind",
+      "id: block-bind\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1540\n",
+    );
+    await writeLedger(
+      "block-bind",
+      `id: block-bind.decisions\nqueue: other-queue\ncreatedAt: 2026-10-09\nitems: []\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-02")).toBe(true);
+  });
+
+  test("ledger id mismatching filename stem → QUEUE-02 error", async () => {
+    await writeRfc("RFC-1541", "status: accepted\n");
+    const file = await writeManifest(
+      "block-stem",
+      "id: block-stem\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1541\n",
+    );
+    await writeLedger(
+      "block-stem",
+      `id: wrong-id\nqueue: block-stem\ncreatedAt: 2026-10-09\nitems: []\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-02")).toBe(true);
+  });
+
+  test("duplicate decision id → QUEUE-05 error", async () => {
+    await writeRfc("RFC-1542", "status: draft\n");
+    const file = await writeManifest(
+      "block-dup",
+      "id: block-dup\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1542\n",
+    );
+    await writeLedger(
+      "block-dup",
+      `${LEDGER_HEADER("block-dup")}items:\n  - id: Q-1\n    doc: RFC-1542\n    stage: enhance\n    question: a\n    resolutionPath: none\n  - id: Q-1\n    doc: RFC-1542\n    stage: plan\n    question: b\n    resolutionPath: none\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-05")).toBe(true);
+  });
+
+  test("answered entry without answer → QUEUE-08 warning, not blocking", async () => {
+    await writeRfc("RFC-1543", "status: accepted\n");
+    const file = await writeManifest(
+      "block-noans",
+      "id: block-noans\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1543\n",
+    );
+    await writeLedger(
+      "block-noans",
+      `${LEDGER_HEADER("block-noans")}items:\n  - id: Q-1\n    doc: RFC-1543\n    stage: plan\n    question: a\n    resolutionPath: none\n    status: answered\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.warnings.some((w) => w.ruleId === "QUEUE-08")).toBe(true);
+  });
+
+  test("decision targeting a foreign doc → QUEUE-08 warning", async () => {
+    await writeRfc("RFC-1544", "status: accepted\n");
+    const file = await writeManifest(
+      "block-foreign",
+      "id: block-foreign\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1544\n",
+    );
+    await writeLedger(
+      "block-foreign",
+      `${LEDGER_HEADER("block-foreign")}items:\n  - id: Q-1\n    doc: RFC-9998\n    stage: plan\n    question: a\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.warnings.some((w) => w.ruleId === "QUEUE-08")).toBe(true);
+  });
+
+  test("QUEUE-07-blocked item cascades exclusion to dependsOn dependents", async () => {
+    await writeRfc("RFC-1550", "status: accepted\n");
+    await writeRfc("RFC-1551", "status: draft\ndependsOn:\n  - RFC-1550\n");
+    await writeRfc("RFC-1552");
+    const file = await writeManifest(
+      "block-q7-cascade",
+      "id: block-q7-cascade\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1550\n  - id: RFC-1551\n  - id: RFC-1552\n",
+    );
+    await writeLedger(
+      "block-q7-cascade",
+      `${LEDGER_HEADER("block-q7-cascade")}items:\n  - id: Q-1\n    doc: RFC-1550\n    stage: plan\n    question: unresolved\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-07")).toBe(true);
+    // RFC-1551 is pending and has no open decisions, but it depends on a
+    // QUEUE-07-blocked item — it must not execute before its dependency.
+    expect(result?.data?.next).toBe("RFC-1552");
+  });
+
+  test("broken manifest + valid ledger → no spurious QUEUE-02/QUEUE-08 noise", async () => {
+    await writeRfc("RFC-1560", "status: accepted\n");
+    const file = await writeManifest("block-broken", "id: [\n"); // unparseable YAML
+    await writeLedger(
+      "block-broken",
+      `${LEDGER_HEADER("block-broken")}items:\n  - id: Q-1\n    doc: RFC-1560\n    stage: plan\n    question: q\n    resolutionPath: none\n    status: open\n`,
+    );
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-02")).toBe(false);
+    expect(result?.data?.warnings.some((w) => w.ruleId === "QUEUE-08")).toBe(false);
+  });
+
+  test("unreadable ledger (non-ENOENT) → QUEUE-01 error, never fails open", async () => {
+    await writeRfc("RFC-1545", "status: accepted\n");
+    const file = await writeManifest(
+      "block-eisdir",
+      "id: block-eisdir\ncreatedAt: 2026-10-09\nitems:\n  - id: RFC-1545\n",
+    );
+    // A directory at the ledger path → EISDIR on read: not legal absence.
+    await fs.mkdir(path.join(tmpDir, "docs/queues/block-eisdir.decisions.yaml"));
+
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.errors.some((e) => e.ruleId === "QUEUE-01")).toBe(true);
+  });
+});
+
 describe("runQueueValidate — command contract (RFC-1140)", () => {
   test("throws without --file", async () => {
     await expect(runQueueValidate({ argv: [], flags: {} }, testContext())).rejects.toThrow(

package/os/queue/queue.module.ts

@@ -13,6 +13,20 @@ Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, r
   <item>RFC-1140: queue.validate missing contract/rules metadata (DNA-91)
 
 fo-review REVIEW-CODE-2026-09-23-01 finding: declare contract queue and emitted ruleIds QUEUE-01..06 so validator.inventory.generate does not fail closed. Manifest regenerated.</item>
+  <item>RFC-1250: review wave — QUEUE-07 gates un-parked opens only, ledger binding checks, fail-closed loader
+
+REVIEW-RFC-1250-01 findings: QUEUE-07 no longer fires on parked entries
+(the park is the containment — a parked queue stays resumable and the
+decision window arbitrates it); loader fails open only on ENOENT —
+other read errors are QUEUE-01; ledger gains queue/id-stem binding
+(QUEUE-02), Q-N uniqueness (QUEUE-05), and QUEUE-08 hygiene warnings
+(missing answers, foreign doc ids); next excludes QUEUE-07-blocked
+items; top-level decision totals added. Orchestrator pre-flight treats
+QUEUE-07 as the window agenda — structural errors still stop the batch;
+maturation skips parked/deferred items; uncovered imperative ask sites
+gain collect riders (ADR code-trace, NC markers, audit-verdict guard).</item>
+  <item>RFC-1250: re-review wave — blocked dependsOn cascade, manifest-failure gating, generated artifacts</item>
+  <history>RFC-1250</history>
 </CHANGE_SUMMARY>
 */
 
@@ -29,12 +43,26 @@ export async function createForgeQueueModule(): Promise<ForgeModule> {
       {
         name: "queue.validate",
         description:
-          "Validate a queue manifest (docs/queues/*.yaml) and report derived " +
-          "per-item pipeline status plus the next actionable item. Read-only — " +
-          "the pipeline orchestrator runs this before starting a queued batch (RFC-1140). Required flags: `--file`.",
+          "Validate a queue manifest (docs/queues/*.yaml) and its decision " +
+          "ledger sibling, report derived per-item pipeline status plus the " +
+          "next actionable item. QUEUE-07 blocks implementable items carrying " +
+          "un-parked open decisions (RFC-1250); QUEUE-08 warns on ledger " +
+          "hygiene issues (missing answers, foreign doc ids). Read-only — " +
+          "the pipeline orchestrator runs this before a queued batch and the " +
+          "decision window consumes its diagnostics (RFC-1140). " +
+          "Required flags: `--file`.",
         scope: "workspace",
         contract: "queue",
-        rules: ["QUEUE-01", "QUEUE-02", "QUEUE-03", "QUEUE-04", "QUEUE-05", "QUEUE-06"],
+        rules: [
+          "QUEUE-01",
+          "QUEUE-02",
+          "QUEUE-03",
+          "QUEUE-04",
+          "QUEUE-05",
+          "QUEUE-06",
+          "QUEUE-07",
+          "QUEUE-08",
+        ],
         mutatesState: false,
         reads: [
           "docs/queues/*.yaml",

package/os/queue/types.ts

@@ -7,10 +7,23 @@ block consumed by queue.validate and the pipeline orchestrator's queue mode.</pu
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1250: decision-ledger schemas — DecisionLedger, DecisionEntry, DecisionStatus, policies.</item>
   <item>RFC-1140: initial QueueManifest schema and queue.validate result types.</item>
   <item>RFC-1140: steps 1-4 — shared resolver, queue module, registration
 
 Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, refactor rfc.pipeline.status onto it, add os/queue module with queue.validate command, register in WORKSHOP_MODULE_MAP.forge + bin/cli.ts + package.json exports.</item>
+  <item>RFC-1250: review wave — QUEUE-07 gates un-parked opens only, ledger binding checks, fail-closed loader
+
+REVIEW-RFC-1250-01 findings: QUEUE-07 no longer fires on parked entries
+(the park is the containment — a parked queue stays resumable and the
+decision window arbitrates it); loader fails open only on ENOENT —
+other read errors are QUEUE-01; ledger gains queue/id-stem binding
+(QUEUE-02), Q-N uniqueness (QUEUE-05), and QUEUE-08 hygiene warnings
+(missing answers, foreign doc ids); next excludes QUEUE-07-blocked
+items; top-level decision totals added. Orchestrator pre-flight treats
+QUEUE-07 as the window agenda — structural errors still stop the batch;
+maturation skips parked/deferred items; uncovered imperative ask sites
+gain collect riders (ADR code-trace, NC markers, audit-verdict guard).</item>
 </CHANGE_SUMMARY>
 */
 
@@ -21,6 +34,46 @@ import type { QueueItemReport } from "../../src/pipeline-status.ts";
 
 export const QUEUE_ITEM_ID_PATTERN = /^(RFC|ADR)-\d{4}$/;
 
+export const DECISION_STATUS = ["open", "answered", "auto-resolved", "deferred"] as const;
+export type DecisionStatus = (typeof DECISION_STATUS)[number];
+
+export const decisionOptionSchema = z.object({
+  label: z.string().min(1),
+  consequence: z.string().optional(),
+  recommended: z.boolean().optional(),
+});
+
+export const decisionEntrySchema = z.object({
+  id: z.string().regex(/^Q-\d+$/),
+  doc: z.string().regex(QUEUE_ITEM_ID_PATTERN),
+  stage: z.enum(["idea", "enhance", "plan", "implement", "review"]),
+  question: z.string().min(1),
+  resolutionPath: z.enum(["codebase", "convention", "profile", "policy", "none"]),
+  options: z.array(decisionOptionSchema).default([]),
+  status: z.enum(DECISION_STATUS).default("open"),
+  answer: z.string().optional(),
+  answeredAt: z.string().optional(),
+  parked: z.boolean().optional(),
+});
+
+export const decisionPolicySchema = z.object({
+  id: z.string().min(1),
+  question: z.string().min(1),
+  answer: z.string().min(1),
+  appliesTo: z.union([z.literal("*"), z.array(z.string())]),
+});
+
+export const decisionLedgerSchema = z.object({
+  id: z.string().min(1),
+  queue: z.string().min(1),
+  createdAt: z.string().min(1),
+  policies: z.array(decisionPolicySchema).default([]),
+  items: z.array(decisionEntrySchema).default([]),
+});
+
+export type DecisionEntry = z.infer<typeof decisionEntrySchema>;
+export type DecisionLedger = z.infer<typeof decisionLedgerSchema>;
+
 export const queueManifestSchema = z.object({
   id: z.string().min(1),
   createdAt: z.string().min(1),
@@ -42,8 +95,10 @@ export interface QueueValidateResult {
   queue: string;
   file: string;
   items: QueueItemReport[];
-  /** First item whose derived status is pending or in-progress; null when fully terminal. */
+  /** First actionable item — pending/in-progress, not parked or QUEUE-07-blocked; null when none. */
   next: string | null;
+  /** Aggregate decision counts across the ledger (present when a sibling ledger exists). */
+  decisions?: { open: number; answered: number; deferred: number; autoResolved: number };
   errors: Diagnostic[];
   warnings: Diagnostic[];
 }

package/os/rfc/handlers/implement-stamp.ts

@@ -12,8 +12,6 @@ verification evidence, and atomically mutates RFC frontmatter.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0795: add RFC-IMP-07 dependsOn dependency gate — blocks stamping when any dependsOn entry is not implemented.</item>
-  <item>RFC-0997: add RFC-IMP-08 minimum-one-probe gate — blocks stamping for post-cutoff architecture/contract/command RFCs with no acceptance probes.</item>
   <item>RFC-1053: integrate generateRfcMetrics after successful stamp (non-fatal, guarded by !isDryRun).</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run
 
@@ -21,7 +19,9 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — packages/forge + services clean
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <history>RFC-0268, RFC-0476, RFC-0756</history>
+  <item>Session-retro 2026-10-08: auto-detect picks the sole implement/feat-prefixed candidate among multi-commit references (RFC-IMP-03 no longer blocks full pipelines); ambiguous sets keep blocking with annotated candidate list + earliest-candidate suggestion.</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
+  <history>RFC-0268, RFC-0476, RFC-0756, RFC-0795, RFC-0997, RFC-IMP-07</history>
 </CHANGE_SUMMARY>
 */
 
@@ -58,6 +58,11 @@ const VERIFICATION_DIR = join(RFC_DIR, "verification");
 
 // ─── Git helpers ─────────────────────────────────────────────────────────────
 
+// Pipeline convention: the implementation commit's subject carries an
+// `implement:` (or `feat:`) conventional prefix — audit/enhance/plan/docs/
+// review/fix/chore commits referencing the same RFC id never claim it.
+const IMPLEMENTATION_SUBJECT_RE = /^(implement|feat)(\([^)]*\))?!?:/i;
+
 function execGit(workspaceRoot: string, args: string[]): Promise<string> {
   return new Promise((resolve) => {
     execFile("git", args, { cwd: workspaceRoot, timeout: 10000 }, (err, stdout) => {
@@ -347,11 +352,35 @@ export async function runRfcImplementStamp(
         message: `No commit referencing ${targetId} found in git history. Pass --implementation-commit <SHA> explicitly.`,
       });
     } else {
-      const candidateList = detected.multiple.map((c) => `  ${c.sha} — ${c.message}`).join("\n");
-      violations.push({
-        rule: "RFC-IMP-03",
-        message: `Multiple commits reference ${targetId}:\n${candidateList}\nPass --implementation-commit <SHA> to specify which one.`,
-      });
+      // Auto-resolve when exactly one candidate looks like an implementation
+      // commit — a multi-commit RFC pipeline (audit → plan → implement → docs →
+      // review) references the id at every step, but only one step implements.
+      const implCandidates = detected.multiple.filter((c) =>
+        IMPLEMENTATION_SUBJECT_RE.test(c.message),
+      );
+      if (implCandidates.length === 1) {
+        implementationCommit = implCandidates[0]!.sha;
+        logger.info(
+          `[rfc.implement.stamp] auto-selected implementation commit ${implCandidates[0]!.sha} (sole implement/feat-prefixed candidate)`,
+        );
+      } else {
+        const candidateList = detected.multiple
+          .map(
+            (c) =>
+              `  ${c.sha} — ${c.message}${IMPLEMENTATION_SUBJECT_RE.test(c.message) ? "  [implementation-shaped]" : ""}`,
+          )
+          .join("\n");
+        // git log lists newest first — the earliest implementation-shaped
+        // commit is the most likely canonical pick for a step-wise wave.
+        const earliest = implCandidates[implCandidates.length - 1];
+        const suggestion = earliest
+          ? `\nLikely: ${earliest.sha} (earliest implementation-shaped commit).`
+          : "";
+        violations.push({
+          rule: "RFC-IMP-03",
+          message: `Multiple commits reference ${targetId}:\n${candidateList}\nPass --implementation-commit <SHA> to specify which one.${suggestion}`,
+        });
+      }
     }
   }
 

package/os/rfc/rfc-read-only-no-side-effects.test.ts

@@ -37,6 +37,7 @@ function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
 
 async function snapshotTree(root: string): Promise<Map<string, string>> {
   const snapshot = new Map<string, string>();
+  // fs.walk.lint: allow — test snapshot helper collects file contents into a Map, not a path list — collectFiles does not read contents
   async function walk(dir: string): Promise<void> {
     for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
       const full = path.join(dir, entry.name);

package/os/rfc/rfc.module.ts

@@ -7,15 +7,14 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0260: declare typed `flags` schemas for the whole rfc.* command family; unknown/malformed flags now fail with KERNEL-FLAG-01/02/03 instead of being silently ignored.</item>
-  <item>RFC-0795: add `--batch` flag to `rfc.list` for filtering by batch slug.</item>
-  <item>RFC-1097: step 6 — compass.migrate codemod run
-
-Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
   <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>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
+  <item>RFC-1231: rfc.verification.refresh gains acceptsAllFlag: true — the declared --all flag is now reachable via werkstatt run (consumed selector re-injected as flags.all after the gate).</item>
+  <item>RFC-1237: honor dry-run via context.dryRun across kernel commands; verification envelopes keep emit-canonical ownership</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
+  <history>RFC-0260, RFC-0795, RFC-1097</history>
 </CHANGE_SUMMARY>
 */
 
@@ -114,6 +113,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.next-id",
+        coverage: "operator" as const,
         mutatesState: false,
         description:
           "Return the next free RFC number (max existing + 1) by scanning docs/rfcs/ recursively including archive/.",
@@ -212,6 +212,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.graph",
+        coverage: "operator" as const,
         mutatesState: false,
         description:
           "Print one RFC's relationship neighbours (supersedes/supersededBy/amends/" +
@@ -249,7 +250,8 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
         description:
           "RFC-0330: execute acceptance probes for target RFC(s) and write per-RFC verification " +
           "evidence artifacts to docs/rfcs/verification/*.generated.yaml. Requires --id <rfc-id> " +
-          "or --status <status>. Reuses runProbe from RFC-0268. Writes via writeFileAtomic.",
+          "or --status <status>. Reuses runProbe from RFC-0268. Writes via the WorkspaceIO port " +
+          "(io.writeFile); --dry-run runs probes and reports without writing (RFC-1237).",
         scope: "workspace",
         mutatesState: true,
         writes: ["docs/rfcs/verification/*.generated.yaml"],
@@ -262,6 +264,15 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
             kind: "string",
             description: "Target every RFC with this status (e.g. implemented).",
           },
+          "dry-run": {
+            kind: "boolean",
+            description: "Run probes and report results without writing envelope files.",
+          },
+          concurrency: {
+            kind: "string",
+            description:
+              "Bounded parallelism across RFCs for sweep runs (default 1, capped at 16 — invalid values warn and fall back). Probe workers spawn subprocesses.",
+          },
         },
         execute: runRfcVerificationEmit,
       },
@@ -274,6 +285,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
           "probes[] with fresh results. Requires --id <rfc-id> or --all. Use --dry-run to " +
           "run probes without writing envelope files.",
         scope: "workspace",
+        acceptsAllFlag: true,
         mutatesState: true,
         writes: ["docs/rfcs/verification/*.generated.yaml"],
         // Secondary writer — rfc.verification.emit owns these envelopes;
@@ -297,6 +309,11 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
             kind: "boolean",
             description: "Run probes and report results without writing envelope files.",
           },
+          concurrency: {
+            kind: "string",
+            description:
+              "Bounded parallelism across RFCs for sweep runs (default 1, capped at 16 — invalid values warn and fall back). Probe workers spawn subprocesses.",
+          },
         },
         execute: runRfcVerificationRefresh,
       },
@@ -321,6 +338,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.dna.trace.generate",
+        coverage: "operator" as const,
         modulePath: "packages/forge/os/rfc/rfc.module.ts",
         description:
           "RFC-0331: generate docs/rfcs/dna-trace.generated.yaml — the machine-readable " +
@@ -360,6 +378,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.supersede.propose",
+        coverage: "operator" as const,
         description:
           "RFC-0334: escalate a blocked implementation by creating a draft superseding RFC " +
           "with the conflict stated and TODO sections for the proposed alternative.",
@@ -391,6 +410,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.archive",
+        coverage: "operator" as const,
         description:
           "Move terminal-status RFC files (implemented, rejected, superseded) into " +
           "docs/rfcs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
@@ -417,6 +437,7 @@ export async function createForgeRfcModule(): Promise<ForgeModule> {
       },
       {
         name: "rfc.pipeline.status",
+        coverage: "operator" as const,
         mutatesState: false,
         description:
           "Report the pipeline status of RFCs — which steps (audit, enhance, plan, implement) " +