@opengsd/gsd-pi 1.8.1 → 1.9.0

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -17,6 +17,7 @@ import {
   insertVerificationEvidence,
   insertGateRow,
   getGateResults,
+  saveReworkBrief,
   updateMilestoneStatus,
   updateSliceStatus,
   SCHEMA_VERSION,
@@ -507,6 +508,77 @@ console.log('\n=== complete-task: disabled hard-blocker escalation rolls back co
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: rollback reverts applied rework resolutions
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: rollback reverts applied rework resolutions ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath } = createTempProject();
+  writeProjectPreferences(basePath, 'phases:\n  mid_execution_escalation: false\n');
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  // Completion resolves the blocking finding but then rolls back because the
+  // hard-blocker escalation is disabled. The rollback must also revert the
+  // finding. Otherwise a retry would see no unresolved blocking findings and
+  // silently skip the blocking gate.
+  const result = await withWorkingDirectory(basePath, () => handleCompleteTask({
+    ...makeValidParams(),
+    blockerDiscovered: true,
+    reworkResolution: [{
+      findingId: 'F1',
+      status: 'resolved',
+      evidence: 'Fixed compile error and reran pnpm run typecheck:extensions.',
+    }],
+    escalation: {
+      question: 'Should execution pause for the hard blocker?',
+      options: makeEscalationOptions(),
+      recommendation: 'pause',
+      recommendationRationale: 'The blocker should not be silently advanced.',
+      continueWithDefault: false,
+    },
+  }, basePath));
+
+  assertTrue('error' in result, 'completion should roll back when hard-blocker escalation is disabled');
+  assertEq(getTask('M001', 'S01', 'T01')?.status, 'pending', 'task status should roll back to pending');
+
+  const finding = _getAdapter()!.prepare(
+    "SELECT status, evidence, decision_ref FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'"
+  ).get() as { status: string; evidence: string; decision_ref: string };
+  assertEq(finding.status, 'pending', 'rework finding should revert to pending after rollback');
+  assertEq(finding.evidence, '', 'rework finding evidence should be cleared after rollback');
+
+  // Retry-safety invariant: the blocking gate must fire again because the
+  // finding is unresolved once more.
+  const retry = await withWorkingDirectory(basePath, () => handleCompleteTask(makeValidParams(), basePath));
+  assertTrue('error' in retry, 'retry without reworkResolution should be blocked again');
+  if ('error' in retry) {
+    assertMatch(retry.error, /unresolved blocking rework finding/i, 'retry should re-trigger the blocking gate');
+  }
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // complete-task: soft escalation with mid-execution escalation disabled
 // ═══════════════════════════════════════════════════════════════════════════
@@ -838,6 +910,220 @@ console.log('\n=== complete-task: closes Q5/Q6/Q7 gates (pass vs omitted) ===');
   cleanup(dbPath);
 }
 
