@warpgogol/forge 5.1.3 → 5.2.3

package/src/knowledge/sync.ts

@@ -0,0 +1,161 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Append-only sync for declared skill knowledge files. Copies files that are
+missing at the destination, merges cumulative K-NNNN files by entry-ID union (local
+entries always win), and never overwrites existing local content. Fixes the data-loss
+bug where forge.upgrade wiped project-accumulated knowledge entries by overwriting
+the synced copy with the package version.</purpose>
+<non-goals>
+  <item>Do not validate entry metadata — SKILL-19/SKILL-20 handle schema checks.</item>
+  <item>Do not sync SKILL.md itself — callers handle that separately.</item>
+  <item>Do not propagate deletions — knowledge files are append-only; removing entries is a compaction concern (compact.ts), not a sync concern.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>2026-09-24: initial append-only knowledge sync — merge by entry-ID union, local wins conflicts, skip divergent non-cumulative files, recurse into declared directories.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseKnowledgeFile } from "./parse.ts";
+import { serializeKnowledgeFile } from "./serialize.ts";
+import type { ParsedKnowledgeFile } from "./schema.ts";
+
+export type KnowledgeSyncAction = "copied" | "merged" | "unchanged" | "skipped";
+
+export interface KnowledgeSyncResult {
+  action: KnowledgeSyncAction;
+  /** Entry IDs appended from the source file (merge only). */
+  appended: string[];
+  /** Entry IDs present in both files — the local version is always kept. */
+  conflicts: string[];
+}
+
+export interface KnowledgeSyncPlan extends KnowledgeSyncResult {
+  /** Serialized content to write at the destination, or null when no write is needed. */
+  content: string | null;
+}
+
+const ACTION_PRIORITY: Record<KnowledgeSyncAction, number> = {
+  merged: 3,
+  copied: 2,
+  skipped: 1,
+  unchanged: 0,
+};
+
+function aggregateInto(target: KnowledgeSyncResult, sub: KnowledgeSyncResult): void {
+  target.appended.push(...sub.appended);
+  target.conflicts.push(...sub.conflicts);
+  if (ACTION_PRIORITY[sub.action] > ACTION_PRIORITY[target.action]) {
+    target.action = sub.action;
+  }
+}
+
+function isCumulative(parsed: ParsedKnowledgeFile): boolean {
+  return !parsed.isKnowledgeAdjacent;
+}
+
+function planFileSync(srcPath: string, destPath: string): KnowledgeSyncPlan {
+  const none = { appended: [], conflicts: [] };
+  if (!fs.existsSync(srcPath)) {
+    return { action: "unchanged", content: null, ...none };
+  }
+
+  const srcContent = fs.readFileSync(srcPath, "utf8");
+  if (!fs.existsSync(destPath)) {
+    return { action: "copied", content: srcContent, ...none };
+  }
+
+  const destContent = fs.readFileSync(destPath, "utf8");
+  if (srcContent === destContent) {
+    return { action: "unchanged", content: null, ...none };
+  }
+
+  const srcParsed = parseKnowledgeFile(srcPath);
+  const destParsed = parseKnowledgeFile(destPath);
+
+  // Both files use the cumulative K-NNNN format → append-only merge:
+  // local entries always win; source entries with new IDs are appended.
+  if (isCumulative(srcParsed) && isCumulative(destParsed)) {
+    const destIds = new Set(destParsed.entries.map((e) => e.meta.id));
+    const appendedEntries = srcParsed.entries.filter((e) => !destIds.has(e.meta.id));
+    const conflicts = srcParsed.entries
+      .filter((e) => destIds.has(e.meta.id))
+      .map((e) => e.meta.id);
+
+    const destLegacyTexts = new Set(destParsed.legacySections.map((l) => l.text.trim()));
+    const appendedLegacy = srcParsed.legacySections.filter(
+      (l) => !destLegacyTexts.has(l.text.trim()),
+    );
+
+    if (appendedEntries.length === 0 && appendedLegacy.length === 0) {
+      return { action: "unchanged", content: null, appended: [], conflicts };
+    }
+
+    const merged: ParsedKnowledgeFile = {
+      path: destPath,
+      layer: destParsed.layer ?? srcParsed.layer,
+      preamble: destParsed.preamble || srcParsed.preamble,
+      entries: [...destParsed.entries, ...appendedEntries],
+      legacySections: [...destParsed.legacySections, ...appendedLegacy],
+      parseIssues: [],
+      isKnowledgeAdjacent: false,
+    };
+
+    return {
+      action: "merged",
+      content: serializeKnowledgeFile(merged),
+      appended: appendedEntries.map((e) => e.meta.id),
+      conflicts,
+    };
+  }
+
+  // Any other divergence means the local file was edited or uses a
+  // non-cumulative format — preserve it (append-only contract).
+  return { action: "skipped", content: null, ...none };
+}
+
+/**
+ * Compute the sync plan for a declared knowledge file (or directory) without
+ * writing anything. Used by doctor for stale detection.
+ */
+export function planKnowledgeSync(srcPath: string, destPath: string): KnowledgeSyncPlan {
+  if (fs.existsSync(srcPath) && fs.statSync(srcPath).isDirectory()) {
+    const aggregate: KnowledgeSyncPlan = {
+      action: "unchanged",
+      appended: [],
+      conflicts: [],
+      content: null,
+    };
+    for (const entry of fs.readdirSync(srcPath)) {
+      const sub = planKnowledgeSync(path.join(srcPath, entry), path.join(destPath, entry));
+      aggregateInto(aggregate, sub);
+    }
+    return aggregate;
+  }
+  return planFileSync(srcPath, destPath);
+}
+
+/**
+ * Sync one declared knowledge file (or directory) from source to destination.
+ * Never overwrites existing local content — cumulative files merge by entry-ID
+ * union, divergent non-cumulative files are skipped.
+ */
+export function syncKnowledgeFile(srcPath: string, destPath: string): KnowledgeSyncResult {
+  if (fs.existsSync(srcPath) && fs.statSync(srcPath).isDirectory()) {
+    const aggregate: KnowledgeSyncResult = { action: "unchanged", appended: [], conflicts: [] };
+    for (const entry of fs.readdirSync(srcPath)) {
+      const sub = syncKnowledgeFile(path.join(srcPath, entry), path.join(destPath, entry));
+      aggregateInto(aggregate, sub);
+    }
+    return aggregate;
+  }
+
+  const plan = planFileSync(srcPath, destPath);
+  if (plan.content !== null) {
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, plan.content, "utf8");
+  }
+  return { action: plan.action, appended: plan.appended, conflicts: plan.conflicts };
+}

