gsd-pi 2.71.0-dev.e17e0ce → 2.72.0-dev.de4c4b3

package/src/resources/extensions/gsd/gsd-db.ts

@@ -10,6 +10,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
+import { getGateIdsForTurn, type OwnerTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 
 const _require = createRequire(import.meta.url);
@@ -2302,3 +2303,53 @@ export function getPendingSliceGateCount(milestoneId: string, sliceId: string):
   ).get({ ":mid": milestoneId, ":sid": sliceId });
   return row ? (row["cnt"] as number) : 0;
 }
+
+/**
+ * Return pending gate rows owned by a specific workflow turn.
+ *
+ * Unlike `getPendingGates(..., scope)`, this filters by the registry's
+ * `ownerTurn` metadata so callers can distinguish Q3/Q4 (owned by
+ * gate-evaluate) from Q8 (owned by complete-slice) even though both are
+ * scope:"slice". Pass `taskId` to narrow task-scoped results to one task.
+ */
+export function getPendingGatesForTurn(
+  milestoneId: string,
+  sliceId: string,
+  turn: OwnerTurn,
+  taskId?: string,
+): GateRow[] {
+  if (!currentDb) return [];
+  const ids = getGateIdsForTurn(turn);
+  if (ids.size === 0) return [];
+  const idList = [...ids];
+  const placeholders = idList.map((_, i) => `:gid${i}`).join(",");
+  const params: Record<string, unknown> = {
+    ":mid": milestoneId,
+    ":sid": sliceId,
+  };
+  idList.forEach((id, i) => {
+    params[`:gid${i}`] = id;
+  });
+  let sql =
+    `SELECT * FROM quality_gates
+     WHERE milestone_id = :mid AND slice_id = :sid
+       AND status = 'pending'
+       AND gate_id IN (${placeholders})`;
+  if (taskId !== undefined) {
+    sql += ` AND task_id = :tid`;
+    params[":tid"] = taskId;
+  }
+  return currentDb.prepare(sql).all(params).map(rowToGate);
+}
+
+/**
+ * Count pending gates for a turn. Convenience wrapper used by state
+ * derivation to decide whether a phase transition should pause.
+ */
+export function getPendingGateCountForTurn(
+  milestoneId: string,
+  sliceId: string,
+  turn: OwnerTurn,
+): number {
+  return getPendingGatesForTurn(milestoneId, sliceId, turn).length;
+}

package/src/resources/extensions/gsd/milestone-validation-gates.ts

@@ -6,19 +6,13 @@
  * records in the DB. This module inserts milestone-level validation gates
  * that correspond to the validation checks performed.
  *
- * Gate IDs for milestone validation:
- *   MV01 — Success criteria checklist
- *   MV02 — Slice delivery audit
- *   MV03 — Cross-slice integration
- *   MV04 — Requirement coverage
- *
- * These use the existing quality_gates table with scope "milestone".
+ * Gate IDs for milestone validation (MV01–MV04) are sourced from the
+ * gate registry so the definitions stay in lockstep with prompt builders,
+ * dispatch rules, and state derivation. See gate-registry.ts.
  */
 
 import { _getAdapter } from "./gsd-db.js";