+
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: unresolved blocking rework findings reject completion
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: rejects unresolved blocking rework findings ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  const result = await handleCompleteTask(makeValidParams(), basePath);
+  assertTrue('error' in result, 'completion should reject unresolved blocking rework findings');
+  if ('error' in result) {
+    assertMatch(result.error, /unresolved blocking rework finding/i, 'error should explain unresolved rework');
+    assertMatch(result.error, /F1/, 'error should name the unresolved finding id');
+  }
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+
+console.log('\n=== complete-task: accepts resolved blocking rework evidence ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  const result = await handleCompleteTask({
+    ...makeValidParams(),
+    reworkResolution: [{
+      findingId: 'F1',
+      status: 'resolved',
+      evidence: 'Fixed compile error and reran pnpm run typecheck:extensions.',
+    }],
+  }, basePath);
+
+  assertTrue(!('error' in result), 'completion should accept resolved blocking rework evidence');
+  assertEq(getTask('M001', 'S01', 'T01')?.status, 'complete', 'task should complete after resolving rework');
+  const finding = _getAdapter()!.prepare("SELECT status, evidence FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'").get() as { status: string; evidence: string };
+  assertEq(finding.status, 'resolved', 'finding status should be updated');
+  assertMatch(finding.evidence, /Fixed compile error/, 'resolution evidence should be persisted');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+console.log('\n=== complete-task: accepts deferred blocking rework with decision reference ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  const result = await handleCompleteTask({
+    ...makeValidParams(),
+    reworkResolution: [{
+      findingId: 'F1',
+      status: 'deferred-with-override',
+      evidence: 'Maintainer accepted temporary deferral.',
+      decisionRef: 'DEC-2026-07-07-rework-deferral',
+    }],
+  }, basePath);
+
+  assertTrue(!('error' in result), 'completion should accept deferred blocking rework with decision reference');
+  const finding = _getAdapter()!.prepare("SELECT status, decision_ref FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'").get() as { status: string; decision_ref: string };
+  assertEq(finding.status, 'deferred-with-override', 'finding status should record the override');
+  assertEq(finding.decision_ref, 'DEC-2026-07-07-rework-deferral', 'decision reference should be persisted');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+console.log('\n=== complete-task: invalid duplicate rework resolution cannot overwrite a valid one ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  // The guard admits F1 because a satisfying entry exists, but a later
+  // non-satisfying duplicate for the same finding must NOT overwrite the valid
+  // resolution and leave F1 resolved with no evidence.
+  const result = await handleCompleteTask({
+    ...makeValidParams(),
+    reworkResolution: [
+      { findingId: 'F1', status: 'resolved', evidence: 'Fixed compile error and reran pnpm run typecheck:extensions.' },
+      { findingId: 'F1', status: 'resolved', evidence: '' },
+    ],
+  }, basePath);
+
+  assertTrue(!('error' in result), 'completion should succeed on the valid resolution');
+  const finding = _getAdapter()!.prepare(
+    "SELECT status, evidence FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'"
+  ).get() as { status: string; evidence: string };
+  assertEq(finding.status, 'resolved', 'finding should remain resolved');
+  assertMatch(finding.evidence, /Fixed compile error/, 'valid evidence must survive the invalid duplicate');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+console.log('\n=== complete-task: invalid deferred duplicate cannot strip decisionRef ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
+  saveReworkBrief({
+    briefId: 'RB-001',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    findings: [{
+      findingId: 'F1',
+      severity: 'blocking',
+      description: 'Compile regression',
+      requiredFix: 'Fix compile error',
+      verificationCommands: ['pnpm run typecheck:extensions'],
+    }],
+  });
+
+  // A deferred-with-override duplicate that omits decisionRef is non-satisfying
+  // and must not overwrite the valid deferral.
+  const result = await handleCompleteTask({
+    ...makeValidParams(),
+    reworkResolution: [
+      { findingId: 'F1', status: 'deferred-with-override', evidence: 'Maintainer accepted temporary deferral.', decisionRef: 'DEC-2026-07-07-rework-deferral' },
+      { findingId: 'F1', status: 'deferred-with-override', evidence: 'Maintainer accepted temporary deferral.' },
+    ],
+  }, basePath);
+
+  assertTrue(!('error' in result), 'completion should succeed on the valid deferral');
+  const finding = _getAdapter()!.prepare(
+    "SELECT status, decision_ref FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'"
+  ).get() as { status: string; decision_ref: string };
+  assertEq(finding.status, 'deferred-with-override', 'finding should remain deferred-with-override');
+  assertEq(finding.decision_ref, 'DEC-2026-07-07-rework-deferral', 'valid decisionRef must survive the invalid duplicate');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 
 report();

package/src/resources/extensions/gsd/tests/db-engine-migrate-guards.test.ts

@@ -0,0 +1,186 @@
+// GSD Extension - Migration guard tests (plan 026).
+// Covers the newer-DB refusal in migrateSchema, whole-chain rollback atomicity
+// via the _setMigrationFaultForTest seam, the legacy-data guard in initSchema,
+// and getCurrentSchemaVersion's empty-table NULL handling.
+
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { createRequire } from 'node:module';
+
+import {
+  openDatabase,
+  closeDatabase,
+  isDbAvailable,
+  SCHEMA_VERSION,
+  _setMigrationFaultForTest,
+} from '../gsd-db.ts';
+import { createDbAdapter } from '../db-adapter.ts';
+import { getCurrentSchemaVersion } from '../db-schema-metadata.ts';
+
+const _require = createRequire(import.meta.url);
+
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-migrate-guards-'));
+  return path.join(dir, 'gsd.db');
+}
+
+function cleanup(dbPath: string): void {
+  closeDatabase();
+  fs.rmSync(path.dirname(dbPath), { recursive: true, force: true });
+}
+
+interface RawDb {
+  exec(sql: string): void;
+  prepare(sql: string): { get(...args: unknown[]): Record<string, unknown> | undefined; all(...args: unknown[]): Array<Record<string, unknown>> };
+  close(): void;
+}
+
+function openRawSqliteForTest(dbPath: string): RawDb {
+  try {
+    const mod = _require('node:sqlite') as { DatabaseSync: new (path: string) => RawDb };
+    return new mod.DatabaseSync(dbPath);
+  } catch {
+    type SqliteCtor = new (path: string) => RawDb;
+    const mod = _require('better-sqlite3') as SqliteCtor | { default: SqliteCtor };
+    const DatabaseCtor: SqliteCtor = typeof mod === 'function' ? mod : mod.default;
+    return new DatabaseCtor(dbPath);
+  }
+}
+
+function rawColumnNames(raw: RawDb, table: string): string[] {
+  return raw.prepare(`PRAGMA table_info(${table})`).all().map((r) => r['name'] as string);
+}
+
+function rawHasTable(raw: RawDb, table: string): boolean {
+  const row = raw.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+  return Boolean(row);
+}
+
+function rawMaxVersion(raw: RawDb): number | null {
+  const row = raw.prepare('SELECT MAX(version) as v FROM schema_version').get();
+  return (row?.['v'] as number | null) ?? null;
+}
+
+describe('db-engine migrate guards', () => {
+  test('getCurrentSchemaVersion returns 0 on an empty schema_version table', () => {
+    const sqlite = _require('node:sqlite') as { DatabaseSync: new (path: string) => unknown };
+    const adapter = createDbAdapter(new sqlite.DatabaseSync(':memory:'));
+    try {
+      adapter.exec('CREATE TABLE schema_version (version INTEGER NOT NULL, applied_at TEXT NOT NULL)');
+      assert.equal(getCurrentSchemaVersion(adapter), 0);
+    } finally {
+      adapter.close();
+    }
+  });
+
+  test('refuses to open a DB whose schema is newer than this binary', () => {
+    const dbPath = tempDbPath();
+    try {
+      assert.ok(openDatabase(dbPath), 'fresh open should succeed');
+      closeDatabase();
+
+      const raw = openRawSqliteForTest(dbPath);
+      raw.exec(
+        `INSERT INTO schema_version (version, applied_at) VALUES (${SCHEMA_VERSION + 1}, '2026-01-01T00:00:00Z')`,
+      );
+      raw.close();
+
+      assert.throws(() => openDatabase(dbPath), /newer than/);
+      assert.equal(isDbAvailable(), false, 'no connection may stay open on refusal');
+    } finally {
+      cleanup(dbPath);
+    }
+  });
+
+  test('a mid-migration failure rolls back to the starting schema version', () => {
+    const dbPath = tempDbPath();
+    try {
+      assert.ok(openDatabase(dbPath), 'fresh open should succeed');
+      closeDatabase();
+
+      // Rewind the DB to v(SCHEMA_VERSION-1): stamp the prior version and drop
+      // the objects the last migration adds, so the re-run has real work to redo.
+      const startVersion = SCHEMA_VERSION - 2;
+      const raw = openRawSqliteForTest(dbPath);
+      raw.exec('DELETE FROM schema_version');
+      raw.exec(`INSERT INTO schema_version (version, applied_at) VALUES (${startVersion}, '2026-01-01T00:00:00Z')`);
+      raw.exec('ALTER TABLE slices DROP COLUMN target_repositories');
+      raw.exec('ALTER TABLE tasks DROP COLUMN target_repositories');
+      raw.close();
+
+      _setMigrationFaultForTest(true);
+      try {
+        assert.throws(() => openDatabase(dbPath), /migration fault injected/);
+      } finally {
+        _setMigrationFaultForTest(false);
+      }
+      assert.equal(isDbAvailable(), false, 'no connection may stay open on migration failure');
+
+      const inspect = openRawSqliteForTest(dbPath);
+      try {
+        assert.equal(rawMaxVersion(inspect), startVersion, 'version must roll back to the starting version');
+        assert.ok(
+          !rawColumnNames(inspect, 'slices').includes('target_repositories'),
+          'column added by the failed migration must be rolled back',
+        );
+      } finally {
+        inspect.close();
+      }
+
+      // The DB is intact — a clean re-open migrates to the current version.
+      assert.ok(openDatabase(dbPath), 're-open without the fault should succeed');
+      closeDatabase();
+      const after = openRawSqliteForTest(dbPath);
+      try {
+        assert.equal(rawMaxVersion(after), SCHEMA_VERSION);
+        assert.ok(rawColumnNames(after, 'slices').includes('target_repositories'));
+        assert.equal(rawHasTable(after, 'rework_briefs'), true);
+        assert.equal(rawHasTable(after, 'rework_brief_findings'), true);
+      } finally {
+        after.close();
+      }
+    } finally {
+      cleanup(dbPath);
+    }
+  });
+
+  test('a DB with data but no version rows migrates from v1 instead of being stamped current', () => {
+    const dbPath = tempDbPath();
+    try {
+      assert.ok(openDatabase(dbPath), 'fresh open should succeed');
+      closeDatabase();
+
+      // Simulate a legacy DB: user data present, version table empty, and a
+      // migration-added column missing so we can observe the chain actually run.
+      const raw = openRawSqliteForTest(dbPath);
+      raw.exec("INSERT INTO milestones (id, title) VALUES ('M001', 'Legacy milestone')");
+      raw.exec('DELETE FROM schema_version');
+      raw.exec('ALTER TABLE milestones DROP COLUMN vision');
+      raw.close();
+
+      assert.ok(openDatabase(dbPath), 'legacy DB open should succeed');
+      closeDatabase();
+
+      const inspect = openRawSqliteForTest(dbPath);
+      try {
+        const versions = inspect.prepare('SELECT version FROM schema_version ORDER BY version').all()
+          .map((r) => r['version'] as number);
+        assert.equal(versions[0], 1, 'baseline v1 must be recorded, not a fresh-install stamp');
+        assert.equal(versions[versions.length - 1], SCHEMA_VERSION, 'migration chain must reach the current version');
+        assert.ok(
+          rawColumnNames(inspect, 'milestones').includes('vision'),
+          'migration-added column must be restored by the chain',
+        );
+        const row = inspect.prepare('SELECT count(*) as cnt FROM milestones').get();
+        assert.equal(row?.['cnt'], 1, 'existing data must survive');
+      } finally {
+        inspect.close();
+      }
+    } finally {
+      cleanup(dbPath);
+    }
+  });
+});

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

@@ -7,6 +7,8 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
 import { deriveState, invalidateStateCache, _deriveStateImpl, deriveStateFromDb, isGhostMilestone } from '../state.ts';
+import { readCachedDeriveState, writeCachedDeriveState } from '../state/derive/cache.ts';
+import type { GSDState } from '../types.ts';
 import {
   openDatabase,
   closeDatabase,
@@ -582,6 +584,33 @@ describe('derive-state-db', async () => {
     }
   });
 
+  // ─── Test 7b: lock flip must not serve a basePath-keyed cache hit ─────
+  // The derive cache is keyed on basePath only, but deriveStateFromDb filters
+  // by GSD_MILESTONE_LOCK. auto.ts's capture/restoreMilestoneLockEnv call
+  // invalidateStateCache() on every flip; this guards that the cache is
+  // genuinely lock-blind (so that invalidate call is load-bearing, not
+  // redundant) and that invalidation defeats the stale read.
+  test('derive-state-db: a milestone-lock flip needs explicit cache invalidation', () => {
+    const prevLock = process.env.GSD_MILESTONE_LOCK;
+    try {
+      const base = '/tmp/gsd-lock-flip-fixture';
+      const stateA = { phase: 'planning' } as unknown as GSDState;
+      process.env.GSD_MILESTONE_LOCK = 'M001';
+      writeCachedDeriveState(base, stateA);
+
+      // Lock flips but basePath is unchanged → the cache still hits.
+      process.env.GSD_MILESTONE_LOCK = 'M002';
+      assert.strictEqual(readCachedDeriveState(base), stateA, 'basePath-only cache ignores the lock flip');
+
+      // What the lock-env functions do on flip:
+      invalidateStateCache();
+      assert.strictEqual(readCachedDeriveState(base), null, 'invalidation defeats the stale-lock read');
+    } finally {
+      if (prevLock === undefined) delete process.env.GSD_MILESTONE_LOCK;
+      else process.env.GSD_MILESTONE_LOCK = prevLock;
+    }
+  });
+
   // ═════════════════════════════════════════════════════════════════════════
   // New: deriveStateFromDb() cross-validation tests
   // ═════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/discuss-routing-fixes.test.ts

@@ -80,6 +80,43 @@ function makeDiscussCtx(notifications: Array<{ message: string; level?: string }
   };
 }
 
