@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -12,15 +12,13 @@
  * despite passing validation.
  */
 
-import { join } from "node:path";
-
 import {
   transaction,
   insertAssessment,
   getMilestoneSlices,
   getMilestone,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache, relMilestoneFile } from "../paths.js";
+import { clearPathCache, targetMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -160,11 +158,12 @@ export async function handleValidateMilestone(
   // worktree exists for this milestone, validation reads/writes the
   // worktree's artifacts instead of stale project-root state.
   const validationMd = renderValidationMarkdown(effectiveParams);
-  // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md;
-  // legacy → milestones/MID/MID-VALIDATION.md.
-  // join(artifactBasePath, relMilestoneFile) gives the absolute path; relMilestoneFile
-  // returns ".gsd/..."-relative so joining with basePath (project/worktree root) is correct.
-  const validationPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, effectiveParams.milestoneId, "VALIDATION"));
+  const validationPath = targetMilestoneFile(
+    artifactBasePath,
+    effectiveParams.milestoneId,
+    "VALIDATION",
+    getMilestone(effectiveParams.milestoneId)?.title,
+  );
 
   // ── DB write first — matches complete-task/complete-slice pattern ───
   // Write DB before disk so a crash between the two leaves a recoverable
@@ -204,7 +203,12 @@ export async function handleValidateMilestone(
     const projectRoot = resolveWorktreeProjectRoot(basePath);
     if (projectRoot !== artifactBasePath) {
       // Mirror to project root using the project root's layout (same logic as above).
-      const projectValidationPath = join(projectRoot, relMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION"));
+      const projectValidationPath = targetMilestoneFile(
+        projectRoot,
+        effectiveParams.milestoneId,
+        "VALIDATION",
+        getMilestone(effectiveParams.milestoneId)?.title,
+      );
       try {
         await saveFile(projectValidationPath, validationMd);
       } catch (mirrorErr) {

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

@@ -2,6 +2,11 @@
 // Types consumed by state derivation, file parsing, and status display.
 // Pure interfaces — no logic, no runtime dependencies.
 
+// Type-only import (erased at compile time — no runtime dependency): sibling
+// single-model fields share the phase-bucket object form so they honor
+// `fallbacks[]` (#1229).
+import type { GSDPhaseModelConfig } from "./preferences-types.js";
+
 // ─── Enums & Literal Unions ────────────────────────────────────────────────
 
 export type RiskLevel = "low" | "medium" | "high";
@@ -303,8 +308,13 @@ export interface PostUnitHookConfig {
   prompt: string;
   /** Max times this hook can fire for the same trigger unit. Default 1, max 10. */
   max_cycles?: number;
-  /** Model override for hook sessions. */
-  model?: string;
+  /**
+   * Model override for hook sessions. Accepts a bare model ID or the extended
+   * `{ model, provider?, fallbacks? }` object form so a transient trip of the
+   * primary provider falls back to the next entry instead of hard-failing the
+   * hook (#1229).
+   */
+  model?: string | GSDPhaseModelConfig;
   /** Expected output file name (relative to task/slice dir). Used for idempotency — skip if exists. */
   artifact?: string;
   /** Whether the hook is advisory or blocks unit advancement. Default advisory. */
@@ -505,6 +515,11 @@ export interface PreDispatchResult {
 export interface PersistedHookState {
   /** Cycle counts keyed as "hookName/triggerUnitType/triggerUnitId". */
   cycleCounts: Record<string, number>;
+  /**
+   * Cycle keys already granted a one-shot re-dispatch after a lost/interrupted
+   * dispatch, so the refund is bounded to one per gate across resumes.
+   */
+  redispatchedGateKeys?: string[];
   /** In-flight hook, persisted so blocking gates cannot be skipped after resume. */
   activeHook?: HookExecutionState | null;
   /** Remaining hook queue by hook name and trigger unit. */
@@ -607,8 +622,12 @@ export interface ReactiveExecutionConfig {
   max_parallel: number;
   /** Isolation mode for parallel tasks within a slice. Currently only "same-tree" is supported. */
   isolation_mode: "same-tree";
-  /** Optional model override for subagents spawned during parallel execution. */
-  subagent_model?: string;
+  /**
+   * Optional model override for subagents spawned during parallel execution.
+   * Accepts a bare model ID or the extended `{ model, provider?, fallbacks? }`
+   * object form for parity with phase buckets (#1229).
+   */
+  subagent_model?: string | GSDPhaseModelConfig;
 }
 
 /** Per-slice reactive execution runtime state, persisted to disk. */

package/src/resources/extensions/gsd/uat-dispatch.ts

@@ -0,0 +1,176 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve whether a completed slice needs run-uat dispatch.
+
+import { loadFile } from "./files.js";
+import type { GSDPreferences } from "./preferences.js";
+import { resolveSliceFile } from "./paths.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
+import { hasVerdict } from "./verdict-parser.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface UatDispatchCandidate {
+  sliceId: string;
+}
+
+export type RunUatDispatch = { sliceId: string; uatType: UatType };
+
+async function loadSliceFileContent(
+  base: string,
+  milestoneId: string,
+  sliceId: string,
+  kind: "UAT" | "ASSESSMENT" | "SUMMARY",
+): Promise<string> {
+  const filePath = resolveSliceFile(base, milestoneId, sliceId, kind);
+  return filePath ? ((await loadFile(filePath)) ?? "") : "";
+}
+
+async function resolveRunUatEffectiveType(
+  base: string,
+  milestoneId: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  let summaryContent = "";
+  try {
+    summaryContent = await loadSliceFileContent(
+      base,
+      milestoneId,
+      sliceId,
+      "SUMMARY",
+    );
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+
+async function resolveCandidateRunUatDispatch(
+  base: string,
+  milestoneId: string,
+  candidate: UatDispatchCandidate,
+  prefs: GSDPreferences | undefined,
+): Promise<RunUatDispatch | null> {
+  const uatContent = await loadSliceFileContent(
+    base,
+    milestoneId,
+    candidate.sliceId,
+    "UAT",
+  );
+  if (!uatContent) return null;
+  if (hasVerdict(uatContent)) return null;
+
+  const assessmentContent = await loadSliceFileContent(
+    base,
+    milestoneId,
+    candidate.sliceId,
+    "ASSESSMENT",
+  );
+  if (assessmentContent && hasVerdict(assessmentContent)) return null;
+  if (!shouldDispatchUatForContent(uatContent, prefs)) return null;
+
+  return {
+    sliceId: candidate.sliceId,
+    uatType: await resolveRunUatEffectiveType(
+      base,
+      milestoneId,
+      candidate.sliceId,
+      uatContent,
+    ),
+  };
+}
+
+async function getDbCompletedSliceCandidates(
+  milestoneId: string,
+): Promise<UatDispatchCandidate[] | null> {
+  const { isDbAvailable, getMilestoneSlices } = await import("./gsd-db.js");
+  if (!isDbAvailable()) return null;
+
+  const slices = getMilestoneSlices(milestoneId);
+  // No DB slice rows for this milestone: the DB has no authoritative view, so
+  // return null to let the caller defer to the roadmap fallback.
+  if (slices.length === 0) return null;
+
+  // The DB has slice rows and is therefore authoritative for this milestone.
+  // Return a (possibly empty) array rather than null: an empty result must NOT
+  // fall through to the roadmap fallback, because the DB, not stale roadmap
+  // checkboxes, is the source of truth for which slices are complete.
+  return slices
+    .filter((slice) => slice.status === "complete")
+    .map((slice) => ({ sliceId: slice.id }))
+    .reverse();
+}
+
+export async function findRunUatDispatchFromCandidates(
+  base: string,
+  milestoneId: string,
+  candidates: readonly UatDispatchCandidate[],
+  prefs: GSDPreferences | undefined,
+): Promise<RunUatDispatch | null> {
+  for (const candidate of candidates) {
+    const dispatch = await resolveCandidateRunUatDispatch(
+      base,
+      milestoneId,
+      candidate,
+      prefs,
+    );
+    if (dispatch) return dispatch;
+  }
+  return null;
+}
+
+/**
+ * Check if the most recently completed slice needs a UAT run.
+ * Returns { sliceId, uatType } if UAT should be dispatched, null otherwise.
+ *
+ * When the DB has slice rows for the milestone it is authoritative: only its
+ * completed slices are considered and the `fallbackCandidates` (roadmap-derived)
+ * are ignored, even when no DB slice is complete. The fallback candidates are
+ * only consulted when the DB has no slice rows for the milestone, is
+ * unavailable, or errors.
+ *
+ * Skips when:
+ * - No completed slices exist in DB or the caller-provided fallback candidates
+ * - uat_dispatch is not enabled and the UAT spec does not require runtime/browser evidence
+ * - No UAT file exists for the slice
+ * - UAT result already exists in the UAT or ASSESSMENT file
+ */
+export async function checkNeedsRunUat(
+  base: string,
+  milestoneId: string,
+  prefs: GSDPreferences | undefined,
+  fallbackCandidates: readonly UatDispatchCandidate[] = [],
+): Promise<RunUatDispatch | null> {
+  try {
+    const dbCandidates = await getDbCompletedSliceCandidates(milestoneId);
+    // A non-null result (including an empty array) means the DB is authoritative
+    // for this milestone; only fall through to the roadmap fallback when the DB
+    // has no slice rows at all (null).
+    if (dbCandidates !== null) {
+      return findRunUatDispatchFromCandidates(
+        base,
+        milestoneId,
+        dbCandidates,
+        prefs,
+      );
+    }
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `checkNeedsRunUat DB lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  return findRunUatDispatchFromCandidates(
+    base,
+    milestoneId,
+    fallbackCandidates,
+    prefs,
+  );
+}

package/src/resources/extensions/gsd/uok/audit-toggle.ts

@@ -1,9 +1,39 @@
 const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+const suppressedBasePaths = new Set<string>();
 
 export function setUnifiedAuditEnabled(enabled: boolean): void {
   process.env[AUDIT_ENV_KEY] = enabled ? "1" : "0";
 }
 
-export function isUnifiedAuditEnabled(): boolean {
-  return process.env[AUDIT_ENV_KEY] === "1";
+export function setUnifiedAuditSuppressedForBasePath(basePath: string, suppressed: boolean): void {
+  if (suppressed) {
+    suppressedBasePaths.add(basePath);
+    return;
+  }
+  suppressedBasePaths.delete(basePath);
+}
+
+export function isUnifiedAuditEnabled(basePath?: string): boolean {
+  if (basePath && suppressedBasePaths.has(basePath)) return false;
+  return process.env[AUDIT_ENV_KEY] !== "0";
+}
+
+export function getUnifiedAuditOverride(): boolean | undefined {
+  const raw = process.env[AUDIT_ENV_KEY];
+  if (raw === "0") return false;
+  if (raw === "1") return true;
+  return undefined;
+}
+
+export function restoreUnifiedAuditOverride(override: boolean | undefined): void {
+  if (override === undefined) {
+    delete process.env[AUDIT_ENV_KEY];
+    return;
+  }
+  setUnifiedAuditEnabled(override);
+}
+
+export function clearUnifiedAuditOverrideForTests(): void {
+  delete process.env[AUDIT_ENV_KEY];
+  suppressedBasePaths.clear();
 }

package/src/resources/extensions/gsd/uok/audit.ts

@@ -9,6 +9,7 @@ import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent, type AuditEventEnvelope } from "./contracts.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 
 function auditLogPath(basePath: string): string {
   return join(gsdRoot(basePath), "audit", "events.jsonl");
@@ -42,6 +43,7 @@ export function buildAuditEnvelope(args: {
 export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
   // Drop writes from a turn superseded by timeout recovery / cancellation.
   if (isStaleWrite("uok-audit")) return;
+  if (!isUnifiedAuditEnabled(basePath)) return;
   const validation = validateAuditEvent(event);
   if (!validation.ok) {
     throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);

package/src/resources/extensions/gsd/uok/gate-runner.ts

@@ -1,6 +1,7 @@
 import type { FailureClass, GateResult } from "./contracts.js";
 import { insertGateRun } from "../gsd-db.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 
 export interface GateRunnerContext {
   basePath: string;
@@ -38,6 +39,29 @@ const RETRY_MATRIX: Record<FailureClass, number> = {
   unknown: 0,
 };
 
+function emitGateAuditIfEnabled(ctx: GateRunnerContext, result: GateResult): void {
+  if (!isUnifiedAuditEnabled(ctx.basePath)) return;
+
+  emitUokAuditEvent(
+    ctx.basePath,
+    buildAuditEnvelope({
+      traceId: ctx.traceId,
+      turnId: ctx.turnId,
+      category: "gate",
+      type: "gate-run",
+      payload: {
+        gateId: result.gateId,
+        gateType: result.gateType,
+        outcome: result.outcome,
+        failureClass: result.failureClass,
+        attempt: result.attempt,
+        maxAttempts: result.maxAttempts,
+        retryable: result.retryable,
+      },
+    }),
+  );
+}
+
 export class UokGateRunner {
   private readonly registry = new Map<string, GateExecutionInput>();
 
@@ -85,24 +109,7 @@ export class UokGateRunner {
         evaluatedAt: unknownResult.evaluatedAt,
       });
 
-      emitUokAuditEvent(
-        ctx.basePath,
-        buildAuditEnvelope({
-          traceId: ctx.traceId,
-          turnId: ctx.turnId,
-          category: "gate",
-          type: "gate-run",
-          payload: {
-            gateId: unknownResult.gateId,
-            gateType: unknownResult.gateType,
-            outcome: unknownResult.outcome,
-            failureClass: unknownResult.failureClass,
-            attempt: unknownResult.attempt,
-            maxAttempts: unknownResult.maxAttempts,
-            retryable: unknownResult.retryable,
-          },
-        }),
-      );
+      emitGateAuditIfEnabled(ctx, unknownResult);
 
       return unknownResult;
     }
@@ -170,24 +177,7 @@ export class UokGateRunner {
         evaluatedAt: final.evaluatedAt,
       });
 
-      emitUokAuditEvent(
-        ctx.basePath,
-        buildAuditEnvelope({
-          traceId: ctx.traceId,
-          turnId: ctx.turnId,
-          category: "gate",
-          type: "gate-run",
-          payload: {
-            gateId: final.gateId,
-            gateType: final.gateType,
-            outcome: final.outcome,
-            failureClass: final.failureClass,
-            attempt: final.attempt,
-            maxAttempts: final.maxAttempts,
-            retryable: final.retryable,
-          },
-        }),
-      );
+      emitGateAuditIfEnabled(ctx, final);
 
       if (!retryable) break;
     }

package/src/resources/extensions/gsd/uok/gitops.ts

@@ -1,6 +1,7 @@
 import { isDbAvailable, upsertTurnGitTransaction } from "../gsd-db.js";
 import type { TurnCloseoutRecord } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 
 export type TurnGitStage = "turn-start" | "stage" | "checkpoint" | "publish" | "record";
 
@@ -34,24 +35,26 @@ export function writeTurnGitTransaction(args: GitTxArgs): void {
     updatedAt: new Date().toISOString(),
   });
 
-  emitUokAuditEvent(
-    args.basePath,
-    buildAuditEnvelope({
-      traceId: args.traceId,
-      turnId: args.turnId,
-      category: "gitops",
-      type: `turn-git-${args.stage}`,
-      payload: {
-        unitType: args.unitType,
-        unitId: args.unitId,
-        action: args.action,
-        push: args.push,
-        status: args.status,
-        error: args.error,
-        ...(args.metadata ?? {}),
-      },
-    }),
-  );
+  if (isUnifiedAuditEnabled(args.basePath)) {
+    emitUokAuditEvent(
+      args.basePath,
+      buildAuditEnvelope({
+        traceId: args.traceId,
+        turnId: args.turnId,
+        category: "gitops",
+        type: `turn-git-${args.stage}`,
+        payload: {
+          unitType: args.unitType,
+          unitId: args.unitId,
+          action: args.action,
+          push: args.push,
+          status: args.status,
+          error: args.error,
+          ...(args.metadata ?? {}),
+        },
+      }),
+    );
+  }
 }
 
 export function writeTurnCloseoutGitRecord(