@warpgogol/forge 5.2.3 → 5.3.0

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

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge memory.compact — mechanical MEMORY.md budget
+enforcement via oldest-first Environment notes truncation (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial memory.compact tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runMemoryCompact, compactMemoryMd } from "../onboarding/memory-compact.ts";
+import type { ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "memory-compact-test-"));
+  await mkdir(join(tempDir, ".agents", "memory"), { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun,
+    outputFormat: "json",
+  };
+}
+
+function memoryMd(envBullets: number, bulletSize = 200): string {
+  const env = Array.from(
+    { length: envBullets },
+    (_, i) => `- env note ${i} ${"x".repeat(bulletSize)}`,
+  ).join("\n");
+  return [
+    "# Project Memory",
+    "",
+    "## Current focus",
+    "",
+    "- keep me",
+    "",
+    "## Decisions in flight",
+    "",
+    "- keep me too",
+    "",
+    "## Environment notes",
+    "",
+    env,
+    "",
+  ].join("\n");
+}
+
+test("compactMemoryMd removes oldest Environment notes bullets until within budget", () => {
+  const content = memoryMd(20);
+  const budget = 2000;
+  const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+
+  expect(fitsBudget).toBe(true);
+  expect(removedLines.length).toBeGreaterThan(0);
+  // Oldest-first: env note 0 removed before env note 19
+  expect(removedLines[0]).toContain("env note 0");
+  expect(lines.join("\n").length).toBeLessThanOrEqual(budget);
+  // Protected sections untouched
+  expect(lines.join("\n")).toContain("- keep me");
+  expect(lines.join("\n")).toContain("- keep me too");
+});
+
+test("compactMemoryMd returns empty removedLines when already within budget", () => {
+  const content = memoryMd(2, 10);
+  const { removedLines, fitsBudget } = compactMemoryMd(content, 4096);
+  expect(removedLines).toHaveLength(0);
+  expect(fitsBudget).toBe(true);
+});
+
+test("runMemoryCompact writes compacted file and reports removed count", async () => {
+  const content = memoryMd(30);
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.status).toBe("pass");
+  expect(result.data?.removed).toBeGreaterThan(0);
+  expect(result.data?.remainingChars).toBeLessThanOrEqual(result.data!.budget);
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after.length).toBeLessThanOrEqual(result.data!.budget);
+  expect(after).toContain("- keep me");
+});
+
+test("runMemoryCompact dryRun reports without writing", async () => {
+  const content = memoryMd(30);
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext(true));
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.removed).toBeGreaterThan(0);
+  expect(result.data?.removedLines?.length).toBe(result.data?.removed);
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after).toBe(content);
+});
+
+test("runMemoryCompact passes when MEMORY.md absent", async () => {
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.removed).toBe(0);
+});
+
+test("runMemoryCompact fails when protected sections alone exceed budget", async () => {
+  // Huge Current focus — Environment notes empty, nothing removable
+  const content = [
+    "# Project Memory",
+    "",
+    "## Current focus",
+    "",
+    `- ${"y".repeat(6000)}`,
+    "",
+    "## Environment notes",
+    "",
+    "- small note",
+    "",
+  ].join("\n");
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(1);
+  expect(result.data?.status).toBe("fail");
+  expect(result.data?.errors[0]).toContain("manual editorial compaction");
+});

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

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

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-1154 skill markers: .forge-managed manifests
+recorded on sync, and the stale-dir prune under the subset-of-manifest rule
+(keeps dirs with consumer files or corrupt markers, never touches unmarked
+dirs).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial marker + prune 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 {
+  SKILL_MARKER_FILE,
+  writeSkillMarker,
+  writeSkillMarkerSync,
+  pruneStaleSkillDirs,
+} from "../onboarding/skill-markers.ts";
+
+let tmpDir: string;
+let skillsDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "skill-marker-"));
+  skillsDir = join(tmpDir, ".agents", "skills");
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function makeSkillDir(name: string, files: string[]): Promise<void> {
+  const dir = join(skillsDir, name);
+  await mkdir(dir, { recursive: true });
+  for (const f of files) {
+    const filePath = join(dir, f);
+    await mkdir(join(filePath, ".."), { recursive: true });
+    await writeFile(filePath, `content of ${f}\n`);
+  }
+}
+
+test("AC-7: writeSkillMarker records the exact file list", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  await writeSkillMarker(dir, ["SKILL.md", "qa-log.md"]);
+  const raw = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  expect(JSON.parse(raw)).toEqual({ files: ["SKILL.md", "qa-log.md"] });
+});
+
+test("marker write is idempotent (identical content on repeat)", async () => {
+  const dir = join(skillsDir, "fo-idea");
+  await mkdir(dir, { recursive: true });
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  const first = await readFile(join(dir, SKILL_MARKER_FILE), "utf8");
+  writeSkillMarkerSync(dir, ["b.md", "a.md"]);
+  expect(await readFile(join(dir, SKILL_MARKER_FILE), "utf8")).toBe(first);
+  expect(JSON.parse(first).files).toEqual(["a.md", "b.md"]); // sorted, deterministic
+});
+
+test("AC-8: prunes a stale marked dir whose contents match the manifest", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["other-skill"]));
+  expect(result.pruned).toEqual(["old-skill"]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("AC-8: keeps a stale marked dir containing consumer files", async () => {
+  const dir = join(skillsDir, "old-skill");
+  await makeSkillDir("old-skill", ["SKILL.md", "my-notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("old-skill");
+  expect(result.keptWithConsumerFiles[0]).toContain("my-notes.md");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("AC-9: unmarked dirs are never pruned", async () => {
+  const dir = join(skillsDir, "consumer-skill");
+  await makeSkillDir("consumer-skill", ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("dirs still in the sync set are kept regardless of marker", async () => {
+  const dir = join(skillsDir, "current-skill");
+  await makeSkillDir("current-skill", ["SKILL.md"]);
+  await writeSkillMarker(dir, ["SKILL.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set(["current-skill"]));
+  expect(result.pruned).toEqual([]);
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("corrupt marker disables prune for that dir (fail-safe keep)", async () => {
+  const dir = join(skillsDir, "broken-skill");
+  await makeSkillDir("broken-skill", ["SKILL.md"]);
+  await writeFile(join(dir, SKILL_MARKER_FILE), "not json {{{");
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual([]);
+  expect(result.keptWithConsumerFiles).toHaveLength(1);
+  expect(result.keptWithConsumerFiles[0]).toContain("corrupt marker");
+  expect(existsSync(dir)).toBe(true);
+});
+
+test("nested manifest files are matched recursively", async () => {
+  const dir = join(skillsDir, "nested-skill");
+  await makeSkillDir("nested-skill", ["SKILL.md", "knowledge/notes.md"]);
+  await writeSkillMarker(dir, ["SKILL.md", "knowledge/notes.md"]);
+
+  const result = await pruneStaleSkillDirs(skillsDir, new Set([]));
+  expect(result.pruned).toEqual(["nested-skill"]);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("missing skills dir returns empty result", async () => {
+  const result = await pruneStaleSkillDirs(join(tmpDir, "nonexistent"), new Set());
+  expect(result).toEqual({ pruned: [], keptWithConsumerFiles: [] });
+});