@warpgogol/forge 2.8.0 → 2.8.2

package/src/tests/init-bindings.test.ts

@@ -0,0 +1,183 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Integration tests for forge.init binding defaults (RFC-0540).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0540: initial init binding defaults integration tests.</item>
+  <item>RFC-0552: add test for Forge-vs-pack skill name conflict detection.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runInit } from "../onboarding/init.ts";
+import { loadForgeConfig } from "../config/forge-config.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-init-bindings-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function setupForgeSource(dir: string): Promise<void> {
+  await mkdir(join(dir, "packages", "forge", "skills"), { recursive: true });
+  await writeFile(
+    join(dir, "packages", "forge", "package.json"),
+    '{"name":"@warpgogol/forge"}',
+    "utf8",
+  );
+  await mkdir(join(dir, "packages", "forge", "os", "rfc"), { recursive: true });
+  await writeFile(
+    join(dir, "packages", "forge", "os", "rfc", "rfc-0000-template.md"),
+    "# RFC Template",
+    "utf8",
+  );
+  await mkdir(join(dir, "packages", "forge", "profiles"), { recursive: true });
+}
+
+test("forge.init creates forge.yaml with non-null forge-CLI bindings and null stack bindings", async () => {
+  await setupForgeSource(tempDir);
+
+  runInit({ flags: {} }, { workspaceRoot: tempDir });
+
+  const config = loadForgeConfig(tempDir);
+  expect(config.bindings).toBeDefined();
+  expect(config.bindings?.commands.validateRfc).toBe(
+    "pnpm exec forge rfc.validate --id {id} --json",
+  );
+  expect(config.bindings?.commands.validateAdr).toBe(
+    "pnpm exec forge adr.validate --id {id} --json",
+  );
+  expect(config.bindings?.commands.implementStamp).toBe(
+    "pnpm exec forge rfc.implement.stamp --id {id} --implementation-commit {commit}",
+  );
+  expect(config.bindings?.commands.specValidate).toBe(
+    "pnpm exec forge spec.validate --spec={id} --json",
+  );
+  expect(config.bindings?.commands.sessionSave).toBe("pnpm exec forge session.save --json");
+  expect(config.bindings?.commands.typecheck).toBeNull();
+  expect(config.bindings?.commands.test).toBeNull();
+  expect(config.bindings?.commands.scopedBuild).toBeNull();
+});
+
+test("forge.yaml written by forge.init contains forge-CLI binding strings", async () => {
+  await setupForgeSource(tempDir);
+
+  runInit({ flags: {} }, { workspaceRoot: tempDir });
+
+  const yamlContent = await readFile(join(tempDir, "forge.yaml"), "utf8");
+  expect(yamlContent).toContain("forge rfc.validate");
+  expect(yamlContent).toContain("forge adr.validate");
+  expect(yamlContent).toContain("forge rfc.implement.stamp");
+  expect(yamlContent).toContain("forge spec.validate");
+  expect(yamlContent).toContain("forge session.save");
+});
+
+test("forge.init does not overwrite existing forge.yaml", async () => {
+  await setupForgeSource(tempDir);
+  const existingYaml = `schema: forge/config@1
+project:
+  name: existing
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: "custom command"
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+`;
+  await writeFile(join(tempDir, "forge.yaml"), existingYaml, "utf8");
+
+  const result = runInit({ flags: {} }, { workspaceRoot: tempDir });
+  expect(result.skipped).toContain("forge.yaml (already exists)");
+
+  const config = loadForgeConfig(tempDir);
+  expect(config.bindings?.commands.validateRfc).toBe("custom command");
+});
+
+test("RFC-0552: forge.init returns skippedSkills field and syncs non-conflicting pack skills", async () => {
+  await setupForgeSource(tempDir);
+
+  // Create a pack with prefix 'wg' containing a non-conflicting skill
+  await mkdir(join(tempDir, "packages", "wg-skills", "skills", "wg-custom"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "wg-skills", "skills", "wg-custom", "SKILL.md"),
+    "---\nname: wg-custom\n---\n# wg-custom (should be synced)\n",
+    "utf8",
+  );
+
+  // Write forge.yaml with skillPacks config
+  const yaml = `schema: forge/config@1
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+skillPacks:
+  - prefix: wg
+    dir: packages/wg-skills/skills
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+`;
+  await writeFile(join(tempDir, "forge.yaml"), yaml, "utf8");
+
+  const result = runInit(
+    { flags: {} },
+    { workspaceRoot: tempDir, forgeRoot: join(tempDir, "packages", "forge") },
+  );
+
+  // skippedSkills field should exist and be empty (no conflicts)
+  expect(result.skippedSkills).toBeDefined();
+  expect(result.skippedSkills).toEqual([]);
+
+  // The non-conflicting pack skill should be synced
+  const wgSkillPath = join(tempDir, ".agents", "skills", "wg-custom", "SKILL.md");
+  expect(existsSync(wgSkillPath)).toBe(true);
+});

