@warpgogol/forge 5.1.2 → 5.2.0

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

@@ -0,0 +1,177 @@
+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 type { ForgeRuntimeContext } from "../../src/types.ts";
+import { runQueueValidate } from "./handlers/queue-validate.ts";
+import { loadQueueManifest } from "./manifest.ts";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "queue-validate-test-"));
+  await fs.mkdir(path.join(tmpDir, "docs/rfcs"), { recursive: true });
+  await fs.mkdir(path.join(tmpDir, "docs/adrs"), { recursive: true });
+  await fs.mkdir(path.join(tmpDir, "docs/queues"), { recursive: true });
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+function testContext(): ForgeRuntimeContext {
+  const logs: string[] = [];
+  return {
+    workspaceRoot: tmpDir,
+    dryRun: false,
+    outputFormat: "json",
+    logger: {
+      section: (m: string) => logs.push(m),
+      info: (m: string) => logs.push(m),
+      warn: (m: string) => logs.push(m),
+      error: (m: string) => logs.push(m),
+      success: (m: string) => logs.push(m),
+    },
+  };
+}
+
+async function writeRfc(id: string, frontmatter = "status: draft\n"): Promise<void> {
+  await fs.writeFile(
+    path.join(tmpDir, `docs/rfcs/${id.toLowerCase()}-test.md`),
+    `---\nid: ${id}\n${frontmatter}---\n# ${id}\n`,
+  );
+}
+
+async function writeManifest(name: string, body: string): Promise<string> {
+  const rel = `docs/queues/${name}.yaml`;
+  await fs.writeFile(path.join(tmpDir, rel), body);
+  return rel;
+}
+
+describe("loadQueueManifest — validation rules (RFC-1140)", () => {
+  test("valid manifest loads with no errors", async () => {
+    await writeRfc("RFC-1300");
+    const file = await writeManifest(
+      "block-a",
+      "id: block-a\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1300\n",
+    );
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors).toEqual([]);
+  });
+
+  test("id↔filename mismatch → QUEUE-02 blocking error", async () => {
+    await writeRfc("RFC-1301");
+    const file = await writeManifest(
+      "block-b",
+      "id: different-id\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1301\n",
+    );
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors.some((e) => e.ruleId === "QUEUE-02")).toBe(true);
+  });
+
+  test("malformed item id → QUEUE-03", async () => {
+    const file = await writeManifest(
+      "block-c",
+      "id: block-c\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-13\n",
+    );
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors.some((e) => e.ruleId === "QUEUE-03")).toBe(true);
+  });
+
+  test("unresolvable item id → QUEUE-04", async () => {
+    const file = await writeManifest(
+      "block-d",
+      "id: block-d\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-9999\n",
+    );
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors.some((e) => e.ruleId === "QUEUE-04")).toBe(true);
+  });
+
+  test("duplicate item id → QUEUE-05", async () => {
+    await writeRfc("RFC-1305");
+    const file = await writeManifest(
+      "block-e",
+      "id: block-e\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1305\n  - id: RFC-1305\n",
+    );
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors.some((e) => e.ruleId === "QUEUE-05")).toBe(true);
+  });
+
+  test("dependsOn order violation → QUEUE-06 warning, not blocking", async () => {
+    await writeRfc("RFC-1310");
+    await writeRfc("RFC-1311", "status: draft\ndependsOn:\n  - RFC-1310\n");
+    const file = await writeManifest(
+      "block-f",
+      "id: block-f\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1311\n  - id: RFC-1310\n",
+    );
+    const { errors, warnings } = await loadQueueManifest(tmpDir, file);
+    expect(errors).toEqual([]);
+    expect(warnings.some((w) => w.ruleId === "QUEUE-06")).toBe(true);
+  });
+
+  test("empty items is valid", async () => {
+    const file = await writeManifest("block-g", "id: block-g\ncreatedAt: 2026-09-23\nitems: []\n");
+    const { errors } = await loadQueueManifest(tmpDir, file);
+    expect(errors).toEqual([]);
+  });
+});
+
+describe("runQueueValidate — command contract (RFC-1140)", () => {
+  test("throws without --file", async () => {
+    await expect(
+      runQueueValidate({ argv: [], flags: {} }, testContext()),
+    ).rejects.toThrow("--file");
+  });
+
+  test("valid manifest → pass, items + next in JSON output", async () => {
+    await writeRfc("RFC-1400", "status: implemented\n");
+    await writeRfc("RFC-1401");
+    const file = await writeManifest(
+      "block-h",
+      "id: block-h\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1400\n  - id: RFC-1401\n",
+    );
+
+    const result = await runQueueValidate(
+      { argv: [], flags: { file } },
+      testContext(),
+    );
+
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.queue).toBe("block-h");
+    expect(result?.data?.items).toHaveLength(2);
+    expect(result?.data?.items[0]?.status).toBe("implemented");
+    expect(result?.data?.items[1]?.status).toBe("pending");
+    expect(result?.data?.next).toBe("RFC-1401");
+    expect(result?.exitCode).toBe(0);
+  });
+
+  test("invalid manifest → fail + exitCode 1", async () => {
+    const file = await writeManifest(
+      "block-i",
+      "id: block-i\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-9999\n",
+    );
+
+    const result = await runQueueValidate(
+      { argv: [], flags: { file } },
+      testContext(),
+    );
+
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.exitCode).toBe(1);
+    expect(result?.data?.errors.length).toBeGreaterThan(0);
+  });
+
+  test("empty items → pass with next null", async () => {
+    const file = await writeManifest("block-j", "id: block-j\ncreatedAt: 2026-09-23\nitems: []\n");
+
+    const result = await runQueueValidate(
+      { argv: [], flags: { file } },
+      testContext(),
+    );
+
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.items).toEqual([]);
+    expect(result?.data?.next).toBeNull();
+  });
+});

