@warpgogol/forge 5.1.3 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.1.3",
+  "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"
       }
     }
   },

package/skills/fo/fo-idea-i-just-want-to-see-the-result/SKILL.md

@@ -8,6 +8,7 @@ dependsOn: ['my-preferences']
 languagePolicy: ref(PREFERENCES.md)
 triggers: ["I just want to see the result", "run the full pipeline automatically", "implement this end-to-end without pauses"]
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>fo-idea-i-just-want-to-see-the-result skill — Orchestrate the full feature pipeline (idea, audit, enhance, plan, implement, review, fix) in one invocation. Accepts a raw idea or RFC/ADR id. Use when the operator wants the complete pipeline.</purpose>
@@ -19,10 +20,15 @@ triggers: ["I just want to see the result", "run the full pipeline automatically
   <item>RFC-1097: sweep — SKILL.md headers + classification fixes
 
 Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from frontmatter description). Fix non-skill-markdown exclusion to check filename not workspace-relative path (packages/AGENTS.md escaped it). Add .coverage to ignoredDirs.</item>
+  <item>RFC-1140: step 5 — queue-mode section in orchestrator SKILL.md
+
+Add Queue mode section (pre-flight queue.validate, loop semantics, failure handling, manifest immutability) to fo-idea-i-just-want-to-see-the-result SKILL.md, sync .agents copy, add forgeQueueModule row to forge AGENTS.md.</item>
+  <item>RFC-1140: queue mode — materialize manifest at invocation from pasted doc list
+
+When the invocation carries >=2 RFC/ADR ids without a manifest path, the orchestrator builds docs/queues/session-<timestamp>.yaml from the pasted order, runs queue.validate, then processes queue mode. Unresolvable ids are named explicitly.</item>
 </CHANGE_SUMMARY>
 -->
 
-
 # Full Pipeline — Just Want to See the Result
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
@@ -48,8 +54,47 @@ The operator may provide either:
 
 - **A raw idea** — natural-language description of a feature, change, or decision. The skill will invoke `fo-idea` as step 0 to create the RFC/ADR first.
 - **An existing RFC/ADR id** — e.g. `RFC-XXXX` or `ADR-XXXX`. The skill skips idea creation and starts the pipeline from the appropriate step.
+- **A queue manifest** — `--queue <path>` or a `docs/queues/*.yaml` path in the invocation text. The skill enters queue mode (see §Queue mode) and processes the manifest's `items[]` in order.
+- **A pasted document list** — >=2 `RFC-XXXX`/`ADR-XXXX` ids in the invocation text (e.g. another agent's ordered implementation plan). The skill materializes a session manifest (see §Queue mode → Manifest materialization) and enters queue mode.
 - **Nothing** — if neither is provided, check session context and IDE for a recently created document. If none found, ask the operator: "Какую идею реализуем? Опишите идею или укажите RFC-XXXX / ADR-XXXX."
 
+## Queue mode
+
+The orchestrator runs in **queue mode** when the invocation carries `--queue <path>`, a `docs/queues/*.yaml` path, OR a pasted document list (>=2 `RFC-XXXX`/`ADR-XXXX` ids — e.g. another agent's ordered implementation plan).
+
+**Manifest materialization (mandatory when no manifest path is given):** Build the manifest from the invocation text before anything else:
+
+1. Extract `RFC-\d{4}`/`ADR-\d{4}` tokens in order of appearance; dedupe preserving first-seen order. The pasted order IS the dependency order — preserve it even when the surrounding prose discusses a different grouping.
+2. Write `docs/queues/session-<YYYYMMDD>-<HHmm>.yaml`:
+
+   ```yaml
+   id: session-<YYYYMMDD>-<HHmm>
+   createdAt: <YYYY-MM-DD>
+   items:
+     - id: RFC-XXXX
+     - id: ADR-XXXX
+   ```
+
+   The `id` field MUST equal the filename stem (`queue.validate` enforces this). Leave the file uncommitted — it is a session artifact; the operator may commit it for cross-session durability.
+
+3. If the paste mixes ids with prose, ignore the prose — only the id sequence matters. Do not invent items that are not in the text.
+
+**Pre-flight (mandatory):** Run `pnpm exec werkstatt run queue.validate --file <manifest> --json`. If the command exits non-zero (schema errors, unknown ids, duplicates, id↔filename mismatch), do NOT start the batch — report the errors and stop. When a pasted list references ids that do not resolve (QUEUE-04), name them explicitly — the operator must create those documents first or fix the list.
+
+**Batch plan preview:** Emit the existing batch plan preview per `_shared/fo-pipeline-conventions.md` §Batch plan preview, listing items in manifest order.
+
+**Loop semantics:** Process `items[]` in manifest order with no pauses between items:
+
+1. **Skip terminal items** — items whose derived status is `implemented` or `skipped` (rejected/superseded frontmatter) are recorded in the batch summary and skipped.
+2. **Resume mid-pipeline items** — an `in-progress` item resumes at its derived `pipelineStep`, not from step 1.
+3. **Run the existing per-doc pipeline** — RFC items run audit → enhance → plan → implement; ADR items run implement only. All skill-internal interactions (grilling) stay inside the invoked skills.
+4. **Batch-item checkpoint** — after each item, emit the context checkpoint per `_shared/fo-pipeline-conventions.md` §Context checkpoint between batch items.
+5. **Clean-tree gate** — before starting the next item, verify the working tree has no uncommitted leftovers from the completed item; warn and stop if dirty.
+
+**Failure:** If an item fails after its error checkpoint, stop the batch. The report names the blocked item id and the remaining item count. `blocked` is in-session report language only — never persist it into frontmatter, manifests, or files. Resume = re-invoke with the same manifest; `queue.validate` derives where to continue.
+
+**Manifest immutability:** Do not edit `items[]` or the manifest during a queue run. Reordering requires stopping the batch and re-validating.
+
 ## Process
 
 ### 0. Idea creation (conditional)