@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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

@@ -1,18 +1,23 @@
-// Structural invariant: gsd-db.ts is the single writer for .gsd/gsd.db.
+// Structural invariant: gsd-db.ts and the typed writer layer own writes for .gsd/gsd.db.
 //
 // No file under src/resources/extensions/gsd/ may issue raw write SQL
 // (INSERT/UPDATE/DELETE/REPLACE) or raw transaction control (BEGIN/COMMIT/
 // ROLLBACK via `.exec(...)`) against the engine database. Every bypass must
-// route through a typed wrapper exported from gsd-db.ts.
+// route through an explicitly allowlisted typed writer.
 //
 // Allowlist:
-// - gsd-db.ts itself — the single writer
+// - gsd-db.ts itself — compatibility barrel and remaining mid-migration wrappers
+// - db/engine.ts — schema, migrations, lifecycle, and transaction primitives
+// - db/writers/** — domain writers
+// - typed coordination/runtime writer modules listed in TYPED_DB_WRITER_FILES
+// - schema/migration helper modules listed in SCHEMA_DB_WRITER_FILES
+// - ADR migration/backfill helpers listed in MIGRATION_BACKFILL_WRITER_FILES
 // - unit-ownership.ts — manages a separate .gsd/unit-claims.db for
 //   cross-worktree claim races; intentionally outside this invariant
 // - tests/** — fixtures and direct DB inspection are fair game
 //
 // When this test fails, do not add a new suppression. Instead:
-// 1. Add a typed wrapper to gsd-db.ts that captures the SQL
+// 1. Add a typed wrapper to the explicit writer layer that captures the SQL
 // 2. Switch the flagged site to call the wrapper
 //
 // See `.claude/plans/joyful-doodling-pony.md` for the full rationale.
@@ -24,11 +29,58 @@ import { join, relative } from "node:path";
 
 const gsdDir = join(process.cwd(), "src/resources/extensions/gsd");
 
