gsd-pi 2.70.1-dev.3591dcf → 2.70.1-dev.6504106

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

@@ -0,0 +1,436 @@
+// GSD Extension — Tests for extracted deriveStateFromDb helper functions
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Tests the composable helpers extracted from deriveStateFromDb:
+//   reconcileDiskToDb, buildCompletenessSet, buildRegistryAndFindActive,
+//   handleNoActiveMilestone, resolveSliceDependencies, reconcileSliceTasks,
+//   detectBlockers, checkReplanTrigger, checkInterruptedWork
+//
+// Helpers are private — exercised through deriveStateFromDb integration.
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { invalidateStateCache, deriveStateFromDb } from '../state.ts';
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  updateTaskStatus,
+} from '../gsd-db.ts';
+
+// ─── Fixture Helpers ───────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-helpers-'));
+  mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true });
+  return base;
+}
+
+function writeFile(base: string, relativePath: string, content: string): void {
+  const full = join(base, '.gsd', relativePath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content);
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+const ROADMAP_CONTENT = `# M001: Test Milestone
+
+**Vision:** Test helpers.
+
+## Slices
+
+- [ ] **S01: First Slice** \`risk:low\` \`depends:[]\`
+  > After this: Slice done.
+
+- [ ] **S02: Second Slice** \`risk:low\` \`depends:[S01]\`
+  > After this: All done.
+`;
+
+const PLAN_CONTENT = `# S01: First Slice
+
+**Goal:** Test executing.
+**Demo:** Tests pass.
+
+## Tasks
+
+- [ ] **T01: First Task** \`est:10m\`
+  First task description.
+
+- [x] **T02: Done Task** \`est:10m\`
+  Already done.
+`;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('derive-state-helpers', () => {
+
+  // ─── handleNoActiveMilestone: all parked ─────────────────────────────
+  test('handleNoActiveMilestone: all milestones parked returns pre-planning with unpark hint', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-CONTEXT.md', '# M001\n\nContext.');
+      writeFile(base, 'milestones/M001/M001-PARKED.md', 'Parked.');
+      writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002\n\nContext.');
+      writeFile(base, 'milestones/M002/M002-PARKED.md', 'Also parked.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'parked' });
+      insertMilestone({ id: 'M002', title: 'Second', status: 'parked' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'pre-planning', 'all-parked: phase is pre-planning');
+      assert.equal(state.activeMilestone, null, 'all-parked: no active milestone');
+      assert.ok(state.nextAction.includes('parked'), 'all-parked: nextAction mentions parked');
+      assert.ok(state.nextAction.includes('unpark'), 'all-parked: nextAction hints unpark');
+      assert.equal(state.registry.length, 2, 'all-parked: both in registry');
+      assert.ok(state.registry.every(e => e.status === 'parked'), 'all-parked: all registry entries parked');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── handleNoActiveMilestone: all complete with active requirements ──
+  test('handleNoActiveMilestone: all complete with unmapped requirements', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
+      writeFile(base, 'REQUIREMENTS.md', `# Requirements\n\n## Active\n\n### R001 — Unmapped\n- Status: active\n- Description: Not mapped.\n`);
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'complete' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'complete', 'complete-reqs: phase is complete');
+      assert.ok(state.nextAction.includes('1 active requirement'), 'complete-reqs: nextAction notes unmapped reqs');
+      assert.equal(state.requirements?.active, 1, 'complete-reqs: requirements.active = 1');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── resolveSliceDependencies: GSD_SLICE_LOCK with missing slice ────
+  test('resolveSliceDependencies: GSD_SLICE_LOCK pointing to non-existent slice returns blocked', async () => {
+    const base = createFixtureBase();
+    const origLock = process.env.GSD_SLICE_LOCK;
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+
+      process.env.GSD_SLICE_LOCK = 'S99';
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'blocked', 'slice-lock-miss: phase is blocked');
+      assert.ok(state.blockers.some(b => b.includes('GSD_SLICE_LOCK=S99')), 'slice-lock-miss: blocker mentions lock');
+    } finally {
+      if (origLock !== undefined) process.env.GSD_SLICE_LOCK = origLock;
+      else delete process.env.GSD_SLICE_LOCK;
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── resolveSliceDependencies: GSD_SLICE_LOCK with valid slice ──────
+  test('resolveSliceDependencies: GSD_SLICE_LOCK targeting valid slice bypasses deps', async () => {
+    const base = createFixtureBase();
+    const origLock = process.env.GSD_SLICE_LOCK;
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      // S02 depends on S01 but we lock to S02 directly
+      writeFile(base, 'milestones/M001/slices/S02/S02-PLAN.md', `# S02\n\n**Goal:** Test.\n**Demo:** Pass.\n\n## Tasks\n\n- [ ] **T01: Task** \`est:5m\`\n  Do thing.\n`);
+      writeFile(base, 'milestones/M001/slices/S02/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S02/tasks/T01-PLAN.md', '# T01 Plan');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'pending', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S02', milestoneId: 'M001', title: 'Task', status: 'pending' });
+
+      process.env.GSD_SLICE_LOCK = 'S02';
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.activeSlice?.id, 'S02', 'slice-lock-valid: activeSlice is S02 (locked)');
+      assert.equal(state.phase, 'executing', 'slice-lock-valid: phase is executing');
+    } finally {
+      if (origLock !== undefined) process.env.GSD_SLICE_LOCK = origLock;
+      else delete process.env.GSD_SLICE_LOCK;
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── reconcileSliceTasks: plan file imports tasks when DB empty ──────
+  test('reconcileSliceTasks: imports tasks from plan file when DB has zero tasks (#3600)', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      // No tasks inserted — reconcileSliceTasks should import from plan file
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // Plan has T01 (pending) and T02 (done) — reconciliation imports both
+      assert.equal(state.phase, 'executing', 'task-reconcile: phase is executing (tasks imported)');
+      assert.equal(state.activeTask?.id, 'T01', 'task-reconcile: activeTask is T01');
+      assert.equal(state.progress?.tasks?.total, 2, 'task-reconcile: total tasks = 2');
+      assert.equal(state.progress?.tasks?.done, 1, 'task-reconcile: done tasks = 1 (T02 was [x])');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── reconcileSliceTasks: stale task reconciled from disk summary ────
+  test('reconcileSliceTasks: stale pending task reconciled to complete when disk SUMMARY exists (#2514)', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
+      // T01 has a summary on disk but DB still says pending
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-SUMMARY.md', '# T01 Summary\n\nDone on disk.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+      insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', title: 'Done Task', status: 'complete' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // T01 should have been reconciled to complete (SUMMARY exists on disk)
+      // Both tasks complete → phase should be summarizing
+      assert.equal(state.phase, 'summarizing', 'stale-task: phase is summarizing (T01 reconciled)');
+      assert.equal(state.activeTask, null, 'stale-task: no active task (all done)');
+      assert.equal(state.progress?.tasks?.done, 2, 'stale-task: tasks.done = 2');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── detectBlockers: blocker_discovered triggers replanning ──────────
+  test('detectBlockers: task with blocker_discovered triggers replanning-slice', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
+      // T02 completed with blocker discovered — written in summary frontmatter
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T02-SUMMARY.md',
+        '---\nblocker_discovered: true\n---\n\n# T02 Summary\n\nFound a blocker.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+      insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', title: 'Done Task', status: 'complete' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'replanning-slice', 'blocker: phase is replanning-slice');
+      assert.ok(state.blockers.some(b => b.includes('T02')), 'blocker: blockers mention T02');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── checkInterruptedWork: continue.md triggers resume hint ─────────
+  test('checkInterruptedWork: continue.md present triggers resume nextAction', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
+      writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
+      writeFile(base, 'milestones/M001/slices/S01/S01-CONTINUE.md', 'Resume from here.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+      insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', title: 'Done Task', status: 'complete' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'executing', 'continue: phase is still executing');
+      assert.ok(state.nextAction.includes('Resume interrupted work'), 'continue: nextAction mentions resume');
+      assert.ok(state.nextAction.includes('continue.md'), 'continue: nextAction mentions continue.md');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── buildCompletenessSet: SUMMARY-on-disk marks complete ───────────
+  test('buildCompletenessSet: milestone with SUMMARY on disk treated as complete', async () => {
+    const base = createFixtureBase();
+    try {
+      // M001 has summary on disk but DB status is still 'active'
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
+      // M002 is the real active milestone
+      writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002\n\nActive.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'active' });
+      insertMilestone({ id: 'M002', title: 'Second', status: 'active' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // M001 should be complete (summary on disk), M002 should be active
+      const m1 = state.registry.find(e => e.id === 'M001');
+      assert.equal(m1?.status, 'complete', 'summary-disk: M001 marked complete via disk SUMMARY');
+      assert.equal(state.activeMilestone?.id, 'M002', 'summary-disk: M002 is active');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── reconcileDiskToDb: disk slices synced into DB (#2533) ──────────
+  test('reconcileDiskToDb: slices in ROADMAP.md but missing from DB are auto-inserted (#2533)', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test', status: 'active' });
+      // No slices inserted — reconcileDiskToDb should insert from roadmap
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // Slices should have been reconciled from roadmap, S01 should be the active slice
+      assert.equal(state.activeMilestone?.id, 'M001', 'slice-reconcile: M001 is active');
+      assert.equal(state.activeSlice?.id, 'S01', 'slice-reconcile: S01 reconciled and active');
+      assert.ok((state.progress?.slices?.total ?? 0) >= 2, 'slice-reconcile: at least 2 slices reconciled');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── Queue order: milestones sorted by custom queue order ───────────
+  test('deriveStateFromDb respects custom queue order from QUEUE-ORDER.json', async () => {
+    const base = createFixtureBase();
+    try {
+      // M003 should come first per queue order, M001 second
+      const queueOrder = JSON.stringify({ order: ['M003', 'M001', 'M002'], updatedAt: new Date().toISOString() });
+      writeFileSync(join(base, '.gsd', 'QUEUE-ORDER.json'), queueOrder);
+      writeFile(base, 'milestones/M001/M001-CONTEXT.md', '# M001\n\nContext.');
+      writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002\n\nContext.');
+      writeFile(base, 'milestones/M003/M003-CONTEXT.md', '# M003\n\nContext.');
+
+      openDatabase(':memory:');
+      // Insert in natural order — queue ordering should override
+      insertMilestone({ id: 'M001', title: 'First', status: 'active' });
+      insertMilestone({ id: 'M002', title: 'Second', status: 'active' });
+      insertMilestone({ id: 'M003', title: 'Third', status: 'active' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // M003 should be the active milestone (first in queue)
+      assert.equal(state.activeMilestone?.id, 'M003', 'queue-order: M003 is active (first in queue)');
+      assert.equal(state.registry[0]?.id, 'M003', 'queue-order: registry[0] is M003');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── handleAllSlicesDone: needs-remediation re-triggers validation ──
+  test('handleAllSlicesDone: needs-remediation verdict triggers validating-milestone', async () => {
+    const base = createFixtureBase();
+    try {
+      const doneRoadmap = `# M001: Remediation Test\n\n**Vision:** Test.\n\n## Slices\n\n- [x] **S01: Done** \`risk:low\` \`depends:[]\`\n  > Done.\n`;
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', doneRoadmap);
+      writeFile(base, 'milestones/M001/M001-VALIDATION.md',
+        '---\nverdict: needs-remediation\nremediation_round: 1\n---\n\n# Validation\nNeeds remediation.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Remediation Test', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Done', status: 'complete', risk: 'low', depends: [] });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      assert.equal(state.phase, 'validating-milestone', 'remediation: phase is validating-milestone');
+      assert.equal(state.activeMilestone?.id, 'M001', 'remediation: activeMilestone is M001');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── Deferred queued shell: shell milestone deferred, real one promoted ──
+  test('buildRegistryAndFindActive: queued shell deferred, later real milestone becomes active (#3470)', async () => {
+    const base = createFixtureBase();
+    try {
+      // M001: queued shell — no content, no slices
+      mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
+      // M002: real milestone with context
+      writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002: Real\n\nActive milestone.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Shell', status: 'queued' });
+      insertMilestone({ id: 'M002', title: 'Real', status: 'active' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // M002 should be active (M001 queued shell deferred)
+      assert.equal(state.activeMilestone?.id, 'M002', 'deferred-shell: M002 is active (shell deferred)');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/discuss-incremental-persistence.test.ts

@@ -27,10 +27,19 @@ describe("discuss incremental persistence (#2152)", () => {
     assert.match(content, /Incremental persistence/, "should have incremental persistence section");
   });
 
+  test("new-project discuss prompt includes CONTEXT-DRAFT save instruction", () => {
+    const content = readFileSync(join(promptsDir, "discuss.md"), "utf-8");
+    assert.match(content, /CONTEXT-DRAFT/, "should mention CONTEXT-DRAFT");
+    assert.match(content, /Incremental persistence/, "should have incremental persistence section");
+    assert.match(content, /gsd_summary_save/, "should use gsd_summary_save tool");
+  });
+
   test("drafts are saved silently without user notification", () => {
     const milestone = readFileSync(join(promptsDir, "guided-discuss-milestone.md"), "utf-8");
     const slice = readFileSync(join(promptsDir, "guided-discuss-slice.md"), "utf-8");
+    const discuss = readFileSync(join(promptsDir, "discuss.md"), "utf-8");
     assert.match(milestone, /Do NOT mention this save to the user/);
     assert.match(slice, /Do NOT mention this to the user/);
+    assert.match(discuss, /Do NOT mention this save to the user/);
   });
 });

package/src/resources/extensions/gsd/tests/secure-env-collect.test.ts

@@ -317,3 +317,48 @@ test("secure_env_collect #2997: null from ctx.ui.custom() is still treated as sk
 		"Key returning null must NOT be in applied list",
 	);
 });
+
+test("secure_env_collect: falls back to secure input prompt when custom UI is unavailable", async (t) => {
+	const { collectSecretsFromManifest } = await loadOrchestrator();
+
+	const tmp = makeTempDir("sec-input-fallback-test");
+	t.after(() => {
+		rmSync(tmp, { recursive: true, force: true });
+	});
+
+	const manifest = makeManifest([
+		{ key: "SECRET_FROM_INPUT_FALLBACK", status: "pending", formatHint: "starts with sk-" },
+	]);
+	await writeManifestFile(tmp, manifest);
+
+	let callIndex = 0;
+	const inputCalls: Array<{ title: string; placeholder?: string; opts?: { secure?: boolean } }> = [];
+	const mockCtx = {
+		cwd: tmp,
+		hasUI: true,
+		ui: {
+			custom: async (_factory: any) => {
+				callIndex++;
+				if (callIndex <= 1) return null; // summary screen dismiss
+				return undefined; // collect screen unavailable on this surface
+			},
+			input: async (title: string, placeholder?: string, opts?: { secure?: boolean }) => {
+				inputCalls.push({ title, placeholder, opts });
+				return "  sk-test-fallback-value  ";
+			},
+		},
+	};
+
+	const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any);
+
+	assert.ok(
+		result.applied.includes("SECRET_FROM_INPUT_FALLBACK"),
+		"Fallback input should collect and apply the key",
+	);
+	assert.ok(
+		!result.skipped.includes("SECRET_FROM_INPUT_FALLBACK"),
+		"Fallback input should not mark the key as skipped",
+	);
+	assert.equal(inputCalls.length, 1, "Fallback input should be requested once");
+	assert.equal(inputCalls[0]?.opts?.secure, true, "Fallback input should request secure entry when supported");
+});

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -0,0 +1,76 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts";
+
+test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "claude-code", baseUrl: "local://claude-code" },
+    modelRegistry: {
+      getProviderAuthMode: () => "externalCli",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is ready", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: () => "apiKey",
+      isProviderRequestReady: (provider: string) => provider === "claude-code",
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is registered", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: (provider: string) => provider === "claude-code" ? "externalCli" : "apiKey",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp stays disabled when neither transport nor provider readiness match", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: () => "apiKey",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, false);
+});
+
+test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep fails", () => {
+  const notifications: Array<{ message: string; level: "info" | "warning" | "error" | "success" }> = [];
+  const result = prepareWorkflowMcpForProject(
+    {
+      model: { provider: "claude-code", baseUrl: "local://claude-code" },
+      modelRegistry: {
+        getProviderAuthMode: () => "externalCli",
+        isProviderRequestReady: () => true,
+      },
+      ui: {
+        notify: (message: string, level?: "info" | "warning" | "error" | "success") => {
+          notifications.push({ message, level: level ?? "info" });
+        },
+      },
+    },
+    "/",
+  );
+
+  assert.equal(result, null);
+  assert.equal(notifications.length, 1);
+  assert.equal(notifications[0].level, "warning");
+  assert.match(notifications[0].message, /Please run \/gsd mcp init \./);
+});