@warpgogol/forge 5.3.4 → 6.2.0

package/os/queue/decision-ledger.test.ts

@@ -0,0 +1,163 @@
+import { test, expect, describe, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import { decisionLedgerPath, loadDecisionLedger } from "./manifest.ts";
+import { decisionLedgerSchema } from "./types.ts";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "decision-ledger-test-"));
+  await fs.mkdir(path.join(tmpDir, "docs/queues"), { recursive: true });
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("decisionLedgerSchema (RFC-1250)", () => {
+  test("round-trips the RFC example shape", () => {
+    const ledger = decisionLedgerSchema.parse({
+      id: "block-a.decisions",
+      queue: "block-a",
+      createdAt: "2026-10-09",
+      policies: [
+        {
+          id: "P-1",
+          question: "Blocking or advisory placement for new validators?",
+          answer: "blocking (build.check)",
+          appliesTo: "*",
+        },
+      ],
+      items: [
+        {
+          id: "Q-1",
+          doc: "RFC-1243",
+          stage: "enhance",
+          question: "Which storage backend?",
+          resolutionPath: "none",
+          options: [
+            { label: "localStorage", recommended: true },
+            { label: "unstorage", consequence: "server-side only" },
+          ],
+          status: "open",
+        },
+      ],
+    });
+    expect(ledger.items).toHaveLength(1);
+    expect(ledger.items[0]?.status).toBe("open");
+    expect(ledger.policies).toHaveLength(1);
+  });
+
+  test("status enum rejects unknown values", () => {
+    const result = decisionLedgerSchema.safeParse({
+      id: "x.decisions",
+      queue: "x",
+      createdAt: "2026-10-09",
+      items: [
+        {
+          id: "Q-1",
+          doc: "RFC-1243",
+          stage: "enhance",
+          question: "q",
+          resolutionPath: "none",
+          status: "parked", // not a status — parked is a flag
+        },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("entry id must match Q-N", () => {
+    const result = decisionLedgerSchema.safeParse({
+      id: "x.decisions",
+      queue: "x",
+      createdAt: "2026-10-09",
+      items: [
+        {
+          id: "q1",
+          doc: "RFC-1243",
+          stage: "enhance",
+          question: "q",
+          resolutionPath: "none",
+        },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("defaults: empty policies/items, status open, options []", () => {
+    const ledger = decisionLedgerSchema.parse({
+      id: "x.decisions",
+      queue: "x",
+      createdAt: "2026-10-09",
+      items: [
+        {
+          id: "Q-1",
+          doc: "RFC-1243",
+          stage: "plan",
+          question: "q",
+          resolutionPath: "codebase",
+        },
+      ],
+    });
+    expect(ledger.policies).toEqual([]);
+    expect(ledger.items[0]?.status).toBe("open");
+    expect(ledger.items[0]?.options).toEqual([]);
+  });
+});
+
+describe("decisionLedgerPath / loadDecisionLedger (RFC-1250)", () => {
+  test("sibling path: <stem>.yaml → <stem>.decisions.yaml", () => {
+    expect(decisionLedgerPath("docs/queues/block-a.yaml")).toBe(
+      "docs/queues/block-a.decisions.yaml",
+    );
+    expect(decisionLedgerPath("docs/queues/block-a.yml")).toBe(
+      "docs/queues/block-a.decisions.yaml",
+    );
+  });
+
+  test("absent ledger → null, no errors", async () => {
+    const { ledger, errors } = await loadDecisionLedger(tmpDir, "docs/queues/none.yaml");
+    expect(ledger).toBeNull();
+    expect(errors).toEqual([]);
+  });
+
+  test("valid ledger parses", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/queues/block-a.yaml"),
+      "id: block-a\ncreatedAt: 2026-10-09\nitems: []\n",
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "docs/queues/block-a.decisions.yaml"),
+      "id: block-a.decisions\nqueue: block-a\ncreatedAt: 2026-10-09\nitems:\n  - id: Q-1\n    doc: RFC-1243\n    stage: enhance\n    question: which?\n    resolutionPath: none\n    status: open\n",
+    );
+    const { ledger, errors } = await loadDecisionLedger(tmpDir, "docs/queues/block-a.yaml");
+    expect(errors).toEqual([]);
+    expect(ledger?.items).toHaveLength(1);
+    expect(ledger?.items[0]?.id).toBe("Q-1");
+  });
+
+  test("invalid YAML → QUEUE-01 error on the manifest load path", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/queues/block-b.decisions.yaml"),
+      "id: [unclosed\n",
+    );
+    const { ledger, errors } = await loadDecisionLedger(tmpDir, "docs/queues/block-b.yaml");
+    expect(ledger).toBeNull();
+    expect(errors.some((e) => e.ruleId === "QUEUE-01")).toBe(true);
+  });
+
+  test("schema violation → QUEUE-01 error naming the ledger path", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/queues/block-c.decisions.yaml"),
+      "id: block-c.decisions\nqueue: block-c\ncreatedAt: 2026-10-09\nitems:\n  - id: BAD\n    doc: RFC-1243\n    stage: enhance\n    question: q\n    resolutionPath: none\n",
+    );
+    const { ledger, errors } = await loadDecisionLedger(tmpDir, "docs/queues/block-c.yaml");
+    expect(ledger).toBeNull();
+    expect(errors.some((e) => e.ruleId === "QUEUE-01")).toBe(true);
+    expect(errors[0]?.file).toBe("docs/queues/block-c.decisions.yaml");
+  });
+});

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

@@ -1,18 +1,37 @@
 /*
 <MODULE_CONTRACT>
-<purpose>queue.validate command handler (RFC-1140) — validates a queue
-manifest and reports derived per-item pipeline status plus the next
-actionable item. Read-only; the orchestrator runs this before a queued batch.</purpose>
+<purpose>queue.validate command handler (RFC-1140 + RFC-1250) — validates a
+queue manifest and its decision-ledger sibling, reports derived per-item
+pipeline status plus the next actionable item. QUEUE-07 blocks implementable
+items carrying open decisions. Read-only; the orchestrator runs this before a
+queued batch.</purpose>
 <non-goals>
   <item>Do not execute the queue — this command validates and previews only.</item>
   <item>Do not mutate any files.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1250: decision-ledger wiring — QUEUE-07 open-decision gate on
+  executable items (un-parked opens only; parked items are already gated),
+  per-item decisions counts plus top-level totals, `next` excludes parked and
+  QUEUE-07-blocked items with dependsOn cascade.</item>
   <item>RFC-1140: initial queue.validate handler.</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>
+  <item>RFC-1250: re-review wave — blocked dependsOn cascade, manifest-failure gating, generated artifacts</item>
 </CHANGE_SUMMARY>
 */
 
@@ -22,8 +41,95 @@ import type {
   ForgeRuntimeContext,
 } from "../../../src/types.ts";
 import { deriveQueueReport } from "../../../src/pipeline-status.ts";
-import { loadQueueManifest } from "../manifest.ts";
-import type { QueueValidateResult } from "../types.ts";
+import { loadDecisionLedger, loadQueueManifest } from "../manifest.ts";
+import type { DecisionEntry, DecisionLedger, QueueValidateResult } from "../types.ts";
+
+interface DecisionSummary {
+  open: number;
+  /** Open entries WITHOUT parked: true — the QUEUE-07 blocking subset. */
+  openUnparked: number;
+  answered: number;
+  deferred: number;
+  autoResolved: number;
+  /** true when an open entry carries parked: true (hard-stop during execution). */
+  parked: boolean;
+}
+
+function summarizeDecisions(ledger: DecisionLedger | null): Map<string, DecisionSummary> {
+  const summaries = new Map<string, DecisionSummary>();
+  if (!ledger) return summaries;
+  for (const entry of ledger.items as DecisionEntry[]) {
+    const doc = entry.doc.toUpperCase();
+    const s = summaries.get(doc) ?? {
+      open: 0,
+      openUnparked: 0,
+      answered: 0,
+      deferred: 0,
+      autoResolved: 0,
+      parked: false,
+    };
+    if (entry.status === "open") {
+      s.open += 1;
+      if (entry.parked === true) {
+        s.parked = true;
+      } else {
+        s.openUnparked += 1;
+      }
+    } else if (entry.status === "answered") {
+      s.answered += 1;
+    } else if (entry.status === "deferred") {
+      s.deferred += 1;
+    } else if (entry.status === "auto-resolved") {
+      s.autoResolved += 1;
+    }
+    summaries.set(doc, s);
+  }
+  return summaries;
+}
+
+/** Fixed-point `dependsOn` cascade: a dependent of an excluded root is excluded. */
+function cascadeDependents(
+  roots: ReadonlySet<string>,
+  dependsOn: Map<string, string[]>,
+): Set<string> {
+  const excluded = new Set(roots);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [itemId, deps] of dependsOn) {
+      if (excluded.has(itemId)) continue;
+      if (deps.some((dep) => excluded.has(dep))) {
+        excluded.add(itemId);
+        changed = true;
+      }
+    }
+  }
+  return excluded;
+}
+
+/**
+ * RFC-1250 parking: an item is parked when its ledger carries `deferred`
+ * entries (operator parked it at a window) or `open` entries with
+ * `parked: true` (system hard-stop during execution). An item whose in-queue
+ * `dependsOn` target is parked is itself parked — fixed-point cascade.
+ */
+function computeParkedDocIds(
+  itemIds: string[],
+  dependsOn: Map<string, string[]>,
+  summaries: Map<string, DecisionSummary>,
+): Set<string> {
+  const roots = new Set<string>();
+  for (const id of itemIds) {
+    const s = summaries.get(id.toUpperCase());
+    if (s && (s.deferred > 0 || s.parked)) roots.add(id.toUpperCase());
+  }
+  return cascadeDependents(roots, dependsOn);
+}
+
+/** QUEUE-07: an item derivable to the implement stage must not carry open decisions. */
+function isImplementable(item: { status: string; pipelineStep?: string; kind?: string }): boolean {
+  return item.pipelineStep === "implement" || (item.kind === "adr" && item.status === "pending");
+}
 
 export async function runQueueValidate(
   input: ForgeCommandInput,
@@ -36,9 +142,29 @@ export async function runQueueValidate(
     throw new Error("queue.validate requires --file <path-to-manifest.yaml>");
   }
 
-  const { manifest, errors, warnings } = await loadQueueManifest(workspaceRoot, file);
+  const { manifest, errors, warnings, dependsOn } = await loadQueueManifest(workspaceRoot, file);
+
+  // The ledger is part of the queue's durable state — its load errors block.
+  const {
+    ledger,
+    errors: ledgerErrors,
+    warnings: ledgerWarnings,
+  } = await loadDecisionLedger(workspaceRoot, file, manifest);
+  errors.push(...ledgerErrors);
+  warnings.push(...ledgerWarnings);
+
+  const summaries = summarizeDecisions(ledger);
+  const parkedIds = computeParkedDocIds(
+    manifest.items.map((i) => i.id),
+    dependsOn,
+    summaries,
+  );
 
-  const report =
+  // QUEUE-07: an executable item — implementable and not already parked —
+  // must not carry un-parked open decisions. Parked items are already
+  // excluded from execution by the park itself; their opens surface through
+  // the decision window's arbitration, not a second gate.
+  const derivable =
     errors.length === 0
       ? await deriveQueueReport(
           workspaceRoot,
@@ -46,15 +172,70 @@ export async function runQueueValidate(
         )
       : { items: [], next: null };
 
+  const blockedIds = new Set<string>();
+  for (const item of derivable.items) {
+    const s = summaries.get(item.id);
+    if (isImplementable(item) && !parkedIds.has(item.id) && s && s.openUnparked > 0) {
+      blockedIds.add(item.id);
+      errors.push({
+        ruleId: "QUEUE-07",
+        severity: "error",
+        message: `Item "${item.id}" is implementable but carries ${s.openUnparked} open decision(s) — resolve the decision window first`,
+        file,
+      });
+    }
+  }
+
+  // Excluded from `next`: parked items, QUEUE-07-blocked items, and the
+  // dependsOn dependents of either — a dependent must not execute while its
+  // dependency sits unresolved behind the window.
+  const excludedFromNext = new Set([...parkedIds, ...cascadeDependents(blockedIds, dependsOn)]);
+  const report = {
+    items: derivable.items,
+    next:
+      derivable.items.find(
+        (i) =>
+          (i.status === "pending" || i.status === "in-progress") && !excludedFromNext.has(i.id),
+      )?.id ?? null,
+  };
+
+  for (const item of report.items) {
+    const s = summaries.get(item.id);
+    if (s) {
+      item.decisions = {
+        open: s.open,
+        deferred: s.deferred,
+        autoResolved: s.autoResolved,
+      };
+    }
+  }
+
   const status = errors.length === 0 ? "pass" : "fail";
 
+  const decisionTotals = ledger
+    ? {
+        open: ledger.items.filter((e) => e.status === "open").length,
+        answered: ledger.items.filter((e) => e.status === "answered").length,
+        deferred: ledger.items.filter((e) => e.status === "deferred").length,
+        autoResolved: ledger.items.filter((e) => e.status === "auto-resolved").length,
+      }
+    : undefined;
+
   if (outputFormat === "pretty") {
     logger.section(`Queue: ${manifest.id || file}`);
     for (const item of report.items) {
       const step = item.pipelineStep ? ` (${item.pipelineStep})` : "";
-      logger.info(`  ${item.id}: ${item.status}${step}`);
+      const decisions = item.decisions
+        ? ` [decisions: ${item.decisions.open} open, ${item.decisions.deferred} deferred, ${item.decisions.autoResolved} auto-resolved]`
+        : "";
+      logger.info(`  ${item.id}: ${item.status}${step}${decisions}`);
     }
     logger.info(`next: ${report.next ?? "—"}`);
+    if (decisionTotals) {
+      logger.info(
+        `decisions: ${decisionTotals.open} open, ${decisionTotals.answered} answered, ${decisionTotals.autoResolved} auto-resolved, ${decisionTotals.deferred} deferred`,
+      );
+    }
     for (const w of warnings) {
       logger.warn(`  ${w.ruleId}: ${w.message}`);
     }
@@ -71,6 +252,7 @@ export async function runQueueValidate(
       file,
       items: report.items,
       next: report.next,
+      decisions: decisionTotals,
       errors,
       warnings,
     },

package/os/queue/manifest.ts

@@ -2,17 +2,37 @@
 <MODULE_CONTRACT>
 <purpose>Queue manifest loading and validation (RFC-1140) — YAML parse, zod
 schema, id↔filename stem check, item id pattern, document resolution across
-active and archive dirs, duplicate detection, and dependsOn order warnings.</purpose>
+active and archive dirs, duplicate detection, and dependsOn order warnings.
+Also loads the decision-ledger sibling (RFC-1250).</purpose>
 <non-goals>
   <item>Do not derive item status — that is src/pipeline-status.ts.</item>
   <item>Do not mutate the manifest file.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1250: loadDecisionLedger — sibling stem.decisions.yaml resolution,
+  ENOENT-only absence (other read errors are QUEUE-01 blocking), schema check,
+  ledger↔manifest binding (queue/id stem QUEUE-02, duplicate Q-N QUEUE-05),
+  hygiene warnings QUEUE-08 (missing answers, foreign doc ids);
+  LoadedQueueManifest exposes resolved dependsOn edges for the parking
+  cascade.</item>
   <item>RFC-1140: initial manifest loader and validator.</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>
+  <item>RFC-1250: re-review wave — blocked dependsOn cascade, manifest-failure gating, generated artifacts</item>
 </CHANGE_SUMMARY>
 */
 
@@ -22,13 +42,15 @@ import YAML from "yaml";
 
 import type { Diagnostic } from "../../src/types.ts";
 import { resolveDocument } from "../../src/pipeline-status.ts";
-import { QUEUE_ITEM_ID_PATTERN, queueManifestSchema } from "./types.ts";
-import type { QueueManifest } from "./types.ts";
+import { QUEUE_ITEM_ID_PATTERN, decisionLedgerSchema, queueManifestSchema } from "./types.ts";
+import type { DecisionLedger, QueueManifest } from "./types.ts";
 
 export interface LoadedQueueManifest {
   manifest: QueueManifest;
   errors: Diagnostic[];
   warnings: Diagnostic[];
+  /** In-queue dependsOn edges resolved from document frontmatter (RFC-1250 parking cascade). */
+  dependsOn: Map<string, string[]>;
 }
 
 function diag(
@@ -66,7 +88,12 @@ export async function loadQueueManifest(
         displayPath,
       ),
     );
-    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+    return {
+      manifest: { id: "", createdAt: "", items: [] },
+      errors,
+      warnings,
+      dependsOn: new Map(),
+    };
   }
 
   let raw: unknown;
@@ -81,7 +108,12 @@ export async function loadQueueManifest(
         displayPath,
       ),
     );
-    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+    return {
+      manifest: { id: "", createdAt: "", items: [] },
+      errors,
+      warnings,
+      dependsOn: new Map(),
+    };
   }
 
   const parsed = queueManifestSchema.safeParse(raw);
@@ -96,7 +128,12 @@ export async function loadQueueManifest(
         ),
       );
     }
