@warpgogol/forge 5.2.0 → 5.2.4

package/src/onboarding/doctor.ts

@@ -35,18 +35,20 @@ import { resolveForgeRoot, loadForgeConfig, resolveBinding, resolveTerminology,
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
 import { discoverWorkspaces } from "./workspace-discovery.ts";
 import { buildNestedAgentsMd, selectNestedTemplate } from "./nested-agents-templates.ts";
-import { readPackageInfo } from "./nested-agents-generate.ts";
+import { readPackageInfo, generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 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";
 import type { DuplicatePair } from "../knowledge/index.ts";
-import { checkMemoryLayerHealth } from "./memory-scaffold.ts";
+import { checkMemoryLayerHealth, resolveMemoryBudget } from "./memory-scaffold.ts";
+import { compactMemoryMd } from "./memory-compact.ts";
 import { checkInvariants } from "./invariant-engine.ts";
 import type { InvariantViolation } from "./invariant-engine.ts";
 import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
@@ -54,6 +56,12 @@ import { execSync } from "node:child_process";
 import fs from "node:fs";
 import type { ProfilePrerequisite } from "../profiles/profile-schema.ts";
 
+interface DoctorFixResult {
+  check: string;
+  action: "fixed" | "skipped" | "failed";
+  detail: string;
+}
+
 interface DoctorCheck {
   name: string;
   status: "pass" | "fail" | "warn";
@@ -243,9 +251,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 +283,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}`);
         }
       }
@@ -825,7 +833,11 @@ async function checkNestedAgentsMd(
     };
   }
 
-  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const workspaces = discoverWorkspaces(
+    workspaceRoot,
+    workspaceTypes,
+    config.bindings?.workspaces?.skipDirs,
+  );
 
   if (workspaces.length === 0) {
     return {
@@ -1208,9 +1220,10 @@ function checkPrerequisites(prerequisites: ProfilePrerequisite[]): DoctorCheck {
 export async function runDoctor(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
-): Promise<ForgeCommandResult<{ command: string; checks: DoctorCheck[]; allPass: boolean; forbiddenImports: ForbiddenImport[]; bindings: BindingValidation; domain?: DomainReport }>> {
-  const { workspaceRoot, logger, outputFormat } = context;
+): Promise<ForgeCommandResult<{ command: string; checks: DoctorCheck[]; allPass: boolean; forbiddenImports: ForbiddenImport[]; bindings: BindingValidation; domain?: DomainReport; fixes?: DoctorFixResult[] }>> {
+  const { workspaceRoot, logger, outputFormat, dryRun } = context;
   const strict = input.flags["strict"] === true;
+  const fix = input.flags["fix"] === true;
   const checks: DoctorCheck[] = [];
 
   // Check forge.yaml
@@ -1417,6 +1430,9 @@ export async function runDoctor(
   // RFC-0664: Check memory layer health (budget, gitignore coverage, leak risk)
   checks.push(checkMemoryLayer(workspaceRoot));
 
+  // RFC-1151: Check dist freshness — stale dist/ silently shadows src/ in source checkouts
+  checks.push(checkDistFreshness(forgeRoot));
+
   // RFC-0539: Check pack skills — stale/missing copies and config validation
   const packCheck = await checkPackSkills(workspaceRoot);
   checks.push(packCheck);
@@ -1434,8 +1450,8 @@ export async function runDoctor(
   // RFC-0640 fix: previously gated by isSoftwareDomain, which skipped the check
   // entirely for non-software domains. Now runs for all domains — profile-driven
   // wsTypes replace hardcoded detection when present.
+  let wsTypes: ProfileWorkspaceType[] | undefined;
   {
-    let wsTypes: ProfileWorkspaceType[] | undefined;
     try {
       const config = loadForgeConfig(workspaceRoot);
       // RFC-0643: prefer config.profile (loaded by loadForgeConfig)
@@ -1471,6 +1487,15 @@ export async function runDoctor(
   const allPass = finalChecks.every((c) => c.status === "pass");
   const hasFails = finalChecks.some((c) => c.status === "fail");
 
+  // RFC-1151: --fix applies registered safe remediations for warn/fail checks
+  const fixes: DoctorFixResult[] = [];
+  if (fix) {
+    for (const check of finalChecks) {
+      if (check.status === "pass") continue;
+      fixes.push(await applyDoctorRemediation(check, workspaceRoot, wsTypes, dryRun === true));
+    }
+  }
+
   if (outputFormat === "pretty") {
     logger.section(`Forge Doctor — ${workspaceRoot}`);
     for (const check of finalChecks) {
@@ -1478,6 +1503,10 @@ export async function runDoctor(
       const fn = check.status === "pass" ? logger.success : check.status === "warn" ? logger.warn : logger.error;
       fn(`${icon} ${check.name}: ${check.message}`);
     }
+    for (const f of fixes) {
+      const fn = f.action === "fixed" ? logger.success : f.action === "failed" ? logger.error : logger.info;
+      fn(`  fix ${f.check}: ${f.action} — ${f.detail}`);
+    }
     if (allPass) {
       logger.success("All checks passed — forge is properly configured.");
     } else if (hasFails) {
@@ -1487,11 +1516,108 @@ export async function runDoctor(
     }
   }
 
+  const fixFailed = fixes.some((f) => f.action === "failed");
+
   return {
-    data: { command: "forge.doctor", checks: finalChecks, allPass, forbiddenImports, bindings: bindingsResult, domain: domainReport },
-    exitCode: hasFails ? 1 : 0,
+    data: { command: "forge.doctor", checks: finalChecks, allPass, forbiddenImports, bindings: bindingsResult, domain: domainReport, ...(fix ? { fixes } : {}) },
+    exitCode: hasFails || fixFailed ? 1 : 0,
     summary: allPass
       ? "forge.doctor: all checks passed"
-      : `forge.doctor: ${finalChecks.filter((c) => c.status === "fail").length} fail(s), ${finalChecks.filter((c) => c.status === "warn").length} warn(s)`,
+      : `forge.doctor: ${finalChecks.filter((c) => c.status === "fail").length} fail(s), ${finalChecks.filter((c) => c.status === "warn").length} warn(s)${fix ? `, ${fixes.filter((f) => f.action === "fixed").length} fixed` : ""}`,
   };
 }
+
+// RFC-1151: dist-freshness — a stale dist/ silently shadows src/ because
+// bin/cli.js prefers dist when present. Warn-only; rebuild is a pnpm script,
+// not forge's call. Pass (skip) when src/ or dist/ is absent — npm consumers
+// ship dist-only, so this activates only in source checkouts.
+function checkDistFreshness(forgeRoot: string): DoctorCheck {
+  const srcDir = join(forgeRoot, "src");
+  const distDir = join(forgeRoot, "dist");
+  if (!fs.existsSync(srcDir) || !fs.existsSync(distDir)) {
+    return {
+      name: "dist-freshness",
+      status: "pass",
+      message: "no src+dist pair — not a source checkout",
+    };
+  }
+  const newestSrc = newestMtime(srcDir);
+  const distMtime = fs.statSync(distDir).mtimeMs;
+  if (newestSrc > distMtime) {
+    return {
+      name: "dist-freshness",
+      status: "warn",
+      message: `dist/ older than newest src/ file — run 'pnpm run build' in ${forgeRoot}`,
+    };
+  }
+  return { name: "dist-freshness", status: "pass", message: "dist/ is fresh" };
+}
+
+function newestMtime(dir: string): number {
+  let newest = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    const m = fs.statSync(join(entry.parentPath, entry.name)).mtimeMs;
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+// RFC-1151: remediation dispatch — check name → safe fix action.
+// Remediations reuse existing generators; hand-written files are never touched
+// (generated-marker edit guard inside generateNestedAgentsMd).
+async function applyDoctorRemediation(
+  check: DoctorCheck,
+  workspaceRoot: string,
+  workspaceTypes: ProfileWorkspaceType[] | undefined,
+  dryRun: boolean,
+): Promise<DoctorFixResult> {
+  switch (check.name) {
+    case "nested-AGENTS.md": {
+      try {
+        const config = loadForgeConfig(workspaceRoot);
+        const res = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes);
+        return {
+          check: check.name,
+          action: res.generated.length > 0 ? "fixed" : "skipped",
+          detail: `${res.generated.length} file(s) ${dryRun ? "would be " : ""}regenerated, ${res.skipped.length} skipped`,
+        };
+      } catch (err) {
+        return { check: check.name, action: "failed", detail: (err as Error).message };
+      }
+    }
+    case "memory-layer": {
+      try {
+        const memoryPath = join(workspaceRoot, ".agents", "memory", "MEMORY.md");
+        if (!fs.existsSync(memoryPath)) {
+          return { check: check.name, action: "skipped", detail: "MEMORY.md absent" };
+        }
+        const content = fs.readFileSync(memoryPath, "utf8");
+        const budget = resolveMemoryBudget(workspaceRoot);
+        const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+        if (!fitsBudget) {
+          return {
+            check: check.name,
+            action: "failed",
+            detail: "still over budget after Environment notes truncation — manual editorial compaction required",
+          };
+        }
+        if (removedLines.length === 0) {
+          return { check: check.name, action: "skipped", detail: "within budget" };
+        }
+        if (!dryRun) {
+          fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+        }
+        return {
+          check: check.name,
+          action: "fixed",
+          detail: `${dryRun ? "would remove" : "removed"} ${removedLines.length} bullet(s)`,
+        };
+      } catch (err) {
+        return { check: check.name, action: "failed", detail: (err as Error).message };
+      }
+    }
+    default:
+      return { check: check.name, action: "skipped", detail: "no-remediation" };
+  }
+}

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/memory-compact.ts

@@ -0,0 +1,188 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge memory.compact — mechanically enforce the MEMORY.md character budget
+(RFC-0664) by removing oldest Environment notes bullets until the file fits.
+Invoked standalone and by forge doctor --fix for the memory-layer check (RFC-1151).</purpose>
+<non-goals>
+  <item>Never touch "## Current focus" or "## Decisions in flight" — those need editorial judgment.</item>
+  <item>No semantic rewriting — bullets are removed whole, never edited or merged.</item>
+  <item>No archiving into daily/ logs — removed content is recoverable via git history.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial memory.compact — oldest-first Environment notes truncation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
+import { resolveMemoryBudget } from "./memory-scaffold.ts";
+
+const MEMORY_MD_PATH = path.join(".agents", "memory", "MEMORY.md");
+const COMPACT_SECTION = "## Environment notes";
+const PROTECTED_SECTIONS = new Set(["## Current focus", "## Decisions in flight"]);
+
+export interface MemoryCompactResult {
+  command: "forge.memory.compact";
+  status: "pass" | "fail";
+  removed: number;
+  remainingChars: number;
+  budget: number;
+  removedLines?: string[];
+  errors: string[];
+}
+
+interface Section {
+  header: string;
+  start: number; // line index of the "## ..." header
+  end: number; // line index one past the section's last line
+}
+
+function parseSections(lines: string[]): Section[] {
+  const sections: Section[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      if (sections.length > 0) sections[sections.length - 1].end = i;
+      sections.push({ header: lines[i].trim(), start: i, end: lines.length });
+    }
+  }
+  return sections;
+}
+
+function isBullet(line: string): boolean {
+  return /^\s*-\s+/.test(line);
+}
+
+/**
+ * Remove oldest bullets from `## Environment notes` until the file fits the
+ * budget. Returns the new line list and the removed bullet lines.
+ * Exported for reuse by `forge doctor --fix` (RFC-1151).
+ */
+export function compactMemoryMd(
+  content: string,
+  budget: number,
+): { lines: string[]; removedLines: string[]; fitsBudget: boolean } {
+  if (content.length <= budget) {
+    return { lines: content.split("\n"), removedLines: [], fitsBudget: true };
+  }
+
+  const lines = content.split("\n");
+  const sections = parseSections(lines);
+  const target = sections.find((s) => s.header === COMPACT_SECTION);
+
+  const removedLines: string[] = [];
+  if (target) {
+    // Sanity: never remove from protected sections even if headers drift.
+    if (PROTECTED_SECTIONS.has(target.header)) {
+      return { lines, removedLines, fitsBudget: false };
+    }
+    // Remove bullet lines oldest-first (document order) within the section.
+    let i = target.start + 1;
+    while (i < target.end && lines.join("\n").length > budget) {
+      if (isBullet(lines[i])) {
+        removedLines.push(lines[i]);
+        lines.splice(i, 1);
+        target.end--;
+        // Recompute section ends after splice — only the target shrinks.
+      } else {
+        i++;
+      }
+    }
+  }
+
+  const fitsBudget = lines.join("\n").length <= budget;
+  return { lines, removedLines, fitsBudget };
+}
+
+export async function runMemoryCompact(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MemoryCompactResult>> {
+  const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const memoryPath = path.join(workspaceRoot, MEMORY_MD_PATH);
+  const budget = resolveMemoryBudget(workspaceRoot);
+
+  const fail = (msg: string): ForgeCommandResult<MemoryCompactResult> => ({
+    data: {
+      command: "forge.memory.compact",
+      status: "fail",
+      removed: 0,
+      remainingChars: 0,
+      budget,
+      errors: [msg],
+    },
+    exitCode: 1,
+    summary: `forge.memory.compact: failed — ${msg}`,
+  });
+
+  if (!fs.existsSync(memoryPath)) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: 0,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: "forge.memory.compact: OK — MEMORY.md absent, nothing to compact",
+    };
+  }
+
+  const content = fs.readFileSync(memoryPath, "utf8");
+  if (content.length <= budget) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: content.length,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: `forge.memory.compact: OK — already within budget (${content.length}/${budget} chars)`,
+    };
+  }
+
+  const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+  const remainingChars = lines.join("\n").length;
+
+  if (!fitsBudget) {
+    return fail(
+      `still over budget after removing ${removedLines.length} Environment notes bullet(s) ` +
+        `(${remainingChars}/${budget} chars) — manual editorial compaction required`,
+    );
+  }
+
+  if (!dryRun) {
+    fs.writeFileSync(memoryPath, lines.join("\n"), "utf8");
+  }
+
+  if (outputFormat === "pretty") {
+    for (const line of removedLines) {
+      logger.info(`removed: ${line.slice(0, 80)}`);
+    }
+    logger.success(
+      `${dryRun ? "[dry-run] would remove" : "removed"} ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`,
+    );
+  }
+
+  return {
+    data: {
+      command: "forge.memory.compact",
+      status: "pass",
+      removed: removedLines.length,
+      remainingChars,
+      budget,
+      removedLines: dryRun ? removedLines : undefined,
+      errors: [],
+    },
+    exitCode: 0,
+    summary: dryRun
+      ? `forge.memory.compact: [dry-run] would remove ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`
+      : `forge.memory.compact: OK — removed ${removedLines.length} bullet(s), ${remainingChars}/${budget} chars`,
+  };
+}

package/src/onboarding/memory-scaffold.ts

@@ -138,7 +138,7 @@ export function scaffoldMemoryLayer(workspaceRoot: string): MemoryScaffoldResult
 // Health check
 // ---------------------------------------------------------------------------
 
-function resolveMemoryBudget(workspaceRoot: string): number {
+export function resolveMemoryBudget(workspaceRoot: string): number {
   try {
     const config = loadForgeConfig(workspaceRoot);
     if (config.bindings?.memory?.budget !== undefined && config.bindings?.memory?.budget !== null) {

package/src/onboarding/nested-agents-generate.ts

@@ -56,7 +56,11 @@ export async function generateNestedAgentsMd(
   dryRun: boolean,
   workspaceTypes?: ProfileWorkspaceType[],
 ): Promise<NestedGenerateResult> {
-  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const workspaces = discoverWorkspaces(
+    workspaceRoot,
+    workspaceTypes,
+    config.bindings?.workspaces?.skipDirs,
+  );
   const generated: string[] = [];
   const skipped: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};

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`
+            : ""),
   };
 }