-const ALLOWLIST = new Set([
-  "gsd-db.ts",
-  "unit-ownership.ts",
+// The single-writer invariant is enforced on a directory layer, not a single
+// filename. Write SQL may live only in:
+//   - db/engine.ts — connection lifecycle, schema/migrations (DDL), and the
+//     BEGIN/COMMIT transaction primitives. The shared handle every writer reads.
+//   - db/writers/**.ts — the Single Writer Layer: one cohesive write subsystem
+//     per file.
+//   - gsd-db.ts — the barrel that re-exports the layer (still holds wrappers
+//     mid-migration).
+//   - typed coordination/runtime writers listed below.
+//   - schema/migration helpers listed below.
+//   - ADR migration/backfill helpers listed below.
+//   - unit-ownership.ts — a separate .gsd/unit-claims.db, intentionally outside.
+// db/queries.ts is explicitly NOT allowed write SQL (asserted separately below).
+const TYPED_DB_WRITER_FILES = new Set([
+  "db/auto-workers.ts",
+  "db/command-queue.ts",
+  "db/milestone-leases.ts",
+  "db/runtime-kv.ts",
+  "db/unit-dispatches.ts",
+]);
+
+const SCHEMA_DB_WRITER_FILES = new Set([
+  "db-memory-fts-schema.ts",
+  "db-schema-metadata.ts",
+  "db-verification-evidence-schema.ts",
 ]);
 
+const MIGRATION_BACKFILL_WRITER_FILES = new Set([
+  "memory-backfill.ts",
+]);
+
+const DB_WRITER_ALLOWLIST_GUIDANCE = [
+  "gsd-db.ts",
+  "db/engine.ts",
+  "db/writers/**",
+  ...TYPED_DB_WRITER_FILES,
+  ...SCHEMA_DB_WRITER_FILES,
+  ...MIGRATION_BACKFILL_WRITER_FILES,
+  "unit-ownership.ts only for .gsd/unit-claims.db",
+].join(", ");
+
+function isSingleWriterFile(rel: string): boolean {
+  const norm = rel.split("\\").join("/");
+  if (norm === "gsd-db.ts" || norm === "unit-ownership.ts") return true;
+  if (norm === "db/engine.ts") return true;
+  if (norm.startsWith("db/writers/") && norm.endsWith(".ts")) return true;
+  if (TYPED_DB_WRITER_FILES.has(norm)) return true;
+  if (SCHEMA_DB_WRITER_FILES.has(norm)) return true;
+  if (MIGRATION_BACKFILL_WRITER_FILES.has(norm)) return true;
+  return false;
+}
+
 /** Walk the gsd extension dir and return all .ts files outside tests/. */
 function walkTsFiles(root: string): string[] {
   const out: string[] = [];
@@ -69,13 +121,151 @@ interface Violation {
   kind: string;
 }
 
-// Match .prepare("... INSERT|UPDATE|DELETE|REPLACE ...") in any quoting style.
-const PREPARE_WRITE_RE = /\.prepare\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE)\b/i;
+const DB_CALL_RE = /\.(prepare|exec)\s*\(/g;
+const PREPARE_WRITE_SQL_RE = /\b(INSERT|UPDATE|DELETE|REPLACE)\b/i;
+const EXEC_WRITE_SQL_RE = /\b(INSERT|UPDATE|DELETE|REPLACE|BEGIN|COMMIT|ROLLBACK)\b/i;
+
+function findRawWriteSqlViolations(file: string, content: string): Violation[] {
+  const violations: Violation[] = [];
+  DB_CALL_RE.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = DB_CALL_RE.exec(content)) !== null) {
+    const method = match[1] as "prepare" | "exec";
+    const sql = readFirstStringArgument(content, DB_CALL_RE.lastIndex);
+    if (sql === null) continue;
+
+    const keywordMatch =
+      method === "prepare"
+        ? PREPARE_WRITE_SQL_RE.exec(sql)
+        : EXEC_WRITE_SQL_RE.exec(sql);
+    if (keywordMatch === null) continue;
+
+    violations.push({
+      file,
+      line: lineNumberAt(content, match.index),
+      snippet: lineSnippetAt(content, match.index),
+      kind: `${method}(${keywordMatch[1].toUpperCase()})`,
+    });
+  }
+
+  return violations;
+}
+
+function readFirstStringArgument(content: string, index: number): string | null {
+  const quoteIndex = skipWhitespace(content, index);
+  const quote = content[quoteIndex];
+  if (quote !== "`" && quote !== "'" && quote !== '"') return null;
+  return readStringLiteral(content, quoteIndex, quote);
+}
+
+function skipWhitespace(content: string, index: number): number {
+  let cursor = index;
+  while (cursor < content.length && /\s/.test(content[cursor] ?? "")) {
+    cursor++;
+  }
+  return cursor;
+}
+
+function readStringLiteral(content: string, quoteIndex: number, quote: string): string | null {
+  let value = "";
+
+  for (let cursor = quoteIndex + 1; cursor < content.length; cursor++) {
+    const char = content[cursor];
+    if (char === "\\") {
+      value += char;
+      cursor++;
+      if (cursor < content.length) value += content[cursor];
+      continue;
+    }
+    if (char === quote) return value;
+    value += char;
+  }
+
+  return null;
+}
+
+function lineNumberAt(content: string, index: number): number {
+  return content.slice(0, index).split("\n").length;
+}
 
-// Match .exec("... INSERT|UPDATE|DELETE|REPLACE ...") or raw BEGIN/COMMIT/ROLLBACK.
-const EXEC_WRITE_RE = /\.exec\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE|BEGIN|COMMIT|ROLLBACK)\b/i;
+function lineSnippetAt(content: string, index: number): string {
+  const lineStart = content.lastIndexOf("\n", index) + 1;
+  const nextNewline = content.indexOf("\n", index);
+  const lineEnd = nextNewline === -1 ? content.length : nextNewline;
+  return content.slice(lineStart, lineEnd).trim();
+}
+
+test("scanner catches multiline template-literal db.prepare write SQL", () => {
+  const violations = findRawWriteSqlViolations(
+    "fixture.ts",
+    [
+      "const stmt = db.prepare(",
+      "  `INSERT INTO tasks (id)",
+      "   VALUES (?)`",
+      ");",
+    ].join("\n"),
+  );
+
+  assert.deepEqual(violations.map(({ line, kind }) => ({ line, kind })), [
+    { line: 1, kind: "prepare(INSERT)" },
+  ]);
+});
+
+test("scanner catches multiline raw transaction control in exec", () => {
+  const violations = findRawWriteSqlViolations(
+    "fixture.ts",
+    [
+      "db.exec(",
+      "  `BEGIN`",
+      ");",
+    ].join("\n"),
+  );
+
+  assert.deepEqual(violations.map(({ line, kind }) => ({ line, kind })), [
+    { line: 1, kind: "exec(BEGIN)" },
+  ]);
+});
 
