gsd-pi 2.16.0 → 2.18.0

package/src/resources/extensions/gsd/tests/context-compression.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Context Compression — unit tests for M004/S02.
+ *
+ * Verifies that prompt builders respect inlineLevel parameter by
+ * inspecting the auto-prompts.ts source for level-aware gating.
+ * Cannot call builders directly due to @gsd/pi-coding-agent import
+ * resolution — uses source-level structural verification instead.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const promptsSrc = readFileSync(join(__dirname, "..", "auto-prompts.ts"), "utf-8");
+
+// ═══════════════════════════════════════════════════════════════════════════
+// inlineLevel Parameter Presence
+// ═══════════════════════════════════════════════════════════════════════════
+
+const BUILDERS_WITH_LEVEL = [
+  "buildPlanMilestonePrompt",
+  "buildPlanSlicePrompt",
+  "buildExecuteTaskPrompt",
+  "buildCompleteSlicePrompt",
+  "buildCompleteMilestonePrompt",
+  "buildReassessRoadmapPrompt",
+];
+
+for (const builder of BUILDERS_WITH_LEVEL) {
+  test(`compression: ${builder} accepts inlineLevel parameter`, () => {
+    // Find the function signature
+    const sigRegex = new RegExp(`export async function ${builder}\\([^)]*level\\?: InlineLevel`);
+    assert.ok(
+      sigRegex.test(promptsSrc),
+      `${builder} should have level?: InlineLevel parameter`,
+    );
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Default Level Resolution
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: builders default to resolveInlineLevel() when no level passed", () => {
+  const defaultPattern = /const inlineLevel = level \?\? resolveInlineLevel\(\)/g;
+  const matches = promptsSrc.match(defaultPattern);
+  assert.ok(matches, "should have resolveInlineLevel() fallback");
+  assert.ok(
+    matches.length >= BUILDERS_WITH_LEVEL.length,
+    `should have ${BUILDERS_WITH_LEVEL.length} fallback instances, found ${matches?.length}`,
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Minimal Level — Template Reduction
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: buildExecuteTaskPrompt minimal drops decisions template", () => {
+  // In the execute-task builder, minimal should only inline task-summary, not decisions
+  assert.ok(
+    promptsSrc.includes('inlineLevel === "minimal"') &&
+    promptsSrc.includes('inlineTemplate("task-summary"'),
+    "execute-task should conditionally include decisions template based on level",
+  );
+});
+
+test("compression: buildExecuteTaskPrompt minimal truncates prior summaries", () => {
+  assert.ok(
+    promptsSrc.includes('inlineLevel === "minimal" && priorSummaries.length > 1'),
+    "execute-task should limit prior summaries for minimal level",
+  );
+});
+
+test("compression: buildPlanMilestonePrompt minimal drops project/requirements/decisions files", () => {
+  // The plan-milestone builder should gate root file inlining on inlineLevel
+  assert.ok(
+    promptsSrc.includes('inlineLevel !== "minimal"') &&
+    promptsSrc.includes('inlineGsdRootFile(base, "project.md"'),
+    "plan-milestone should conditionally include project.md based on level",
+  );
+});
+
+test("compression: buildPlanMilestonePrompt minimal drops extra templates", () => {
+  // Full inlines 5 templates, minimal should inline fewer
+  assert.ok(
+    promptsSrc.includes('if (inlineLevel === "full")') &&
+    promptsSrc.includes('inlineTemplate("secrets-manifest"'),
+    "plan-milestone should only include secrets-manifest template at full level",
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Complete-Slice Level Gating
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: buildCompleteSlicePrompt minimal drops requirements", () => {
+  // Find the complete-slice section and verify requirements gating
+  const completeSliceIdx = promptsSrc.indexOf("buildCompleteSlicePrompt");
+  const nextBuilder = promptsSrc.indexOf("buildCompleteMilestonePrompt");
+  const completeSliceBlock = promptsSrc.slice(completeSliceIdx, nextBuilder);
+  assert.ok(
+    completeSliceBlock.includes('inlineLevel !== "minimal"'),
+    "complete-slice should gate requirements inlining on level",
+  );
+});
+
+test("compression: buildCompleteSlicePrompt minimal drops UAT template", () => {
+  const completeSliceIdx = promptsSrc.indexOf("buildCompleteSlicePrompt");
+  const nextBuilder = promptsSrc.indexOf("buildCompleteMilestonePrompt");
+  const completeSliceBlock = promptsSrc.slice(completeSliceIdx, nextBuilder);
+  assert.ok(
+    completeSliceBlock.includes('inlineLevel !== "minimal"') &&
+    completeSliceBlock.includes('inlineTemplate("uat"'),
+    "complete-slice should conditionally include UAT template based on level",
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Complete-Milestone Level Gating
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: buildCompleteMilestonePrompt minimal drops root GSD files", () => {
+  const completeMilestoneIdx = promptsSrc.indexOf("buildCompleteMilestonePrompt");
+  const nextBuilder = promptsSrc.indexOf("buildReplanSlicePrompt");
+  const block = promptsSrc.slice(completeMilestoneIdx, nextBuilder);
+  assert.ok(
+    block.includes('inlineLevel !== "minimal"') &&
+    block.includes('inlineGsdRootFile(base, "requirements.md"'),
+    "complete-milestone should gate root file inlining on level",
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Reassess-Roadmap Level Gating
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: buildReassessRoadmapPrompt minimal drops project/requirements/decisions", () => {
+  const reassessIdx = promptsSrc.indexOf("buildReassessRoadmapPrompt");
+  const block = promptsSrc.slice(reassessIdx, reassessIdx + 1500);
+  assert.ok(
+    block.includes('inlineLevel !== "minimal"'),
+    "reassess-roadmap should gate file inlining on level",
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Full Level — No Regression
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: full level preserves all templates and files (no regression)", () => {
+  // Verify the key template names are still present in the source
+  const expectedTemplates = [
+    "roadmap", "decisions", "plan", "task-plan", "secrets-manifest",
+    "task-summary", "slice-summary", "uat", "milestone-summary",
+  ];
+  for (const tpl of expectedTemplates) {
+    assert.ok(
+      promptsSrc.includes(`inlineTemplate("${tpl}"`),
+      `template "${tpl}" should still be present in auto-prompts.ts`,
+    );
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Import Verification
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("compression: auto-prompts.ts imports resolveInlineLevel and InlineLevel", () => {
+  assert.ok(
+    promptsSrc.includes("resolveInlineLevel"),
+    "should import resolveInlineLevel from preferences",
+  );
+  assert.ok(
+    promptsSrc.includes("InlineLevel"),
+    "should import InlineLevel type from types",
+  );
+});

package/src/resources/extensions/gsd/tests/derive-state-deps.test.ts

@@ -303,6 +303,105 @@ async function main(): Promise<void> {
     }
   }
 
+  // ─── Test Group 7: unique-id-deps ──────────────────────────────────────
+  // M004-0zjrg0 is complete, M005-b0m2hl depends_on M004-0zjrg0 → M005 should activate.
+  // Regression: parseContextDependsOn() used .toUpperCase(), converting "M004-0zjrg0"
+  // to "M004-0ZJRG0", breaking the case-sensitive lookup in completeMilestoneIds.
+  console.log('\n=== unique-id-deps: unique milestone IDs with lowercase hex suffix ===');
+  {
+    const base = createFixtureBase();
+    try {
+      // M004-0zjrg0: complete (all slices done + SUMMARY present)
+      writeRoadmap(base, 'M004-0zjrg0', `# M004-0zjrg0: First Unique Milestone
+
+**Vision:** Complete milestone with unique ID.
+
+## Slices
+
+- [x] **S01: Done** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+`);
+      writeMilestoneSummary(base, 'M004-0zjrg0', '# M004-0zjrg0 Summary\n\nComplete.');
+
+      // M005-b0m2hl: depends on M004-0zjrg0 (lowercase hex suffix)
+      writeContext(base, 'M005-b0m2hl', 'depends_on: [M004-0zjrg0]');
+
+      const state = await deriveState(base);
+
+      assertEq(state.registry.find(e => e.id === 'M004-0zjrg0')?.status, 'complete',
+        'unique-id-deps: M004-0zjrg0 is complete');
+      assertEq(state.registry.find(e => e.id === 'M005-b0m2hl')?.status, 'active',
+        'unique-id-deps: M005-b0m2hl is active (dep on M004-0zjrg0 met)');
+      assertEq(state.activeMilestone?.id, 'M005-b0m2hl',
+        'unique-id-deps: activeMilestone is M005-b0m2hl');
+      assertTrue(state.phase !== 'blocked',
+        'unique-id-deps: phase is not blocked');
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  // ─── Test Group 8: unique-id-deps-blocked ─────────────────────────────
+  // M004-0zjrg0 is NOT complete, M005-b0m2hl depends_on M004-0zjrg0 → M005 should be pending
+  console.log('\n=== unique-id-deps-blocked: unique ID dep not yet met ===');
+  {
+    const base = createFixtureBase();
+    try {
+      // M004-0zjrg0: incomplete (slice not done)
+      writeRoadmap(base, 'M004-0zjrg0', `# M004-0zjrg0: Incomplete Unique Milestone
+
+**Vision:** Still in progress.
+
+## Slices
+
+- [ ] **S01: In Progress** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+`);
+      writeSlicePlan(base, 'M004-0zjrg0', 'S01', `# S01: In Progress
+
+**Goal:** Test dep blocking with unique IDs.
+
+## Tasks
+
+- [ ] **T01: Work** \`est:15m\`
+  Still doing work.
+`);
+
+      // M005-b0m2hl: depends on M004-0zjrg0 (still incomplete)
+      writeContext(base, 'M005-b0m2hl', 'depends_on: [M004-0zjrg0]');
+
+      const state = await deriveState(base);
+
+      assertEq(state.activeMilestone?.id, 'M004-0zjrg0',
+        'unique-id-deps-blocked: activeMilestone is M004-0zjrg0');
+      assertEq(state.registry.find(e => e.id === 'M005-b0m2hl')?.status, 'pending',
+        'unique-id-deps-blocked: M005-b0m2hl is pending (dep not met)');
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  // ─── Test Group 9: parseContextDependsOn preserves case ───────────────
+  // Direct unit test: verify the parsed dep ID matches the input exactly
+  console.log('\n=== parseContextDependsOn: preserves case of unique IDs ===');
+  {
+    const { parseContextDependsOn } = await import('../files.ts');
+
+    const deps1 = parseContextDependsOn('---\ndepends_on: [M004-0zjrg0]\n---\n');
+    assertEq(deps1[0], 'M004-0zjrg0',
+      'parseContextDependsOn preserves lowercase hex suffix');
+
+    const deps2 = parseContextDependsOn('---\ndepends_on: [M001, M004-abc123]\n---\n');
+    assertEq(deps2[0], 'M001', 'preserves classic uppercase ID');
+    assertEq(deps2[1], 'M004-abc123', 'preserves mixed-case unique ID');
+
+    const deps3 = parseContextDependsOn('---\ndepends_on: []\n---\n');
+    assertEq(deps3.length, 0, 'empty deps returns empty array');
+
+    const deps4 = parseContextDependsOn(null);
+    assertEq(deps4.length, 0, 'null content returns empty array');
+  }
+
   report();
 }
 

package/src/resources/extensions/gsd/tests/git-service.test.ts

@@ -1020,6 +1020,138 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ─── commit_docs: false — smartStage excludes .gsd/ ──────────────────
+
+  console.log("\n=== commit_docs: false — smartStage excludes .gsd/ ===");
+
+  {
+    const repo = mkdtempSync(join(tmpdir(), "gsd-commit-docs-"));
+    run("git init -b main", repo);
+    run("git config user.email test@test.com", repo);
+    run("git config user.name Test", repo);
+    writeFileSync(join(repo, "README.md"), "init");
+    run("git add -A && git commit -m init", repo);
+
+    // Create .gsd/ planning files + a normal source file
+    mkdirSync(join(repo, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "milestones", "M001", "ROADMAP.md"), "# Roadmap");
+    writeFileSync(join(repo, ".gsd", "preferences.md"), "---\nversion: 1\n---");
+    writeFileSync(join(repo, "src.ts"), "const x = 1;");
+
+    // With commit_docs: false, smartStage should exclude .gsd/
+    const svc = new GitServiceImpl(repo, { commit_docs: false });
+    const msg = svc.commit({ message: "test commit" });
+    assertTrue(msg !== null, "commit_docs=false: commit succeeds with non-.gsd files");
+
+    // .gsd/ files should NOT be in the commit
+    const committed = run("git show --name-only HEAD", repo);
+    assertTrue(!committed.includes(".gsd/"), "commit_docs=false: .gsd/ files not in commit");
+    assertTrue(committed.includes("src.ts"), "commit_docs=false: source files ARE in commit");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── commit_docs: true (default) — smartStage includes .gsd/ ────────
+
+  console.log("\n=== commit_docs: true — smartStage includes .gsd/ ===");
+
+  {
+    const repo = mkdtempSync(join(tmpdir(), "gsd-commit-docs-default-"));
+    run("git init -b main", repo);
+    run("git config user.email test@test.com", repo);
+    run("git config user.name Test", repo);
+    writeFileSync(join(repo, "README.md"), "init");
+    run("git add -A && git commit -m init", repo);
+
+    mkdirSync(join(repo, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "milestones", "M001", "ROADMAP.md"), "# Roadmap");
+    writeFileSync(join(repo, "src.ts"), "const x = 1;");
+
+    // Default behavior (commit_docs not set) — .gsd/ files ARE committed
+    const svc = new GitServiceImpl(repo);
+    const msg = svc.commit({ message: "test commit" });
+    assertTrue(msg !== null, "commit_docs=default: commit succeeds");
+
+    const committed = run("git show --name-only HEAD", repo);
+    assertTrue(committed.includes(".gsd/"), "commit_docs=default: .gsd/ files ARE in commit");
+    assertTrue(committed.includes("src.ts"), "commit_docs=default: source files in commit");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── writeIntegrationBranch: commitDocs false skips commit ──────────
+
+  console.log("\n=== writeIntegrationBranch: commitDocs false skips commit ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const commitsBefore = run("git rev-list --count HEAD", repo);
+
+    writeIntegrationBranch(repo, "M001", "f-123-new-thing", { commitDocs: false });
+
+    // File should still be written to disk
+    assertEq(readIntegrationBranch(repo, "M001"), "f-123-new-thing",
+      "commitDocs=false: metadata file exists on disk");
+
+    // But no new commit should have been created
+    const commitsAfter = run("git rev-list --count HEAD", repo);
+    assertEq(commitsBefore, commitsAfter,
+      "commitDocs=false: no git commit created for integration branch");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── ensureGitignore: commit_docs false adds blanket .gsd/ ──────────
+
+  console.log("\n=== ensureGitignore: commit_docs false ===");
+
+  {
+    const { ensureGitignore } = await import("../gitignore.ts");
+    const repo = mkdtempSync(join(tmpdir(), "gsd-gitignore-commit-docs-"));
+
+    // When commit_docs is false, should add blanket .gsd/ to gitignore
+    const modified = ensureGitignore(repo, { commitDocs: false });
+    assertTrue(modified, "commit_docs=false: gitignore was modified");
+
+    const { readFileSync } = await import("node:fs");
+    const content = readFileSync(join(repo, ".gitignore"), "utf-8");
+    assertTrue(content.includes(".gsd/"), "commit_docs=false: .gitignore contains blanket .gsd/");
+    assertTrue(content.includes("commit_docs: false"), "commit_docs=false: .gitignore contains explanatory comment");
+
+    // Should NOT contain individual runtime patterns (those are subsumed by blanket .gsd/)
+    // But it's OK if it does — the blanket .gsd/ covers everything
+
+    // Idempotent — calling again doesn't add duplicates
+    const modified2 = ensureGitignore(repo, { commitDocs: false });
+    assertTrue(!modified2, "commit_docs=false: second call is idempotent");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── ensureGitignore: commit_docs true removes blanket .gsd/ ────────
+
+  console.log("\n=== ensureGitignore: commit_docs true self-heals ===");
+
+  {
+    const { ensureGitignore } = await import("../gitignore.ts");
+    const repo = mkdtempSync(join(tmpdir(), "gsd-gitignore-selfheal-"));
+
+    // Start with a gitignore that has a blanket .gsd/ (e.g., user switched setting)
+    writeFileSync(join(repo, ".gitignore"), ".gsd/\n");
+
+    const modified = ensureGitignore(repo, { commitDocs: true });
+    assertTrue(modified, "commit_docs=true: gitignore was modified");
+
+    const { readFileSync } = await import("node:fs");
+    const content = readFileSync(join(repo, ".gitignore"), "utf-8");
+    // Blanket .gsd/ should be removed
+    const lines = content.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#"));
+    assertTrue(!lines.includes(".gsd/"), "commit_docs=true: blanket .gsd/ was removed");
+    assertTrue(!lines.includes(".gsd"), "commit_docs=true: blanket .gsd was removed");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
   report();
 }
 

package/src/resources/extensions/gsd/tests/in-flight-tool-tracking.test.ts

@@ -0,0 +1,79 @@
+/**
+ * In-flight tool tracking tests — verifies that markToolStart/markToolEnd
+ * correctly manage the in-flight tools set used by the idle watchdog to
+ * distinguish "agent waiting on long-running tool" from "agent is idle".
+ *
+ * Background: The idle watchdog checks every 15s for agent progress. Without
+ * in-flight tool tracking, agents waiting on await_job or async_bash (which
+ * can run 20+ minutes for evaluations, deployments, test suites) are falsely
+ * declared idle and interrupted by recovery steering messages.
+ *
+ * The fix hooks tool_execution_start/end events to track active tool calls.
+ * When tools are in-flight, the watchdog resets lastProgressAt instead of
+ * triggering idle recovery.
+ */
+
+import { markToolStart, markToolEnd, isAutoActive } from "../auto.ts";
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+// ═══ markToolStart / markToolEnd basic behavior ═════════════════════════════
+
+{
+  console.log("\n=== markToolStart: no-op when auto-mode is not active ===");
+  // When auto-mode is not active, markToolStart should silently ignore
+  // (the guard `if (!active) return` prevents set pollution outside auto-mode)
+  assertTrue(!isAutoActive(), "auto-mode should not be active in tests");
+  markToolStart("tool-1");
+  // We can't directly inspect the set, but markToolEnd should be a safe no-op
+  markToolEnd("tool-1");
+  // If we got here without error, the guard works
+  assertTrue(true, "markToolStart/markToolEnd are safe no-ops when inactive");
+}
+
+{
+  console.log("\n=== markToolEnd: no-op for unknown toolCallId ===");
+  // Set.delete on non-existent key is a no-op — verify no crash
+  markToolEnd("nonexistent-tool-call-id");
+  assertTrue(true, "markToolEnd handles unknown IDs gracefully");
+}
+
+{
+  console.log("\n=== markToolEnd: idempotent — double-end does not crash ===");
+  markToolEnd("some-id");
+  markToolEnd("some-id");
+  assertTrue(true, "double markToolEnd is safe");
+}
+
+// ═══ Integration contract: expected exports from auto.ts ═════════════════════
+
+{
+  console.log("\n=== auto.ts exports markToolStart and markToolEnd ===");
+  assertEq(typeof markToolStart, "function", "markToolStart should be a function");
+  assertEq(typeof markToolEnd, "function", "markToolEnd should be a function");
+}
+
+{
+  console.log("\n=== markToolStart accepts string toolCallId ===");
+  // Verify the function signature handles string input without error
+  // (when inactive, this is a no-op but should not throw)
+  try {
+    markToolStart("toolu_01ABC123");
+    assertTrue(true, "accepts standard Claude tool call ID format");
+  } catch (e) {
+    assertTrue(false, `should not throw: ${e}`);
+  }
+}
+
+{
+  console.log("\n=== markToolEnd accepts string toolCallId ===");
+  try {
+    markToolEnd("toolu_01ABC123");
+    assertTrue(true, "accepts standard Claude tool call ID format");
+  } catch (e) {
+    assertTrue(false, `should not throw: ${e}`);
+  }
+}
+
+report();

package/src/resources/extensions/gsd/tests/knowledge.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Unit tests for KNOWLEDGE.md integration.
+ *
+ * Tests:
+ * - KNOWLEDGE is registered in GSD_ROOT_FILES
+ * - resolveGsdRootFile resolves KNOWLEDGE paths correctly
+ * - inlineGsdRootFile works with the KNOWLEDGE key
+ * - before_agent_start hook includes/omits knowledge block appropriately
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { GSD_ROOT_FILES, resolveGsdRootFile } from '../paths.ts';
+import { inlineGsdRootFile } from '../auto-prompts.ts';
+import { appendKnowledge } from '../files.ts';
+
+// ─── KNOWLEDGE is registered in GSD_ROOT_FILES ─────────────────────────────
+
+test('knowledge: KNOWLEDGE key exists in GSD_ROOT_FILES', () => {
+  assert.ok('KNOWLEDGE' in GSD_ROOT_FILES, 'GSD_ROOT_FILES should have KNOWLEDGE key');
+  assert.strictEqual(GSD_ROOT_FILES.KNOWLEDGE, 'KNOWLEDGE.md');
+});
+
+// ─── resolveGsdRootFile resolves KNOWLEDGE.md ───────────────────────────────
+
+test('knowledge: resolveGsdRootFile returns canonical path when KNOWLEDGE.md exists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'KNOWLEDGE.md'), '# Project Knowledge\n');
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  assert.strictEqual(resolved, join(gsdDir, 'KNOWLEDGE.md'));
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: resolveGsdRootFile resolves when legacy knowledge.md exists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'knowledge.md'), '# Project Knowledge\n');
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  // On case-insensitive filesystems (macOS), canonical path matches;
+  // on case-sensitive (Linux), legacy path matches. Either is valid.
+  const canonical = join(gsdDir, 'KNOWLEDGE.md');
+  const legacy = join(gsdDir, 'knowledge.md');
+  assert.ok(
+    resolved === canonical || resolved === legacy,
+    `resolved path should be canonical or legacy, got: ${resolved}`,
+  );
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: resolveGsdRootFile returns canonical path when file does not exist', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  assert.strictEqual(resolved, join(gsdDir, 'KNOWLEDGE.md'));
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── inlineGsdRootFile works with knowledge.md ─────────────────────────────
+
+test('knowledge: inlineGsdRootFile returns content when KNOWLEDGE.md exists', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'KNOWLEDGE.md'), '# Project Knowledge\n\n## Rules\n\nK001: Use real DB');
+
+  const result = await inlineGsdRootFile(tmp, 'knowledge.md', 'Project Knowledge');
+  assert.ok(result !== null, 'should return content');
+  assert.ok(result!.includes('Project Knowledge'), 'should include label');
+  assert.ok(result!.includes('K001'), 'should include knowledge content');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: inlineGsdRootFile returns null when KNOWLEDGE.md does not exist', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const result = await inlineGsdRootFile(tmp, 'knowledge.md', 'Project Knowledge');
+  assert.strictEqual(result, null, 'should return null when file does not exist');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── appendKnowledge creates file and appends entries ──────────────────────
+
+test('knowledge: appendKnowledge creates KNOWLEDGE.md with rule when file does not exist', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'rule', 'Use real DB for integration tests', 'M001/S01');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('# Project Knowledge'), 'should have header');
+  assert.ok(content.includes('K001'), 'should have K001 id');
+  assert.ok(content.includes('Use real DB for integration tests'), 'should have rule text');
+  assert.ok(content.includes('M001/S01'), 'should have scope');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge appends to existing KNOWLEDGE.md with auto-incrementing ID', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  // Create initial file with one rule
+  await appendKnowledge(tmp, 'rule', 'First rule', 'M001');
+  // Add second rule
+  await appendKnowledge(tmp, 'rule', 'Second rule', 'M001/S02');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('K001'), 'should have K001');
+  assert.ok(content.includes('K002'), 'should have K002');
+  assert.ok(content.includes('First rule'), 'should have first rule');
+  assert.ok(content.includes('Second rule'), 'should have second rule');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge handles pattern type', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'pattern', 'Middleware chain for auth', 'M001');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('P001'), 'should have P001 id');
+  assert.ok(content.includes('Middleware chain for auth'), 'should have pattern text');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge handles lesson type', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'lesson', 'API timeout on large payloads', 'M002');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('L001'), 'should have L001 id');
+  assert.ok(content.includes('API timeout on large payloads'), 'should have lesson text');
+
+  rmSync(tmp, { recursive: true, force: true });
+});