@warpgogol/forge 5.2.0 → 5.2.3

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/tests/upgrade.test.ts

@@ -431,3 +431,56 @@ test("forge.upgrade without --update-npm does not attempt npm install", async ()
   expect(result.data?.npmUpdated).toBe(false);
   expect(result.data?.npmUpdateSkipped).toBe(null);
 });
+
+function qaLog(entries: { id: string; title: string; body: string }[]): string {
+  const blocks = entries.map(
+    (e) =>
+      `### ${e.id}: ${e.title}\n\n\`\`\`knowledge-entry\nid: ${e.id}\nlayer: L0\ncreated: 2026-08-03\nstatus: active\n\`\`\`\n\n${e.body}\n`,
+  );
+  return `<!-- knowledge-layer: L0 -->\n\n# Q&A Log (L0)\n\n${blocks.join("\n")}`;
+}
+
+test("forge.upgrade preserves project-accumulated knowledge entries (append-only merge)", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  // Declare a knowledge file on the fixture skill
+  await writeFile(
+    join(tempDir, "packages", "forge", "skills", "fo", "fo-idea", "SKILL.md"),
+    "---\nname: fo-idea\nknowledge: [qa-log.md]\n---\n# fo-idea\n",
+    "utf8",
+  );
+  // Package ships K-0001 + new K-0003
+  await writeFile(
+    join(tempDir, "packages", "forge", "skills", "fo", "fo-idea", "qa-log.md"),
+    qaLog([
+      { id: "K-0001", title: "First", body: "Package body." },
+      { id: "K-0003", title: "Third", body: "New package entry." },
+    ]),
+    "utf8",
+  );
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // Local copy already accumulated: edited K-0001 + project-only K-0002
+  await mkdir(join(tempDir, ".agents", "skills", "fo-idea"), { recursive: true });
+  await writeFile(
+    join(tempDir, ".agents", "skills", "fo-idea", "qa-log.md"),
+    qaLog([
+      { id: "K-0001", title: "First", body: "Locally edited body." },
+      { id: "K-0002", title: "Local record", body: "Project-accumulated entry." },
+    ]),
+    "utf8",
+  );
+
+  const result = await runUpgrade({ argv: [], flags: {} }, makeContext(tempDir, false));
+
+  expect(result.data?.status).toBe("pass");
+  const merged = await readFile(join(tempDir, ".agents", "skills", "fo-idea", "qa-log.md"), "utf8");
+  // Local entries preserved — the data-loss bug would have wiped K-0002
+  expect(merged).toContain("K-0002");
+  expect(merged).toContain("Project-accumulated entry.");
+  // Local version of the conflicting entry wins
+  expect(merged).toContain("Locally edited body.");
+  expect(merged).not.toContain("Package body.");
+  // New package entry appended
+  expect(merged).toContain("K-0003");
+  expect(merged).toContain("New package entry.");
+});

package/src/types.ts

@@ -16,6 +16,7 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>RFC-1147: ForgeRegisteredCommandInfo.provider narrowed to "workspace" and siteName field removed — forge never enumerated sites; mirrors the KernelRegisteredCommandInfo cleanup.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -112,8 +113,7 @@ export interface GateMetadata {
 
 export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
   name: string;
-  provider: "workspace" | "site";
-  siteName?: string;
+  provider: "workspace";
   module?: string;
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];

package/src/utils/fs-atomic.ts

@@ -56,7 +56,7 @@ function sleep(ms: number): Promise<void> {
 function makeTempPath(filePath: string): string {
   const dir = dirname(filePath);
   const name = basename(filePath);
-  const random = randomBytes(6).toString("hex");
+  const random = Array.from(randomBytes(6), (b) => b.toString(16).padStart(2, "0")).join("");
   return join(dir, `${name}.${random}.tmp`);
 }