-test("no module outside gsd-db.ts issues raw write SQL against the engine DB", () => {
+test("scanner ignores multiline SELECT statements", () => {
+  const violations = findRawWriteSqlViolations(
+    "fixture.ts",
+    [
+      "const stmt = db.prepare(",
+      "  `SELECT id",
+      "   FROM tasks`",
+      ");",
+    ].join("\n"),
+  );
+
+  assert.deepEqual(violations, []);
+});
+
+const DB_WORKSPACE_MECHANICS = new Set([
+  "backupDatabaseSnapshot",
+  "checkpointDatabase",
+  "closeAllDatabases",
+  "closeDatabase",
+  "closeDatabaseByWorkspace",
+  "getDbPath",
+  "getDbProvider",
+  "getDbStatus",
+  "openDatabase",
+  "openDatabaseByScope",
+  "openDatabaseByWorkspace",
+  "refreshOpenDatabaseFromDisk",
+  "vacuumDatabase",
+  "wasDbOpenAttempted",
+]);
+
+function importNames(specifierBlock: string): string[] {
+  return specifierBlock
+    .split(",")
+    .map((name) => name.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim() ?? "")
+    .filter(Boolean);
+}
+
+test("no module outside the explicit DB writer allowlist issues raw write SQL", () => {
   const files = walkTsFiles(gsdDir);
   assert.ok(files.length >= 20, `Expected at least 20 .ts files under gsd/, found ${files.length}`);
 
@@ -83,8 +273,7 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
 
   for (const abs of files) {
     const rel = relative(gsdDir, abs);
-    const base = rel.split("/").pop()!;
-    if (ALLOWLIST.has(base)) continue;
+    if (isSingleWriterFile(rel)) continue;
 
     let content: string;
     try {
@@ -93,30 +282,7 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
       continue;
     }
 
-    const lines = content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-
-      const prepareMatch = PREPARE_WRITE_RE.exec(line);
-      if (prepareMatch) {
-        violations.push({
-          file: rel,
-          line: i + 1,
-          snippet: line.trim(),
-          kind: `prepare(${prepareMatch[1].toUpperCase()})`,
-        });
-      }
-
-      const execMatch = EXEC_WRITE_RE.exec(line);
-      if (execMatch) {
-        violations.push({
-          file: rel,
-          line: i + 1,
-          snippet: line.trim(),
-          kind: `exec(${execMatch[1].toUpperCase()})`,
-        });
-      }
-    }
+    violations.push(...findRawWriteSqlViolations(rel, content));
   }
 
   if (violations.length > 0) {
@@ -124,13 +290,29 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
       (v) => `  ${v.file}:${v.line} [${v.kind}] — ${v.snippet}`,
     );
     assert.fail(
-      `Found ${violations.length} raw write SQL bypass(es) outside gsd-db.ts:\n` +
+      `Found ${violations.length} raw write SQL bypass(es) outside the explicit DB writer allowlist:\n` +
         lines.join("\n") +
-        "\n\nEach of these must be replaced with a typed wrapper exported from gsd-db.ts.",
+        `\n\nMove each write to the appropriate allowlisted owner: ${DB_WRITER_ALLOWLIST_GUIDANCE}.`,
     );
   }
 });
 
+test("db/queries.ts (the Query Module) is read-only — contains no write SQL", () => {
+  // The read seam is separate from the single-writer layer. queries.ts holds
+  // SELECT-only wrappers so read-only callers depend on a read seam, not the
+  // write surface. (test 1 above also forbids this, since queries.ts is not in
+  // db/writers/ — this is the explicit, positive statement of intent.)
+  const queriesPath = join(gsdDir, "db", "queries.ts");
+  const content = readFileSync(queriesPath, "utf-8");
+  const violations = findRawWriteSqlViolations("db/queries.ts", content);
+  assert.equal(
+    violations.length,
+    0,
+    `db/queries.ts must contain no write SQL — move write wrappers to the explicit DB writer allowlist:\n` +
+      violations.map((v) => `  db/queries.ts:${v.line} [${v.kind}] — ${v.snippet}`).join("\n"),
+  );
+});
+
 test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   // Positive assertion — fail loudly if the module layout changes so this
   // structural test can't silently become a no-op.
@@ -166,6 +348,84 @@ test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   }
 });
 