-
-/** Milestone validation gate IDs. */
-const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"] as const;
+import { getGatesForTurn } from "./gate-registry.js";
 
 /**
  * Insert milestone-level quality_gates records for a validation run.
@@ -27,6 +21,9 @@ const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"] as const;
  * from the overall milestone validation verdict. Individual gate-level
  * verdicts are not available (the handler receives a single verdict),
  * so all gates share the overall verdict.
+ *
+ * Gate IDs come from the registry — adding/removing an MV-scoped gate
+ * in gate-registry.ts automatically flows through here.
  */
 export function insertMilestoneValidationGates(
   milestoneId: string,
@@ -38,8 +35,9 @@ export function insertMilestoneValidationGates(
   if (!db) return;
 
   const gateVerdict = verdict === "pass" ? "pass" : "flag";
+  const milestoneGates = getGatesForTurn("validate-milestone");
 
-  for (const gateId of MILESTONE_GATE_IDS) {
+  for (const def of milestoneGates) {
     db.prepare(
       `INSERT OR REPLACE INTO quality_gates
        (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
@@ -47,9 +45,9 @@ export function insertMilestoneValidationGates(
     ).run({
       ":mid": milestoneId,
       ":sid": sliceId,
-      ":gid": gateId,
+      ":gid": def.id,
       ":verdict": gateVerdict,
-      ":rationale": `Milestone validation verdict: ${verdict}`,
+      ":rationale": `${def.promptSection} — milestone validation verdict: ${verdict}`,
       ":evaluated_at": evaluatedAt,
     });
   }

package/src/resources/extensions/gsd/notification-overlay.ts

@@ -9,6 +9,7 @@ import {
   readNotifications,
   markAllRead,
   clearNotifications,
+  onNotificationStoreChange,
   type NotificationEntry,
   type NotifySeverity,
 } from "./notification-store.js";
@@ -82,6 +83,7 @@ export class GSDNotificationOverlay {
   private refreshTimer: ReturnType<typeof setInterval>;
   private disposed = false;
   private resizeHandler: (() => void) | null = null;
+  private unsubscribeStore: (() => void) | null = null;
 
   constructor(
     tui: { requestRender: () => void },
@@ -105,19 +107,17 @@ export class GSDNotificationOverlay {
     };
     process.stdout.on("resize", this.resizeHandler);
 
-    // Refresh every 3s for new notifications
+    // Subscribe to store mutations for immediate updates
+    this.unsubscribeStore = onNotificationStoreChange(() => {
+      if (this.disposed) return;
+      this._refreshFromDisk();
+    });
+
+    // 30s safety-net for cross-process edits (web subprocess, parallel workers)
     this.refreshTimer = setInterval(() => {
       if (this.disposed) return;
-      const fresh = readNotifications();
-      const signature = notificationSignature(fresh);
-      if (signature !== this.entriesSignature) {
-        markAllRead();
-        this.entries = readNotifications();
-        this.entriesSignature = notificationSignature(this.entries);
-        this.invalidate();
-        this.tui.requestRender();
-      }
-    }, 3000);
+      this._refreshFromDisk();
+    }, 30_000);
   }
 
   private get filter(): FilterMode {
@@ -215,12 +215,28 @@ export class GSDNotificationOverlay {
   dispose(): void {
     this.disposed = true;
     clearInterval(this.refreshTimer);
+    if (this.unsubscribeStore) {
+      this.unsubscribeStore();
+      this.unsubscribeStore = null;
+    }
     if (this.resizeHandler) {
       process.stdout.removeListener("resize", this.resizeHandler);
       this.resizeHandler = null;
     }
   }
 
+  private _refreshFromDisk(): void {
+    const fresh = readNotifications();
+    const signature = notificationSignature(fresh);
+    if (signature !== this.entriesSignature) {
+      markAllRead();
+      this.entries = readNotifications();
+      this.entriesSignature = notificationSignature(this.entries);
+      this.invalidate();
+      this.tui.requestRender();
+    }
+  }
+
   private wrapInBox(inner: string[], width: number): string[] {
     const th = this.theme;
     const border = (s: string) => th.fg("borderAccent", s);

package/src/resources/extensions/gsd/notification-store.ts

@@ -323,10 +323,11 @@ function _withLock<T>(basePath: string, fn: () => T): T {
     }
   }
 
-  // Only run the mutation if we actually own the lock
-  const ownsLock = fd !== null;
+  // Best-effort: mutation runs regardless of lock status (idempotent overwrites).
+  // createdLock gates cleanup only — never skip fn() on lock failure.
+  const createdLock = fd !== null;
   try {
-    if (ownsLock && fd !== null) {
+    if (createdLock && fd !== null) {
       // Write our PID timestamp into the lock for stale detection
       writeFileSync(lockPath, String(Date.now()), "utf-8");
       closeSync(fd);
@@ -334,7 +335,7 @@ function _withLock<T>(basePath: string, fn: () => T): T {
     return fn();
   } finally {
     // Only delete the lock if we created it — never remove another process's lock
-    if (ownsLock) {
+    if (createdLock) {
       try { unlinkSync(lockPath); } catch { /* best-effort cleanup */ }
     }
   }

package/src/resources/extensions/gsd/prompt-validation.ts

@@ -0,0 +1,157 @@
+/**
+ * GSD Prompt Validation — Validates enhanced context and turn output
+ * artifacts before writing.
+ *
+ * Implements R109 validation requirement: CONTEXT.md must have required
+ * sections before being written to disk. Additionally, per-turn validators
+ * check that artifacts produced by gate-owning turns contain the gate
+ * sections declared in gate-registry.ts, so a malformed summary/validation
+ * markdown file cannot silently drop a quality gate.
+ */
+
+import { getGatesForTurn, type OwnerTurn } from "./gate-registry.js";
+
+/**
+ * Result of validating enhanced context output.
+ */
+export interface ValidationResult {
+  /** Whether all required sections are present. */
+  valid: boolean;
+  /** List of missing required sections. */
+  missing: string[];
+}
+
+/**
+ * Validate that enhanced context content has all required sections.
+ *
+ * Required sections per R109:
+ * - Scope section (## Scope, ## Milestone Scope, or ## Why This Milestone)
+ * - Architectural Decisions section (## Architectural Decisions)
+ * - Acceptance Criteria section (## Acceptance Criteria or ## Final Integrated Acceptance)
+ *
+ * Additionally validates that the Architectural Decisions section contains
+ * at least one decision entry (### heading or **Decision marker).
+ *
+ * @param content - The enhanced context markdown content
+ * @returns ValidationResult with valid flag and list of missing sections
+ */
+export function validateEnhancedContext(content: string): ValidationResult {
+  const missing: string[] = [];
+
+  // Required section 1: Scope (multiple acceptable header variants)
+  const hasScopeSection =
+    /^## Scope\b/m.test(content) ||
+    /^## Milestone Scope\b/m.test(content) ||
+    /^## Why This Milestone\b/m.test(content);
+
+  if (!hasScopeSection) {
+    missing.push("Milestone Scope or Why This Milestone");
+  }
+
+  // Required section 2: Architectural Decisions
+  const hasArchitecturalDecisions = /^## Architectural Decisions\b/m.test(content);
+  if (!hasArchitecturalDecisions) {
+    missing.push("Architectural Decisions");
+  }
+
+  // Required section 3: Acceptance Criteria (multiple acceptable header variants)
+  const hasAcceptanceCriteria =
+    /^## Acceptance Criteria\b/m.test(content) ||
+    /^## Final Integrated Acceptance\b/m.test(content);
+
+  if (!hasAcceptanceCriteria) {
+    missing.push("Acceptance Criteria");
+  }
+
+  // Additional validation: Architectural Decisions must have at least one entry
+  if (hasArchitecturalDecisions) {
+    // Extract the section content between ## Architectural Decisions and the next ## heading.
+    // Uses indexOf-based extraction instead of regex with \z (which is invalid in JavaScript
+    // regex — it's PCRE/Ruby syntax and JS treats it as literal 'z').
+    const sectionStart = content.indexOf("## Architectural Decisions");
+    if (sectionStart === -1) {
+      missing.push("Architectural Decisions");
+    } else {
+      const afterHeading = content.slice(sectionStart + "## Architectural Decisions".length);
+      const nextSection = afterHeading.search(/^## /m);
+      const sectionContent = nextSection === -1 ? afterHeading : afterHeading.slice(0, nextSection);
+
+      // Check for actual decision entries:
+      // - ### heading (subsection per decision)
+      // - **Decision marker (inline decision format)
+      const hasDecisionEntry = /^### /m.test(sectionContent) || /^\*\*Decision/m.test(sectionContent);
+
+      if (!hasDecisionEntry) {
+        missing.push("At least one architectural decision entry");
+      }
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+// ─── Per-Turn Gate Section Validators ─────────────────────────────────────
+//
+// Each validator checks that the artifact written by a turn contains a
+// heading for every gate owned by that turn. The registry is the source
+// of truth for which sections must exist; adding a new gate automatically
+// flows through via `getGatesForTurn(turn)`.
+
+/**
+ * Escape a string so it can be embedded safely inside a regular expression.
+ */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Validate that an artifact contains an `## H2` heading for every gate the
+ * named turn owns. Returns the list of missing gate section headers.
+ *
+ * Soft rule: a section counts as "present" if it is declared (H2 heading
+ * exists) — empty-body sections are allowed and handled by the tool
+ * handler, which will record such gates as `omitted`.
+ */
+export function validateGateSections(
+  content: string,
+  turn: OwnerTurn,
+): ValidationResult {
+  const missing: string[] = [];
+  for (const def of getGatesForTurn(turn)) {
+    const pattern = new RegExp(`^##\\s+${escapeRegExp(def.promptSection)}\\b`, "m");
+    if (!pattern.test(content)) {
+      missing.push(`${def.id} (## ${def.promptSection})`);
+    }
+  }
+  return { valid: missing.length === 0, missing };
+}
+
+/**
+ * Validate a SUMMARY.md produced by the complete-slice turn. Requires
+ * an H2 heading for every gate owned by complete-slice (e.g. Q8 →
+ * "## Operational Readiness"). Intended for use in the tool handler's
+ * pre-write checks or in the post-unit validation sweep.
+ */
+export function validateSliceSummaryOutput(content: string): ValidationResult {
+  return validateGateSections(content, "complete-slice");
+}
+
+/**
+ * Validate a task SUMMARY.md produced by the execute-task turn. Only
+ * flags gates that are still pending for the task; skips the check
+ * when no rows are seeded (simple task).
+ */
+export function validateTaskSummaryOutput(content: string): ValidationResult {
+  return validateGateSections(content, "execute-task");
+}
+
+/**
+ * Validate a VALIDATION.md produced by the validate-milestone turn.
+ * Requires an H2 heading for every MV gate declared in the registry.
+ */
+export function validateMilestoneValidationOutput(content: string): ValidationResult {
+  return validateGateSections(content, "validate-milestone");
+}

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -16,6 +16,8 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 {{inlinedContext}}
 
+{{gatesToClose}}
+
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
 Then:
@@ -23,7 +25,7 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first. Task artifacts use a **flat file layout** directly inside `tasks/` (for example `T01-SUMMARY.md`, `T02-SUMMARY.md`) rather than per-task subdirectories. If you need to count or re-read task summaries during verification, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never use `tasks/*/SUMMARY.md` — that glob expects subdirectories that do not exist.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
+5. Address every gate listed in the **Gates to Close** section above — each gate maps to a specific slice-summary section the handler inspects (for example, Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, and monitoring gaps). Leaving a section empty records the gate as `omitted`.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
 8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -22,6 +22,8 @@ A researcher explored the codebase and a planner decomposed the work — you are
 
 {{slicePlanExcerpt}}
 
+{{gatesToClose}}
+
 ## Backing Source Artifacts
 - Slice plan: `{{planPath}}`
 - Task plan source: `{{taskPlanPath}}`

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -18,6 +18,8 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 {{inlinedContext}}
 
+{{gatesToEvaluate}}
+
 ## Execution Protocol
 
 ### Step 1 — Dispatch Parallel Reviewers

package/src/resources/extensions/gsd/shortcut-defs.ts

@@ -8,6 +8,8 @@ type GSDShortcutDef = {
   key: "g" | "n" | "p";
   action: string;
   command: string;
+  /** Whether the Ctrl+Shift fallback is registered (false when it conflicts with an app keybinding). */
+  hasFallback: boolean;
 };
 
 export const GSD_SHORTCUTS: Record<GSDShortcutId, GSDShortcutDef> = {
@@ -15,16 +17,19 @@ export const GSD_SHORTCUTS: Record<GSDShortcutId, GSDShortcutDef> = {
     key: "g",
     action: "Open GSD dashboard",
     command: "/gsd status",
+    hasFallback: true,
   },
   notifications: {
     key: "n",
     action: "Open notification history",
     command: "/gsd notifications",
+    hasFallback: true,
   },
   parallel: {
     key: "p",
     action: "Open parallel worker monitor",
     command: "/gsd parallel watch",
+    hasFallback: false, // Ctrl+Shift+P conflicts with cycleModelBackward
   },
 };
 
@@ -41,7 +46,9 @@ export function fallbackShortcutCombo(id: GSDShortcutId): string {
 }
 
 export function shortcutPair(id: GSDShortcutId, formatter: (combo: string) => string = (combo) => combo): string {
-  return `${formatter(primaryShortcutCombo(id))} / ${formatter(fallbackShortcutCombo(id))}`;
+  const primary = formatter(primaryShortcutCombo(id));
+  if (!GSD_SHORTCUTS[id].hasFallback) return primary;
+  return `${primary} / ${formatter(fallbackShortcutCombo(id))}`;
 }
 
 export function formattedShortcutPair(id: GSDShortcutId): string {

package/src/resources/extensions/gsd/state.ts

@@ -58,7 +58,7 @@ import {
   insertSlice,
   insertTask,
   updateTaskStatus,
-  getPendingSliceGateCount,
+  getPendingGateCountForTurn,
   type MilestoneRow,
   type SliceRow,
   type TaskRow,
@@ -864,7 +864,18 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     }
   }
 
-  const pendingGateCount = getPendingSliceGateCount(activeMilestone.id, activeSlice.id);
+  // ── Quality gate evaluation check ──────────────────────────────────
+  // Pause before execution only when gates owned by the `gate-evaluate`
+  // turn (Q3/Q4) are still pending. Q8 is also `scope:"slice"` but is
+  // owned by `complete-slice`, so it must NOT block the evaluating-gates
+  // phase — otherwise auto-loop stalls forever waiting for a gate that
+  // this turn never evaluates. See gate-registry.ts for the ownership map.
+  // Slices with zero gate rows (pre-feature or simple) skip straight through.
+  const pendingGateCount = getPendingGateCountForTurn(
+    activeMilestone.id,
+    activeSlice.id,
+    "gate-evaluate",
+  );
   if (pendingGateCount > 0) {
     return {
       activeMilestone, activeSlice, activeTask: null,

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

@@ -48,3 +48,17 @@ test("bootstrapAutoSession checks manual session override before preferences", (
     "manual override and preference fallback must be resolved before building startModelSnapshot",
   );
 });
+
+test("bootstrapAutoSession validates preferred model against live registry auth (#unconfigured-models)", () => {
+  // The raw PREFERENCES.md value must be validated against getAvailable()
+  // before being captured as the snapshot, so an unconfigured provider
+  // (no API key / OAuth) can't become autoModeStartModel.
+  const validationIdx = source.indexOf("ctx.modelRegistry.getAvailable()");
+  assert.ok(validationIdx > -1, "auto-start.ts should validate preferred model against getAvailable()");
+
+  const resolveModelIdIdx = source.indexOf("resolveModelId");
+  assert.ok(resolveModelIdIdx > -1, "auto-start.ts should resolve preferred model against the registry");
+
+  const warningIdx = source.indexOf("is not configured; falling back to session default");
+  assert.ok(warningIdx > -1, "auto-start.ts should warn when preferred model is unconfigured");
+});

package/src/resources/extensions/gsd/tests/complete-slice-gate-closure.test.ts

@@ -0,0 +1,167 @@
+/**
+ * complete-slice gate closure integration test.
+ *
+ * Pins the fix for the Q8-stall bug: complete-slice must close every gate
+ * owned by the complete-slice turn based on the content of the matching
+ * CompleteSliceParams field. Without this, Q8 stays pending forever and
+ * blocks state derivation on subsequent loops.
+ */
+
+import { describe, test, beforeEach, afterEach } 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 {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  insertGateRow,
+  getGateResults,
+} from "../gsd-db.ts";
+import { handleCompleteSlice } from "../tools/complete-slice.ts";
+import type { CompleteSliceParams } from "../types.ts";
+
+function makeValidSliceParams(overrides: Partial<CompleteSliceParams> = {}): CompleteSliceParams {
+  return {
+    sliceId: "S01",
+    milestoneId: "M001",
+    sliceTitle: "Test Slice",
+    oneLiner: "Implemented test slice",
+    narrative: "Built and tested.",
+    verification: "All tests pass.",
+    deviations: "None.",
+    knownLimitations: "None.",
+    followUps: "None.",
+    keyFiles: ["src/foo.ts"],
+    keyDecisions: [],
+    patternsEstablished: [],
+    observabilitySurfaces: [],
+    provides: [],
+    requirementsSurfaced: [],
+    drillDownPaths: [],
+    affects: [],
+    requirementsAdvanced: [],
+    requirementsValidated: [],
+    requirementsInvalidated: [],
+    filesModified: [],
+    requires: [],
+    uatContent: "## Smoke Test\n\nVerify happy path.",
+    ...overrides,
+  };
+}
+
+describe("complete-slice closes complete-slice-owned gates", () => {
+  let dbPath: string;
+  let basePath: string;
+
+  beforeEach(() => {
+    dbPath = path.join(
+      fs.mkdtempSync(path.join(os.tmpdir(), "gsd-slice-gate-")),
+      "test.db",
+    );
+    openDatabase(dbPath);
+
+    basePath = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-slice-gate-handler-"));
+    const sliceDir = path.join(
+      basePath, ".gsd", "milestones", "M001", "slices", "S01", "tasks",
+    );
+    fs.mkdirSync(sliceDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(basePath, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Test Milestone",
+        "",
+        "## Slices",
+        "",
+        '- [ ] **S01: Test Slice** `risk:medium` `depends:[]`',
+        "  - After this: basic functionality works",
+      ].join("\n"),
+    );
+
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+    insertTask({
+      id: "T01", sliceId: "S01", milestoneId: "M001",
+      status: "complete", title: "Task 1",
+    });
+
+    // Seed Q8 as pending — this is what plan-slice does today.
+    insertGateRow({
+      milestoneId: "M001", sliceId: "S01",
+      gateId: "Q8", scope: "slice",
+    });
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    fs.rmSync(path.dirname(dbPath), { recursive: true, force: true });
+    fs.rmSync(basePath, { recursive: true, force: true });
+  });
+
+  test("Q8 closes as 'pass' when operationalReadiness is populated", async () => {
+    const params = makeValidSliceParams({
+      operationalReadiness: [
+        "- Health signal: /health endpoint returns 200",
+        "- Failure signal: error rate alert in observability dashboard",
+        "- Recovery: systemd auto-restart",
+      ].join("\n"),
+    });
+
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8, "Q8 row must exist after complete-slice");
+    assert.equal(q8.status, "complete");
+    assert.equal(q8.verdict, "pass");
+    assert.ok(
+      q8.findings.includes("Health signal"),
+      "Q8 findings must capture the operationalReadiness content",
+    );
+  });
+
+  test("Q8 closes as 'omitted' when operationalReadiness is empty", async () => {
+    const params = makeValidSliceParams({ operationalReadiness: "" });
+
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8, "Q8 row must exist after complete-slice");
+    assert.equal(q8.status, "complete");
+    assert.equal(q8.verdict, "omitted");
+  });
+
+  test("Q8 also closes when operationalReadiness is omitted entirely", async () => {
+    // A model that doesn't pass operationalReadiness at all must still
+    // move Q8 out of 'pending' — leaving it pending produces the stall.
+    const params = makeValidSliceParams();
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8);
+    assert.notEqual(q8.status, "pending", "Q8 must never remain pending after complete-slice");
+    assert.equal(q8.verdict, "omitted");
+  });
+
+  test("summary markdown contains Operational Readiness section", async () => {
+    const params = makeValidSliceParams({
+      operationalReadiness: "- Health signal: /health\n- Failure signal: alert",
+    });
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result));
+    if (!("error" in result)) {
+      const summary = fs.readFileSync(result.summaryPath, "utf-8");
+      assert.match(summary, /^## Operational Readiness/m);
+      assert.match(summary, /Health signal: \/health/);
+    }
+  });
+});