@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/tests/unit-registry.test.ts

@@ -7,6 +7,8 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   KNOWN_UNIT_TYPES,
@@ -15,6 +17,7 @@ import {
   SECTION_CLOSE_GATE_UNIT_TYPES,
   getUnitDescriptor,
   getUnitPhaseChain,
+  getUnitPromptTemplate,
 } from "../unit-registry.ts";
 import {
   AUTO_UNIT_SCOPED_TOOLS,
@@ -96,6 +99,37 @@ const EXPECTED_PHASE_CHAINS: Record<string, string[] | undefined> = {
   "no-such-unit": undefined,
 };
 
+const EXPECTED_DIRECT_PROMPT_TEMPLATES: Record<string, string> = {
+  "research-milestone": "research-milestone",
+  "plan-milestone": "plan-milestone",
+  "validate-milestone": "validate-milestone",
+  "complete-milestone": "complete-milestone",
+  "research-slice": "research-slice",
+  "plan-slice": "plan-slice",
+  "refine-slice": "refine-slice",
+  "replan-slice": "replan-slice",
+  "complete-slice": "complete-slice",
+  "reassess-roadmap": "reassess-roadmap",
+  "execute-task": "execute-task",
+  "reactive-execute": "reactive-execute",
+  "run-uat": "run-uat",
+  "gate-evaluate": "gate-evaluate",
+  "rewrite-docs": "rewrite-docs",
+  "workflow-preferences": "guided-workflow-preferences",
+  "discuss-project": "guided-discuss-project",
+  "discuss-requirements": "guided-discuss-requirements",
+  "research-decision": "guided-research-decision",
+  "research-project": "guided-research-project",
+};
+
+const EXPECTED_UNDECLARED_PROMPT_TEMPLATE_TYPES = [
+  "discuss-milestone",
+  "discuss-slice",
+  "execute-task-simple",
+  "triage-captures",
+  "quick-task",
+];
+
 // ─── Derived-view parity ──────────────────────────────────────────────────
 
 test("KNOWN_UNIT_TYPES derives exactly the pre-registry list, in order", () => {
@@ -134,6 +168,28 @@ test("phaseChainForUnit matches the pre-registry switch for every known input",
   }
 });
 
+test("direct prompt-template associations live on the Unit Registry", () => {
+  for (const [unitType, promptTemplate] of Object.entries(EXPECTED_DIRECT_PROMPT_TEMPLATES)) {
+    assert.equal(
+      getUnitPromptTemplate(unitType),
+      promptTemplate,
+      `prompt template for ${unitType}`,
+    );
+    assert.ok(
+      existsSync(join(process.cwd(), "src/resources/extensions/gsd/prompts", `${promptTemplate}.md`)),
+      `prompt template file must exist for ${unitType}: ${promptTemplate}`,
+    );
+  }
+
+  for (const unitType of EXPECTED_UNDECLARED_PROMPT_TEMPLATE_TYPES) {
+    assert.equal(
+      getUnitPromptTemplate(unitType),
+      undefined,
+      `${unitType} prompt association is conditional or not verified yet`,
+    );
+  }
+});
+
 test("AUTO_UNIT_SCOPED_TOOLS mirrors each contract's allowed tools", () => {
   for (const [unitType, contract] of Object.entries(UNIT_TOOL_CONTRACTS)) {
     assert.deepEqual(AUTO_UNIT_SCOPED_TOOLS[unitType], contract.allowedGsdTools);

package/src/resources/extensions/gsd/tests/unit-runtime.test.ts

@@ -6,7 +6,9 @@ import {
   formatExecuteTaskRecoveryStatus,
   inspectExecuteTaskDurability,
   isInFlightRuntimePhase,
+  readUnitHarnessAbort,
   readUnitRuntimeRecord,
+  recordUnitHarnessAbort,
   writeUnitRuntimeRecord,
 } from "../unit-runtime.ts";
 import { closeDatabase, insertMilestone, insertSlice, insertTask, openDatabase } from "../gsd-db.ts";
@@ -41,6 +43,34 @@ console.log("\n=== runtime record write/read/update ===");
   assert.deepStrictEqual(loaded!.phase, "wrapup-warning-sent", "updated phase readable");
 }
 
+console.log("\n=== runtime harness abort preservation and explicit clear ===");
+{
+  const startedAt = 3000;
+  recordUnitHarnessAbort(base, "gate-evaluate", "M100/S02/gates+Q3", startedAt, {
+    kind: "tool-error",
+    reason: "Tool execution failed before the unit could complete its gate evaluation.",
+    toolName: "browser_click",
+  });
+
+  const preserved = writeUnitRuntimeRecord(base, "gate-evaluate", "M100/S02/gates+Q3", startedAt, {
+    phase: "wrapup-warning-sent",
+  });
+  assert.equal(preserved.harnessAbort?.kind, "tool-error", "ordinary same-run updates preserve harness abort");
+
+  const cleared = writeUnitRuntimeRecord(base, "gate-evaluate", "M100/S02/gates+Q3", startedAt, {
+    phase: "recovered",
+    harnessAbort: undefined,
+  });
+  assert.equal(cleared.harnessAbort, undefined, "explicit clear removes stale harness abort");
+  assert.equal(
+    readUnitHarnessAbort(base, "gate-evaluate", "M100/S02/gates+Q3", startedAt),
+    null,
+    "cleared harness abort no longer blocks result saves",
+  );
+
+  clearUnitRuntimeRecord(base, "gate-evaluate", "M100/S02/gates+Q3");
+}
+
 console.log("\n=== execute-task durability inspection ===");
 {
   let status = await inspectExecuteTaskDurability(base, "M100/S02/T09");

package/src/resources/extensions/gsd/tests/unmerged-milestone-guard.test.ts

@@ -53,6 +53,34 @@ test("findUnmergedCompletedMilestones blocks completed milestone branch product
   }
 });
 
+test("findUnmergedCompletedMilestones does not block after a --no-ff merge that diverges from the branch tip", async () => {
+  const base = makeTempRepo("gsd-unmerged-guard-");
+  try {
+    seedMilestone(base, "M011");
+    // Milestone branch adds a product file.
+    commitBranchFile(base, "milestone/M011", "index.html", "<h1>M011</h1>\n");
+
+    // Merge the branch into main with --no-ff, but resolve the file to main's
+    // (empty) side so the merge result diverges from the milestone branch tip.
+    // The branch is now an ancestor of main even though a raw diff is non-empty.
+    git(base, "merge", "--no-ff", "--no-commit", "milestone/M011");
+    writeFileSync(join(base, "index.html"), "<h1>main wins</h1>\n");
+    git(base, "add", "index.html");
+    git(base, "commit", "-m", "merge: take main side for index.html");
+
+    // Sanity: the diff between main and the branch tip is non-empty...
+    assert.notEqual(git(base, "diff", "--numstat", "main", "milestone/M011"), "");
+    // ...but the branch tip is an ancestor of main (merge is done).
+
+    const blockers = await findUnmergedCompletedMilestones(base);
+
+    assert.equal(blockers.length, 0);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("findUnmergedCompletedMilestones ignores projection-only branch diffs", async () => {
   const base = makeTempRepo("gsd-unmerged-guard-");
   try {
@@ -99,6 +127,31 @@ test("formatUnmergedMilestoneBlockMessage includes files, branch, and dirty over
   }
 });
 
+test("findUnmergedCompletedMilestones reports dirty overlap without content fingerprints", async () => {
+  const base = makeTempRepo("gsd-unmerged-guard-");
+  try {
+    const relPath = "build/output.bin";
+    const absPath = join(base, relPath);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, "main artifact\n");
+    git(base, "add", relPath);
+    git(base, "commit", "-m", "test: track build output fixture");
+
+    seedMilestone(base, "M012");
+    commitBranchFile(base, "milestone/M012", relPath, "milestone artifact\n");
+    writeFileSync(absPath, "dirty root artifact\n");
+
+    const [blocker] = await findUnmergedCompletedMilestones(base);
+    assert.ok(blocker);
+    assert.deepEqual(blocker.files, [relPath]);
+    assert.deepEqual(blocker.dirtyOverlap, [{ path: relPath, status: "M" }]);
+    assert.equal(Object.hasOwn(blocker.dirtyOverlap[0], "fingerprint"), false);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("isUnmergedMilestoneAllowedCommand permits inspection and explicit recovery commands", () => {
   assert.equal(isUnmergedMilestoneAllowedCommand(""), false);
   assert.equal(isUnmergedMilestoneAllowedCommand("auto"), false);
@@ -117,11 +170,17 @@ test("isUnmergedMilestoneAllowedCommand permits inspection and explicit recovery
   assert.equal(isUnmergedMilestoneAllowedCommand("queue"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("quick"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("config"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("progress"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("progress --forensic"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("parallel status"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("parallel watch"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("worktree list"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("dispatch complete"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("dispatch complete M008"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("dispatch complete-milestone"), true);
   assert.equal(isUnmergedMilestoneAllowedCommand("dispatch complete-milestone M008"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("docs-update --verify-only"), true);
+  assert.equal(isUnmergedMilestoneAllowedCommand("phase list"), true);
 });
 
 test("isUnmergedMilestoneAllowedCommand blocks direct dispatch aliases", () => {
@@ -134,9 +193,37 @@ test("isUnmergedMilestoneAllowedCommand blocks direct dispatch aliases", () => {
     "complete-slice",
     "validate-milestone",
     "complete-milestone",
+    "docs-update",
+    "review-backlog",
+    "import",
+    "ingest-docs",
+    "secure-phase",
+    "plan-review-convergence",
+    "resume-work",
+    "progress --next",
+    'progress --do "fix the login bug"',
+    "parallel start",
+    "parallel resume",
+    "parallel merge",
+    "parallel pause",
   ];
 
   for (const alias of aliases) {
     assert.equal(isUnmergedMilestoneAllowedCommand(alias), false, alias);
   }
 });
+
+test("isUnmergedMilestoneAllowedCommand blocks mutating phase subcommands", () => {
+  const commands = [
+    "phase add M009",
+    "phase create M009",
+    "phase new M009",
+    "phase insert M009 after M008",
+    "phase remove M008",
+    "phase edit M008",
+  ];
+
+  for (const command of commands) {
+    assert.equal(isUnmergedMilestoneAllowedCommand(command), false, command);
+  }
+});

package/src/resources/extensions/gsd/tests/uok-gitops-turn-action.test.ts

@@ -3,11 +3,22 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "../git-constants.ts";
 import { handleTurnGitActionError, runTurnGitAction } from "../git-service.ts";
+import { _resetLogs, drainLogs } from "../workflow-logger.ts";
 
 function run(cmd: string, cwd: string): string {
   return execSync(cmd, { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
@@ -101,6 +112,43 @@ workspace:
   }
 });
 
+test("uok gitops turn action status-only reports dirty undeclared nested git repositories", () => {
+  const root = mkdtempSync(join(tmpdir(), "gsd-uok-gitops-nested-"));
+  try {
+    initRepo(root);
+    mkdirSync(join(root, "nested"), { recursive: true });
+    initRepo(join(root, "nested"));
+    writeFileSync(join(root, ".gitignore"), "nested/\n", "utf-8");
+    run("git add .gitignore", root);
+    run('git commit -m "chore: ignore nested repo"', root);
+
+    writeFileSync(join(root, "nested", "README.md"), "# Dirty nested\n", "utf-8");
+
+    _resetLogs();
+    const result = runTurnGitAction({
+      basePath: root,
+      action: "status-only",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    const warnings = drainLogs();
+
+    assert.equal(result.status, "ok");
+    assert.equal(result.dirty, true);
+    assert.deepEqual(result.dirtyRepositories, {
+      project: false,
+      "nested (undeclared)": true,
+    });
+    assert.ok(
+      warnings.some((entry) => entry.message.includes("undeclared dirty nested git repo nested")),
+      "dirty undeclared nested repo should be logged as a warning",
+    );
+  } finally {
+    _resetLogs();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("uok gitops turn action snapshot writes snapshot refs", () => {
   const repo = makeRepo();
   try {
@@ -138,6 +186,119 @@ test("uok gitops turn action commit creates commit with unit trailer", () => {
   }
 });
 
+test("uok gitops turn action commit defaults to child repositories in parent mode", () => {
+  const root = mkdtempSync(join(tmpdir(), "gsd-uok-gitops-parent-commit-"));
+  try {
+    initRepo(root);
+    mkdirSync(join(root, ".gsd"), { recursive: true });
+    mkdirSync(join(root, "frontend"), { recursive: true });
+    mkdirSync(join(root, "backend"), { recursive: true });
+    initRepo(join(root, "frontend"));
+    initRepo(join(root, "backend"));
+    writeFileSync(join(root, ".gitignore"), "frontend/\nbackend/\n", "utf-8");
+    run("git add .gitignore", root);
+    run('git commit -m "chore: ignore nested repos"', root);
+    writeFileSync(join(root, ".gsd", "PREFERENCES.md"), `---
+version: 1
+workspace:
+  mode: parent
+  repositories:
+    frontend:
+      path: frontend
+    backend:
+      path: backend
+---
+`, "utf-8");
+    run("git add .gsd/PREFERENCES.md", root);
+    run('git commit -m "chore: configure parent workspace repos"', root);
+
+    const rootHeadBefore = run("git rev-parse HEAD", root);
+    writeFileSync(join(root, "frontend", "README.md"), "# frontend dirty\n", "utf-8");
+    writeFileSync(join(root, "backend", "README.md"), "# backend dirty\n", "utf-8");
+
+    const result = runTurnGitAction({
+      basePath: root,
+      action: "commit",
+      unitType: "execute-task",
+      unitId: "M001/S01/T-parent",
+    });
+
+    assert.equal(result.status, "ok");
+    assert.equal(result.commitMessages?.project, undefined);
+    assert.equal(typeof result.commitMessages?.frontend, "string");
+    assert.equal(typeof result.commitMessages?.backend, "string");
+    assert.equal(result.commitMessage, result.commitMessages?.frontend);
+    assert.equal(run("git rev-parse HEAD", root), rootHeadBefore);
+    assert.equal(run("git status --porcelain", join(root, "frontend")), "");
+    assert.equal(run("git status --porcelain", join(root, "backend")), "");
+    assert.ok(run("git log -1 --pretty=%B", join(root, "frontend")).includes("GSD-Unit: M001/S01/T-parent"));
+    assert.ok(run("git log -1 --pretty=%B", join(root, "backend")).includes("GSD-Unit: M001/S01/T-parent"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("uok gitops turn action commit reuses the collected dirty status", () => {
+  const repo = makeRepo();
+  const wrapperDir = mkdtempSync(join(tmpdir(), "gsd-uok-git-wrapper-"));
+  const logPath = join(wrapperDir, "git.log");
+  const wrapperPath = join(wrapperDir, "git");
+  const realGit = execSync("command -v git", { encoding: "utf-8" }).trim();
+  const gitEnv = GIT_NO_PROMPT_ENV as NodeJS.ProcessEnv;
+  const previousPath = gitEnv.PATH;
+  const previousRealGit = gitEnv.GSD_TEST_REAL_GIT;
+  const previousLogPath = gitEnv.GSD_TEST_GIT_LOG;
+
+  writeFileSync(wrapperPath, [
+    "#!/bin/sh",
+    "printf '%s\\n' \"$*\" >> \"$GSD_TEST_GIT_LOG\"",
+    "exec \"$GSD_TEST_REAL_GIT\" \"$@\"",
+    "",
+  ].join("\n"), "utf-8");
+  chmodSync(wrapperPath, 0o755);
+
+  try {
+    gitEnv.PATH = `${wrapperDir}:${previousPath ?? ""}`;
+    gitEnv.GSD_TEST_REAL_GIT = realGit;
+    gitEnv.GSD_TEST_GIT_LOG = logPath;
+
+    writeFileSync(join(repo, "feature.ts"), "export const x = 1;\n", "utf-8");
+    const result = runTurnGitAction({
+      basePath: repo,
+      action: "commit",
+      unitType: "execute-task",
+      unitId: "M001/S01/T-status",
+    });
+
+    assert.equal(result.status, "ok");
+    const invocations = readFileSync(logPath, "utf-8").trim().split("\n");
+    assert.equal(
+      invocations.filter((line) => line === "status --porcelain").length,
+      1,
+      "turn status is collected once",
+    );
+    assert.equal(
+      invocations.includes("status --short"),
+      false,
+      "autoCommit should not re-read working-tree status when turn status is known",
+    );
+  } finally {
+    gitEnv.PATH = previousPath;
+    if (previousRealGit === undefined) {
+      delete gitEnv.GSD_TEST_REAL_GIT;
+    } else {
+      gitEnv.GSD_TEST_REAL_GIT = previousRealGit;
+    }
+    if (previousLogPath === undefined) {
+      delete gitEnv.GSD_TEST_GIT_LOG;
+    } else {
+      gitEnv.GSD_TEST_GIT_LOG = previousLogPath;
+    }
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(wrapperDir, { recursive: true, force: true });
+  }
+});
+
 test("uok gitops turn action commits the active external-state worktree", () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-uok-gitops-project-"));
   const externalState = mkdtempSync(join(tmpdir(), "gsd-uok-gitops-state-"));

package/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts

@@ -15,7 +15,12 @@ import { clearParseCache } from "../files.js";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-val-handler-${randomUUID()}`);
-  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  const mDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(mDir, { recursive: true });
+  // A content-bearing legacy milestone dir requires at least one non-META file
+  // (dirIsContentBearingLegacyMilestone) so the layout sniffer treats it as a
+  // real legacy milestone rather than a metadata-only placeholder.
+  writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001\n");
   return base;
 }
 
@@ -101,6 +106,9 @@ describe("handleValidateMilestone write ordering (#2725)", () => {
     const milestoneDir = join(base, ".gsd", "milestones", "M001");
     rmSync(milestoneDir, { recursive: true, force: true });
     writeFileSync(milestoneDir, "not-a-directory");
+    // Also block the flat-phase fallback path: write a regular file named
+    // "phases" so mkdir("phases/01-m001", {recursive:true}) throws ENOTDIR.
+    writeFileSync(join(base, ".gsd", "phases"), "not-a-directory");
 
     const result = await handleValidateMilestone(VALID_PARAMS, base);
 

package/src/resources/extensions/gsd/tests/validation-block-guard.test.ts

@@ -3,13 +3,28 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const _require = createRequire(import.meta.url);
 
 import {
   formatValidationBlockedMessage,
+  getValidationBlockMessageForBase,
   isValidationBlockAllowedCommand,
   isValidationBlockedState,
 } from "../validation-block-guard.ts";
+import {
+  _getAdapter,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  openDatabase,
+} from "../gsd-db.ts";
+import { invalidateStateCache } from "../state.ts";
 import type { GSDState } from "../types.ts";
+import { cleanup, makeTempDir } from "./test-utils.ts";
 
 function blockedState(): GSDState {
   return {
@@ -38,6 +53,24 @@ function blockedState(): GSDState {
   };
 }
 
+function makeBase(): string {
+  const base = makeTempDir("gsd-validation-block-");
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function openRawSqliteForTest(dbPath: string): { exec(sql: string): void; close(): void } {
+  try {
+    const mod = _require("node:sqlite") as { DatabaseSync: new (path: string) => { exec(sql: string): void; close(): void } };
+    return new mod.DatabaseSync(dbPath);
+  } catch {
+    type SqliteCtor = new (path: string) => { exec(sql: string): void; close(): void };
+    const mod = _require("better-sqlite3") as SqliteCtor | { default: SqliteCtor };
+    const DatabaseCtor: SqliteCtor = typeof mod === "function" ? mod : mod.default;
+    return new DatabaseCtor(dbPath);
+  }
+}
+
 test("validation block detection only matches validation blockers", () => {
   assert.equal(isValidationBlockedState(blockedState()), true);
   assert.equal(isValidationBlockedState({
@@ -80,6 +113,19 @@ test("validation block allows recovery, diagnostics, and unrelated commands", ()
     "parallel stop M007",
     "parallel pause M007",
     "parallel watch",
+    "progress",
+    "progress --forensic",
+    // code-review is allowed when not applying fixes
+    "code-review",
+    "code-review --depth deep",
+    // audit-fix is allowed in dry-run mode (read-only review, no commits)
+    "audit-fix --dry-run",
+    // docs-update is allowed in verify-only mode (read-only check, no writes)
+    "docs-update --verify-only",
+    // phase read-only subcommands are fine while validation-blocked
+    "phase",
+    "phase list",
+    "phase status",
   ];
 
   for (const command of allowed) {
@@ -95,7 +141,19 @@ test("validation block rejects workflow-start and advancing commands", () => {
     "next",
     "next M006",
     "do mark all complete",
+    "progress --next",
+    'progress --do "mark all complete"',
     "start bugfix",
+    "plan-phase",
+    "execute-phase --milestone M009",
+    "autonomous --from 1",
+    "spec-phase M009",
+    "mvp-phase --milestone M009",
+    "ui-phase M009",
+    "ai-integration-phase M009",
+    "ultraplan-phase M009",
+    "plan-review-convergence M009",
+    "resume-work",
     "workflow resume",
     "workflow run release-checklist",
     "workflow release-checklist",
@@ -107,6 +165,32 @@ test("validation block rejects workflow-start and advancing commands", () => {
     "dispatch uat",
     "complete-milestone",
     "ship",
+    // code-review --fix applies changes and should be blocked
+    "code-review --fix",
+    "code-review --depth deep --fix",
+    // audit-fix without --dry-run applies fixes and commits
+    "audit-fix",
+    "audit-fix --verbose",
+    // mutating workflow-advancing commands added in v2
+    "discuss-phase",
+    "discuss-phase M006",
+    "import",
+    "import milestones.json",
+    "ingest-docs",
+    "ingest-docs --path docs/",
+    "review-backlog",
+    "secure-phase",
+    "secure-phase --milestone M006",
+    // docs-update without --verify-only applies writes
+    "docs-update",
+    "docs-update --milestone M006",
+    // phase mutating subcommands change milestone queue state and must be blocked
+    "phase add M009",
+    "phase create M009",
+    "phase new",
+    "phase insert M009 after M008",
+    "phase remove M008",
+    "phase edit M008",
   ];
 
   for (const command of blocked) {
@@ -143,3 +227,49 @@ test("validation block message can guide remediation through dispatch reassess",
   assert.match(message, /\/gsd dispatch reassess/);
   assert.doesNotMatch(message, /gsd_reassess_roadmap/);
 });
+
+test("validation block guard refreshes from disk and sees external validation blocks", async () => {
+  const base = makeBase();
+  const dbPath = join(base, ".gsd", "gsd.db");
+  const validationPath = join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+  try {
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001", title: "Active Milestone", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Done Slice",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    invalidateStateCache();
+
+    const adapterBefore = _getAdapter();
+    assert.ok(adapterBefore);
+
+    const externalDb = openRawSqliteForTest(dbPath);
+    try {
+      externalDb.exec(`
+        INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+        VALUES (
+          '${validationPath.replace(/'/g, "''")}',
+          'M001', NULL, NULL, 'needs-attention', 'milestone-validation',
+          '---\nverdict: needs-attention\n---', datetime('now')
+        )
+      `);
+    } finally {
+      externalDb.close();
+    }
+
+    const message = await getValidationBlockMessageForBase(base, "next");
+
+    assert.ok(message);
+    assert.match(message, /cannot run because the active milestone is blocked by validation/);
+    assert.notEqual(_getAdapter(), adapterBefore, "guard must refresh stale database handle");
+  } finally {
+    closeDatabase();
+    invalidateStateCache();
+    cleanup(base);
+  }
+});