package/src/onboarding/doctor.ts

@@ -42,6 +42,7 @@ import { TERMINOLOGY_DEFAULTS } from "../profiles/profile-schema.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
 import { runProfileValidate } from "./profile-validate.ts";
 import { parseKnowledgeFile } from "../knowledge/index.ts";
+import { planKnowledgeSync } from "../knowledge/index.ts";
 import type { ParsedKnowledgeFile } from "../knowledge/index.ts";
 import { computeLayerBudgets, resolveKnowledgeBudgets, DEFAULT_KNOWLEDGE_BUDGETS } from "../knowledge/budgets.ts";
 import { detectDuplicatePrinciples } from "../knowledge/index.ts";
@@ -243,9 +244,10 @@ async function checkStaleKnowledgeFiles(
       const destExists = await pathExists(destPath);
 
       if (srcExists && destExists) {
-        const srcContent = await readFile(srcPath, "utf8").catch(() => "");
-        const destContent = await readFile(destPath, "utf8").catch(() => "");
-        if (srcContent !== destContent) {
+        // Append-only contract: local copies legitimately accumulate entries.
+        // Stale = source has entries the local copy lacks (sync would merge).
+        const plan = planKnowledgeSync(srcPath, destPath);
+        if (plan.action === "merged") {
           stale.push(`${skill.name}/${kf}`);
         }
       }
@@ -274,9 +276,8 @@ async function checkStaleKnowledgeFiles(
       const destExists = await pathExists(destPath);
 
       if (srcExists && destExists) {
-        const srcContent = await readFile(srcPath, "utf8").catch(() => "");
-        const destContent = await readFile(destPath, "utf8").catch(() => "");
-        if (srcContent !== destContent) {
+        const plan = planKnowledgeSync(srcPath, destPath);
+        if (plan.action === "merged") {
           stale.push(`${skill.name}/${kf}`);
         }
       }

package/src/onboarding/init.ts

@@ -24,6 +24,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { stringify as stringifyYaml, parse as parseYaml } from "yaml";
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
+import { syncKnowledgeFile } from "../knowledge/index.ts";
 import { defaultForgeConfig, loadForgeConfig, resolveForgeRoot, type ForgeConfig } from "../config/forge-config.ts";
 import { listStackProfiles, detectStack } from "../profiles/stack-profile.ts";
 
@@ -292,9 +293,11 @@ export function runInit(
             const kfSrcPath = path.join(skillSrcDir, kf);
             const kfDestPath = path.join(destDir, kf);
             if (fs.existsSync(kfSrcPath)) {
-              const kfContent = fs.readFileSync(kfSrcPath, "utf8");
-              fs.writeFileSync(kfDestPath, kfContent, "utf8");
-              created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
+              // Append-only sync — never overwrite local knowledge entries
+              const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
+              if (syncResult.action === "copied" || syncResult.action === "merged") {
+                created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
+              }
             } else {
               errors.push(`Knowledge file '${kf}' declared in ${skillName} but not found in source`);
             }
@@ -362,9 +365,11 @@ export function runInit(
             const kfSrcPath = path.join(skillSrcDir, kf);
             const kfDestPath = path.join(destDir, kf);
             if (fs.existsSync(kfSrcPath)) {
-              const kfContent = fs.readFileSync(kfSrcPath, "utf8");
-              fs.writeFileSync(kfDestPath, kfContent, "utf8");
-              created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
+              // Append-only sync — never overwrite local knowledge entries
+              const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
+              if (syncResult.action === "copied" || syncResult.action === "merged") {
+                created.push(`${config.paths.skillsDir}/${skillName}/${kf}`);
+              }
             } else {
               errors.push(`Knowledge file '${kf}' declared in ${skillName} but not found in source`);
             }
@@ -382,8 +387,10 @@ export function runInit(
     const sharedKnowledgeDestDir = path.join(agentsSkillsDir, "shared-knowledge");
     fs.mkdirSync(sharedKnowledgeDestDir, { recursive: true });
     const sharedKnowledgeDest = path.join(sharedKnowledgeDestDir, "learned-principles.md");
-    fs.writeFileSync(sharedKnowledgeDest, fs.readFileSync(sharedKnowledgeSrc, "utf8"), "utf8");
-    created.push(`${config.paths.skillsDir}/shared-knowledge/learned-principles.md`);
+    const syncResult = syncKnowledgeFile(sharedKnowledgeSrc, sharedKnowledgeDest);
+    if (syncResult.action === "copied" || syncResult.action === "merged") {
+      created.push(`${config.paths.skillsDir}/shared-knowledge/learned-principles.md`);
+    }
   }
 
   // 4. Create docs directories from config paths

package/src/onboarding/upgrade.ts

@@ -39,6 +39,7 @@ import {
   type ForgeBindings,
 } from "../config/forge-config.ts";
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
+import { syncKnowledgeFile } from "../knowledge/index.ts";
 import { generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { scaffoldMemoryLayer } from "./memory-scaffold.ts";
 import type { SkippedSkill } from "./init.ts";
@@ -143,8 +144,9 @@ function syncForgeSkills(
   forgeRoot: string,
   skillsDir: string,
   dryRun: boolean,
-): string[] {
+): { updated: string[]; knowledgeConflicts: string[] } {
   const updated: string[] = [];
+  const knowledgeConflicts: string[] = [];
   const agentsSkillsDir = path.join(workspaceRoot, skillsDir);
 
   for (const skill of FORGE_SKILLS) {
@@ -160,7 +162,7 @@ function syncForgeSkills(
       const content = fs.readFileSync(srcPath, "utf8");
       fs.writeFileSync(destPath, content, "utf8");
 
-      // Sync knowledge files
+      // Sync knowledge files (append-only — never overwrite local entries)
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
       if (fmMatch) {
         try {
@@ -173,7 +175,10 @@ function syncForgeSkills(
               const kfSrcPath = path.join(skillSrcDir, kf);
               const kfDestPath = path.join(destDir, kf);
               if (fs.existsSync(kfSrcPath)) {
-                fs.writeFileSync(kfDestPath, fs.readFileSync(kfSrcPath, "utf8"), "utf8");
+                const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
+                for (const id of syncResult.conflicts) {
+                  knowledgeConflicts.push(`${skillName}/${kf}#${id}`);
+                }
               }
             }
           }
@@ -185,7 +190,7 @@ function syncForgeSkills(
     updated.push(skillName);
   }
 
-  return updated;
+  return { updated, knowledgeConflicts };
 }
 
 function syncSharedKnowledge(
@@ -193,20 +198,24 @@ function syncSharedKnowledge(
   forgeRoot: string,
   skillsDir: string,
   dryRun: boolean,
-): string[] {
+): { updated: string[]; knowledgeConflicts: string[] } {
   const updated: string[] = [];
+  const knowledgeConflicts: string[] = [];
   const srcPath = path.join(forgeRoot, "skills", "shared", "knowledge", "learned-principles.md");
-  if (!fs.existsSync(srcPath)) return updated;
+  if (!fs.existsSync(srcPath)) return { updated, knowledgeConflicts };
 
   const destDir = path.join(workspaceRoot, skillsDir, "shared-knowledge");
   const destPath = path.join(destDir, "learned-principles.md");
 
   if (!dryRun) {
     fs.mkdirSync(destDir, { recursive: true });
-    fs.writeFileSync(destPath, fs.readFileSync(srcPath, "utf8"), "utf8");
+    const syncResult = syncKnowledgeFile(srcPath, destPath);
+    for (const id of syncResult.conflicts) {
+      knowledgeConflicts.push(`shared-knowledge/learned-principles.md#${id}`);
+    }
   }
   updated.push("shared-knowledge");
-  return updated;
+  return { updated, knowledgeConflicts };
 }
 
 function syncPackSkills(
@@ -214,9 +223,10 @@ function syncPackSkills(
   config: ForgeConfig,
   skillsDir: string,
   dryRun: boolean,
-): { updated: string[]; skipped: SkippedSkill[] } {
+): { updated: string[]; skipped: SkippedSkill[]; knowledgeConflicts: string[] } {
   const updated: string[] = [];
   const skipped: SkippedSkill[] = [];
+  const knowledgeConflicts: string[] = [];
   const agentsSkillsDir = path.join(workspaceRoot, skillsDir);
   let packSkills: ReturnType<typeof discoverPackSkills> = [];
   try {
@@ -245,7 +255,7 @@ function syncPackSkills(
       const content = fs.readFileSync(srcPath, "utf8");
       fs.writeFileSync(destPath, content, "utf8");
 
-      // Sync knowledge files
+      // Sync knowledge files (append-only — never overwrite local entries)
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
       if (fmMatch) {
         try {
@@ -258,7 +268,10 @@ function syncPackSkills(
               const kfSrcPath = path.join(skillSrcDir, kf);
               const kfDestPath = path.join(destDir, kf);
               if (fs.existsSync(kfSrcPath)) {
-                fs.writeFileSync(kfDestPath, fs.readFileSync(kfSrcPath, "utf8"), "utf8");
+                const syncResult = syncKnowledgeFile(kfSrcPath, kfDestPath);
+                for (const id of syncResult.conflicts) {
+                  knowledgeConflicts.push(`${skillName}/${kf}#${id}`);
+                }
               }
             }
           }
@@ -270,7 +283,7 @@ function syncPackSkills(
     updated.push(skillName);
   }
 
-  return { updated, skipped };
+  return { updated, skipped, knowledgeConflicts };
 }
 
 function addMissingBindingDefaults(
@@ -467,7 +480,7 @@ export async function runUpgrade(
   }
 
   // Step 3: Sync forge skills
-  const forgeSkillsUpdated = syncForgeSkills(
+  const forgeSkillsResult = syncForgeSkills(
     workspaceRoot,
     forgeRoot,
     config.paths.skillsDir,
@@ -483,14 +496,29 @@ export async function runUpgrade(
   );
 
   // Step 3c: Sync shared knowledge layer (RFC-0663)
-  const sharedKnowledgeUpdated = syncSharedKnowledge(
+  const sharedKnowledgeResult = syncSharedKnowledge(
     workspaceRoot,
     forgeRoot,
     config.paths.skillsDir,
     isDryRun,
   );
 
-  const skillsUpdated = [...forgeSkillsUpdated, ...packResult.updated, ...sharedKnowledgeUpdated];
+  const skillsUpdated = [
+    ...forgeSkillsResult.updated,
+    ...packResult.updated,
+    ...sharedKnowledgeResult.updated,
+  ];
+  const knowledgeConflicts = [
+    ...forgeSkillsResult.knowledgeConflicts,
+    ...packResult.knowledgeConflicts,
+    ...sharedKnowledgeResult.knowledgeConflicts,
+  ];
+  if (knowledgeConflicts.length > 0) {
+    context.logger.warn(
+      `forge.upgrade: ${knowledgeConflicts.length} knowledge entr${knowledgeConflicts.length === 1 ? "y" : "ies"} ` +
+        `diverge between package and project — local versions kept: ${knowledgeConflicts.join(", ")}`,
+    );
+  }
 
   // Step 3d: Scaffold memory layer (RFC-0664)
   const memoryScaffold = isDryRun ? { created: [], gitignoreUpdated: false, skipped: [] } : scaffoldMemoryLayer(workspaceRoot);
@@ -565,6 +593,9 @@ export async function runUpgrade(
       ? `[dry-run] forge.upgrade: would sync ${skillsUpdated.length} skill(s), add ${bindingsAdded.length} binding(s), update syncedVersion to ${toVersion}`
       : npmCheck.warning
         ? `[forge.upgrade] OK — ${skillsUpdated.length} skill(s) synced, ${bindingsAdded.length} binding(s) added, syncedVersion → ${toVersion} — ⚠ ${npmCheck.warning}`
-        : `[forge.upgrade] OK — ${skillsUpdated.length} skill(s) synced, ${bindingsAdded.length} binding(s) added, syncedVersion → ${toVersion}`,
+        : `[forge.upgrade] OK — ${skillsUpdated.length} skill(s) synced, ${bindingsAdded.length} binding(s) added, syncedVersion → ${toVersion}` +
+          (knowledgeConflicts.length > 0
+            ? ` — ${knowledgeConflicts.length} knowledge conflict(s), local kept`
+            : ""),
   };
 }

package/src/pipeline-status.test.ts

@@ -0,0 +1,192 @@
+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 {
+  deriveQueueItemStatus,
+  deriveQueueReport,
+  resolveDocument,
+  computeRfcPipelineStages,
+  nextPipelineStep,
+} from "./pipeline-status.ts";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "pipeline-status-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/audits"), { recursive: true });
+  await fs.mkdir(path.join(tmpDir, "docs/plans"), { recursive: true });
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+async function writeRfc(id: string, frontmatter: string): Promise<void> {
+  await fs.writeFile(
+    path.join(tmpDir, `docs/rfcs/${id.toLowerCase()}-test.md`),
+    `---\nid: ${id}\n${frontmatter}---\n# ${id}\n`,
+  );
+}
+
+async function writeAdr(id: string, frontmatter: string): Promise<void> {
+  await fs.writeFile(
+    path.join(tmpDir, `docs/adrs/${id.toLowerCase()}-test.md`),
+    `---\nid: ${id}\n${frontmatter}---\n# ${id}\n`,
+  );
+}
+
+describe("resolveDocument", () => {
+  test("resolves an active RFC file", async () => {
+    await writeRfc("RFC-1001", "status: draft\n");
+    const doc = await resolveDocument(tmpDir, "RFC-1001");
+    expect(doc?.kind).toBe("rfc");
+    expect(doc?.frontmatter["status"]).toBe("draft");
+  });
+
+  test("resolves an archived RFC file", async () => {
+    await fs.mkdir(path.join(tmpDir, "docs/rfcs/archive/implemented"), { recursive: true });
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/archive/implemented/rfc-1002-old.md"),
+      "---\nid: RFC-1002\nstatus: implemented\n---\n# RFC-1002\n",
+    );
+    const doc = await resolveDocument(tmpDir, "RFC-1002");
+    expect(doc?.file).toContain("archive/implemented");
+    expect(doc?.frontmatter["status"]).toBe("implemented");
+  });
+
+  test("returns undefined for malformed ids", async () => {
+    expect(await resolveDocument(tmpDir, "NOT-A-DOC")).toBeUndefined();
+    expect(await resolveDocument(tmpDir, "RFC-999")).toBeUndefined();
+  });
+});
+
+describe("deriveQueueItemStatus — derivation matrix (RFC-1140)", () => {
+  test("implemented status → implemented", async () => {
+    await writeRfc("RFC-1100", "status: implemented\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1100");
+    expect(r?.status).toBe("implemented");
+  });
+
+  test("implementedAt set → implemented", async () => {
+    await writeRfc("RFC-1101", "status: accepted\nimplementedAt: 2026-09-01\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1101");
+    expect(r?.status).toBe("implemented");
+  });
+
+  test("rejected → skipped", async () => {
+    await writeRfc("RFC-1102", "status: rejected\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1102");
+    expect(r?.status).toBe("skipped");
+  });
+
+  test("superseded → skipped", async () => {
+    await writeRfc("RFC-1103", "status: superseded\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1103");
+    expect(r?.status).toBe("skipped");
+  });
+
+  test("accepted RFC → in-progress/implement", async () => {
+    await writeRfc("RFC-1104", "status: accepted\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1104");
+    expect(r?.status).toBe("in-progress");
+    expect(r?.pipelineStep).toBe("implement");
+  });
+
+  test("plan file exists → in-progress/implement", async () => {
+    await writeRfc("RFC-1105", "status: draft\nenhancedAt: 2026-09-01\n");
+    await fs.writeFile(
+      path.join(tmpDir, "docs/plans/plan-rfc-1105-test.md"),
+      "---\nrfcId: RFC-1105\n---\n",
+    );
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1105");
+    expect(r?.status).toBe("in-progress");
+    expect(r?.pipelineStep).toBe("implement");
+  });
+
+  test("enhancedAt without plan → in-progress/plan", async () => {
+    await writeRfc("RFC-1106", "status: draft\nenhancedAt: 2026-09-01\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1106");
+    expect(r?.status).toBe("in-progress");
+    expect(r?.pipelineStep).toBe("plan");
+  });
+
+  test("audit file only → in-progress/enhance", async () => {
+    await writeRfc("RFC-1107", "status: draft\n");
+    await fs.writeFile(
+      path.join(tmpDir, "docs/audits/audit-rfc-1107-test.md"),
+      "# audit\n",
+    );
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1107");
+    expect(r?.status).toBe("in-progress");
+    expect(r?.pipelineStep).toBe("enhance");
+  });
+
+  test("no artifacts → pending", async () => {
+    await writeRfc("RFC-1108", "status: draft\n");
+    const r = await deriveQueueItemStatus(tmpDir, "RFC-1108");
+    expect(r?.status).toBe("pending");
+    expect(r?.pipelineStep).toBeUndefined();
+  });
+
+  test("non-terminal ADR → pending", async () => {
+    await writeAdr("ADR-0100", "status: accepted\n");
+    const r = await deriveQueueItemStatus(tmpDir, "ADR-0100");
+    expect(r?.status).toBe("pending");
+  });
+
+  test("unresolvable id → undefined", async () => {
+    expect(await deriveQueueItemStatus(tmpDir, "RFC-9999")).toBeUndefined();
+  });
+});
+
+describe("deriveQueueReport", () => {
+  test("preserves manifest order and picks the first actionable item as next", async () => {
+    await writeRfc("RFC-1200", "status: implemented\n");
+    await writeRfc("RFC-1201", "status: draft\n");
+    await writeRfc("RFC-1202", "status: draft\n");
+
+    const report = await deriveQueueReport(tmpDir, ["RFC-1200", "RFC-1201", "RFC-1202"]);
+
+    expect(report.items.map((i) => i.id)).toEqual(["RFC-1200", "RFC-1201", "RFC-1202"]);
+    expect(report.next).toBe("RFC-1201");
+  });
+
+  test("next is null when every item is terminal", async () => {
+    await writeRfc("RFC-1210", "status: implemented\n");
+    await writeRfc("RFC-1211", "status: rejected\n");
+
+    const report = await deriveQueueReport(tmpDir, ["RFC-1210", "RFC-1211"]);
+
+    expect(report.next).toBeNull();
+  });
+
+  test("in-progress items are actionable for next", async () => {
+    await writeRfc("RFC-1220", "status: draft\nenhancedAt: 2026-09-01\n");
+    await writeRfc("RFC-1221", "status: draft\n");
+
+    const report = await deriveQueueReport(tmpDir, ["RFC-1220", "RFC-1221"]);
+
+    expect(report.next).toBe("RFC-1220");
+  });
+});
+
+describe("computeRfcPipelineStages + nextPipelineStep", () => {
+  test("stages reflect artifact completion", () => {
+    const stages = computeRfcPipelineStages({
+      status: "draft",
+      enhancedAt: "2026-09-01",
+      auditFile: "docs/audits/audit-rfc-1.md",
+    });
+    expect(stages.map((s) => s.done)).toEqual([true, true, false, false]);
+    expect(nextPipelineStep("draft", stages)).toBe("plan");
+  });
+
+  test("terminal status yields null next step", () => {
+    const stages = computeRfcPipelineStages({ status: "implemented" });
+    expect(nextPipelineStep("implemented", stages)).toBeNull();
+  });
+});