@warpgogol/forge 5.1.3 → 5.2.3

package/os/rfc/rfc-create-concurrent.test.ts

@@ -0,0 +1,118 @@
+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 { runRfcCreate } from "./handlers/list-create.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1138 AC-5: concurrent rfc.create invocations must produce distinct
+    RFC ids — the wx (exclusive-create) write + bounded retry on EEXIST
+    replaces the old scan-then-write race.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+const RFC_TEMPLATE = `---
+id: RFC-0000
+title: "TEMPLATE"
+kind: command
+scope: workspace
+createdAt: YYYY-MM-DD
+updatedAt: YYYY-MM-DD
+satisfies: []
+---
+
+# RFC-0000: TEMPLATE
+`;
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      info: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    outputFormat: "json",
+    dryRun: false,
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(title: string): ForgeCommandInput {
+  return {
+    commandName: "rfc.create",
+    // kind "command" avoids the post-cutoff --satisfies requirement
+    // (only architecture|contract require DNA ids).
+    flags: { title, kind: "command", scope: "workspace" },
+  } as unknown as ForgeCommandInput;
+}
+
+describe("rfc.create — RFC-1138 concurrent id allocation", () => {
+  let tmpDir: string;
+  let rfcDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-create-"));
+    rfcDir = path.join(tmpDir, "docs", "rfcs");
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.writeFile(path.join(rfcDir, "rfc-0000-template.md"), RFC_TEMPLATE, "utf-8");
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test("AC-5: five concurrent creates produce five distinct ids", async () => {
+    const results = await Promise.all(
+      [1, 2, 3, 4, 5].map((n) =>
+        runRfcCreate(makeInput(`Concurrent RFC ${n}`), makeContext(tmpDir)),
+      ),
+    );
+
+    const ids = results.map((r) => (r.data as { id: string }).id);
+    expect(new Set(ids).size).toBe(5);
+
+    const files = (await fs.readdir(rfcDir)).filter((f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md");
+    expect(files).toHaveLength(5);
+  });
+
+  test("AC-5: sequential creates still allocate monotonically", async () => {
+    const first = await runRfcCreate(makeInput("First"), makeContext(tmpDir));
+    const second = await runRfcCreate(makeInput("Second"), makeContext(tmpDir));
+
+    const firstId = (first.data as { id: string }).id;
+    const secondId = (second.data as { id: string }).id;
+    expect(firstId).not.toBe(secondId);
+    expect(secondId > firstId).toBe(true);
+  });
+
+  test("AC-5: pre-existing highest id is respected after a collision", async () => {
+    // Seed rfc-0001 so the first create takes 0002; a file racing in at 0002
+    // forces the retry path to land on 0003.
+    await fs.writeFile(path.join(rfcDir, "rfc-0001-seeded.md"), "---\nid: RFC-0001\n---\n", "utf-8");
+    const winner = runRfcCreate(makeInput("Winner"), makeContext(tmpDir));
+    // Interleave a manual claim at the id the scan will compute.
+    const claim = (async () => {
+      // Small delay so the create's scan completes first, then we steal 0002.
+      await new Promise((r) => setTimeout(r, 5));
+      await fs
+        .writeFile(path.join(rfcDir, "rfc-0002-interloper.md"), "---\nid: RFC-0002\n---\n", {
+          flag: "wx",
+        })
+        .catch(() => {});
+    })();
+    const [result] = await Promise.all([winner, claim]);
+
+    const id = (result.data as { id: string }).id;
+    // Either the create won 0002 (interloper lost the wx race) or it retried to 0003.
+    expect(["RFC-0002", "RFC-0003"]).toContain(id);
+    const files = (await fs.readdir(rfcDir)).filter((f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md");
+    // Seeded + interloper (if it won) + create output — never a silent overwrite.
+    expect(files.length).toBeGreaterThanOrEqual(2);
+  });
+});

package/os/rfc/rfc-create-hint.test.ts

@@ -0,0 +1,90 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1139 AC-1: the next-steps hint printed by rfc.create must be an
+    executable command — correct binary (werkstatt, not forge), correct
+    subcommand (run), and correct flags (--id, not --file).
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runRfcCreate } from "./handlers/list-create.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+const RFC_DIR = "docs/rfcs";
+
+const TEMPLATE = `---
+id: RFC-0000
+title: "Template"
+status: draft
+kind: command
+scope: workspace
+createdAt: YYYY-MM-DD
+updatedAt: YYYY-MM-DD
+satisfies: []
+---
+
+# RFC-0000: Template
+`;
+
+function makeContext(root: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot: root,
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      success() {},
+      section() {},
+      getEvents: () => [],
+    },
+    outputFormat: "json",
+    dryRun: false,
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown>): ForgeCommandInput {
+  return { argv: [], flags } as unknown as ForgeCommandInput;
+}
+
+describe("rfc.create — RFC-1139 next-steps hint accuracy", () => {
+  let root: string;
+  let rfcDir: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-hint-"));
+    rfcDir = path.join(root, RFC_DIR);
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.writeFile(path.join(rfcDir, "rfc-0000-template.md"), TEMPLATE, "utf8");
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-1: next-steps hint is an executable werkstatt command with --id", async () => {
+    const result = await runRfcCreate(
+      makeInput({ title: "Hint Test", kind: "command", scope: "workspace" }),
+      makeContext(root),
+    );
+
+    const steps = result.nextSteps ?? [];
+    expect(steps.length).toBeGreaterThan(0);
+
+    for (const step of steps) {
+      const match = step.action.match(/pnpm exec (\S+) run ([\w.]+)/);
+      expect(match, `hint "${step.action}" must contain a runnable command`).not.toBeNull();
+      const [, binary, command] = match!;
+      // forge has no `run` subcommand — werkstatt does
+      expect(binary).toBe("werkstatt");
+      expect(command).toBe("rfc.validate");
+      // rfc.validate takes --id, not --file
+      expect(step.action).toContain("--id RFC-");
+      expect(step.action).not.toContain("--file");
+    }
+  });
+});

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