package/src/tests/knowledge-parse.test.ts

@@ -0,0 +1,307 @@
+import { test, expect, describe } from "vitest";
+import { parseKnowledgeFile } from "../knowledge/parse.ts";
+import { serializeKnowledgeFile } from "../knowledge/serialize.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+function writeTempFile(content: string, fileName: string): string {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-knowledge-"));
+  const filePath = path.join(tmpDir, fileName);
+  fs.writeFileSync(filePath, content, "utf8");
+  return filePath;
+}
+
+describe("RFC-0660: knowledge file parser", () => {
+  test("valid L0 entry with minimal metadata parses correctly", () => {
+    const content = `<!-- knowledge-layer: L0 -->
+# Q&A Log
+
+### K-0001: First question
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+status: active
+\`\`\`
+
+- **Question:** Is this a test?
+- **Answer:** Yes.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.isKnowledgeAdjacent).toBe(false);
+      expect(parsed.layer).toBe("L0");
+      expect(parsed.entries).toHaveLength(1);
+      expect(parsed.entries[0].meta.id).toBe("K-0001");
+      expect(parsed.entries[0].meta.layer).toBe("L0");
+      expect(parsed.entries[0].meta.status).toBe("active");
+      expect(parsed.entries[0].title).toBe("First question");
+      expect(parsed.entries[0].body).toContain("Is this a test?");
+      expect(parsed.parseIssues).toHaveLength(0);
+      expect(parsed.legacySections).toHaveLength(0);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("valid L2 entry with confirmations and lastConfirmedAt parses correctly", () => {
+    const content = `<!-- knowledge-layer: L2 -->
+# Learned Principles
+
+### K-0001: Test principle
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 3
+status: active
+\`\`\`
+
+This is a confirmed principle.
+`;
+    const filePath = writeTempFile(content, "learned-principles.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.entries).toHaveLength(1);
+      expect(parsed.entries[0].meta.confirmations).toBe(3);
+      expect(parsed.entries[0].meta.lastConfirmedAt).toBe("2026-08-03");
+      expect(parsed.parseIssues).toHaveLength(0);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("L0 with forbidden confirmations produces parse issue", () => {
+    const content = `<!-- knowledge-layer: L0 -->
+# Q&A Log
+
+### K-0001: Bad entry
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+confirmations: 5
+status: active
+\`\`\`
+
+Body.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.parseIssues.length).toBeGreaterThan(0);
+      expect(parsed.parseIssues.some((i) => i.message.includes("confirmations"))).toBe(true);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("L2 without required confirmations produces parse issue", () => {
+    const content = `<!-- knowledge-layer: L2 -->
+# Learned Principles
+
+### K-0001: Incomplete entry
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+status: active
+\`\`\`
+
+Body.
+`;
+    const filePath = writeTempFile(content, "learned-principles.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.parseIssues.length).toBeGreaterThan(0);
+      expect(parsed.parseIssues.some((i) => i.message.includes("confirmations is required"))).toBe(
+        true,
+      );
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("malformed YAML in metadata block produces parse issue, does not throw", () => {
+    const content = `<!-- knowledge-layer: L0 -->
+# Q&A Log
+
+### K-0001: Broken entry
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+status: [unclosed
+\`\`\`
+
+Body.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.parseIssues.length).toBeGreaterThan(0);
+      expect(parsed.entries).toHaveLength(0);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("knowledge-adjacent file (no K-NNNN headings, no layer preamble) returns empty result", () => {
+    const content = `# About Forge
+
+This is a knowledge-adjacent file with no entries and no layer declaration.
+It should be exempt from SKILL-19/SKILL-20.
+`;
+    const filePath = writeTempFile(content, "forge-about.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.isKnowledgeAdjacent).toBe(true);
+      expect(parsed.entries).toHaveLength(0);
+      expect(parsed.legacySections).toHaveLength(0);
+      expect(parsed.parseIssues).toHaveLength(0);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("file with layer but no entries is structured-empty (not knowledge-adjacent)", () => {
+    const content = `<!-- knowledge-layer: L0 -->
+# Q&A Log
+
+<!-- Entries are appended by the skill during runs. -->
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.isKnowledgeAdjacent).toBe(false);
+      expect(parsed.layer).toBe("L0");
+      expect(parsed.entries).toHaveLength(0);
+      expect(parsed.legacySections).toHaveLength(0);
+      expect(parsed.parseIssues).toHaveLength(0);
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("layer detected via filename convention when no preamble comment", () => {
+    const content = `# Q&A Log
+
+### K-0001: Test
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+status: active
+\`\`\`
+
+Body.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.layer).toBe("L0");
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("layer comment overrides filename convention", () => {
+    const content = `<!-- knowledge-layer: L2 -->
+# Custom File
+
+### K-0001: Test
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+\`\`\`
+
+Body.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed = parseKnowledgeFile(filePath);
+      expect(parsed.layer).toBe("L2");
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+
+  test("non-existent file returns empty result without throwing", () => {
+    const parsed = parseKnowledgeFile("/nonexistent/path/to/file.md");
+    expect(parsed.isKnowledgeAdjacent).toBe(true);
+    expect(parsed.entries).toHaveLength(0);
+  });
+
+  test("directory path returns empty result without throwing", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-knowledge-dir-"));
+    try {
+      const parsed = parseKnowledgeFile(tmpDir);
+      expect(parsed.isKnowledgeAdjacent).toBe(true);
+      expect(parsed.entries).toHaveLength(0);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("RFC-0660: knowledge file serializer round-trip", () => {
+  test("parse → serialize → parse produces identical metadata", () => {
+    const content = `<!-- knowledge-layer: L0 -->
+# Q&A Log
+
+### K-0001: First question
+
+\`\`\`knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+status: active
+\`\`\`
+
+- **Question:** Is this a test?
+- **Answer:** Yes.
+
+### K-0002: Second question
+
+\`\`\`knowledge-entry
+id: K-0002
+layer: L0
+created: 2026-08-03
+status: active
+\`\`\`
+
+- **Question:** Another question?
+- **Answer:** Another answer.
+`;
+    const filePath = writeTempFile(content, "qa-log.md");
+    try {
+      const parsed1 = parseKnowledgeFile(filePath);
+      const serialized = serializeKnowledgeFile(parsed1);
+      const filePath2 = writeTempFile(serialized, "qa-log.md");
+      const parsed2 = parseKnowledgeFile(filePath2);
+
+      expect(parsed2.entries).toHaveLength(parsed1.entries.length);
+      for (let i = 0; i < parsed1.entries.length; i++) {
+        expect(parsed2.entries[i].meta).toEqual(parsed1.entries[i].meta);
+        expect(parsed2.entries[i].title).toBe(parsed1.entries[i].title);
+      }
+      fs.rmSync(path.dirname(filePath2), { recursive: true, force: true });
+    } finally {
+      fs.rmSync(path.dirname(filePath), { recursive: true, force: true });
+    }
+  });
+});

package/src/tests/knowledge-pbt.test.ts

@@ -0,0 +1,164 @@
+import { test, expect, describe } from "vitest";
+import { parseKnowledgeFile } from "../knowledge/parse.ts";
+import { serializeKnowledgeFile } from "../knowledge/serialize.ts";
+import { knowledgeEntryMetaSchema, type KnowledgeEntryMeta } from "../knowledge/schema.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import fc from "fast-check";
+
+function buildMarkdown(entries: KnowledgeEntryMeta[], layer: string, fileName: string): string {
+  const parts: string[] = [`<!-- knowledge-layer: ${layer} -->`, `# ${fileName}`, ""];
+  for (const meta of entries) {
+    parts.push(`### ${meta.id}: Test entry`);
+    parts.push("");
+    parts.push("```knowledge-entry");
+    const fields: [string, unknown][] = [
+      ["id", meta.id],
+      ["layer", meta.layer],
+      ["created", meta.created],
+    ];
+    if (meta.lastConfirmedAt !== undefined) fields.push(["lastConfirmedAt", meta.lastConfirmedAt]);
+    if (meta.confirmations !== undefined) fields.push(["confirmations", meta.confirmations]);
+    if (meta.expiresAt !== undefined) fields.push(["expiresAt", meta.expiresAt]);
+    if (meta.supersedes !== undefined) fields.push(["supersedes", meta.supersedes]);
+    if (meta.promotedTo !== undefined) fields.push(["promotedTo", meta.promotedTo]);
+    fields.push(["status", meta.status]);
+    for (const [key, value] of fields) {
+      if (value === null) {
+        parts.push(`${key}: null`);
+      } else if (Array.isArray(value)) {
+        parts.push(`${key}: [${value.join(", ")}]`);
+      } else {
+        parts.push(`${key}: ${value}`);
+      }
+    }
+    parts.push("```");
+    parts.push("");
+    parts.push("Body text for this entry.");
+    parts.push("");
+  }
+  return parts.join("\n");
+}
+
+function writeTempFile(content: string, fileName: string): string {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-knowledge-pbt-"));
+  const filePath = path.join(tmpDir, fileName);
+  fs.writeFileSync(filePath, content, "utf8");
+  return filePath;
+}
+
+describe("RFC-0660: property-based round-trip", () => {
+  test("parse → serialize → parse produces identical metadata for L0 entries", () => {
+    const l0EntryArbitrary = fc.integer({ min: 1, max: 9999 }).map((n) => ({
+      id: `K-${String(n).padStart(4, "0")}`,
+      layer: "L0" as const,
+      created: "2026-08-03",
+      status: "active" as const,
+    })) as fc.Arbitrary<KnowledgeEntryMeta>;
+
+    fc.assert(
+      fc.property(fc.array(l0EntryArbitrary, { minLength: 1, maxLength: 5 }), (entries) => {
+        const markdown = buildMarkdown(entries, "L0", "qa-log.md");
+        const filePath1 = writeTempFile(markdown, "qa-log.md");
+        try {
+          const parsed1 = parseKnowledgeFile(filePath1);
+          const serialized = serializeKnowledgeFile(parsed1);
+          const filePath2 = writeTempFile(serialized, "qa-log.md");
+          try {
+            const parsed2 = parseKnowledgeFile(filePath2);
+            expect(parsed2.entries.length).toBe(parsed1.entries.length);
+            for (let i = 0; i < parsed1.entries.length; i++) {
+              expect(parsed2.entries[i].meta).toEqual(parsed1.entries[i].meta);
+            }
+          } finally {
+            fs.rmSync(path.dirname(filePath2), { recursive: true, force: true });
+          }
+        } finally {
+          fs.rmSync(path.dirname(filePath1), { recursive: true, force: true });
+        }
+      }),
+      { numRuns: 50 },
+    );
+  });
+
+  test("parse → serialize → parse produces identical metadata for L2 entries", () => {
+    const l2EntryArbitrary = fc.integer({ min: 1, max: 9999 }).map((n) => ({
+      id: `K-${String(n).padStart(4, "0")}`,
+      layer: "L2" as const,
+      created: "2026-08-03",
+      lastConfirmedAt: "2026-08-03",
+      confirmations: n % 100,
+      status: "active" as const,
+    })) as fc.Arbitrary<KnowledgeEntryMeta>;
+
+    fc.assert(
+      fc.property(fc.array(l2EntryArbitrary, { minLength: 1, maxLength: 5 }), (entries) => {
+        const markdown = buildMarkdown(entries, "L2", "learned-principles.md");
+        const filePath1 = writeTempFile(markdown, "learned-principles.md");
+        try {
+          const parsed1 = parseKnowledgeFile(filePath1);
+          const serialized = serializeKnowledgeFile(parsed1);
+          const filePath2 = writeTempFile(serialized, "learned-principles.md");
+          try {
+            const parsed2 = parseKnowledgeFile(filePath2);
+            expect(parsed2.entries.length).toBe(parsed1.entries.length);
+            for (let i = 0; i < parsed1.entries.length; i++) {
+              expect(parsed2.entries[i].meta).toEqual(parsed1.entries[i].meta);
+            }
+          } finally {
+            fs.rmSync(path.dirname(filePath2), { recursive: true, force: true });
+          }
+        } finally {
+          fs.rmSync(path.dirname(filePath1), { recursive: true, force: true });
+        }
+      }),
+      { numRuns: 50 },
+    );
+  });
+
+  test("schema validates well-formed L0 entry", () => {
+    const validL0 = {
+      id: "K-0001",
+      layer: "L0",
+      created: "2026-08-03",
+      status: "active",
+    };
+    expect(knowledgeEntryMetaSchema.safeParse(validL0).success).toBe(true);
+  });
+
+  test("schema validates well-formed L2 entry with confirmations", () => {
+    const validL2 = {
+      id: "K-0001",
+      layer: "L2",
+      created: "2026-08-03",
+      lastConfirmedAt: "2026-08-03",
+      confirmations: 3,
+      status: "active",
+    };
+    expect(knowledgeEntryMetaSchema.safeParse(validL2).success).toBe(true);
+  });
+
+  test("schema rejects L0 with confirmations", () => {
+    const invalidL0 = {
+      id: "K-0001",
+      layer: "L0",
+      created: "2026-08-03",
+      confirmations: 5,
+      status: "active",
+    };
+    const result = knowledgeEntryMetaSchema.safeParse(invalidL0);
+    expect(result.success).toBe(false);
+  });
+
+  test("schema rejects L2 without confirmations", () => {
+    const invalidL2 = {
+      id: "K-0001",
+      layer: "L2",
+      created: "2026-08-03",
+      status: "active",
+    };
+    const result = knowledgeEntryMetaSchema.safeParse(invalidL2);
+    expect(result.success).toBe(false);
+  });
+});