@warpgogol/forge 5.2.0 → 5.2.3

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.2.0",
+  "version": "5.2.3",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

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";

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}`);
         }
       }