@@ -0,0 +1,83 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1139 AC-4: read-only commands must not write to the working tree —
+    no ambient regeneration of tracked generated files as a side effect.
+    Guards against future read-path writers.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runRfcList } from "./handlers/list-create.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+function makeContext(root: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot: root,
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      success() {},
+      section() {},
+      getEvents: () => [],
+    },
+    outputFormat: "json",
+    dryRun: false,
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { argv: [], flags } as unknown as ForgeCommandInput;
+}
+
+async function snapshotTree(root: string): Promise<Map<string, string>> {
+  const snapshot = new Map<string, string>();
+  async function walk(dir: string): Promise<void> {
+    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        snapshot.set(path.relative(root, full), await fs.readFile(full, "utf8"));
+      }
+    }
+  }
+  await walk(root);
+  return snapshot;
+}
+
+describe("read-only commands — RFC-1139 no side-effect writes", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-readonly-"));
+    const rfcDir = path.join(root, "docs", "rfcs");
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.writeFile(
+      path.join(rfcDir, "rfc-0001-test.md"),
+      `---\nid: RFC-0001\ntitle: "Test"\nstatus: draft\n---\n\n# RFC-0001\n`,
+      "utf8",
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-4: rfc.list leaves the working tree byte-identical", async () => {
+    const before = await snapshotTree(root);
+    const result = await runRfcList(makeInput(), makeContext(root));
+    expect(result.data?.status).toBe("ok");
+    const after = await snapshotTree(root);
+
+    expect([...after.keys()].sort()).toEqual([...before.keys()].sort());
+    for (const [file, content] of before) {
+      expect(after.get(file), `${file} modified by read-only command`).toBe(content);
+    }
+  });
+});

package/os/rfc/rfc.module.ts

@@ -396,7 +396,7 @@ const {
         "RFC-0476: the exclusive atomic path for accepted → implemented transitions. " +
         "Verifies preconditions (accepted status, checked+evidenced criteria, clean tree, " +
         "reachable RFC-referencing commit, passing probe evidence) then atomically sets " +
-        "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview.",
+        "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview. Required flags: `--id`.",
       scope: "workspace",
       mutatesState: true,
       writes: ["docs/rfcs/**/*.md"],

package/os/spec/spec.module.ts

@@ -103,6 +103,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         "List all living feature specs in docs/specs/live/. " +
         "Returns domain, title, lastMergedRfc, updatedAt, and historyCount for each spec.",
       scope: "workspace",
+      flags: {},
       reads: ["docs/specs/live/*.md"],
       execute: runSpecLiveList,
     },