package/os/queue/queue.module.ts

@@ -0,0 +1,59 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the queue.validate command with the forge kernel registry (RFC-1140).</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/queue-validate.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1140: initial forgeQueueModule registering queue.validate.</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-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>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export async function createForgeQueueModule(): Promise<ForgeModule> {
+  const { runQueueValidate } = await import("./handlers/queue-validate.ts");
+  return {
+    name: "forge-queue",
+    version: "0.1.0",
+    runtime: "autonomous",
+    declarations: [],
+    commands: [
+      {
+        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).",
+        scope: "workspace",
+        contract: "queue",
+        rules: ["QUEUE-01", "QUEUE-02", "QUEUE-03", "QUEUE-04", "QUEUE-05", "QUEUE-06"],
+        mutatesState: false,
+        reads: [
+          "docs/queues/*.yaml",
+          "docs/rfcs/**/*.md",
+          "docs/adrs/**/*.md",
+          "docs/audits/*.md",
+          "docs/plans/*.md",
+        ],
+        cacheable: false,
+        flags: {
+          file: {
+            kind: "string",
+            required: true,
+            description: "Path to the queue manifest YAML file.",
+          },
+        },
+        execute: runQueueValidate,
+      },
+    ],
+    pipelines: [],
+  };
+}

package/os/queue/types.ts

@@ -0,0 +1,49 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Queue manifest contract (RFC-1140) — the durable ordered document
+block consumed by queue.validate and the pipeline orchestrator's queue mode.</purpose>
+<non-goals>
+  <item>Do not store per-item progress state — status is derived, never persisted.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+import type { Diagnostic } from "../../src/types.ts";
+import type { QueueItemReport } from "../../src/pipeline-status.ts";
+
+export const QUEUE_ITEM_ID_PATTERN = /^(RFC|ADR)-\d{4}$/;
+
+export const queueManifestSchema = z.object({
+  id: z.string().min(1),
+  createdAt: z.string().min(1),
+  items: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        note: z.string().optional(),
+      }),
+    )
+    .default([]),
+});
+
+export type QueueManifest = z.infer<typeof queueManifestSchema>;
+
+export interface QueueValidateResult {
+  command: "queue.validate";
+  status: "pass" | "fail";
+  queue: string;
+  file: string;
+  items: QueueItemReport[];
+  /** First item whose derived status is pending or in-progress; null when fully terminal. */
+  next: string | null;
+  errors: Diagnostic[];
+  warnings: Diagnostic[];
+}

package/os/rfc/frontmatter-io.ts

