@warpgogol/forge 5.2.0 → 5.2.4

package/src/config/forge-config.ts

@@ -83,6 +83,13 @@ export const forgeBindingsSchema = z.object({
       budget: z.number().int().positive().default(4096),
     })
     .optional(),
+  // RFC-1150: consumer-declared directory names excluded from workspace
+  // discovery (merged over the SKIP_DIRS defaults in workspace-discovery.ts).
+  workspaces: z
+    .object({
+      skipDirs: z.array(z.string()).default([]),
+    })
+    .optional(),
 });
 
 export interface ForgeBindings {
@@ -126,6 +133,10 @@ export interface ForgeBindings {
   memory?: {
     budget: number;
   };
+  // RFC-1150: consumer-declared workspace discovery exclusions
+  workspaces?: {
+    skipDirs: string[];
+  };
 }
 
 // ---------------------------------------------------------------------------

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/agents-generate.ts

@@ -2,7 +2,7 @@
 <MODULE_CONTRACT>
 <purpose>forge.agents.generate — regenerates AGENTS.md deterministically from forge.yaml + skill registry. Carries the standard generated-file marker.</purpose>
 <non-goals>
-  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — refuse with exit 1.</item>
+  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — skip with warning, continue nested (RFC-1150).</item>
   <item>Do not read or modify forge.yaml — only read it via loadForgeConfig.</item>
 </non-goals>
 </MODULE_CONTRACT>
@@ -215,6 +215,9 @@ interface AgentsGenerateResult {
   errors: string[];
   renderedFiles?: { [relPath: string]: string };
   details?: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }>;
+  // RFC-1150: set when the root AGENTS.md was skipped (hand-written, no marker)
+  rootSkipped?: boolean;
+  rootSkipReason?: string;
 }
 
 export async function runAgentsGenerate(
@@ -247,26 +250,18 @@ export async function runAgentsGenerate(
 
   const agentsMdPath = path.join(workspaceRoot, "AGENTS.md");
 
-  // Edit guard: refuse to overwrite a hand-written AGENTS.md (skipped in dryRun)
+  // Edit guard: never overwrite a hand-written AGENTS.md — skip the root file
+  // with a warning and continue to nested generation (RFC-1150, non-fatal).
+  let rootSkipped = false;
   if (!dryRun && fs.existsSync(agentsMdPath)) {
     const existing = fs.readFileSync(agentsMdPath, "utf8");
     if (!hasGeneratedMarker(existing)) {
-      const msg = `AGENTS.md exists without a generated marker — refusing to overwrite a hand-written file. Delete or rename it first, then re-run forge.agents.generate.`;
+      rootSkipped = true;
       if (outputFormat === "pretty") {
-        logger.error(msg);
+        logger.warn(
+          "AGENTS.md exists without a generated marker — skipping root file (hand-written). Nested AGENTS.md generation continues.",
+        );
       }
-      return {
-        data: {
-          command: "forge.agents.generate",
-          status: "fail",
-          configPath: "forge.yaml",
-          generated: [],
-          skipped: [],
-          errors: [msg],
-        },
-        exitCode: 1,
-        summary: `forge.agents.generate: failed — hand-written AGENTS.md`,
-      };
     }
   }
 
@@ -371,7 +366,7 @@ export async function runAgentsGenerate(
   const resolvedTerminology = resolveAllTerminology(config, profile);
   content = substituteTemplate(content, resolvedTerminology);
 
-  const generated: string[] = ["AGENTS.md"];
+  const generated: string[] = [];
   const skipped: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};
   const details: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }> = [];
@@ -383,8 +378,12 @@ export async function runAgentsGenerate(
 
   if (dryRun) {
     renderedFiles["AGENTS.md"] = content;
+    generated.push("AGENTS.md");
+  } else if (rootSkipped) {
+    skipped.push("AGENTS.md (hand-written)");
   } else {
     await writeFileIfChanged(agentsMdPath, content);
+    generated.push("AGENTS.md");
     if (outputFormat === "pretty") {
       logger.success(`Generated ${path.relative(workspaceRoot, agentsMdPath)}`);
     }
@@ -443,11 +442,12 @@ export async function runAgentsGenerate(
       skipped,
       errors: [],
       details,
+      ...(rootSkipped ? { rootSkipped: true, rootSkipReason: "hand-written" } : {}),
       ...(dryRun ? { renderedFiles } : {}),
     },
     exitCode: 0,
     summary: dryRun
       ? `forge.agents.generate: [dry-run] would generate ${generated.length} file(s), skip ${skipped.length}`
-      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped`,
+      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped${rootSkipped ? " (root AGENTS.md hand-written — skipped)" : ""}`,
   };
 }