-    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+    return {
+      manifest: { id: "", createdAt: "", items: [] },
+      errors,
+      warnings,
+      dependsOn: new Map(),
+    };
   }
 
   const manifest = parsed.data;
@@ -180,5 +217,162 @@ export async function loadQueueManifest(
     }
   }
 
-  return { manifest, errors, warnings };
+  return { manifest, errors, warnings, dependsOn: resolvedDependsOn };
+}
+
+// ---------------------------------------------------------------------------
+// Decision ledger (RFC-1250) — sibling <stem>.decisions.yaml of the manifest
+// ---------------------------------------------------------------------------
+
+export interface LoadedDecisionLedger {
+  ledger: DecisionLedger | null;
+  errors: Diagnostic[];
+  warnings: Diagnostic[];
+}
+
+/** Manifest `docs/queues/<id>.yaml` → sibling ledger `docs/queues/<id>.decisions.yaml`. */
+export function decisionLedgerPath(manifestPath: string): string {
+  return manifestPath.replace(/\.(ya?ml)$/i, ".decisions.yaml");
+}
+
+/**
+ * Load the decision ledger sibling of a queue manifest. An absent ledger is
+ * legal — it means zero recorded decisions. An unreadable or schema-invalid
+ * ledger joins the manifest load path as a QUEUE-01 blocking error: the ledger
+ * is part of the queue's durable state.
+ */
+export async function loadDecisionLedger(
+  workspaceRoot: string,
+  filePath: string,
+  manifest?: QueueManifest,
+): Promise<LoadedDecisionLedger> {
+  const errors: Diagnostic[] = [];
+  const warnings: Diagnostic[] = [];
+  const ledgerPath = decisionLedgerPath(filePath);
+  const absolutePath = path.isAbsolute(ledgerPath)
+    ? ledgerPath
+    : path.join(workspaceRoot, ledgerPath);
+  const displayPath = path.isAbsolute(ledgerPath)
+    ? path.relative(workspaceRoot, ledgerPath)
+    : ledgerPath;
+
+  let source: string;
+  try {
+    source = await fs.readFile(absolutePath);
+  } catch (e) {
+    // ENOENT = legal absence (zero recorded decisions). Any other read
+    // failure (EACCES, EISDIR, …) is an unreadable durable artifact — the
+    // ledger must never fail open into "no decisions" or QUEUE-07 disarms.
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+      return { ledger: null, errors, warnings };
+    }
+    errors.push(
+      diag(
+        "QUEUE-01",
+        "error",
+        `Cannot read decision ledger: ${e instanceof Error ? e.message : String(e)}`,
+        displayPath,
+      ),
+    );
+    return { ledger: null, errors, warnings };
+  }
+
+  let raw: unknown;
+  try {
+    raw = YAML.parse(source);
+  } catch (e) {
+    errors.push(
+      diag(
+        "QUEUE-01",
+        "error",
+        `Decision ledger YAML parse error: ${e instanceof Error ? e.message : String(e)}`,
+        displayPath,
+      ),
+    );
+    return { ledger: null, errors, warnings };
+  }
+
+  const parsed = decisionLedgerSchema.safeParse(raw);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      errors.push(
+        diag(
+          "QUEUE-01",
+          "error",
+          `Decision ledger schema violation at ${issue.path.join(".") || "<root>"}: ${issue.message}`,
+          displayPath,
+        ),
+      );
+    }
+    return { ledger: null, errors, warnings };
+  }
+
+  const ledger = parsed.data;
+
+  // Binding and hygiene checks require a successfully loaded manifest — when
+  // the manifest itself failed, the stub (empty id, no items) would blame a
+  // healthy ledger for a broken queue (QUEUE-02 against "") and flag every
+  // entry as foreign (QUEUE-08). The manifest failure already blocks.
+  const manifestId = manifest?.id ?? "";
+  const manifestReady = manifestId !== "";
+
+  // QUEUE-02-family binding: the ledger belongs to exactly one manifest —
+  // `queue` names the manifest id and `id` names the ledger filename stem
+  // (`<manifest-stem>.decisions`). A misplaced or copy-pasted ledger must not
+  // silently apply foreign decisions to this queue.
+  const ledgerStem = path.basename(absolutePath).replace(/\.(ya?ml)$/i, "");
+  if (manifestReady && ledger.queue !== manifestId) {
+    errors.push(
+      diag(
+        "QUEUE-02",
+        "error",
+        `Decision ledger queue "${ledger.queue}" does not match manifest id "${manifestId}"`,
+        displayPath,
+      ),
+    );
+  }
+  if (ledger.id !== ledgerStem) {
+    errors.push(
+      diag(
+        "QUEUE-02",
+        "error",
+        `Decision ledger id "${ledger.id}" does not match filename stem "${ledgerStem}"`,
+        displayPath,
+      ),
+    );
+  }
+
+  // QUEUE-05-family: decision ids are queue-global — window codes and
+  // PENDING DECISION markers address them, so duplicates corrupt arbitration.
+  const seenDecisions = new Set<string>();
+  const manifestDocs = new Set((manifest?.items ?? []).map((i) => i.id.trim().toUpperCase()));
+  for (const entry of ledger.items) {
+    if (seenDecisions.has(entry.id)) {
+      errors.push(diag("QUEUE-05", "error", `Duplicate decision id "${entry.id}"`, displayPath));
+      continue;
+    }
+    seenDecisions.add(entry.id);
+    if ((entry.status === "answered" || entry.status === "auto-resolved") && !entry.answer) {
+      warnings.push(
+        diag(
+          "QUEUE-08",
+          "warning",
+          `Decision "${entry.id}" is ${entry.status} but carries no answer — implement has nothing to bind`,
+          displayPath,
+        ),
+      );
+    }
+    if (manifestReady && !manifestDocs.has(entry.doc.toUpperCase())) {
+      warnings.push(
+        diag(
+          "QUEUE-08",
+          "warning",
+          `Decision "${entry.id}" targets "${entry.doc}" which is not a manifest item — invisible to this queue`,
+          displayPath,
+        ),
+      );
+    }
+  }
+
+  return { ledger, errors, warnings };
 }