@@ -56,6 +56,7 @@ export async function listRfcFiles(rfcDirPath: string): Promise<string[]> {
           entry.isFile() &&
           entry.name.endsWith(".md") &&
           !entry.name.startsWith("rfc-0000") &&
+          !entry.name.endsWith(".generated.md") &&
           entry.name !== "README.md"
         ) {
           results.push(relativePath);

package/os/rfc/handlers/pipeline-status.ts

@@ -8,16 +8,21 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1140: refactored onto the shared resolver in src/pipeline-status.ts —
+  artifact finders, TERMINAL_STATUSES, and stage computation now imported from
+  the portable layer so queue.validate and the orchestrator share one derivation.</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-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>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
 import path from "node:path";
 
 import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
@@ -26,17 +31,18 @@ import type {
   ForgeCommandResult,
   ForgeRuntimeContext,
 } from "../../../src/types.ts";
+import {
+  TERMINAL_STATUSES,
+  computeRfcPipelineStages,
+  findAuditFile,
+  findPlanFile,
+  nextPipelineStep,
+} from "../../../src/pipeline-status.ts";
+import type { PipelineStage, RfcPipelineStageInfo } from "../../../src/pipeline-status.ts";
 import type { RfcStatus } from "../types.ts";
 import { RFC_DIR } from "../types.ts";
 
-export type PipelineStage = "audit" | "enhance" | "plan" | "implement";
-
-export interface RfcPipelineStageInfo {
-  stage: PipelineStage;
-  done: boolean;
-  /** File or marker that confirms completion, when applicable. */
-  evidence?: string;
-}
+export type { PipelineStage, RfcPipelineStageInfo };
 
 export interface RfcPipelineEntry {
   id: string;
@@ -55,32 +61,6 @@ export interface RfcPipelineStatusResult {
   entries: RfcPipelineEntry[];
 }
 
-const TERMINAL_STATUSES: ReadonlySet<string> = new Set(["implemented", "rejected", "superseded"]);
-
-async function findAuditFile(workspaceRoot: string, rfcId: string): Promise<string | undefined> {
-  const auditsDir = path.join(workspaceRoot, "docs/audits");
-  try {
-    const entries = await fs.readdir(auditsDir);
-    const prefix = `audit-${rfcId.toLowerCase()}`;
-    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
-    return match ? path.join("docs/audits", match) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function findPlanFile(workspaceRoot: string, rfcId: string): Promise<string | undefined> {
-  const plansDir = path.join(workspaceRoot, "docs/plans");
-  try {
-    const entries = await fs.readdir(plansDir);
-    const prefix = `plan-${rfcId.toLowerCase()}`;
-    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
-    return match ? path.join("docs/plans", match) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 export async function runRfcPipelineStatus(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
@@ -116,38 +96,15 @@ export async function runRfcPipelineStatus(
     const auditFile = await findAuditFile(workspaceRoot, id);
     const planFile = await findPlanFile(workspaceRoot, id);
 
-    const stages: RfcPipelineStageInfo[] = [
-      {
-        stage: "audit",
-        done: !!auditFile,
-        evidence: auditFile,
-      },
-      {
-        stage: "enhance",
-        done: !!enhancedAt,
-        evidence: enhancedAt ? `enhancedAt: ${enhancedAt}` : undefined,
-      },
-      {
-        stage: "plan",
-        done: !!planFile,
-        evidence: planFile,
-      },
-      {
-        stage: "implement",
-        done: status === "implemented" || !!implementedAt,
-        evidence: implementedAt ? `implementedAt: ${implementedAt}` : undefined,
-      },
-    ];
-
-    let nextStep: PipelineStage | null = null;
-    if (!isTerminal) {
-      for (const s of stages) {
-        if (!s.done) {
-          nextStep = s.stage;
-          break;
-        }
-      }
-    }
+    const stages: RfcPipelineStageInfo[] = computeRfcPipelineStages({
+      status,
+      enhancedAt,
+      implementedAt,
+      auditFile,
+      planFile,
+    });
+
+    const nextStep: PipelineStage | null = isTerminal ? null : nextPipelineStep(status, stages);
 
     entries.push({
       id,

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

@@ -404,7 +404,14 @@ async function checkImplementationCommitDrift(
   createdAt: string,
   currentStatus: string,
 ): Promise<{ found: boolean; commitCount: number }> {
-  if (currentStatus === "implemented") {
+  // Terminal statuses are exempt: implemented is the target state, and
+  // superseded/rejected RFCs may legitimately carry implement: commits from
+  // work that landed before the status transition (RFC-0769 lifecycle).
+  if (
+    currentStatus === "implemented" ||
+    currentStatus === "superseded" ||
+    currentStatus === "rejected"
+  ) {
     return { found: false, commitCount: 0 };
   }
 

package/os/werkstatt/handlers/workspace-deps.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Lazy dynamic-import bridge for @warpgogol/werkstatt-engine/fingerprint and @warpgogol/werkstatt-shared/node/fs. These workspace packages are not published to npm — when forge is installed standalone from npm, they are unavailable and handlers that depend on them must degrade gracefully.</purpose>
+<purpose>Lazy dynamic-import bridge for @warpgogol/werkstatt-shared/node/fs and @warpgogol/werkstatt-shared/fingerprint. These workspace packages are not published to npm — when forge is installed standalone from npm, they are unavailable and handlers that depend on them must degrade gracefully.</purpose>
 <non-goals>
   <item>Do not re-export types from @warpgogol/* — only runtime functions.</item>
   <item>Do not use static imports — that would break npm installs without workspace deps.</item>
@@ -9,6 +9,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0682: extract dynamic-import helper so forge publishes without workspace:* deps.</item>
   <item>RFC-0940: moved from os/core/handlers/ to os/werkstatt/handlers/ — this module imports @warpgogol/werkstatt-engine and belongs in the adapter directory.</item>
+  <item>2026-09-22: fingerprint import switched from @warpgogol/werkstatt-engine/fingerprint to @warpgogol/werkstatt-shared/fingerprint (canonical home since RFC-1104) — breaks the forge↔engine package cycle reported by turbo.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -40,7 +41,7 @@ export async function loadWorkspaceDeps(): Promise<WorkspaceDeps> {
     const shareMod = await import("@warpgogol/werkstatt-shared/node/fs");
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore — workspace dep, may not be installed when forge is used standalone from npm
-    const fpMod = await import("@warpgogol/werkstatt-engine/fingerprint");
+    const fpMod = await import("@warpgogol/werkstatt-shared/fingerprint");
     cached = {
       collectFiles: shareMod.collectFiles as CollectFilesFn,
       byteHashFile: fpMod.byteHashFile as ByteHashFileFn,
@@ -48,7 +49,7 @@ export async function loadWorkspaceDeps(): Promise<WorkspaceDeps> {
     return cached;
   } catch (err) {
     loadError =
-      `@warpgogol/werkstatt-engine/fingerprint and @warpgogol/werkstatt-shared are required for this command but not installed. ` +
+      `@warpgogol/werkstatt-shared/fingerprint and @warpgogol/werkstatt-shared/node/fs are required for this command but not installed. ` +
       `When using forge standalone from npm, install them separately or use forge within the warpgogol workspace. ` +
       `Error: ${(err as Error).message}`;
     throw new Error(loadError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -147,6 +147,14 @@
     "./os/plugin": {
       "types": "./os/plugin/plugin.module.ts",
       "default": "./os/plugin/plugin.module.ts"
+    },
+    "./os/queue": {
+      "types": "./os/queue/index.ts",
+      "default": "./os/queue/index.ts"
+    },
+    "./os/queue-module": {
+      "types": "./os/queue/queue.module.ts",
+      "default": "./os/queue/queue.module.ts"
     }
   },
   "files": [
@@ -324,6 +332,14 @@
       "./os/plugin": {
         "types": "./dist/os/plugin/plugin.module.d.ts",
         "default": "./dist/os/plugin/plugin.module.js"
+      },
+      "./os/queue": {
+        "types": "./dist/os/queue/index.d.ts",
+        "default": "./dist/os/queue/index.js"
+      },
+      "./os/queue-module": {
+        "types": "./dist/os/queue/queue.module.d.ts",
+        "default": "./dist/os/queue/queue.module.js"
       }
     }
   },