@warpgogol/forge 5.2.4 → 5.3.0

package/src/tests/file-size-lint.test.ts

@@ -31,7 +31,10 @@ function mockContext(workspaceRoot: string): ForgeRuntimeContext {
   };
 }
 
-function input(flags: Record<string, unknown> = {}): { argv: string[]; flags: Record<string, unknown> } {
+function input(flags: Record<string, unknown> = {}): {
+  argv: string[];
+  flags: Record<string, unknown>;
+} {
   return { argv: [], flags };
 }
 
@@ -108,16 +111,10 @@ describe("runFileSizeLint (RFC-1088, command-level)", () => {
     const big = Array.from({ length: 700 }, (_, i) => `const x${i} = ${i};`).join("\n");
     await writeFile(join(tempDir, "packages", "some-pkg", "src", "big.ts"), big, "utf8");
 
-    const result = await runFileSizeLint(
-      input({ "write-baseline": true }),
-      mockContext(tempDir),
-    );
+    const result = await runFileSizeLint(input({ "write-baseline": true }), mockContext(tempDir));
     expect(result.exitCode ?? 0).toBe(0);
 
-    const baselineRaw = await readFile(
-      join(tempDir, "file-size-lint.baseline.yaml"),
-      "utf8",
-    );
+    const baselineRaw = await readFile(join(tempDir, "file-size-lint.baseline.yaml"), "utf8");
     expect(baselineRaw).toContain("schemaVersion");
     expect(baselineRaw).toContain("threshold: 600");
     expect(baselineRaw).toContain("big.ts");
@@ -155,9 +152,8 @@ describe("runFileSizeLint (RFC-1088, command-level)", () => {
     const result = await runFileSizeLint(input(), mockContext(tempDir));
     expect(result.exitCode ?? 0).toBe(0);
 
-    const diagnostics = (
-      result.data as { diagnostics: Array<{ ruleId: string; message: string }> }
-    ).diagnostics;
+    const diagnostics = (result.data as { diagnostics: Array<{ ruleId: string; message: string }> })
+      .diagnostics;
     const hit = diagnostics.find((d) => d.ruleId === "SIZE-01");
     expect(hit).toBeDefined();
     expect(hit!.message).toContain("grew from the baselined 700 to 800");

package/src/tests/fixtures/agents-generate-business-before.txt

@@ -35,76 +35,76 @@
 
 ## Skills
 
-| Name | Category | Invocation | Concerns |
-| --- | --- | --- | --- |
-| fo-add-tests | fo | user | code-mutation |
-| fo-architecture | fo | user | document-only |
-| fo-compass-annotate | fo | user | content-mutation |
-| fo-design-summit | fo | user | document-only |
-| fo-doc-audit | fo | user | document-only |
-| fo-explore | fo | user | document-only |
-| fo-extract-dna | fo | user | document-only |
-| fo-fix | fo | user | code-mutation |
-| fo-handoff | fo | user | document-only |
-| fo-harvest | fo | user | code-mutation |
-| fo-idea | fo | user | document-only |
-| fo-idea-audit | fo | user | read-only |
-| fo-idea-create-adr | fo | user | document-only |
-| fo-idea-create-rfc | fo | user | document-only |
-| fo-idea-enhance | fo | user | document-only |
-| fo-idea-i-just-want-to-see-the-plan | fo | user | document-only |
-| fo-idea-i-just-want-to-see-the-result | fo | user | code-mutation |
-| fo-idea-implement | fo | user | code-mutation |
-| fo-idea-plan | fo | user | document-only |
-| fo-idea-status | fo | user | read-only |
-| fo-knowledge-distill | fo | user | document-only |
-| fo-memory-sync | fo | user | content-mutation |
-| fo-qa | fo | user | document-only |
-| fo-review | fo | user | read-only |
-| fo-session-retro | fo | user | document-only |
-| fo-session-save | fo | user | document-only |
-| fo-spec-ingest | fo | user | document-only |
-| fo-step-commit | fo | model | code-mutation |
-| fo-triage | fo | user | document-only |
-| forge-bootstrap | meta | user | content-mutation |
-| grilling | shared | user | read-only |
-| my-preferences | shared | user | document-only |
-| port-to-forge | meta | user | code-mutation |
-| skill-create | meta | user | document-only |
-| windows-ai-tooling | shared | user | code-mutation |
-| writing-great-skills | shared | user | read-only |
+| Name                                  | Category | Invocation | Concerns         |
+| ------------------------------------- | -------- | ---------- | ---------------- |
+| fo-add-tests                          | fo       | user       | code-mutation    |
+| fo-architecture                       | fo       | user       | document-only    |
+| fo-compass-annotate                   | fo       | user       | content-mutation |
+| fo-design-summit                      | fo       | user       | document-only    |
+| fo-doc-audit                          | fo       | user       | document-only    |
+| fo-explore                            | fo       | user       | document-only    |
+| fo-extract-dna                        | fo       | user       | document-only    |
+| fo-fix                                | fo       | user       | code-mutation    |
+| fo-handoff                            | fo       | user       | document-only    |
+| fo-harvest                            | fo       | user       | code-mutation    |
+| fo-idea                               | fo       | user       | document-only    |
+| fo-idea-audit                         | fo       | user       | read-only        |
+| fo-idea-create-adr                    | fo       | user       | document-only    |
+| fo-idea-create-rfc                    | fo       | user       | document-only    |
+| fo-idea-enhance                       | fo       | user       | document-only    |
+| fo-idea-i-just-want-to-see-the-plan   | fo       | user       | document-only    |
+| fo-idea-i-just-want-to-see-the-result | fo       | user       | code-mutation    |
+| fo-idea-implement                     | fo       | user       | code-mutation    |
+| fo-idea-plan                          | fo       | user       | document-only    |
+| fo-idea-status                        | fo       | user       | read-only        |
+| fo-knowledge-distill                  | fo       | user       | document-only    |
+| fo-memory-sync                        | fo       | user       | content-mutation |
+| fo-qa                                 | fo       | user       | document-only    |
+| fo-review                             | fo       | user       | read-only        |
+| fo-session-retro                      | fo       | user       | document-only    |
+| fo-session-save                       | fo       | user       | document-only    |
+| fo-spec-ingest                        | fo       | user       | document-only    |
+| fo-step-commit                        | fo       | model      | code-mutation    |
+| fo-triage                             | fo       | user       | document-only    |
+| forge-bootstrap                       | meta     | user       | content-mutation |
+| grilling                              | shared   | user       | read-only        |
+| my-preferences                        | shared   | user       | document-only    |
+| port-to-forge                         | meta     | user       | code-mutation    |
+| skill-create                          | meta     | user       | document-only    |
+| windows-ai-tooling                    | shared   | user       | code-mutation    |
+| writing-great-skills                  | shared   | user       | read-only        |
 
 ## Capabilities
 
 Bindings resolved from `forge.yaml`:
 
-| Key | Status | Value |
-| --- | --- | --- |
-| commands.validateRfc | resolved | `pnpm exec forge rfc.validate` |
-| commands.validateAdr | resolved | `pnpm exec forge adr.validate` |
-| commands.typecheck | absent | — |
-| commands.test | absent | — |
-| commands.scopedBuild | absent | — |
+| Key                   | Status   | Value                           |
+| --------------------- | -------- | ------------------------------- |
+| commands.validateRfc  | resolved | `pnpm exec forge rfc.validate`  |
+| commands.validateAdr  | resolved | `pnpm exec forge adr.validate`  |
+| commands.typecheck    | absent   | —                               |
+| commands.test         | absent   | —                               |
+| commands.scopedBuild  | absent   | —                               |
 | commands.specValidate | resolved | `pnpm exec forge spec.validate` |
-| commands.sessionSave | resolved | `pnpm exec forge session.save` |
-| paths.invariantsFile | resolved | `docs/architecture-dna.md` |
-| paths.reviewsDir | resolved | `docs/reviews` |
-| paths.handoffsDir | resolved | `docs/handoffs` |
-| paths.sessionsDir | resolved | `docs/sessions` |
-| paths.compassDocs | resolved | `docs/requirements.xml` |
+| commands.sessionSave  | resolved | `pnpm exec forge session.save`  |
+| paths.invariantsFile  | resolved | `docs/architecture-dna.md`      |
+| paths.reviewsDir      | resolved | `docs/reviews`                  |
+| paths.handoffsDir     | resolved | `docs/handoffs`                 |
+| paths.sessionsDir     | resolved | `docs/sessions`                 |
+| paths.compassDocs     | resolved | `docs/requirements.xml`         |
 
 <!-- forge:begin behavioral-layer -->
 
 ## Behavioral layer
 
-This section defines the agent's core behavioral contract. It is generated from skill `triggers` and fixed policy text. The agent MUST follow these behaviors in every session.
+This section defines the agent's core behavioral contract. It is generated from skill `triggerPhrases` and fixed policy text. The agent MUST follow these behaviors in every session.
 
 ### Intent-to-skill routing
 
-When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggers` fields in skill frontmatter.
+When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggerPhrases` fields in skill frontmatter.
 
 | Operator says something like | Skill |
-| --- | --- |
+| ---------------------------- | ----- |
 
 The agent uses judgment to calibrate routing — minor edits (typo fixes, small CSS changes) do not require skill invocation, while significant changes (new features, architectural decisions) do.
 

package/src/tests/markdown-table.test.ts

@@ -0,0 +1,107 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for alignMarkdownTable + parseMarkdownTable (RFC-1154):
+prettier-normal emission, separator dash-padding, escaped-pipe literals,
+idempotency, and a regression guard over forge emission surfaces.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial table-emitter tests + compact-separator regression guard.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { alignMarkdownTable, parseMarkdownTable } from "../utils/markdown-table.ts";
+
+test("aligns cells and pads separator with dashes to column width", () => {
+  const out = alignMarkdownTable(
+    ["Name", "Value"],
+    [
+      ["long-name-here", "x"],
+      ["a", "b"],
+    ],
+  );
+  expect(out).toBe(
+    [
+      "| Name           | Value |",
+      "| -------------- | ----- |",
+      "| long-name-here | x     |",
+      "| a              | b     |",
+    ].join("\n"),
+  );
+});
+
+test("minimum column width is 3 even for short cells", () => {
+  const out = alignMarkdownTable(["a", "b"], [["1", "2"]]);
+  expect(out).toBe("| a   | b   |\n| --- | --- |\n| 1   | 2   |");
+});
+
+test("escaped pipe inside a cell is a literal, not a delimiter", () => {
+  const out = alignMarkdownTable(["Pattern", "Meaning"], [["a \\| b", "or"]]);
+  const lines = out.split("\n");
+  expect(lines[0]).toBe("| Pattern | Meaning |");
+  expect(lines[1]).toBe("| ------- | ------- |");
+  expect(lines[2]).toBe("| a \\| b  | or      |");
+});
+
+test("rows shorter or longer than headers extend the column set", () => {
+  const out = alignMarkdownTable(["A"], [["x", "extra"]]);
+  expect(out.split("\n")[0]).toBe("| A   |       |");
+  expect(out.split("\n")[2]).toBe("| x   | extra |");
+});
+
+test("empty input emits empty string", () => {
+  expect(alignMarkdownTable([], [])).toBe("");
+});
+
+test("AC-5: re-aligning emitted output is byte-identical", () => {
+  const once = alignMarkdownTable(
+    ["Name", "Category", "Concerns"],
+    [
+      ["fo-idea", "fo", "classification"],
+      ["wg-mission", "wg", "lifecycle"],
+    ],
+  );
+  const parsed = parseMarkdownTable(once);
+  expect(parsed).not.toBeNull();
+  const twice = alignMarkdownTable(parsed!.headers, parsed!.rows);
+  expect(twice, "align(parse(emit)) must be byte-stable — check separator width math").toBe(once);
+});
+
+test("parseMarkdownTable returns null for non-table input", () => {
+  expect(parseMarkdownTable("just prose\nno table here")).toBeNull();
+  expect(parseMarkdownTable("| a |\nno separator")).toBeNull();
+});
+
+test("parseMarkdownTable splits on unescaped pipes only", () => {
+  const parsed = parseMarkdownTable("| a \\| b | c |\n| --- | --- |\n| 1 | 2 |");
+  expect(parsed).not.toBeNull();
+  expect(parsed!.headers).toEqual(["a \\| b", "c"]);
+});
+
+test("regression guard: no forge emitter emits a compact '| --- |' separator", () => {
+  const srcDir = join(import.meta.dirname, "..");
+  const offenders: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        if (entry === "tests" || entry === "__tests__") continue;
+        walk(full);
+        continue;
+      }
+      if (!entry.endsWith(".ts")) continue;
+      const content = readFileSync(full, "utf8");
+      // Flag compact separator literals — all tables must route through
+      // alignMarkdownTable. The aligner itself lives in utils/markdown-table.ts.
+      if (full.endsWith("markdown-table.ts")) continue;
+      if (/\| -{2,} \|/.test(content)) offenders.push(full);
+    }
+  };
+  walk(srcDir);
+  expect(
+    offenders,
+    "compact '| --- |' table literals found — route through alignMarkdownTable",
+  ).toEqual([]);
+});

package/src/tests/prettierignore-manage.test.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the RFC-1154 managed .prettierignore block:
+root-only prettier detection, delimited-block reconcile preserving operator
+content, marker-driven skill entries, and the skipped contract for
+prettier-free consumers.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial prettierignore plan/apply tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  planPrettierignore,
+  applyPrettierignore,
+  reconcilePrettierignoreContent,
+  PRETTIERIGNORE_BLOCK_BEGIN,
+  PRETTIERIGNORE_BLOCK_END,
+} from "../onboarding/prettierignore.ts";
+import { SKILL_MARKER_FILE } from "../onboarding/skill-markers.ts";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "prettierignore-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function withPrettier(root: string): Promise<void> {
+  await writeFile(join(root, ".prettierrc"), "{}\n");
+}
+
+test("detects prettier via root .prettierrc", async () => {
+  await withPrettier(tmpDir);
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via package.json prettier key", async () => {
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({ prettier: {} }));
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via prettier devDependency", async () => {
+  await writeFile(
+    join(tmpDir, "package.json"),
+    JSON.stringify({ devDependencies: { prettier: "^3" } }),
+  );
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("detects prettier via existing .prettierignore alone", async () => {
+  await writeFile(join(tmpDir, ".prettierignore"), "dist/\n");
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(true);
+});
+
+test("AC-4: no prettier markers — plan does not apply, apply writes nothing", async () => {
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.applies).toBe(false);
+  const result = await applyPrettierignore(tmpDir, plan);
+  expect(result).toBe("skipped");
+  expect(existsSync(join(tmpDir, ".prettierignore"))).toBe(false);
+});
+
+test("AC-2: block contains generated.yaml glob, sessions, metrics, queues entries", async () => {
+  await withPrettier(tmpDir);
+  const plan = await planPrettierignore(tmpDir);
+  const result = await applyPrettierignore(tmpDir, plan);
+  expect(result).toBe("written");
+  const content = await readFile(join(tmpDir, ".prettierignore"), "utf8");
+  expect(content).toContain(PRETTIERIGNORE_BLOCK_BEGIN);
+  expect(content).toContain("**/*.generated.yaml");
+  expect(content).toContain("docs/sessions/");
+  expect(content).toContain("docs/metrics/");
+  expect(content).toContain("docs/queues/session-*.yaml");
+  expect(content).toContain(PRETTIERIGNORE_BLOCK_END);
+});
+
+test("skill entries enumerate only marker-carrying dirs (AC-9)", async () => {
+  await withPrettier(tmpDir);
+  const skillsDir = join(tmpDir, ".agents", "skills");
+  await mkdir(join(skillsDir, "fo-idea"), { recursive: true });
+  await writeFile(join(skillsDir, "fo-idea", SKILL_MARKER_FILE), '{"files":["SKILL.md"]}');
+  await mkdir(join(skillsDir, "my-own-skill"), { recursive: true }); // unmarked — consumer-owned
+
+  const plan = await planPrettierignore(tmpDir);
+  expect(plan.entries).toContain(".agents/skills/fo-idea/");
+  expect(plan.entries).not.toContain(".agents/skills/my-own-skill/");
+});
+
+test("reconcile preserves operator content outside the block", async () => {
+  const existing = `dist/\nnode_modules/\n${PRETTIERIGNORE_BLOCK_BEGIN}\nold-entry/\n${PRETTIERIGNORE_BLOCK_END}\ncustom/\n`;
+  const { next, changed } = reconcilePrettierignoreContent(existing, ["a/", "b/"]);
+  expect(changed).toBe("updated");
+  expect(next).toContain("dist/\nnode_modules/\n");
+  expect(next).toContain("custom/\n");
+  expect(next).not.toContain("old-entry/");
+  expect(next).toContain("a/\nb/");
+});
+
+test("unbalanced markers treat the file as operator-owned and append a fresh block", async () => {
+  const existing = `dist/\n${PRETTIERIGNORE_BLOCK_BEGIN}\nstray/\n`; // no END marker
+  const { next, changed } = reconcilePrettierignoreContent(existing, ["x/"]);
+  expect(changed).toBe("updated");
+  expect(next).toContain("dist/\n");
+  // Original content preserved verbatim — forge does not merge into a
+  // corrupted region; a fresh block is appended.
+  expect(next.indexOf(PRETTIERIGNORE_BLOCK_BEGIN)).toBeLessThan(
+    next.lastIndexOf(PRETTIERIGNORE_BLOCK_BEGIN),
+  );
+});
+
+test("repeated apply is idempotent", async () => {
+  await withPrettier(tmpDir);
+  await writeFile(join(tmpDir, ".prettierignore"), "dist/\n");
+  const plan = await planPrettierignore(tmpDir);
+  const first = await applyPrettierignore(tmpDir, plan);
+  expect(first).toBe("updated");
+  const second = await applyPrettierignore(tmpDir, await planPrettierignore(tmpDir));
+  expect(second, "second apply must be unchanged — check reconcile block boundaries").toBe(
+    "unchanged",
+  );
+});