+test("DB Workspace Interface owns database open-state and maintenance calls", async () => {
+  const workspaceDb = await import("../db-workspace.js");
+
+  const expected = [
+    "backupWorkflowDatabaseSnapshot",
+    "checkpointWorkflowDatabase",
+    "closeAllWorkflowDatabases",
+    "closeWorkflowDatabase",
+    "closeWorkflowDatabaseByWorkspace",
+    "getWorkflowDatabasePath",
+    "getWorkflowDatabaseProvider",
+    "getWorkflowDatabaseStatus",
+    "isWorkflowDatabaseOpen",
+    "openExistingWorkflowDatabase",
+    "openWorkflowDatabase",
+    "openWorkflowDatabaseByScope",
+    "openWorkflowDatabaseByWorkspace",
+    "openWorkflowDatabasePath",
+    "refreshWorkflowDatabaseFromDisk",
+    "resolveProjectRootDbPath",
+    "resolveWorkflowDatabaseLocation",
+    "vacuumWorkflowDatabase",
+    "wasWorkflowDatabaseOpenAttempted",
+  ];
+
+  for (const name of expected) {
+    assert.ok(
+      typeof (workspaceDb as Record<string, unknown>)[name] === "function",
+      `db-workspace.ts must export ${name} as a function`,
+    );
+  }
+});
+
+test("production modules do not import DB open-state mechanics from gsd-db.ts", () => {
+  const files = walkTsFiles(gsdDir);
+  const violations: Violation[] = [];
+  const staticImportRe = /import\s*\{([\s\S]*?)\}\s*from\s*["'][^"']*gsd-db\.(?:js|ts)["']/g;
+  const dynamicImportRe = /(?:const|let)\s*\{([\s\S]*?)\}\s*=\s*await\s+import\(["'][^"']*gsd-db\.(?:js|ts)["']\)/g;
+
+  for (const abs of files) {
+    const rel = relative(gsdDir, abs);
+    if (rel === "gsd-db.ts" || rel === "db-workspace.ts") continue;
+
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      continue;
+    }
+
+    for (const re of [staticImportRe, dynamicImportRe]) {
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content)) !== null) {
+        const leaked = importNames(match[1] ?? "").filter((name) => DB_WORKSPACE_MECHANICS.has(name));
+        if (leaked.length === 0) continue;
+        violations.push({
+          file: rel,
+          line: content.slice(0, match.index).split("\n").length,
+          snippet: leaked.join(", "),
+          kind: "db-workspace-leak",
+        });
+      }
+    }
+  }
+
+  if (violations.length > 0) {
+    const lines = violations.map(
+      (v) => `  ${v.file}:${v.line} [${v.kind}] — ${v.snippet}`,
+    );
+    assert.fail(
+      `Found ${violations.length} DB open-state import(s) from gsd-db.ts:\n` +
+        lines.join("\n") +
+        "\n\nImport these through db-workspace.ts so gsd-db.ts stays the writer compatibility barrel, not the caller-facing DB Workspace Interface.",
+    );
+  }
+});
+
 test("the invariant test touches every .ts module under gsd/ (sanity check)", () => {
   const files = walkTsFiles(gsdDir);
   // Rough sanity: ensure we're not accidentally walking an empty tree
@@ -177,4 +437,3 @@ test("the invariant test touches every .ts module under gsd/ (sanity check)", ()
   assert.ok(rels.includes("memory-store.ts"), "walker must include memory-store.ts");
   assert.ok(rels.includes("workflow-manifest.ts"), "walker must include workflow-manifest.ts");
 });
-

package/src/resources/extensions/gsd/tests/skill-activation.test.ts

@@ -92,14 +92,14 @@ test("buildSkillActivationBlock activates skills via prefer_skills when context
       prefer_skills: ["react"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
+    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
     assert.doesNotMatch(result, /swiftui/);
   } finally {
     cleanup(base);
   }
 });
 