@@ -128,6 +129,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         "V-LS-03 (lastMergedRfc is archived), V-LS-04 (history entries are archived), " +
         "V-LS-05 (no duplicate domains).",
       scope: "workspace",
+      flags: {},
       reads: ["docs/specs/live/*.md", "docs/rfcs/**/*.md"],
       execute: runSpecLiveValidate,
     }

package/package.json

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

package/src/knowledge/__tests__/sync.test.ts

@@ -0,0 +1,227 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the append-only knowledge sync (syncKnowledgeFile / planKnowledgeSync) — covers copy, merge by entry-ID union, conflict handling, skip semantics, and directory recursion.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>2026-09-24: initial tests for append-only knowledge sync.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { planKnowledgeSync, syncKnowledgeFile } from "../sync.ts";
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "forge-knowledge-sync-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+function entry(id: string, title: string, body: string, layer = "L0"): string {
+  const confirmations =
+    layer === "L2" ? `lastConfirmedAt: 2026-08-03\nconfirmations: 1\n` : "";
+  return `### ${id}: ${title}\n\n\`\`\`knowledge-entry\nid: ${id}\nlayer: ${layer}\ncreated: 2026-08-03\n${confirmations}status: active\n\`\`\`\n\n${body}\n`;
+}
+
+function knowledgeFile(layer: string, entries: string[]): string {
+  return `<!-- knowledge-layer: ${layer} -->\n\n# Knowledge (${layer})\n\n${entries.join("\n")}`;
+}
+
+test("copies file when destination does not exist", () => {
+  const src = join(tempDir, "src", "qa-log.md");
+  const dest = join(tempDir, "dest", "qa-log.md");
+  mkdirSync(join(tempDir, "src"), { recursive: true });
+  const content = knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]);
+  writeFileSync(src, content, "utf8");
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("copied");
+  expect(readFileSync(dest, "utf8")).toBe(content);
+});
+
+test("unchanged when contents are identical", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  const content = knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]);
+  writeFileSync(src, content, "utf8");
+  writeFileSync(dest, content, "utf8");
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("unchanged");
+});
+
+test("merges: local entries preserved, new source entries appended", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(
+    src,
+    knowledgeFile("L0", [
+      entry("K-0001", "First", "Package body."),
+      entry("K-0002", "Second", "New package entry."),
+    ]),
+    "utf8",
+  );
+  writeFileSync(
+    dest,
+    knowledgeFile("L0", [
+      entry("K-0001", "First", "Locally edited body."),
+      entry("K-0057", "Local accumulation", "Project-specific record."),
+    ]),
+    "utf8",
+  );
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("merged");
+  expect(result.appended).toEqual(["K-0002"]);
+  expect(result.conflicts).toEqual(["K-0001"]);
+
+  const merged = readFileSync(dest, "utf8");
+  // Local version of the conflicting entry wins
+  expect(merged).toContain("Locally edited body.");
+  expect(merged).not.toContain("Package body.");
+  // Local accumulated entry preserved
+  expect(merged).toContain("K-0057");
+  expect(merged).toContain("Project-specific record.");
+  // New source entry appended
+  expect(merged).toContain("K-0002");
+  expect(merged).toContain("New package entry.");
+});
+
+test("merge into empty template appends all source entries", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(
+    src,
+    knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]),
+    "utf8",
+  );
+  // Destination is the shipped empty template (layer marker, no entries)
+  writeFileSync(dest, `<!-- knowledge-layer: L0 -->\n\n# Q&A Log (L0)\n`, "utf8");
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("merged");
+  expect(result.appended).toEqual(["K-0001"]);
+  expect(readFileSync(dest, "utf8")).toContain("K-0001");
+});
+
+test("unchanged when source has no new entries (conflicts only)", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(src, knowledgeFile("L0", [entry("K-0001", "First", "Package body.")]), "utf8");
+  writeFileSync(
+    dest,
+    knowledgeFile("L0", [
+      entry("K-0001", "First", "Locally edited body."),
+      entry("K-0002", "Local extra", "Local only."),
+    ]),
+    "utf8",
+  );
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("unchanged");
+  expect(result.conflicts).toEqual(["K-0001"]);
+  // File untouched — local content preserved byte-for-byte
+  expect(readFileSync(dest, "utf8")).toContain("Locally edited body.");
+});
+
+test("skips divergent non-cumulative destination (knowledge-adjacent)", () => {
+  const src = join(tempDir, "forge-about.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(src, "# Forge\n\nNew package template text.\n", "utf8");
+  const localContent = "# Forge\n\nLocally filled-in project description.\n";
+  writeFileSync(dest, localContent, "utf8");
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("skipped");
+  expect(readFileSync(dest, "utf8")).toBe(localContent);
+});
+
+test("skips when destination is cumulative but source is not", () => {
+  const src = join(tempDir, "notes.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(src, "# Plain notes\n\nPackage rewrite.\n", "utf8");
+  const localContent = knowledgeFile("L0", [entry("K-0001", "First", "Local body.")]);
+  writeFileSync(dest, localContent, "utf8");
+
+  const result = syncKnowledgeFile(src, dest);
+
+  expect(result.action).toBe("skipped");
+  expect(readFileSync(dest, "utf8")).toBe(localContent);
+});
+
+test("recurses into declared directories", () => {
+  const srcDir = join(tempDir, "gallery");
+  const destDir = join(tempDir, "dest-gallery");
+  mkdirSync(srcDir, { recursive: true });
+  writeFileSync(join(srcDir, "a.md"), "A package\n", "utf8");
+  writeFileSync(join(srcDir, "b.md"), "B package\n", "utf8");
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync(join(destDir, "b.md"), "B local edits\n", "utf8");
+
+  const result = syncKnowledgeFile(srcDir, destDir);
+
+  expect(result.action).toBe("copied");
+  expect(readFileSync(join(destDir, "a.md"), "utf8")).toBe("A package\n");
+  // Existing local file preserved (non-cumulative → skipped)
+  expect(readFileSync(join(destDir, "b.md"), "utf8")).toBe("B local edits\n");
+});
+
+test("planKnowledgeSync reports merged without writing", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(
+    src,
+    knowledgeFile("L0", [
+      entry("K-0001", "First", "Body one."),
+      entry("K-0002", "Second", "Body two."),
+    ]),
+    "utf8",
+  );
+  const localContent = knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]);
+  writeFileSync(dest, localContent, "utf8");
+
+  const plan = planKnowledgeSync(src, dest);
+
+  expect(plan.action).toBe("merged");
+  expect(plan.appended).toEqual(["K-0002"]);
+  expect(plan.content).not.toBeNull();
+  // No write happened
+  expect(readFileSync(dest, "utf8")).toBe(localContent);
+});
+
+test("planKnowledgeSync reports unchanged for locally accumulated file", () => {
+  const src = join(tempDir, "qa-log.md");
+  const dest = join(tempDir, "dest.md");
+  writeFileSync(src, knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]), "utf8");
+  writeFileSync(
+    dest,
+    knowledgeFile("L0", [
+      entry("K-0001", "First", "Body one."),
+      entry("K-0002", "Local", "Accumulated locally."),
+    ]),
+    "utf8",
+  );
+
+  const plan = planKnowledgeSync(src, dest);
+
+  // Local superset — nothing to merge, not stale
+  expect(plan.action).toBe("unchanged");
+});
+
+test("missing source returns unchanged", () => {
+  const result = syncKnowledgeFile(join(tempDir, "nope.md"), join(tempDir, "dest.md"));
+  expect(result.action).toBe("unchanged");
+  expect(existsSync(join(tempDir, "dest.md"))).toBe(false);
+});

package/src/knowledge/index.ts

@@ -51,3 +51,10 @@ export {
   type DuplicatePair,
   type PromotionPlan,
 } from "./promote.ts";
+export {
+  planKnowledgeSync,
+  syncKnowledgeFile,
+  type KnowledgeSyncAction,
+  type KnowledgeSyncResult,
+  type KnowledgeSyncPlan,
+} from "./sync.ts";