gsd-pi 2.63.0 → 2.64.0-dev.1a85e85

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

@@ -24,6 +24,7 @@ import {
   saveDecisionToDb,
   updateRequirementInDb,
   saveArtifactToDb,
+  extractDeferredSliceRef,
 } from '../db-writer.ts';
 import type { Decision, Requirement } from '../types.ts';
 
@@ -475,6 +476,71 @@ describe('db-writer', () => {
     }
   });
 
+  test('updateRequirementInDb — seeds from REQUIREMENTS.md when DB empty (#3346)', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      // Write a REQUIREMENTS.md with real content (simulating discussion phase output)
+      const reqContent = [
+        '# Requirements',
+        '',
+        '## Active',
+        '',
+        '### R005 — User authentication',
+        '- Class: functional',
+        '- Why: Users need secure access',
+        '- Source: user-research',
+        '- Primary owner: M001/S02',
+        '',
+        '### R007 — API rate limiting',
+        '- Class: non-functional',
+        '- Why: Prevent abuse',
+        '- Source: architecture',
+        '- Primary owner: M001/S03',
+        '',
+        '## Validated',
+        '',
+        '### R001 — Database schema',
+        '- Class: functional',
+        '- Why: Foundation for storage',
+        '- Source: design',
+        '- Validation: S01 verified',
+      ].join('\n');
+      fs.writeFileSync(path.join(tmpDir, '.gsd', 'REQUIREMENTS.md'), reqContent);
+
+      // DB is empty — no requirements seeded. Update R005 to "validated".
+      // Before #3346 fix: this would create a skeleton with empty fields.
+      // After fix: this seeds all 3 requirements from REQUIREMENTS.md first.
+      await updateRequirementInDb('R005', {
+        status: 'validated',
+        validation: 'S02 — auth flow verified',
+      }, tmpDir);
+
+      // R005 should have the update AND the original content from markdown
+      const r005 = getRequirementById('R005');
+      assert.ok(r005, 'R005 should exist');
+      assert.equal(r005!.status, 'validated', 'status should be updated');
+      assert.equal(r005!.validation, 'S02 — auth flow verified', 'validation should be updated');
+      assert.equal(r005!.class, 'functional', 'class should be preserved from REQUIREMENTS.md');
+      assert.ok(r005!.description?.includes('authentication') || r005!.full_content?.includes('authentication'),
+        'original content should be preserved');
+
+      // R007 and R001 should also be seeded (not just the one being updated)
+      const r007 = getRequirementById('R007');
+      assert.ok(r007, 'R007 should be seeded from REQUIREMENTS.md');
+      assert.equal(r007!.status, 'active', 'R007 status should be active');
+
+      const r001 = getRequirementById('R001');
+      assert.ok(r001, 'R001 should be seeded from REQUIREMENTS.md');
+      assert.equal(r001!.status, 'validated', 'R001 status should be validated (from section heading)');
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // saveArtifactToDb Tests
   // ═══════════════════════════════════════════════════════════════════════════
@@ -694,4 +760,72 @@ describe('db-writer', () => {
 
   // ═══════════════════════════════════════════════════════════════════════════
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  extractDeferredSliceRef
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  describe('extractDeferredSliceRef', () => {
+    const fields = (scope: string, choice: string, decision: string) => ({
+      scope,
+      choice,
+      decision,
+    });
+
+    test('detects deferral in scope with M###/S## pattern in choice', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferral of low-priority work', 'Move M001/S03 to backlog', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M001', sliceId: 'S03' });
+    });
+
+    test('detects deferral in choice field', () => {
+      const result = extractDeferredSliceRef(
+        fields('slice prioritization', 'defer M002/S01 until next sprint', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M002', sliceId: 'S01' });
+    });
+
+    test('detects deferral in decision field', () => {
+      const result = extractDeferredSliceRef(
+        fields('resource constraints', '', 'deferred M010/S12 pending review'),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M010', sliceId: 'S12' });
+    });
+
+    test('returns null when no M###/S## pattern is present', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferral of work', 'will revisit later', 'deferred indefinitely'),
+      );
+      assert.strictEqual(result, null);
+    });
+
+    test('recognises "deferring" variant', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferring this slice', 'M005/S02 can wait', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M005', sliceId: 'S02' });
+    });
+
+    test('recognises "defers" variant', () => {
+      const result = extractDeferredSliceRef(
+        fields('team defers slice', 'M100/S10 not urgent', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M100', sliceId: 'S10' });
+    });
+
+    test('returns first M###/S## match when multiple patterns exist', () => {
+      const result = extractDeferredSliceRef(
+        fields('', 'defer M003/S01 and M003/S02', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M003', sliceId: 'S01' });
+    });
+
+    test('returns null when no deferral keyword is present', () => {
+      const result = extractDeferredSliceRef(
+        fields('approved work', 'M001/S01 is ready', 'proceed with M001/S01'),
+      );
+      assert.strictEqual(result, null);
+    });
+  });
+
 });