-test("buildSkillActivationBlock includes always_use_skills from preferences using exact Skill tool format", () => {
+test("buildSkillActivationBlock includes always_use_skills using read-based skill loading", () => {
   const base = makeTempBase();
   try {
     writeSkill(base, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
@@ -109,7 +109,10 @@ test("buildSkillActivationBlock includes always_use_skills from preferences usin
       always_use_skills: ["swift-testing"],
     });
 
-    assert.equal(result, "<skill_activation>Call Skill({ skill: 'swift-testing' }).</skill_activation>");
+    assert.equal(
+      result,
+      "<skill_activation>Read the installed 'swift-testing' skill file from <available_skills>.</skill_activation>",
+    );
   } finally {
     cleanup(base);
   }
@@ -137,8 +140,8 @@ test("buildSkillActivationBlock includes skill_rules matches and task-plan skill
       skill_rules: [{ when: "prisma database schema", use: ["prisma"] }],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'accessibility' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'prisma' \}\)/);
+    assert.match(result, /Read the installed 'accessibility' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'prisma' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -160,7 +163,7 @@ test("buildSkillActivationBlock matches skill_rules against exact unit type cont
       ],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'complete-slice-policies' \}\)/);
+    assert.match(result, /Read the installed 'complete-slice-policies' skill file from <available_skills>/);
     assert.doesNotMatch(result, /slice-broad/);
   } finally {
     cleanup(base);
@@ -264,8 +267,8 @@ test("buildSkillActivationBlock allows valid skill names and rejects invalid one
     });
 
     assert.match(result, /skill_activation/);