package/src/tests/skill-agents-sync.test.ts

@@ -0,0 +1,168 @@
+/*
+<MODULE_CONTRACT>
+<purpose>CI gate: every forge/pack skill source must be fully propagated to
+`.agents/skills/` (IDE discovery copy written by forge.init/forge.upgrade).
+SKILL.md syncs verbatim; declared knowledge files follow the append-only
+syncKnowledgeFile contract — in the canonical repo a resync must be a no-op,
+otherwise source and copy have drifted apart.</purpose>
+<non-goals>
+  <item>Do not validate skill content/schema — forge.skill.validate owns that.</item>
+  <item>Do not flag unmarked dirs — a missing .forge-managed marker means
+    consumer-owned (RFC-1154), e.g. `_shared/`.</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>planKnowledgeSync is reused so the gate encodes the exact merge
+    semantics of the syncer — only "unchanged" is a pass; "merged" (source has
+    entries the copy lacks), "copied" (copy missing), and "skipped"
+    (non-mergeable divergence = hand-edited copy) all fail.</item>
+  <item>Runs on the real repo — this is a drift gate, not a fixture test.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>Initial version — covers FORGE_SKILLS, declared pack skills
+    (discoverPackSkills), and the shared-knowledge layer.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { loadForgeConfig } from "../config/forge-config.ts";
+import { planKnowledgeSync } from "../knowledge/index.ts";
+import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
+
+const forgeRoot = path.resolve(import.meta.dirname, "../..");
+const workspaceRoot = path.resolve(import.meta.dirname, "../../../..");
+
+interface SkillSource {
+  name: string;
+  srcDir: string;
+  knowledge: string[];
+}
+
+function collectSkillSources(): SkillSource[] {
+  const sources: SkillSource[] = [];
+  for (const skill of FORGE_SKILLS) {
+    sources.push({
+      name: skill.name,
+      srcDir: path.dirname(path.join(forgeRoot, skill.path)),
+      knowledge: skill.knowledge ?? [],
+    });
+  }
+  const config = loadForgeConfig(workspaceRoot);
+  for (const skill of discoverPackSkills(workspaceRoot, config)) {
+    sources.push({
+      name: skill.name,
+      srcDir: path.dirname(path.join(workspaceRoot, skill.dir, skill.path)),
+      knowledge: skill.knowledge ?? [],
+    });
+  }
+  return sources;
+}
+
+// Skipped in the standalone package repo — the gate needs a forge-managed
+// workspace root (forge.yaml + synced skillsDir), which only exists for the
+// monorepo and consumer projects, not for the published forge source tree.
+const hasForgeWorkspace = fs.existsSync(path.join(workspaceRoot, "forge.yaml"));
+describe.runIf(hasForgeWorkspace)(
+  ".agents/skills sync gate (forge.init/forge.upgrade parity)",
+  () => {
+    // describe callbacks still run during collection even when runIf is false,
+    // so initializers must tolerate the absent forge.yaml themselves.
+    const config = hasForgeWorkspace ? loadForgeConfig(workspaceRoot) : null;
+    const skillsDir = config ? path.join(workspaceRoot, config.paths.skillsDir) : "";
+    const sources = config ? collectSkillSources() : [];
+
+    it("every forge + pack skill has a synced copy in .agents/skills/", () => {
+      const missing = sources
+        .filter((s) => !fs.existsSync(path.join(skillsDir, s.name, "SKILL.md")))
+        .map((s) => `${s.name} (src ${path.relative(workspaceRoot, s.srcDir)})`);
+      expect(
+        missing,
+        `skills never synced — run \`forge init\`/\`forge upgrade\` to populate ${path.relative(workspaceRoot, skillsDir)}`,
+      ).toEqual([]);
+    });
+
+    it("SKILL.md copies are byte-identical to their sources", () => {
+      const drifted: string[] = [];
+      for (const s of sources) {
+        const src = path.join(s.srcDir, "SKILL.md");
+        const dest = path.join(skillsDir, s.name, "SKILL.md");
+        if (!fs.existsSync(dest)) continue; // reported by the presence test
+        if (fs.readFileSync(src, "utf8") !== fs.readFileSync(dest, "utf8")) {
+          drifted.push(s.name);
+        }
+      }
+      expect(
+        drifted,
+        "SKILL.md drift — edit the pack source and re-sync, never edit .agents/skills/ directly",
+      ).toEqual([]);
+    });
+
+    it("declared knowledge files are in sync (append-only merge would be a no-op)", () => {
+      const stale: string[] = [];
+      for (const s of sources) {
+        for (const kf of s.knowledge) {
+          const src = path.join(s.srcDir, kf);
+          const dest = path.join(skillsDir, s.name, kf);
+          if (!fs.existsSync(src)) {
+            stale.push(`${s.name}/${kf} — declared but missing in source`);
+            continue;
+          }
+          if (!fs.existsSync(dest)) {
+            stale.push(`${s.name}/${kf} — missing in .agents/skills (run forge upgrade)`);
+            continue;
+          }
+          const plan = planKnowledgeSync(src, dest);
+          if (plan.action === "merged") {
+            stale.push(`${s.name}/${kf} — source has entries the copy lacks`);
+          } else if (plan.action === "skipped") {
+            stale.push(`${s.name}/${kf} — copy diverged non-mergeably (hand-edited .agents copy)`);
+          }
+        }
+      }
+      expect(stale).toEqual([]);
+    });
+
+    it("undeclared aux files in the copy still match their sources", () => {
+      // The syncer writes SKILL.md + declared knowledge files only. Aux files
+      // (references, templates, placeholder dirs) that exist in BOTH trees are
+      // hand-copied and silently diverge — a same-named pair must stay identical,
+      // and a copy-only orphan can never resync.
+      const flagged: string[] = [];
+      for (const s of sources) {
+        const destDir = path.join(skillsDir, s.name);
+        if (!fs.existsSync(destDir)) continue;
+        const declared = new Set(["SKILL.md", ".forge-managed", ...s.knowledge]);
+        for (const entry of fs.readdirSync(destDir)) {
+          if (declared.has(entry)) continue;
+          const srcEntry = path.join(s.srcDir, entry);
+          const destEntry = path.join(destDir, entry);
+          if (fs.statSync(destEntry).isDirectory()) {
+            if (!fs.existsSync(srcEntry))
+              flagged.push(`${s.name}/${entry}/ — dir absent in source`);
+            continue;
+          }
+          if (!fs.existsSync(srcEntry)) {
+            flagged.push(`${s.name}/${entry} — absent in source, copy can never resync`);
+          } else if (fs.readFileSync(srcEntry, "utf8") !== fs.readFileSync(destEntry, "utf8")) {
+            flagged.push(`${s.name}/${entry} — diverged from source`);
+          }
+        }
+      }
+      expect(
+        flagged,
+        "aux-file drift — declare aux files via `knowledge:` in SKILL.md or keep copies identical to source",
+      ).toEqual([]);
+    });
+
+    it("shared-knowledge layer is synced", () => {
+      const src = path.join(forgeRoot, "skills", "shared", "knowledge", "learned-principles.md");
+      const dest = path.join(skillsDir, "shared-knowledge", "learned-principles.md");
+      if (!fs.existsSync(src)) return; // layer absent — nothing to gate
+      expect(fs.existsSync(dest), "shared-knowledge/learned-principles.md not synced").toBe(true);
+      const plan = planKnowledgeSync(src, dest);
+      expect(plan.action, `shared-knowledge drift (sync action: ${plan.action})`).toBe("unchanged");
+    });
+  },
+);