+async function runDiscussTargetFixture(
+  target: string,
+  milestones: Array<{ id: string; title?: string; status?: string }>,
+  writeArtifacts?: (base: string) => void,
+) {
+  const base = mkdtempSync(join(tmpdir(), "gsd-discuss-target-"));
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const harness = makeDiscussPi();
+  try {
+    mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+    writeArtifacts?.(base);
+    const dbPath = join(base, ".gsd", "gsd.db");
+    assert.equal(openDatabase(dbPath), true);
+    for (const milestone of milestones) {
+      insertMilestone(milestone);
+    }
+
+    await showDiscuss(
+      makeDiscussCtx(notifications) as any,
+      harness.pi as any,
+      base,
+      { target },
+    );
+
+    return {
+      notifications: [...notifications],
+      sent: [...harness.sent],
+    };
+  } finally {
+    harness.restore();
+    if (isDbAvailable()) closeDatabase();
+    invalidateStateCache();
+    clearGuidedUnitContext();
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
 describe("discuss target normalization", () => {
   test("canonicalizes milestone and slice casing", () => {
     assert.equal(normalizeDiscussTarget("m014"), "M014");
@@ -90,6 +127,92 @@ describe("discuss target normalization", () => {
   });
 });
 
+describe("showDiscuss targeted milestone guardrails (#1320)", () => {
+  test("missing, complete, and parked milestone targets get actionable messages", async () => {
+    const cases = [
+      {
+        target: "M006",
+        milestones: [{ id: "M005", title: "Current", status: "active" }],
+        level: "warning",
+        message: /Milestone M006 was not found in the roadmap\. Use \/gsd new-milestone to add it, or \/gsd status to see available milestones\./,
+      },
+      {
+        target: "M006/S01",
+        milestones: [{ id: "M005", title: "Current", status: "active" }],
+        level: "warning",
+        message: /Milestone M006 was not found in the roadmap\. Use \/gsd new-milestone to add it, or \/gsd status to see available milestones\./,
+      },
+      {
+        target: "M006",
+        milestones: [{ id: "M006", title: "Done", status: "complete" }],
+        level: "info",
+        message: /Milestone M006 is already complete\./,
+      },
+      {
+        target: "M006/S01",
+        milestones: [{ id: "M006", title: "Done", status: "complete" }],
+        level: "info",
+        message: /Milestone M006 is already complete\./,
+      },
+      {
+        target: "M006",
+        milestones: [{ id: "M006", title: "Deferred", status: "parked" }],
+        level: "warning",
+        message: /Milestone M006 is parked\. Run \/gsd unpark M006 to reactivate\./,
+      },
+      {
+        target: "M006/S01",
+        milestones: [{ id: "M006", title: "Deferred", status: "parked" }],
+        level: "warning",
+        message: /Milestone M006 is parked\. Run \/gsd unpark M006 to reactivate\./,
+      },
+    ];
+
+    for (const testCase of cases) {
+      const result = await runDiscussTargetFixture(testCase.target, testCase.milestones);
+      assert.equal(result.sent.length, 0, `${testCase.target} must not dispatch`);
+      assert.equal(result.notifications.length, 1, `${testCase.target} must emit one notification`);
+      assert.equal(result.notifications[0]?.level, testCase.level);
+      assert.match(result.notifications[0]?.message ?? "", testCase.message);
+      assert.doesNotMatch(result.notifications[0]?.message ?? "", /not discussable/i);
+    }
+  });
+
+  test("bare milestone targets match unique-suffix milestone IDs", async () => {
+    const result = await runDiscussTargetFixture("M006", [
+      { id: "M006-abc123", title: "Unique milestone", status: "active" },
+    ]);
+
+    assert.equal(result.notifications.length, 0);
+    assert.equal(result.sent.length, 1, "bare ID must dispatch the suffixed milestone");
+    assert.match(String(result.sent[0]?.content), /M006-abc123|Unique milestone|guided-discuss-milestone/i);
+  });
+
+  test("bare slice targets match unique-suffix milestone IDs", async () => {
+    const result = await runDiscussTargetFixture(
+      "M006/S01",
+      [{ id: "M006-abc123", title: "Unique milestone", status: "active" }],
+      (base) => {
+        mkdirSync(join(base, ".gsd", "milestones", "M006-abc123"), { recursive: true });
+        writeFileSync(
+          join(base, ".gsd", "milestones", "M006-abc123", "M006-abc123-ROADMAP.md"),
+          `# M006-abc123 Roadmap
+
+## Slices
+- [ ] **S01: Unique slice** \`risk:medium\` \`depends:[]\`
+  > After this: the suffixed milestone slice can be discussed
+`,
+          "utf-8",
+        );
+      },
+    );
+
+    assert.equal(result.notifications.length, 0);
+    assert.equal(result.sent.length, 1, "bare ID slice target must dispatch through the suffixed milestone");
+    assert.match(String(result.sent[0]?.content), /M006-abc123|S01|Unique slice|guided-discuss-slice/i);
+  });
+});
+
 describe("loadDiscussNormSlices roadmap fallback (#2892)", () => {
   test("falls back to ROADMAP when DB has no slice rows", async () => {
     const base = mkdtempSync(join(tmpdir(), "gsd-discuss-slices-"));