gsd-pi 2.44.0-dev.0b97ffd → 2.44.0-dev.73f2fd5

package/src/resources/extensions/gsd/state.ts

@@ -48,6 +48,7 @@ import {
   getSliceTasks,
   getReplanHistory,
   getSlice,
+  insertMilestone,
   type MilestoneRow,
   type SliceRow,
   type TaskRow,
@@ -257,7 +258,24 @@ function isStatusDone(status: string): boolean {
 export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   const requirements = parseRequirementCounts(await loadFile(resolveGsdRootFile(basePath, "REQUIREMENTS")));
 
-  const allMilestones = getAllMilestones();
+  let allMilestones = getAllMilestones();
+
+  // Incremental disk→DB sync: milestone directories created outside the DB
+  // write path (via /gsd queue, manual mkdir, or complete-milestone writing the
+  // next CONTEXT.md) are never inserted by the initial migration guard in
+  // auto-start.ts because that guard only runs when gsd.db doesn't exist yet.
+  // Reconcile here so deriveStateFromDb never silently misses queued milestones.
+  // insertMilestone uses INSERT OR IGNORE, so this is safe to call every time.
+  const dbIdSet = new Set(allMilestones.map(m => m.id));
+  const diskIds = findMilestoneIds(basePath);
+  let synced = false;
+  for (const diskId of diskIds) {
+    if (!dbIdSet.has(diskId) && !isGhostMilestone(basePath, diskId)) {
+      insertMilestone({ id: diskId, status: 'active' });
+      synced = true;
+    }
+  }
+  if (synced) allMilestones = getAllMilestones();
 
   // Parallel worker isolation: when locked, filter to just the locked milestone
   const milestoneLock = process.env.GSD_MILESTONE_LOCK;

package/src/resources/extensions/gsd/tests/auto-pr-bugs.test.ts

@@ -0,0 +1,88 @@
+/**
+ * auto-pr-bugs.test.ts — Regression tests for #2302.
+ *
+ * Three interacting bugs prevented auto_pr from ever creating a PR:
+ * 1. auto_pr was gated on `pushed` (which requires auto_push)
+ * 2. Milestone branch was not pushed to remote before PR creation
+ * 3. createDraftPR in git-service.ts lacked --head/--base parameters
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Bug 1: auto_pr should not depend on auto_push / pushed flag ────────────
+
+const autoWorktreeSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+const autoWorktreeSrc = readFileSync(autoWorktreeSrcPath, "utf-8");
+
+test("#2302 bug 1: auto_pr condition should not require pushed flag", () => {
+  // Find the auto_pr block in mergeMilestoneToMain
+  const autoPrIdx = autoWorktreeSrc.indexOf("auto_pr");
+  assert.ok(autoPrIdx !== -1, "auto_pr reference exists in auto-worktree.ts");
+
+  // Get context around the auto_pr check
+  const lineStart = autoWorktreeSrc.lastIndexOf("\n", autoPrIdx) + 1;
+  const lineEnd = autoWorktreeSrc.indexOf("\n", autoPrIdx);
+  const autoPrLine = autoWorktreeSrc.slice(lineStart, lineEnd);
+
+  // The condition should NOT include `&& pushed`
+  assert.ok(
+    !autoPrLine.includes("&& pushed"),
+    "auto_pr condition should not be gated on pushed flag (auto_push dependency)",
+  );
+});
+
+// ─── Bug 2: phases.ts should not duplicate PR creation ──────────────────────
+
+const phasesSrcPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const phasesSrc = readFileSync(phasesSrcPath, "utf-8");
+
+test("#2302 bug 2: phases.ts should not call createDraftPR (handled by mergeMilestoneToMain)", () => {
+  // After fix, phases.ts should not import or call createDraftPR because
+  // PR creation is handled inside mergeMilestoneToMain in auto-worktree.ts
+  const createDraftPRCalls = phasesSrc.match(/createDraftPR\(/g) || [];
+
+  assert.equal(
+    createDraftPRCalls.length,
+    0,
+    "phases.ts should not call createDraftPR — it's handled by mergeMilestoneToMain",
+  );
+});
+
+// ─── Bug 3: createDraftPR should accept head and base branch parameters ─────
+
+const gitServiceSrcPath = join(import.meta.dirname, "..", "git-service.ts");
+const gitServiceSrc = readFileSync(gitServiceSrcPath, "utf-8");
+
+test("#2302 bug 3: createDraftPR should accept head and base branch parameters", () => {
+  // Find the createDraftPR function signature
+  const fnIdx = gitServiceSrc.indexOf("function createDraftPR");
+  assert.ok(fnIdx !== -1, "createDraftPR function exists");
+
+  // Get the function signature (up to the closing paren)
+  const sigEnd = gitServiceSrc.indexOf(")", fnIdx);
+  const signature = gitServiceSrc.slice(fnIdx, sigEnd);
+
+  // Should have head and base parameters
+  assert.ok(
+    signature.includes("head") || signature.includes("branch"),
+    "createDraftPR should accept a head/branch parameter",
+  );
+});
+
+test("#2302 bug 3: createDraftPR should pass --head and --base to gh pr create", () => {
+  const fnIdx = gitServiceSrc.indexOf("function createDraftPR");
+  const fnEnd = gitServiceSrc.indexOf("\n}", fnIdx);
+  const fnBody = gitServiceSrc.slice(fnIdx, fnEnd);
+
+  assert.ok(
+    fnBody.includes("--head"),
+    "createDraftPR should pass --head to gh pr create",
+  );
+  assert.ok(
+    fnBody.includes("--base"),
+    "createDraftPR should pass --base to gh pr create",
+  );
+});

package/src/resources/extensions/gsd/tests/completed-units-metrics-sync.test.ts

@@ -0,0 +1,114 @@
+/**
+ * completed-units-metrics-sync.test.ts — Regression tests for #2313.
+ *
+ * 1. completed-units.json should be archived (not wiped) on milestone transition
+ * 2. metrics.json should be in the worktree → project root sync file list
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, existsSync, cpSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ─── Bug 1: completed-units.json should be archived, not wiped ─────────────
+
+const phasesSrcPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const phasesSrc = readFileSync(phasesSrcPath, "utf-8");
+
+test("#2313: completed-units.json should not be blindly wiped to [] on milestone transition", () => {
+  // The milestone transition block should NOT write an empty array to completed-units.json
+  // without first archiving the existing data. Look for the archive/rename pattern.
+  const transitionIdx = phasesSrc.indexOf("Milestone transition");
+  assert.ok(transitionIdx !== -1, "Milestone transition section exists");
+
+  // Find the completed-units handling block
+  const completedUnitsIdx = phasesSrc.indexOf("completed-units", transitionIdx);
+  assert.ok(completedUnitsIdx !== -1, "completed-units handling exists in transition");
+
+  // Get a window around the completed-units handling (1200 chars to
+  // accommodate CRLF line endings on Windows which inflate byte offsets).
+  const windowStart = Math.max(0, completedUnitsIdx - 300);
+  const windowEnd = Math.min(phasesSrc.length, completedUnitsIdx + 900);
+  const window = phasesSrc.slice(windowStart, windowEnd).toLowerCase();
+
+  // Should archive/rename the old file before resetting
+  const hasArchive = window.includes("archive") ||
+    window.includes("rename") ||
+    window.includes("cpsync") ||
+    window.includes("safecopy") ||
+    window.includes("completed-units-");
+
+  assert.ok(
+    hasArchive,
+    "completed-units.json should be archived before reset during milestone transition",
+  );
+});
+
+// ─── Bug 2: metrics.json should be in the sync file lists ──────────────────
+
+test("#2313: syncStateToProjectRoot should sync metrics.json", () => {
+  const syncSrcPath = join(import.meta.dirname, "..", "auto-worktree-sync.ts");
+  const syncSrc = readFileSync(syncSrcPath, "utf-8");
+
+  // syncStateToProjectRoot should copy metrics.json from worktree to project root
+  assert.ok(
+    syncSrc.includes("metrics.json"),
+    "auto-worktree-sync.ts should reference metrics.json for sync",
+  );
+});
+
+test("#2313: syncWorktreeStateBack should include metrics.json in root files list", () => {
+  const autoWorktreeSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+  const autoWorktreeSrc = readFileSync(autoWorktreeSrcPath, "utf-8");
+
+  // Find the rootFiles array in syncWorktreeStateBack
+  const syncBackIdx = autoWorktreeSrc.indexOf("syncWorktreeStateBack");
+  assert.ok(syncBackIdx !== -1, "syncWorktreeStateBack exists");
+
+  const rootFilesIdx = autoWorktreeSrc.indexOf("rootFiles", syncBackIdx);
+  assert.ok(rootFilesIdx !== -1, "rootFiles list exists in syncWorktreeStateBack");
+
+  // Get the rootFiles array content
+  const arrayStart = autoWorktreeSrc.indexOf("[", rootFilesIdx);
+  const arrayEnd = autoWorktreeSrc.indexOf("]", arrayStart);
+  const rootFilesBlock = autoWorktreeSrc.slice(arrayStart, arrayEnd);
+
+  assert.ok(
+    rootFilesBlock.includes("metrics.json"),
+    "metrics.json should be in syncWorktreeStateBack rootFiles list",
+  );
+});
+
+// ─── Functional test: completed-units archive ────────────────────────────────
+
+test("#2313: functional — completed-units archive creates milestone-specific file", () => {
+  const tmpBase = mkdtempSync(join(tmpdir(), "gsd-completed-units-"));
+  const gsdDir = join(tmpBase, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  // Simulate existing completed-units.json with data
+  const existing = [
+    { type: "task", id: "T01" },
+    { type: "slice", id: "S01" },
+  ];
+  const completedKeysPath = join(gsdDir, "completed-units.json");
+  writeFileSync(completedKeysPath, JSON.stringify(existing, null, 2));
+
+  // Simulate the archive behavior: copy to milestone-specific file
+  const milestoneId = "M001";
+  const archivePath = join(gsdDir, `completed-units-${milestoneId}.json`);
+  cpSync(completedKeysPath, archivePath);
+
+  // Reset the main file
+  writeFileSync(completedKeysPath, JSON.stringify([], null, 2));
+
+  // Verify archive exists with original data
+  assert.ok(existsSync(archivePath), "archive file should exist");
+  const archived = JSON.parse(readFileSync(archivePath, "utf-8"));
+  assert.deepEqual(archived, existing, "archived data should match original");
+
+  // Verify main file is reset
+  const current = JSON.parse(readFileSync(completedKeysPath, "utf-8"));
+  assert.deepEqual(current, [], "current completed-units should be empty after transition");
+});

package/src/resources/extensions/gsd/tests/db-writer.test.ts

@@ -483,6 +483,85 @@ describe('db-writer', () => {
     }
   });
 
+  test('saveArtifactToDb — shrinkage guard preserves larger existing file', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      const fullContent = '# Full Research\n\n' + 'x'.repeat(20000) + '\n';
+      const abbreviatedContent = '# Summary\n\nShort version.\n';
+
+      // Pre-create the file with full content (simulating a prior `write` tool call)
+      const relPath = 'milestones/M001/M001-RESEARCH.md';
+      const filePath = path.join(tmpDir, '.gsd', relPath);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, fullContent);
+
+      // Call saveArtifactToDb with abbreviated content — should trigger shrinkage guard
+      await saveArtifactToDb({
+        path: relPath,
+        artifact_type: 'RESEARCH',
+        content: abbreviatedContent,
+        milestone_id: 'M001',
+      }, tmpDir);
+
+      // Disk file should be preserved (not overwritten)
+      assert.deepStrictEqual(
+        fs.readFileSync(filePath, 'utf-8'),
+        fullContent,
+        'disk file preserved — shrinkage guard prevented overwrite',
+      );
+
+      // DB should contain the full disk content, not the abbreviated content
+      const adapter = _getAdapter();
+      const row = adapter!
+        .prepare('SELECT full_content FROM artifacts WHERE path = ?')
+        .get(relPath);
+      assert.deepStrictEqual(
+        row!['full_content'],
+        fullContent,
+        'DB stores the richer disk content instead of abbreviated content',
+      );
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
+  test('saveArtifactToDb — allows overwrite when new content is similar size', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      const oldContent = '# Summary v1\n\nOriginal content here.\n';
+      const newContent = '# Summary v2\n\nUpdated content here with more details.\n';
+
+      const relPath = 'milestones/M001/M001-SUMMARY.md';
+      const filePath = path.join(tmpDir, '.gsd', relPath);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, oldContent);
+
+      await saveArtifactToDb({
+        path: relPath,
+        artifact_type: 'SUMMARY',
+        content: newContent,
+        milestone_id: 'M001',
+      }, tmpDir);
+
+      // Disk file should be updated (new content is >=50% of old size)
+      assert.deepStrictEqual(
+        fs.readFileSync(filePath, 'utf-8'),
+        newContent,
+        'disk file updated when new content is similar size',
+      );
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // Full Round-Trip: DB → Markdown → Parse → Compare
   // ═══════════════════════════════════════════════════════════════════════════

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

@@ -11,6 +11,7 @@ import {
   insertArtifact,
   isDbAvailable,
   insertMilestone,
+  getAllMilestones,
   insertSlice,
   insertTask,
 } from '../gsd-db.ts';
@@ -962,4 +963,63 @@ describe('derive-state-db', async () => {
       cleanup(base);
     }
   });
+
+  // ─── Regression: disk-only milestones synced into DB (#2416) ─────────
+  test('derive-state-db: disk-only milestone auto-synced into DB (#2416)', async () => {
+    const base = createFixtureBase();
+    try {
+      // M001 is complete and exists in DB. M002 was queued on disk only — no DB row.
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
+      writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002: Queued\n\nQueued milestone.');
+
+      openDatabase(':memory:');
+      // Only insert M001 — simulates the state after migration guard ran then /gsd queue added M002
+      insertMilestone({ id: 'M001', title: 'First', status: 'complete' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // Before the fix, M002 was invisible: getAllMilestones() returned only M001
+      // (complete) → phase='complete' → auto-mode stopped.
+      // After the fix, deriveStateFromDb reconciles disk dirs and inserts M002.
+      assert.deepStrictEqual(state.phase, 'pre-planning', 'disk-sync-2416: phase is pre-planning, not complete');
+      assert.deepStrictEqual(state.registry.length, 2, 'disk-sync-2416: both milestones visible in registry');
+      assert.deepStrictEqual(state.registry[0]?.id, 'M001', 'disk-sync-2416: registry[0] is M001');
+      assert.deepStrictEqual(state.registry[0]?.status, 'complete', 'disk-sync-2416: M001 is complete');
+      assert.deepStrictEqual(state.registry[1]?.id, 'M002', 'disk-sync-2416: registry[1] is M002');
+      assert.deepStrictEqual(state.registry[1]?.status, 'active', 'disk-sync-2416: M002 is active');
+      assert.deepStrictEqual(state.activeMilestone?.id, 'M002', 'disk-sync-2416: activeMilestone is M002');
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── Queued milestone row not clobbered by later plan (#2416 root cause) ──
+  test('derive-state-db: queued milestone row survives gsd_plan_milestone INSERT OR IGNORE', async () => {
+    try {
+      openDatabase(':memory:');
+
+      // Simulates gsd_milestone_generate_id inserting a minimal queued row
+      insertMilestone({ id: 'M001', status: 'queued' });
+
+      const before = getAllMilestones();
+      assert.equal(before.length, 1, 'queued-row: one row after generate_id');
+      assert.equal(before[0]!.status, 'queued', 'queued-row: status is queued');
+
+      // Simulates gsd_plan_milestone calling insertMilestone (INSERT OR IGNORE)
+      insertMilestone({ id: 'M001', title: 'Planned Title', status: 'active' });
+
+      const after = getAllMilestones();
+      assert.equal(after.length, 1, 'queued-row: still one row after plan');
+      // INSERT OR IGNORE keeps the original row — status stays 'queued'
+      assert.equal(after[0]!.status, 'queued', 'queued-row: INSERT OR IGNORE preserves original status');
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/est-annotation-timeout.test.ts

@@ -0,0 +1,120 @@
+/**
+ * est-annotation-timeout.test.ts — Regression tests for #2243.
+ *
+ * Tasks with `est: 30m` or `est: 2h` annotations should get extended
+ * supervision timeouts. The parseEstimateMinutes helper should parse
+ * estimate strings, and startUnitSupervision should use them.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const timersSrcPath = join(import.meta.dirname, "..", "auto-timers.ts");
+const timersSrc = readFileSync(timersSrcPath, "utf-8");
+
+// ─── Source analysis: parseEstimateMinutes exists and is exported ────────────
+
+test("#2243: auto-timers.ts should export parseEstimateMinutes", () => {
+  assert.ok(
+    timersSrc.includes("export function parseEstimateMinutes"),
+    "parseEstimateMinutes should be exported from auto-timers.ts",
+  );
+});
+
+// ─── Inline unit test of parseEstimateMinutes logic ─────────────────────────
+// Since importing the module pulls in heavy deps, test the parsing logic inline.
+
+function parseEstimateMinutes(estimate: string): number | null {
+  if (!estimate || typeof estimate !== "string") return null;
+  const trimmed = estimate.trim();
+  if (!trimmed) return null;
+
+  let totalMinutes = 0;
+  let matched = false;
+
+  const hoursMatch = trimmed.match(/(\d+)\s*h/i);
+  if (hoursMatch) {
+    totalMinutes += Number(hoursMatch[1]) * 60;
+    matched = true;
+  }
+
+  const minutesMatch = trimmed.match(/(\d+)\s*m/i);
+  if (minutesMatch) {
+    totalMinutes += Number(minutesMatch[1]);
+    matched = true;
+  }
+
+  return matched ? totalMinutes : null;
+}
+
+test("#2243: parseEstimateMinutes parses '30m' correctly", () => {
+  assert.equal(parseEstimateMinutes("30m"), 30);
+});
+
+test("#2243: parseEstimateMinutes parses '2h' correctly", () => {
+  assert.equal(parseEstimateMinutes("2h"), 120);
+});
+
+test("#2243: parseEstimateMinutes parses '1h30m' correctly", () => {
+  assert.equal(parseEstimateMinutes("1h30m"), 90);
+});
+
+test("#2243: parseEstimateMinutes parses '15m' correctly", () => {
+  assert.equal(parseEstimateMinutes("15m"), 15);
+});
+
+test("#2243: parseEstimateMinutes returns null for empty string", () => {
+  assert.equal(parseEstimateMinutes(""), null);
+});
+
+test("#2243: parseEstimateMinutes returns null for invalid string", () => {
+  assert.equal(parseEstimateMinutes("not a time"), null);
+});
+
+// ─── Source analysis: startUnitSupervision uses task estimates ───────────────
+
+test("#2243: startUnitSupervision should reference task estimates for timeout scaling", () => {
+  const usesEstimate =
+    timersSrc.includes("parseEstimateMinutes") &&
+    timersSrc.includes("estimateMinutes") &&
+    timersSrc.includes("taskEstimate");
+
+  assert.ok(
+    usesEstimate,
+    "startUnitSupervision should use task estimate annotations for timeout scaling",
+  );
+});
+
+test("#2243: SupervisionContext should accept an optional taskEstimate field", () => {
+  const ctxIdx = timersSrc.indexOf("SupervisionContext");
+  assert.ok(ctxIdx !== -1, "SupervisionContext interface exists");
+
+  const ctxEnd = timersSrc.indexOf("}", ctxIdx);
+  const ctxBlock = timersSrc.slice(ctxIdx, ctxEnd);
+
+  assert.ok(
+    ctxBlock.includes("taskEstimate"),
+    "SupervisionContext should include a taskEstimate field",
+  );
+});
+
+test("#2243: timeouts should be scaled by estimate (timeoutScale in source)", () => {
+  assert.ok(
+    timersSrc.includes("timeoutScale"),
+    "auto-timers.ts should use a timeoutScale factor derived from est: annotations",
+  );
+});
+
+test("#2243: idle timeout should NOT be scaled (idle is idle regardless of estimate)", () => {
+  // Find the idleTimeoutMs line
+  const idleIdx = timersSrc.indexOf("const idleTimeoutMs");
+  assert.ok(idleIdx !== -1, "idleTimeoutMs variable exists");
+  
+  const idleLine = timersSrc.slice(idleIdx, timersSrc.indexOf("\n", idleIdx));
+  assert.ok(
+    !idleLine.includes("timeoutScale"),
+    "idleTimeoutMs should NOT be scaled — idle is idle",
+  );
+});

package/src/resources/extensions/gsd/tests/infra-error.test.ts

@@ -7,10 +7,13 @@ import { isInfrastructureError, INFRA_ERROR_CODES } from "../auto/infra-errors.j
 // ── INFRA_ERROR_CODES constant ───────────────────────────────────────────────
 
 test("INFRA_ERROR_CODES contains the expected codes", () => {
-  for (const code of ["ENOSPC", "ENOMEM", "EROFS", "EDQUOT", "EMFILE", "ENFILE"]) {
+  for (const code of [
+    "ENOSPC", "ENOMEM", "EROFS", "EDQUOT", "EMFILE", "ENFILE",
+    "ECONNREFUSED", "ENOTFOUND", "ENETUNREACH",
+  ]) {
     assert.ok(INFRA_ERROR_CODES.has(code), `missing ${code}`);
   }
-  assert.equal(INFRA_ERROR_CODES.size, 6, "unexpected extra codes");
+  assert.equal(INFRA_ERROR_CODES.size, 9, "unexpected extra codes");
 });
 
 // ── isInfrastructureError: code property detection ───────────────────────────
@@ -45,6 +48,21 @@ test("detects ENFILE via code property", () => {
   assert.equal(isInfrastructureError(err), "ENFILE");
 });
 
+test("detects ECONNREFUSED via code property", () => {
+  const err = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:3000"), { code: "ECONNREFUSED" });
+  assert.equal(isInfrastructureError(err), "ECONNREFUSED");
+});
+
+test("detects ENOTFOUND via code property", () => {
+  const err = Object.assign(new Error("getaddrinfo ENOTFOUND api.example.com"), { code: "ENOTFOUND" });
+  assert.equal(isInfrastructureError(err), "ENOTFOUND");
+});
+
+test("detects ENETUNREACH via code property", () => {
+  const err = Object.assign(new Error("connect ENETUNREACH 2607:f8b0:4004::"), { code: "ENETUNREACH" });
+  assert.equal(isInfrastructureError(err), "ENETUNREACH");
+});
+
 // ── isInfrastructureError: message fallback ──────────────────────────────────
 
 test("falls back to message scanning when no code property", () => {

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

@@ -6,6 +6,7 @@
  * - resolveGsdRootFile resolves KNOWLEDGE paths correctly
  * - inlineGsdRootFile works with the KNOWLEDGE key
  * - before_agent_start hook includes/omits knowledge block appropriately
+ * - loadKnowledgeBlock merges global and project knowledge correctly
  */
 
 import test from 'node:test';
@@ -16,6 +17,7 @@ import { tmpdir } from 'node:os';
 import { GSD_ROOT_FILES, resolveGsdRootFile } from '../paths.ts';
 import { inlineGsdRootFile } from '../auto-prompts.ts';
 import { appendKnowledge } from '../files.ts';
+import { loadKnowledgeBlock } from '../bootstrap/system-context.ts';
 
 // ─── KNOWLEDGE is registered in GSD_ROOT_FILES ─────────────────────────────
 
@@ -159,3 +161,90 @@ test('knowledge: appendKnowledge handles lesson type', async () => {
 
   rmSync(tmp, { recursive: true, force: true });
 });
+
+// ─── loadKnowledgeBlock — global + project merge ────────────────────────────
+
+test('loadKnowledgeBlock: returns empty block when neither file exists', () => {
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-kb-')));
+  const gsdHome = join(tmp, 'home');
+  const cwd = join(tmp, 'project');
+  mkdirSync(join(cwd, '.gsd'), { recursive: true });
+  mkdirSync(join(gsdHome, 'agent'), { recursive: true });
+
+  const result = loadKnowledgeBlock(gsdHome, cwd);
+  assert.strictEqual(result.block, '');
+  assert.strictEqual(result.globalSizeKb, 0);
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('loadKnowledgeBlock: uses project knowledge alone when no global file', () => {
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-kb-')));
+  const gsdHome = join(tmp, 'home');
+  const cwd = join(tmp, 'project');
+  mkdirSync(join(cwd, '.gsd'), { recursive: true });
+  mkdirSync(join(gsdHome, 'agent'), { recursive: true });
+  writeFileSync(join(cwd, '.gsd', 'KNOWLEDGE.md'), 'K001: Use real DB');
+
+  const result = loadKnowledgeBlock(gsdHome, cwd);
+  assert.ok(result.block.includes('[KNOWLEDGE — Rules, patterns, and lessons learned]'));
+  assert.ok(result.block.includes('## Project Knowledge'));
+  assert.ok(result.block.includes('K001: Use real DB'));
+  assert.ok(!result.block.includes('## Global Knowledge'));
+  assert.strictEqual(result.globalSizeKb, 0);
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('loadKnowledgeBlock: uses global knowledge alone when no project file', () => {
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-kb-')));
+  const gsdHome = join(tmp, 'home');
+  const cwd = join(tmp, 'project');
+  mkdirSync(join(cwd, '.gsd'), { recursive: true });
+  mkdirSync(join(gsdHome, 'agent'), { recursive: true });
+  writeFileSync(join(gsdHome, 'agent', 'KNOWLEDGE.md'), 'G001: Respond in English');
+
+  const result = loadKnowledgeBlock(gsdHome, cwd);
+  assert.ok(result.block.includes('[KNOWLEDGE — Rules, patterns, and lessons learned]'));
+  assert.ok(result.block.includes('## Global Knowledge'));
+  assert.ok(result.block.includes('G001: Respond in English'));
+  assert.ok(!result.block.includes('## Project Knowledge'));
+  assert.ok(result.globalSizeKb > 0);
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('loadKnowledgeBlock: merges global before project when both exist', () => {
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-kb-')));
+  const gsdHome = join(tmp, 'home');
+  const cwd = join(tmp, 'project');
+  mkdirSync(join(cwd, '.gsd'), { recursive: true });
+  mkdirSync(join(gsdHome, 'agent'), { recursive: true });
+  writeFileSync(join(gsdHome, 'agent', 'KNOWLEDGE.md'), 'G001: Global rule');
+  writeFileSync(join(cwd, '.gsd', 'KNOWLEDGE.md'), 'K001: Project rule');
+
+  const result = loadKnowledgeBlock(gsdHome, cwd);
+  assert.ok(result.block.includes('## Global Knowledge'));
+  assert.ok(result.block.includes('## Project Knowledge'));
+  assert.ok(result.block.includes('G001: Global rule'));
+  assert.ok(result.block.includes('K001: Project rule'));
+  // Global section appears before project section
+  assert.ok(result.block.indexOf('## Global Knowledge') < result.block.indexOf('## Project Knowledge'));
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('loadKnowledgeBlock: reports globalSizeKb above 4KB threshold', () => {
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-kb-')));
+  const gsdHome = join(tmp, 'home');
+  const cwd = join(tmp, 'project');
+  mkdirSync(join(cwd, '.gsd'), { recursive: true });
+  mkdirSync(join(gsdHome, 'agent'), { recursive: true });
+  // Write > 4KB of content
+  writeFileSync(join(gsdHome, 'agent', 'KNOWLEDGE.md'), 'x'.repeat(5000));
+
+  const result = loadKnowledgeBlock(gsdHome, cwd);
+  assert.ok(result.globalSizeKb > 4, `expected > 4KB, got ${result.globalSizeKb}`);
+
+  rmSync(tmp, { recursive: true, force: true });
+});