@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -25,6 +25,12 @@ export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 
+function normalizeMilestoneId(milestoneId: string): string {
+  const match = milestoneId.match(/^(M)(\d+)(?:-([a-z0-9]{6}))?$/i);
+  if (!match) return milestoneId;
+  return `M${match[2]}${match[3] ? `-${match[3].toLowerCase()}` : ""}`;
+}
+
 /**
  * Path segment that identifies .gsd/ planning artifacts.
  * Writes to these paths are allowed during queue mode.
@@ -91,8 +97,19 @@ function createEmptyWriteGateState(): InMemoryWriteGateState {
 
 const writeGateStatesByBasePath = new Map<string, InMemoryWriteGateState>();
 
+/**
+ * Write-gate snapshots are project-scoped, not worktree-scoped. When auto-mode
+ * routes MCP tool writes to `.gsd-worktrees/<MID>/`, depth verification still
+ * lands in the authoritative project `.gsd/runtime/` tree (or external-state
+ * symlink target). Without this canonicalization, `loadWriteGateSnapshot(worktree)`
+ * sees an empty snapshot and CONTEXT saves loop forever (#M020 gate loop).
+ */
+function resolveWriteGateSnapshotRoot(basePath: string): string {
+  return resolve(resolveWorktreeProjectRoot(basePath));
+}
+
 function writeGateStateKey(basePath: string): string {
-  return resolve(basePath);
+  return resolveWriteGateSnapshotRoot(basePath);
 }
 
 function getWriteGateState(basePath: string = process.cwd()): InMemoryWriteGateState {
@@ -155,17 +172,18 @@ function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): b
 }
 
 function writeGateSnapshotPath(basePath: string): string {
-  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+  return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 
 function ensureWriteGateSnapshotDirectory(basePath: string): void {
-  const gsdPath = join(basePath, ".gsd");
+  const snapshotRoot = resolveWriteGateSnapshotRoot(basePath);
+  const gsdPath = join(snapshotRoot, ".gsd");
   if (!existsSync(gsdPath)) {
     try {
       const stat = lstatSync(gsdPath);
       if (stat.isSymbolicLink()) {
         const target = readlinkSync(gsdPath);
-        mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+        mkdirSync(isAbsolute(target) ? target : resolve(snapshotRoot, target), { recursive: true });
       }
     } catch {
       // If .gsd truly does not exist, the runtime mkdir below will create it.
@@ -174,7 +192,7 @@ function ensureWriteGateSnapshotDirectory(basePath: string): void {
   mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
 
-function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+export function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const state = getWriteGateState(basePath);
   return {
     verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -228,7 +246,9 @@ function clearPersistedWriteGateSnapshot(basePath: string): void {
 function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
   const verified = Array.isArray(record.verifiedDepthMilestones)
-    ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
+    ? record.verifiedDepthMilestones
+        .filter((item): item is string => typeof item === "string")
+        .map(normalizeMilestoneId)
     : [];
   const verifiedGates = Array.isArray(record.verifiedApprovalGates)
     ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
@@ -289,7 +309,7 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
  *     guard that previously protected only the tool_execution_start window.
  */
 function mergeSnapshotIntoState(state: InMemoryWriteGateState, disk: WriteGateSnapshot): void {
-  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(milestone);
+  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
   for (const gate of disk.verifiedApprovalGates ?? []) state.verifiedApprovalGates.add(gate);
   state.activeQueuePhase = disk.activeQueuePhase;
   state.pendingGateId = disk.pendingGateId;
@@ -395,7 +415,7 @@ export function isMilestoneDepthVerified(
 ): boolean {
   if (!milestoneId) return false;
   refreshWriteGateStateFromDisk(basePath);
-  return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+  return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 
 export function isMilestoneDepthVerifiedInSnapshot(
@@ -403,7 +423,7 @@ export function isMilestoneDepthVerifiedInSnapshot(
   milestoneId: string | null | undefined,
 ): boolean {
   if (!milestoneId) return false;
-  return snapshot.verifiedDepthMilestones.includes(milestoneId);
+  return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 
 export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
@@ -466,7 +486,7 @@ export function isGateQuestionId(questionId: string): boolean {
  */
 export function extractDepthVerificationMilestoneId(questionId: string): string | null {
   const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -474,7 +494,7 @@ export function extractDepthVerificationMilestoneId(questionId: string): string
  */
 function extractContextMilestoneId(inputPath: string): string | null {
   const match = inputPath.match(CONTEXT_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -560,7 +580,7 @@ export const hostWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     mutateWriteGateState(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     }, { writer: "host" });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -601,7 +621,7 @@ export const childWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     childMutate(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -735,6 +755,13 @@ export interface AskUserQuestionsGateQuestion {
 export interface AskUserQuestionsGateDetails {
   cancelled?: boolean;
   interrupted?: boolean;
+  /**
+   * True when the host elicitation channel timed out before the user answered.
+   * Distinct from `cancelled` (deliberate dismissal): the gate verdict maps
+   * this to "timeout" so callers pause-and-wait instead of letting the model
+   * re-ask into the same timeout loop (#852).
+   */
+  timed_out?: boolean;
   response?: {
     answers?: Record<string, { selected?: unknown } | undefined>;
   } | null;
@@ -744,7 +771,8 @@ export type AskUserQuestionsGateResult =
   | { status: "not-gate" }
   | { status: "waiting"; pendingGateId: string; interrupted: boolean }
   | { status: "verified"; gateId: string; milestoneId: string | null }
-  | { status: "declined"; gateId: string };
+  | { status: "declined"; gateId: string }
+  | { status: "timeout"; pendingGateId: string; interrupted: boolean };
 
 function findGateQuestion(
   questions: AskUserQuestionsGateQuestion[],
@@ -768,11 +796,22 @@ function verifyAnsweredGate(
 
 /** Map an unresolved (non-verified) gate verdict to the caller-facing result. */
 function unresolvedGateResult(
-  verdict: "declined" | "waiting" | "cancelled",
+  verdict: "declined" | "waiting" | "cancelled" | "timeout",
   gateId: string,
   details: AskUserQuestionsGateDetails,
 ): AskUserQuestionsGateResult {
   if (verdict === "declined") return { status: "declined", gateId };
+  if (verdict === "timeout") {
+    // Host elicitation expired before the user answered. The gate stays
+    // pending (fail-closed — a timeout is never approval), but the status is
+    // "timeout" so the caller pauses-and-waits instead of re-asking into the
+    // same timeout loop (#852).
+    return {
+      status: "timeout",
+      pendingGateId: gateId,
+      interrupted: details.interrupted === true,
+    };
+  }
   // "waiting" (and the unreachable post-cancel case): an empty selection is
   // not an answer — keep the gate pending and make the caller pause.
   return {
@@ -803,6 +842,16 @@ export function applyAskUserQuestionsGateResult(options: {
   const { basePath, questions, details, fallbackMilestoneId } = options;
   const currentPendingGate = getPendingGate(basePath);
   if (currentPendingGate) {
+    if (details.timed_out) {
+      // Host elicitation timed out before the user answered. Keep the gate
+      // pending (fail-closed) but report "timeout" so the caller pauses-and-
+      // waits instead of re-asking into the same timeout loop (#852).
+      return {
+        status: "timeout",
+        pendingGateId: currentPendingGate,
+        interrupted: details.interrupted === true,
+      };
+    }
     if (details.cancelled || !details.response) {
       return {
         status: "waiting",
@@ -821,6 +870,7 @@ export function applyAskUserQuestionsGateResult(options: {
     }
   }
 
+  if (details.timed_out) return { status: "not-gate" };
   if (details.cancelled || !details.response) return { status: "not-gate" };
 
   for (const question of questions) {
@@ -855,6 +905,24 @@ export function formatPendingAskUserQuestionsGateMessage(
   ].join(" ");
 }
 
+/**
+ * Format the LLM-facing message returned when a depth-confirmation gate
+ * elicitation times out. Distinct from {@link formatPendingAskUserQuestionsGateMessage}:
+ * a timeout must NOT tell the model to immediately re-ask (that re-triggers
+ * the same timeout loop). Instead it tells the model to stop, that auto-mode
+ * is paused, and that the user will respond on their own (#852).
+ */
+export function formatTimedOutAskUserQuestionsGateMessage(
+  pendingGateId: string,
+): string {
+  return [
+    `Depth confirmation on gate "${pendingGateId}" timed out waiting for a response.`,
+    "The user did not answer within the host elicitation window — do not re-ask in this turn, it will time out again.",
+    "Auto-mode is paused. Stop calling tools and wait for the user to respond on a new turn.",
+    "When the user replies with confirmation, the gate will be satisfied and work will resume.",
+  ].join(" ");
+}
+
 export function shouldBlockContextWrite(
   toolName: string,
   inputPath: string,
@@ -865,7 +933,7 @@ export function shouldBlockContextWrite(
   if (toolName !== "write") return { block: false };
   if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
 
-  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId;
+  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? (milestoneId ? normalizeMilestoneId(milestoneId) : null);
   if (!targetMilestoneId) {
     return {
       block: true,
@@ -884,8 +952,8 @@ export function shouldBlockContextWrite(
     reason: [
       `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
       `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
-      `Required action: call ask_user_questions with question id containing "depth_verification".`,
-      `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+      `Required action: call ask_user_questions with question id "depth_verification_${targetMilestoneId}_confirm".`,
+      `The user MUST select the first "(Recommended)" confirmation option to unlock this gate.`,
       `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
     ].join(" "),
   };
@@ -1101,7 +1169,7 @@ function allowsControlledSubagentDispatch(
   policy: ToolsPolicy,
 ): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
   return (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
   );
 }
@@ -1131,6 +1199,7 @@ function warnMissingControlledDispatchAgentClasses(unitType: string, mode: strin
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
+  "memory_query",
   "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
   "search_and_read",
 ]);
@@ -1197,6 +1266,9 @@ type PlanningUnitBlockResult = {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1286,6 +1358,24 @@ export function shouldBlockPlanningUnit(
     return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
+  if (policy.mode === "workflow-only") {
+    if (tool === "bash") {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`,
+      );
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`,
+      );
+    }
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+  }
+
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };

package/src/resources/extensions/gsd/closeout-consistency-gate.ts

@@ -1,7 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
 
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import {
   getLatestAssessmentByScope,
@@ -9,14 +10,19 @@ import {
   getMilestoneSlices,
   getPendingGates,
   getSliceTasks,
+  insertAssessment,
   isDbAvailable,
+  transaction,
 } from "./gsd-db.js";
 import {
   getWorkflowDatabasePath,
   refreshWorkflowDatabaseFromDisk,
 } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
+import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
+import { relMilestoneFile, resolveSliceFile } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
 
 export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
 
@@ -44,6 +50,7 @@ export interface CloseoutConsistencyOptions {
   refreshFromDisk?: boolean;
   allowOpenMilestone?: boolean;
   artifactBasePath?: string;
+  allowPassThroughValidation?: boolean;
 }
 
 function blocked(reason: CloseoutConsistencyFailureReason, message: string): CloseoutConsistencyResult {
@@ -65,6 +72,87 @@ function artifactBasePathFromDb(): string | undefined {
   return dirname(dirname(dbPath!));
 }
 
+function allSlicesHaveCloseoutSummaryEvidence(milestoneId: string, artifactBasePath: string): boolean {
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return false;
+
+  return slices.every((slice) => {
+    if (!isClosedStatus(slice.status)) return false;
+    for (const task of getSliceTasks(milestoneId, slice.id)) {
+      if (!isClosedStatus(task.status)) return false;
+    }
+    const summaryPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "SUMMARY");
+    return Boolean(summaryPath && existsSync(summaryPath));
+  });
+}
+
+function renderCloseoutPassThroughValidation(milestoneId: string): string {
+  return [
+    "---",
+    "verdict: pass",
+    "skip_validation: true",
+    "skip_validation_reason: closeout-recovery",
+    "remediation_round: 0",
+    "---",
+    "",
+    "# Milestone Validation (skipped)",
+    "",
+    `Milestone validation was recorded during closeout for ${milestoneId} because all slices already had SUMMARY evidence and no milestone-validation assessment was present.`,
+    "",
+  ].join("\n");
+}
+
+function recordCloseoutPassThroughValidationIfReady(
+  milestoneId: string,
+  artifactBasePath?: string,
+): boolean {
+  const basePath = artifactBasePath ?? artifactBasePathFromDb();
+  if (!basePath) return false;
+
+  const existing = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (existing?.status === "pass") return true;
+  if (existing) return false;
+  if (!allSlicesHaveCloseoutSummaryEvidence(milestoneId, basePath)) return false;
+
+  const validationPath = join(basePath, relMilestoneFile(basePath, milestoneId, "VALIDATION"));
+  const content = renderCloseoutPassThroughValidation(milestoneId);
+  mkdirSync(dirname(validationPath), { recursive: true });
+  writeFileSync(validationPath, content, "utf-8");
+
+  try {
+    transaction(() => {
+      insertAssessment({
+        path: validationPath,
+        milestoneId,
+        sliceId: null,
+        taskId: null,
+        status: "pass",
+        scope: "milestone-validation",
+        fullContent: content,
+      });
+      const gateSliceId = getMilestoneSlices(milestoneId)[0]?.id;
+      if (gateSliceId) {
+        insertMilestoneValidationGates(
+          milestoneId,
+          gateSliceId,
+          "pass",
+          new Date().toISOString(),
+        );
+      }
+    });
+  } catch (err) {
+    try {
+      unlinkSync(validationPath);
+    } catch {
+      // best effort cleanup
+    }
+    throw err;
+  }
+
+  invalidateAllCaches();
+  return true;
+}
+
 export function checkCloseoutConsistencyGate(
   milestoneId: string,
   options: CloseoutConsistencyOptions = {},
@@ -97,14 +185,30 @@ export function checkCloseoutConsistencyGate(
     );
   }
 
-  const validation = milestone.status === "skipped"
+  let validation = milestone.status === "skipped"
     ? null
     : getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (
+    milestone.status !== "skipped" &&
+    validation?.status !== "pass" &&
+    options.allowPassThroughValidation &&
+    recordCloseoutPassThroughValidationIfReady(
+      milestoneId,
+      options.artifactBasePath ?? artifactBasePathFromDb(),
+    )
+  ) {
+    validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  }
   if (milestone.status !== "skipped") {
     if (validation?.status !== "pass") {
+      const validationStatus = validation?.status ?? "absent";
+      const recovery =
+        validationStatus === "absent"
+          ? ` Run \`/gsd validate-milestone ${milestoneId}\` to create the validation, or set \`phases.skip_milestone_validation: true\` in .gsd/PREFERENCES.md to skip it.`
+          : "";
       return blocked(
         "validation-not-pass",
-        `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`,
+        `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validationStatus}".${recovery}`,
       );
     }
   }
@@ -125,6 +229,7 @@ export function checkCloseoutConsistencyGate(
   }
 
   for (const slice of slices) {
+    if (isDeferredStatus(slice.status)) continue;
     if (!isClosedStatus(slice.status)) {
       return blocked(
         "slice-open",