package/src/resources/extensions/gsd/tests/deferred-slice-dispatch.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Regression test for #2661: Auto-mode dispatches deferred slices.
+ *
+ * When a decision defers a slice, the dispatcher must skip it and advance
+ * to the next eligible slice. This tests both:
+ *   1. deriveStateFromDb skips slices with status "deferred"
+ *   2. saveDecisionToDb updates the slice status when the decision is a deferral
+ */
+
+import { describe, test } 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 { deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  isDbAvailable,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  insertArtifact,
+  updateSliceStatus,
+} from "../gsd-db.ts";
+import { isDeferredStatus } from "../status-guards.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-deferred-dispatch-"));
+  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 });
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+describe("deferred-slice-dispatch (#2661)", () => {
+  test("isDeferredStatus returns true for 'deferred'", () => {
+    assert.ok(isDeferredStatus("deferred"), "should recognize 'deferred'");
+    assert.ok(!isDeferredStatus("active"), "should not match 'active'");
+    assert.ok(!isDeferredStatus("complete"), "should not match 'complete'");
+    assert.ok(!isDeferredStatus("pending"), "should not match 'pending'");
+  });
+
+  test("deriveStateFromDb skips deferred slice and picks next eligible", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+      assert.ok(isDbAvailable());
+
+      // M001 with three slices: S01 complete, S02 deferred, S03 pending
+      insertMilestone({ id: "M001", title: "Test Milestone", status: "active" });
+
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred Slice", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Next Slice", status: "pending", risk: "low", depends: [] });
+
+      // S01 needs a SUMMARY file to count as complete for milestone-level checks
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001: Test Milestone
+
+**Vision:** Test deferred slices.
+
+## Slices
+
+- [x] **S01: Done Slice** \`risk:low\` \`depends:[]\`
+  > Done.
+
+- [ ] **S02: Deferred Slice** \`risk:low\` \`depends:[]\`
+  > Deferred.
+
+- [ ] **S03: Next Slice** \`risk:low\` \`depends:[]\`
+  > Next.
+`);
+      writeFile(base, "milestones/M001/slices/S01/S01-SUMMARY.md", "# S01 Summary\nDone.");
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // The active slice must be S03, NOT S02 (which is deferred)
+      assert.equal(state.activeMilestone?.id, "M001", "active milestone is M001");
+      assert.equal(state.activeSlice?.id, "S03", "active slice should skip deferred S02 and land on S03");
+      assert.notEqual(state.activeSlice?.id, "S02", "active slice must NOT be the deferred S02");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("deriveStateFromDb does not count deferred slices as done for progress", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Complete", status: "complete", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Pending", status: "pending", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [x] **S01: Complete** \`risk:low\` \`depends:[]\`
+- [ ] **S02: Deferred** \`risk:low\` \`depends:[]\`
+- [ ] **S03: Pending** \`risk:low\` \`depends:[]\`
+`);
+      writeFile(base, "milestones/M001/slices/S01/S01-SUMMARY.md", "# Done");
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // Deferred slices should not count as "done" in progress
+      // Only S01 (complete) counts as done
+      assert.equal(state.progress?.slices?.done, 1, "only 1 slice (S01) should be done");
+      // Total should still be 3 (deferred slices are still part of the milestone)
+      assert.equal(state.progress?.slices?.total, 3, "all 3 slices counted in total");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("all slices deferred results in blocked state", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Deferred A", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred B", status: "deferred", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [ ] **S01: Deferred A** \`risk:low\` \`depends:[]\`
+- [ ] **S02: Deferred B** \`risk:low\` \`depends:[]\`
+`);
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // No eligible slice — should be blocked
+      assert.equal(state.activeSlice, null, "no active slice when all deferred");
+      assert.equal(state.phase, "blocked", "phase should be blocked when all slices deferred");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("saveDecisionToDb marks slice as deferred when decision is a deferral", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Target Slice", status: "active", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [ ] **S03: Target Slice** \`risk:low\` \`depends:[]\`
+`);
+
+      const { saveDecisionToDb } = await import("../db-writer.ts");
+      const { getSlice } = await import("../gsd-db.ts");
+
+      // Save a deferral decision that references M001/S03
+      await saveDecisionToDb(
+        {
+          scope: "deferral",
+          decision: "Defer S03 to focus on higher priority work",
+          choice: "defer M001/S03",
+          rationale: "Not ready yet",
+        },
+        base,
+      );
+
+      // The slice status should now be "deferred"
+      const slice = getSlice("M001", "S03");
+      assert.equal(slice?.status, "deferred", "slice status should be updated to 'deferred' after deferral decision");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/discuss-tool-scope-leak.test.ts

@@ -0,0 +1,76 @@
+// GSD-2 — Regression test for #3616: discuss tool scoping must not leak into subsequent sessions
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+/**
+ * Bug #3616: After a discuss session narrows the active tool set via
+ * setActiveTools(), the narrowed list persisted into the next auto-mode
+ * session because newSession() did not restore extension tools when cwd
+ * was unchanged. This caused gsd_plan_slice and other DB tools to be
+ * missing from plan-slice subagent sessions.
+ *
+ * This test verifies the structural properties that prevent the leak:
+ *   1. guided-flow.ts narrows tools ONLY for discuss-* unit types
+ *   2. The narrowed set explicitly excludes gsd_plan_slice (a HEAVY_TOOL)
+ *   3. agent-session.ts:newSession() has an else-branch that restores
+ *      all extension tools even when cwd hasn't changed
+ */
+
+import { describe, 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";
+
+import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const guidedFlowSource = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
+
+describe("#3616 — discuss tool scoping must not leak across sessions", () => {
+	test("gsd_plan_slice is NOT in DISCUSS_TOOLS_ALLOWLIST", () => {
+		assert.ok(
+			!DISCUSS_TOOLS_ALLOWLIST.includes("gsd_plan_slice"),
+			"gsd_plan_slice should be excluded from discuss scope (it's a heavy planning tool)",
+		);
+	});
+
+	test("tool scoping only activates for discuss-* unit types", () => {
+		// The guard must be: if (unitType?.startsWith("discuss-"))
+		assert.ok(
+			guidedFlowSource.includes('unitType?.startsWith("discuss-")'),
+			"tool scoping should only trigger for discuss-* unit types",
+		);
+	});
+
+	test("discuss tool scoping uses setActiveTools (not setTools) for reversibility", () => {
+		// setActiveTools changes the active subset but doesn't remove tools from
+		// the registry. newSession()'s _refreshToolRegistry can restore them.
+		assert.ok(
+			guidedFlowSource.includes("pi.setActiveTools(scopedTools)"),
+			"should use pi.setActiveTools to narrow tools (preserving registry)",
+		);
+	});
+
+	test("newSession() in agent-session.ts has defense against tool narrowing persistence", () => {
+		const agentSessionSource = readFileSync(
+			join(process.cwd(), "packages/pi-coding-agent/src/core/agent-session.ts"),
+			"utf-8",
+		);
+		const newSessionStart = agentSessionSource.indexOf("async newSession(options?:");
+		assert.ok(newSessionStart >= 0, "should find newSession");
+		const body = agentSessionSource.slice(newSessionStart, newSessionStart + 3000);
+
+		// Both branches (cwd-changed and cwd-unchanged) must include extension tools
+		assert.ok(
+			body.includes("includeAllExtensionTools: true"),
+			"newSession() must include all extension tools in both branches",
+		);
+
+		// Count occurrences — should be at least 2 (one per branch)
+		const matches = body.match(/includeAllExtensionTools:\s*true/g);
+		assert.ok(
+			matches && matches.length >= 2,
+			`expected >=2 includeAllExtensionTools:true in newSession(), got ${matches?.length ?? 0}`,
+		);
+	});
+});

package/src/resources/extensions/gsd/tests/discuss-tool-scoping.test.ts

@@ -0,0 +1,130 @@
+/**
+ * discuss-tool-scoping.test.ts — Tests for #2949.
+ *
+ * xAI/Grok returns "Grammar is too complex" (400) when the combined tool
+ * schemas exceed the provider's grammar limit. The GSD discuss flow only
+ * needs a small subset of tools (summary_save, decision_save, etc.), but
+ * was sending ALL ~30+ tools to the provider.
+ *
+ * These tests verify:
+ *   1. DISCUSS_TOOLS_ALLOWLIST is exported and contains only the tools
+ *      needed during discuss flows (no heavy planning/execution/completion tools).
+ *   2. Heavy execution tools are NOT in the allowlist.
+ *   3. The allowlist includes the tools actually referenced by discuss prompts.
+ *   4. dispatchWorkflow scopes tools when unitType is a discuss variant.
+ */
+
+import { describe, 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";
+
+import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const promptsDir = join(__dirname, "..", "prompts");
+const guidedFlowPath = join(__dirname, "..", "guided-flow.ts");
+
+// ─── Heavy tools that should NOT be in discuss scope ─────────────────────────
+
+/** Tools that are only needed during planning, execution, or completion phases */
+const HEAVY_TOOLS = [
+  "gsd_plan_slice",
+  "gsd_slice_plan",
+  "gsd_plan_task",
+  "gsd_task_plan",
+  "gsd_task_complete",
+  "gsd_complete_task",
+  "gsd_slice_complete",
+  "gsd_complete_slice",
+  "gsd_complete_milestone",
+  "gsd_milestone_complete",
+  "gsd_validate_milestone",
+  "gsd_milestone_validate",
+  "gsd_replan_slice",
+  "gsd_slice_replan",
+  "gsd_reassess_roadmap",
+  "gsd_roadmap_reassess",
+  "gsd_save_gate_result",
+];
+
+// ─── Tools that discuss prompts reference ────────────────────────────────────
+
+/** Tools explicitly called by discuss prompt templates */
+const DISCUSS_REQUIRED_TOOLS = [
+  "gsd_summary_save",          // guided-discuss-slice.md, guided-discuss-milestone.md, discuss.md
+  "gsd_decision_save",         // discuss.md output phase
+  "gsd_plan_milestone",        // discuss.md output phase (single + multi milestone)
+  "gsd_milestone_generate_id", // discuss.md multi-milestone Phase 1
+  "gsd_requirement_update",    // used during discuss for requirement updates
+];
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("discuss tool scoping (#2949)", () => {
+  test("DISCUSS_TOOLS_ALLOWLIST is exported and non-empty", () => {
+    assert.ok(Array.isArray(DISCUSS_TOOLS_ALLOWLIST), "should be an array");
+    assert.ok(DISCUSS_TOOLS_ALLOWLIST.length > 0, "should not be empty");
+  });
+
+  test("DISCUSS_TOOLS_ALLOWLIST excludes heavy execution/completion tools", () => {
+    for (const heavy of HEAVY_TOOLS) {
+      assert.ok(
+        !DISCUSS_TOOLS_ALLOWLIST.includes(heavy),
+        `allowlist should NOT include heavy tool "${heavy}"`,
+      );
+    }
+  });
+
+  test("DISCUSS_TOOLS_ALLOWLIST includes tools referenced by discuss prompts", () => {
+    for (const required of DISCUSS_REQUIRED_TOOLS) {
+      assert.ok(
+        DISCUSS_TOOLS_ALLOWLIST.includes(required),
+        `allowlist should include "${required}" (used by discuss prompts)`,
+      );
+    }
+  });
+
+  test("DISCUSS_TOOLS_ALLOWLIST is significantly smaller than full tool set", () => {
+    // Full set is 27 DB tools + dynamic + journal = 33+
+    // Discuss set should be roughly 10 GSD tools (5 canonical + 5 aliases)
+    assert.ok(
+      DISCUSS_TOOLS_ALLOWLIST.length <= 12,
+      `allowlist should have at most 12 GSD tools, got ${DISCUSS_TOOLS_ALLOWLIST.length}`,
+    );
+  });
+
+  test("guided-discuss-slice.md references gsd_summary_save", () => {
+    const prompt = readFileSync(join(promptsDir, "guided-discuss-slice.md"), "utf-8");
+    assert.ok(
+      prompt.includes("gsd_summary_save"),
+      "guided-discuss-slice.md should reference gsd_summary_save",
+    );
+  });
+
+  test("discuss.md references gsd_plan_milestone and gsd_decision_save", () => {
+    const prompt = readFileSync(join(promptsDir, "discuss.md"), "utf-8");
+    assert.ok(
+      prompt.includes("gsd_plan_milestone"),
+      "discuss.md should reference gsd_plan_milestone",
+    );
+    assert.ok(
+      prompt.includes("gsd_decision_save"),
+      "discuss.md should reference gsd_decision_save",
+    );
+  });
+
+  test("dispatchWorkflow source code scopes tools for discuss unit types", () => {
+    const source = readFileSync(guidedFlowPath, "utf-8");
+    // Verify that dispatchWorkflow references the allowlist for tool scoping
+    assert.ok(
+      source.includes("DISCUSS_TOOLS_ALLOWLIST"),
+      "guided-flow.ts should reference DISCUSS_TOOLS_ALLOWLIST for tool scoping",
+    );
+    assert.ok(
+      source.includes("setActiveTools"),
+      "guided-flow.ts should call setActiveTools to scope tools during discuss",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/doctor-fix-flag.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Regression test for #1919: --fix flag not stripped before positional parse.
+ *
+ * parseDoctorArgs("--fix") must:
+ *   1. Set fixFlag = true
+ *   2. Not leak "--fix" into requestedScope
+ *   3. Keep mode as "doctor" (the flag is not a positional subcommand)
+ */
+
+import { parseDoctorArgs } from "../commands-handlers.js";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+async function main(): Promise<void> {
+  // ── 1. Bare --fix flag ──────────────────────────────────────────────────────
+  console.log("\n=== bare --fix flag (#1919) ===");
+  {
+    const r = parseDoctorArgs("--fix");
+    assertTrue(r.fixFlag, "--fix sets fixFlag to true");
+    assertEq(r.mode, "doctor", "--fix does not change mode from doctor");
+    assertEq(r.requestedScope, undefined, "--fix is stripped and does not become requestedScope");
+  }
+
+  // ── 2. --fix with a scope ──────────────────────────────────────────────────
+  console.log("\n=== --fix with scope ===");
+  {
+    const r = parseDoctorArgs("--fix M001/S01");
+    assertTrue(r.fixFlag, "--fix M001/S01 sets fixFlag to true");
+    assertEq(r.mode, "doctor", "--fix M001/S01 keeps mode as doctor");
+    assertEq(r.requestedScope, "M001/S01", "scope is M001/S01 after stripping --fix");
+  }
+
+  // ── 3. Positional fix still works ──────────────────────────────────────────
+  console.log("\n=== positional fix subcommand ===");
+  {
+    const r = parseDoctorArgs("fix");
+    assertEq(r.fixFlag, false, "positional fix does not set fixFlag");
+    assertEq(r.mode, "fix", "positional fix sets mode to fix");
+    assertEq(r.requestedScope, undefined, "no scope with bare positional fix");
+  }
+
+  // ── 4. Positional fix with scope ───────────────────────────────────────────
+  console.log("\n=== positional fix with scope ===");
+  {
+    const r = parseDoctorArgs("fix M001");
+    assertEq(r.mode, "fix", "fix M001 sets mode to fix");
+    assertEq(r.requestedScope, "M001", "fix M001 parses scope as M001");
+  }
+
+  // ── 5. --fix combined with other flags ─────────────────────────────────────
+  console.log("\n=== --fix combined with --dry-run ===");
+  {
+    const r = parseDoctorArgs("--fix --dry-run");
+    assertTrue(r.fixFlag, "--fix --dry-run sets fixFlag");
+    assertTrue(r.dryRun, "--fix --dry-run sets dryRun");
+    assertEq(r.requestedScope, undefined, "no scope leaked from combined flags");
+  }
+
+  // ── 6. --fix combined with --json ──────────────────────────────────────────
+  console.log("\n=== --fix with --json ===");
+  {
+    const r = parseDoctorArgs("--fix --json");
+    assertTrue(r.fixFlag, "--fix --json sets fixFlag");
+    assertTrue(r.jsonMode, "--fix --json sets jsonMode");
+    assertEq(r.requestedScope, undefined, "no scope leaked from --fix --json");
+  }
+
+  // ── 7. Empty args (baseline) ───────────────────────────────────────────────
+  console.log("\n=== empty args baseline ===");
+  {
+    const r = parseDoctorArgs("");
+    assertEq(r.fixFlag, false, "empty args: fixFlag false");
+    assertEq(r.mode, "doctor", "empty args: mode is doctor");
+    assertEq(r.requestedScope, undefined, "empty args: no scope");
+  }
+
+  // ── 8. heal and audit modes unaffected ─────────────────────────────────────
+  console.log("\n=== heal and audit modes ===");
+  {
+    const rh = parseDoctorArgs("heal M001/S01");
+    assertEq(rh.mode, "heal", "heal mode parsed correctly");
+    assertEq(rh.requestedScope, "M001/S01", "heal scope parsed correctly");
+
+    const ra = parseDoctorArgs("audit");
+    assertEq(ra.mode, "audit", "audit mode parsed correctly");
+  }
+
+  report();
+}
+
+main();