-    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'good-skill-2' \}\)/);
+    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'good-skill-2' skill file from <available_skills>/);
     assert.doesNotMatch(result, /bad'name/);
   } finally {
     cleanup(base);
@@ -289,8 +292,8 @@ test("buildSkillActivationBlock: explicit always_use_skills bypass the unit-type
       always_use_skills: ["write-docs", "swiftui"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -307,7 +310,7 @@ test("buildSkillActivationBlock falls through to all skills for unknown unit typ
     });
 
     // Unknown unit type = wildcard fallback (pre-manifest behavior).
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -324,7 +327,7 @@ test("buildSkillActivationBlock without unitType preserves pre-manifest behavior
       always_use_skills: ["swiftui"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -341,12 +344,12 @@ test("milestone prompt builders propagate always_use_skills through buildSkillAc
     loadOnlyTestSkills(base);
 
     const researchPrompt = await buildResearchMilestonePrompt("M001", "Test", base);
-    assert.match(researchPrompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(researchPrompt, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(researchPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(researchPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
 
     const planPrompt = await buildPlanMilestonePrompt("M001", "Test", base);
-    assert.match(planPrompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(planPrompt, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(planPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(planPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -377,7 +380,7 @@ test("complete-slice prompt propagates always_use_skills through buildSkillActiv
 
     const prompt = await buildCompleteSlicePrompt("M001", "Test", "S01", "Slice", base);
 
-    assert.match(prompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
+    assert.match(prompt, /Read the installed 'write-docs' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/stale-queued-milestone.test.ts

@@ -74,6 +74,33 @@ describe("stale queued milestone selection (#3470)", () => {
     assert.equal(m070Entry!.status, "active", "M070 should be active in registry");
   });
 
+  test("queued milestone with roadmap projection but no DB slices stays deferred", async () => {
+    base = createFixtureBase();
+    openDatabase(":memory:");
+
+    // M068: queued shell with a stale ROADMAP projection, but no CONTEXT and no DB slices.
+    insertMilestone({ id: "M068", title: "Queued Roadmap Projection", status: "queued" });
+    writeFile(base, "milestones/M068/M068-ROADMAP.md", "# M068\n\n## Slices\n\n- [ ] **S99: Stale Slice**");
+
+    // M070: real active milestone — context, roadmap, slices, tasks
+    insertMilestone({ id: "M070", title: "Real Active", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M070", title: "Slice One", status: "active", risk: "low", depends: [] });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M070", title: "Task One", status: "pending" });
+
+    writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Real Active\n\nThis is the real milestone.");
+    writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070: Real Active\n\n## Slices\n\n- [ ] **S01: Slice One**");
+    writeFile(base, "milestones/M070/slices/S01/S01-PLAN.md", "# S01: Slice One\n\n## Tasks\n\n- [ ] **T01: Task One**");
+
+    invalidateStateCache();
+    const state = await deriveStateFromDb(base);
+
+    assert.equal(state.activeMilestone?.id, "M070", "ROADMAP-only queued milestone must not block active M070");
+
+    const m068Entry = state.registry.find((e: any) => e.id === "M068");
+    assert.ok(m068Entry, "M068 should still appear in registry");
+    assert.equal(m068Entry!.status, "pending", "M068 should stay pending without CONTEXT or DB slices");
+  });
+
   test("queued milestone WITH context file can still be selected as active", async () => {
     base = createFixtureBase();
     openDatabase(":memory:");

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -339,7 +339,7 @@ test("resume path only hard-exits on blocked stop, not blocked pause (#6154)", (
   );
 });
 
-test("prepareForUnit skips worktree safety when isolation is not worktree (#6154)", () => {
+test("prepareForUnit enforces worktree safety for all isolation modes (#6154)", () => {
   const orchSrc = readGsdFile("auto/orchestrator.ts");
   const prepareForUnitIdx = orchSrc.indexOf("private async prepareWorktreeForUnit(");
   const prepareForUnitBody = orchSrc.slice(prepareForUnitIdx, orchSrc.indexOf("private classifyAndRecover(", prepareForUnitIdx));
@@ -350,8 +350,12 @@ test("prepareForUnit skips worktree safety when isolation is not worktree (#6154
     "prepareForUnit should resolve the effective isolation mode once",
   );
   assert.ok(
-    prepareForUnitBody.includes('if (isolationMode !== "worktree")'),
-    "prepareForUnit should bypass worktree safety validation outside worktree isolation mode",
+    prepareForUnitBody.includes('const writeScope ='),
+    "prepareForUnit should classify the unit's write scope before validating",
+  );
+  assert.ok(
+    !prepareForUnitBody.includes('if (isolationMode !== "worktree")'),
+    "prepareForUnit must not bypass worktree safety outside worktree isolation mode",
   );
 });
 
@@ -364,6 +368,7 @@ test("effective unit isolation follows degraded branch fallback", () => {
 
 test("discuss-to-auto handoff defaults to step mode unless explicitly disabled", () => {
   const guidedFlowSrc = readGsdFile("guided-flow.ts");
+  const discussionHandoffSrc = readGsdFile("discussion-handoff.ts");
   const workflowSrc = readGsdFile("commands/handlers/workflow.ts");
 
   assert.ok(
@@ -371,7 +376,7 @@ test("discuss-to-auto handoff defaults to step mode unless explicitly disabled",
     "guided-flow must not hardcode step: false on pending auto-start entries",
   );
   assert.match(
-    guidedFlowSrc,
+    discussionHandoffSrc,
     /scheduleAutoStartAfterIdle\(ctx, pi, basePath, false, \{ step: step \?\? true \}\)/,
     "checkAutoStartAfterDiscuss should default missing step flags to step mode",
   );

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -5,6 +5,8 @@ import {
   STATE_TRANSITION_MATRIX,
   findTransition,
   validateTransitionMatrix,
+  isLegalEdge,
+  IllegalPhaseTransitionError,
 } from "../state-transition-matrix.ts";
 
 test("state transition matrix covers required swarm hardening events", () => {
@@ -42,3 +44,37 @@ test("state transition matrix entries all have guard and reason codes", () => {
     assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
   }
 });
+
+// ─── ADR-030: Phase Transition Invariant ───────────────────────────────────
+
+test("isLegalEdge treats a self-edge as trivially legal", () => {
+  assert.equal(isLegalEdge("executing", "executing"), true);
+  assert.equal(isLegalEdge("planning", "planning"), true);
+});
+
+test("isLegalEdge accepts edges enumerated in the matrix", () => {
+  assert.equal(isLegalEdge("planning", "executing"), true);
+  assert.equal(isLegalEdge("executing", "summarizing"), true);
+  assert.equal(isLegalEdge("summarizing", "validating-milestone"), true);
+  assert.equal(isLegalEdge("completing-milestone", "complete"), true);
+});
+
+test("isLegalEdge honors the * wildcard rows (any -> blocked, any -> executing)", () => {
+  assert.equal(isLegalEdge("planning", "blocked"), true);
+  assert.equal(isLegalEdge("summarizing", "executing"), true);
+});
+
+test("isLegalEdge rejects an edge no matrix entry permits", () => {
+  // executing -> complete skips validation — exactly the illegal jump the
+  // invariant exists to catch.
+  assert.equal(isLegalEdge("executing", "complete"), false);
+  assert.equal(isLegalEdge("planning", "summarizing"), false);
+});
+
+test("IllegalPhaseTransitionError carries both endpoints and a descriptive message", () => {
+  const err = new IllegalPhaseTransitionError("executing", "complete");
+  assert.equal(err.from, "executing");
+  assert.equal(err.to, "complete");
+  assert.equal(err.name, "IllegalPhaseTransitionError");
+  assert.match(err.message, /executing -> complete/);
+});