gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

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

@@ -25,10 +25,18 @@ export interface PlanMilestoneSliceInput {
   depends: string[];
   demo: string;
   goal: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   successCriteria: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   proofLevel: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   integrationClosure: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   observabilityImpact: string;
+  /** ADR-011: when true, this slice is a sketch awaiting refine-slice expansion. */
+  isSketch?: boolean;
+  /** ADR-011: 2–3 sentence scope boundary, required when isSketch is true. */
+  sketchScope?: string;
 }
 
 export interface PlanMilestoneParams {
@@ -125,6 +133,16 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     const proofLevel = obj.proofLevel;
     const integrationClosure = obj.integrationClosure;
     const observabilityImpact = obj.observabilityImpact;
+    const isSketchRaw = obj.isSketch;
+    const sketchScopeRaw = obj.sketchScope;
+    // ADR-011: preserve the 3-valued semantics of isSketch (true / false / absent).
+    // Callers that omit isSketch must receive `undefined` here so `insertSlice`'s
+    // ON CONFLICT clause preserves any existing is_sketch on the row rather than
+    // silently overwriting a legitimate sketch to non-sketch.
+    const isSketch: boolean | undefined =
+      isSketchRaw === true ? true
+      : isSketchRaw === false ? false
+      : undefined;
 
     if (!isNonEmptyString(sliceId)) throw new Error(`slices[${index}].sliceId must be a non-empty string`);
     if (seen.has(sliceId)) throw new Error(`slices[${index}].sliceId must be unique`);
@@ -136,10 +154,18 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     }
     if (!isNonEmptyString(demo)) throw new Error(`slices[${index}].demo must be a non-empty string`);
     if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`);
-    if (!isNonEmptyString(successCriteria)) throw new Error(`slices[${index}].successCriteria must be a non-empty string`);
-    if (!isNonEmptyString(proofLevel)) throw new Error(`slices[${index}].proofLevel must be a non-empty string`);
-    if (!isNonEmptyString(integrationClosure)) throw new Error(`slices[${index}].integrationClosure must be a non-empty string`);
-    if (!isNonEmptyString(observabilityImpact)) throw new Error(`slices[${index}].observabilityImpact must be a non-empty string`);
+
+    // ADR-011: sketch slices may defer the heavyweight planning fields to refine-slice.
+    if (isSketch === true) {
+      if (!isNonEmptyString(sketchScopeRaw)) {
+        throw new Error(`slices[${index}].sketchScope must be a non-empty string when isSketch is true`);
+      }
+    } else {
+      if (!isNonEmptyString(successCriteria)) throw new Error(`slices[${index}].successCriteria must be a non-empty string`);
+      if (!isNonEmptyString(proofLevel)) throw new Error(`slices[${index}].proofLevel must be a non-empty string`);
+      if (!isNonEmptyString(integrationClosure)) throw new Error(`slices[${index}].integrationClosure must be a non-empty string`);
+      if (!isNonEmptyString(observabilityImpact)) throw new Error(`slices[${index}].observabilityImpact must be a non-empty string`);
+    }
 
     return {
       sliceId,
@@ -148,10 +174,14 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
       depends,
       demo,
       goal,
-      successCriteria,
-      proofLevel,
-      integrationClosure,
-      observabilityImpact,
+      successCriteria: isNonEmptyString(successCriteria) ? successCriteria : "",
+      proofLevel: isNonEmptyString(proofLevel) ? proofLevel : "",
+      integrationClosure: isNonEmptyString(integrationClosure) ? integrationClosure : "",
+      observabilityImpact: isNonEmptyString(observabilityImpact) ? observabilityImpact : "",
+      isSketch,
+      // Only carry the sketch scope through if the caller explicitly provided it
+      // — preserves ON CONFLICT semantics for re-plans that omit the field.
+      sketchScope: sketchScopeRaw === undefined ? undefined : (isNonEmptyString(sketchScopeRaw) ? sketchScopeRaw : ""),
     };
   });
 }
@@ -274,6 +304,10 @@ export async function handlePlanMilestone(
           depends: slice.depends,
           demo: slice.demo,
           sequence: i + 1, // Preserve agent-ordered sequence (#3356)
+          // ADR-011: pass undefined through so ON CONFLICT preserves existing values
+          // when the caller omitted the fields on a re-plan.
+          isSketch: slice.isSketch,
+          sketchScope: slice.sketchScope,
         });
         upsertSlicePlanning(params.milestoneId, slice.sliceId, {
           goal: slice.goal,

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -1,5 +1,5 @@
 import { clearParseCache } from "../files.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
 import {
   transaction,
@@ -9,6 +9,7 @@ import {
   upsertSlicePlanning,
   upsertTaskPlanning,
   insertGateRow,
+  updateSliceStatus,
 } from "../gsd-db.js";
 import type { GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
@@ -166,6 +167,10 @@ export async function handlePlanSlice(
         return;
       }
 
+      if (isDeferredStatus(parentSlice.status)) {
+        updateSliceStatus(params.milestoneId, params.sliceId, "pending");
+      }
+
       upsertSlicePlanning(params.milestoneId, params.sliceId, {
         goal: params.goal,
         successCriteria: params.successCriteria,

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

@@ -23,6 +23,9 @@ import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 import { insertMilestoneValidationGates } from "../milestone-validation-gates.js";
 import { logWarning } from "../workflow-logger.js";
+import { UokGateRunner } from "../uok/gate-runner.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { resolveUokFlags } from "../uok/flags.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -43,6 +46,12 @@ export interface ValidateMilestoneResult {
   validationPath: string;
 }
 
+export interface ValidateMilestoneOptions {
+  uokGatesEnabled?: boolean;
+  traceId?: string;
+  turnId?: string;
+}
+
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -81,6 +90,7 @@ ${params.verdictRationale}
 export async function handleValidateMilestone(
   params: ValidateMilestoneParams,
   basePath: string,
+  opts?: ValidateMilestoneOptions,
 ): Promise<ValidateMilestoneResult | { error: string }> {
   if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
     return { error: "milestoneId is required and must be a non-empty string" };
@@ -108,6 +118,8 @@ export async function handleValidateMilestone(
   // rendering can regenerate. The inverse (file exists, no DB row) is
   // harder to detect and recover from (#2725).
   const validatedAt = new Date().toISOString();
+  const slices = getMilestoneSlices(params.milestoneId);
+  const gateSliceId = slices.length > 0 ? slices[0].id : "_milestone";
 
   transaction(() => {
     insertAssessment({
@@ -123,11 +135,9 @@ export async function handleValidateMilestone(
     // #2945 Bug 4: persist quality_gates records alongside the assessment.
     // Previously only the assessment was written, leaving M002+ milestones
     // with zero quality_gate records despite passing validation.
-    const slices = getMilestoneSlices(params.milestoneId);
-    const sliceId = slices.length > 0 ? slices[0].id : "_milestone";
     insertMilestoneValidationGates(
       params.milestoneId,
-      sliceId,
+      gateSliceId,
       params.verdict,
       validatedAt,
     );
@@ -147,6 +157,41 @@ export async function handleValidateMilestone(
   clearPathCache();
   clearParseCache();
 
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const gatesEnabled = opts?.uokGatesEnabled ?? resolveUokFlags(prefs).gates;
+  if (gatesEnabled) {
+    try {
+      const gateRunner = new UokGateRunner();
+      const nonPassVerdict = params.verdict !== "pass";
+      gateRunner.register({
+        id: "milestone-validation-gates",
+        type: "verification",
+        execute: async () => ({
+          outcome: nonPassVerdict ? "manual-attention" : "pass",
+          failureClass: nonPassVerdict ? "manual-attention" : "none",
+          rationale: `milestone validation verdict: ${params.verdict}`,
+          findings: nonPassVerdict
+            ? [params.verdictRationale, params.remediationPlan ?? ""].filter(Boolean).join("\n")
+            : "",
+        }),
+      });
+      await gateRunner.run("milestone-validation-gates", {
+        basePath,
+        traceId: opts?.traceId ?? `validate-milestone:${params.milestoneId}`,
+        turnId: opts?.turnId ?? `${params.milestoneId}:validate`,
+        milestoneId: params.milestoneId,
+        sliceId: gateSliceId,
+        unitType: "validate-milestone",
+        unitId: params.milestoneId,
+      });
+    } catch (err) {
+      logWarning(
+        "tool",
+        `validate_milestone — failed to persist UOK gate result: ${(err as Error).message}`,
+      );
+    }
+  }
+
   return {
     milestoneId: params.milestoneId,
     verdict: params.verdict,

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -5,7 +5,7 @@ import {
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
-  _getAdapter,
+  readTransaction,
   saveGateResult,
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
@@ -616,12 +616,9 @@ export async function executeMilestoneStatus(
       };
     }
 
-    const adapter = _getAdapter()!;
-    adapter.exec("BEGIN");
-    try {
+    return readTransaction(() => {
       const milestone = getMilestone(params.milestoneId);
       if (!milestone) {
-        adapter.exec("COMMIT");
         return {
           content: [{ type: "text", text: `Milestone ${params.milestoneId} not found in database.` }],
           details: { operation: "milestone_status", milestoneId: params.milestoneId, found: false },
@@ -635,8 +632,6 @@ export async function executeMilestoneStatus(
         taskCounts: getSliceTaskCounts(params.milestoneId, s.id),
       }));
 
-      adapter.exec("COMMIT");
-
       const result = {
         milestoneId: milestone.id,
         title: milestone.title,
@@ -651,10 +646,7 @@ export async function executeMilestoneStatus(
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: { operation: "milestone_status", milestoneId: milestone.id, sliceCount: slices.length },
       };
-    } catch (txErr) {
-      try { adapter.exec("ROLLBACK"); } catch { /* swallow */ }
-      throw txErr;
-    }
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     logWarning("tool", `gsd_milestone_status tool failed: ${msg}`);

package/src/resources/extensions/gsd/triage-resolution.ts

@@ -111,14 +111,9 @@ export function executeReplan(
     // Also write replan_triggered_at column for DB-backed detection
     try {
       const req = createRequire(import.meta.url);
-      const { isDbAvailable, _getAdapter } = req("./gsd-db.js");
+      const { isDbAvailable, setSliceReplanTriggeredAt } = req("./gsd-db.js");
       if (isDbAvailable()) {
-        const adapter = _getAdapter();
-        if (adapter) {
-          adapter.prepare(
-            "UPDATE slices SET replan_triggered_at = :ts WHERE milestone_id = :mid AND id = :sid",
-          ).run({ ":ts": ts, ":mid": mid, ":sid": sid });
-        }
+        setSliceReplanTriggeredAt(mid, sid, ts);
       }
     } catch {
       // DB write is best-effort — disk file is the primary trigger for fallback path

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

@@ -11,6 +11,7 @@ export type Phase =
   | "discussing"
   | "researching"
   | "planning"
+  | "refining"
   | "evaluating-gates"
   | "executing"
   | "verifying"
@@ -19,6 +20,7 @@ export type Phase =
   | "validating-milestone"
   | "completing-milestone"
   | "replanning-slice"
+  | "escalating-task"
   | "complete"
   | "paused"
   | "blocked";
@@ -253,6 +255,19 @@ export interface GSDState {
   lastCompletedMilestone?: ActiveRef | null;
 }
 
+// ─── GSD Ecosystem Extension API Types ────────────────────────────────────
+// Pure data type — no runtime deps. The GSDExtensionAPI interface itself
+// lives in ecosystem/gsd-extension-api.ts (it imports from pi).
+
+export interface GSDActiveUnit {
+  milestoneId: string;
+  milestoneTitle: string;
+  sliceId: string;
+  sliceTitle: string;
+  taskId: string;
+  taskTitle: string;
+}
+
 // ─── Post-Unit Hook Types ─────────────────────────────────────────────────
 
 export interface PostUnitHookConfig {
@@ -306,7 +321,7 @@ export interface HookDispatchResult {
 
 export type BudgetEnforcementMode = "warn" | "pause" | "halt";
 
-export type TokenProfile = "budget" | "balanced" | "quality";
+export type TokenProfile = "budget" | "balanced" | "quality" | "burn-max";
 
 export type InlineLevel = "full" | "standard" | "minimal";
 
@@ -337,6 +352,51 @@ export interface PhaseSkipPreferences {
   reassess_after_slice?: boolean;
   /** When true, auto-mode pauses before each slice for discussion (#789). */
   require_slice_discussion?: boolean;
+  /** ADR-011 Phase 2: when true, executors may escalate task-level ambiguity via T##-ESCALATION.json. */
+  mid_execution_escalation?: boolean;
+  /** ADR-011 Phase 1: when true, plan S01 in full and S02+ as sketches refined just-in-time. */
+  progressive_planning?: boolean;
+}
+
+// ─── ADR-011 Phase 2 Escalation ──────────────────────────────────────────
+
+export interface EscalationOption {
+  /** Short identifier, e.g. "A", "B". Used as the `choice` value in `/gsd escalate resolve <taskId> <id>`. */
+  id: string;
+  /** One-line label for the option. */
+  label: string;
+  /** 1-2 sentence description of the tradeoffs of this option. */
+  tradeoffs: string;
+}
+
+export interface EscalationArtifact {
+  /** Schema version for the artifact file — bumps if we change the shape. */
+  version: 1;
+  taskId: string;
+  sliceId: string;
+  milestoneId: string;
+  /** The question the executor needs the user to resolve. */
+  question: string;
+  /** 2-4 options the user can choose between. */
+  options: EscalationOption[];
+  /** Which option the executor recommends (references `options[].id`). */
+  recommendation: string;
+  /** Why the executor recommends that option (1-2 sentences). */
+  recommendationRationale: string;
+  /**
+   * When true, the executor proceeds with the recommendation as the answer
+   * and the loop continues. User's later choice becomes a carry-forward
+   * override for the NEXT task. When false, auto-mode pauses until the
+   * user resolves via `/gsd escalate resolve`.
+   */
+  continueWithDefault: boolean;
+  createdAt: string;
+  /** Populated by `/gsd escalate resolve`. */
+  respondedAt?: string;
+  /** User's choice — either an option id, "accept" (use recommendation), or "reject-blocker". */
+  userChoice?: string;
+  /** Optional free-text rationale from the user. */
+  userRationale?: string;
 }
 
 export interface NotificationPreferences {
@@ -422,6 +482,7 @@ export interface Decision {
   rationale: string; // why this choice
   revisable: string; // whether/when revisable
   made_by: DecisionMadeBy; // who made the decision: human, agent, or collaborative
+  source?: string; // ADR-011 P2: origin — "discussion" (default) | "planning" | "escalation"
   superseded_by: string | null; // ID of superseding decision, or null
 }
 
@@ -529,6 +590,20 @@ export interface CompleteTaskParams {
   knownIssues?: string;
   /** @optional — defaults to false when omitted */
   blockerDiscovered?: boolean;
+  /**
+   * ADR-011 Phase 2 — optional escalation payload. When populated, the executor
+   * is asking the user to resolve an ambiguity. If `continueWithDefault: true`
+   * the task still completes (using the recommendation) but an artifact is
+   * written for later user review. If false, auto-mode pauses.
+   * @optional
+   */
+  escalation?: {
+    question: string;
+    options: EscalationOption[];
+    recommendation: string;
+    recommendationRationale: string;
+    continueWithDefault: boolean;
+  };
   /** @optional — defaults to [] when omitted by models with limited tool-calling */
   verificationEvidence?: Array<{
     command: string;

package/src/resources/extensions/gsd/unit-ownership.ts

@@ -46,8 +46,8 @@ let loadAttempted = false;
 
 function suppressSqliteWarning(): void {
   const origEmit = process.emit;
-  // @ts-expect-error overriding process.emit for warning filter
-  process.emit = function (event: string, ...args: unknown[]): boolean {
+  // Override via loose cast: Node's overloaded emit signature is not directly assignable.
+  (process as any).emit = function (event: string, ...args: unknown[]): boolean {
     if (
       event === "warning" &&
       args[0] &&

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

@@ -14,6 +14,7 @@ export type UnitRuntimePhase =
   | "dispatched"
   | "wrapup-warning-sent"
   | "timeout"
+  | "finalize-timeout"
   | "recovered"
   | "finalized"
   | "paused"

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

@@ -0,0 +1,9 @@
+const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+
+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";
+}

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

@@ -0,0 +1,51 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { gsdRoot } from "../paths.js";
+import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
+import type { AuditEventEnvelope } from "./contracts.js";
+
+function auditLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "audit", "events.jsonl");
+}
+
+function ensureAuditDir(basePath: string): void {
+  mkdirSync(join(gsdRoot(basePath), "audit"), { recursive: true });
+}
+
+export function buildAuditEnvelope(args: {
+  traceId: string;
+  turnId?: string;
+  causedBy?: string;
+  category: AuditEventEnvelope["category"];
+  type: string;
+  payload?: Record<string, unknown>;
+}): AuditEventEnvelope {
+  return {
+    eventId: randomUUID(),
+    traceId: args.traceId,
+    turnId: args.turnId,
+    causedBy: args.causedBy,
+    category: args.category,
+    type: args.type,
+    ts: new Date().toISOString(),
+    payload: args.payload ?? {},
+  };
+}
+
+export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
+  try {
+    ensureAuditDir(basePath);
+    appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+  } catch {
+    // Best-effort: audit writes must never break orchestration.
+  }
+
+  if (!isDbAvailable()) return;
+  try {
+    insertAuditEvent(event);
+  } catch {
+    // Projection failures are non-fatal while legacy readers are still active.
+  }
+}

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

@@ -0,0 +1,136 @@
+export type FailureClass =
+  | "none"
+  | "policy"
+  | "input"
+  | "execution"
+  | "artifact"
+  | "verification"
+  | "closeout"
+  | "git"
+  | "timeout"
+  | "manual-attention"
+  | "unknown";
+
+export type GateOutcome = "pass" | "fail" | "retry" | "manual-attention";
+
+export interface GateResult {
+  gateId: string;
+  gateType: string;
+  outcome: GateOutcome;
+  failureClass: FailureClass;
+  rationale?: string;
+  findings?: string;
+  attempt: number;
+  maxAttempts: number;
+  retryable: boolean;
+  evaluatedAt: string;
+}
+
+export type TurnPhase =
+  | "pre-dispatch"
+  | "dispatch"
+  | "unit"
+  | "finalize"
+  | "guard"
+  | "custom-engine";
+
+export type TurnStatus =
+  | "completed"
+  | "failed"
+  | "paused"
+  | "stopped"
+  | "skipped"
+  | "retry";
+
+export interface TurnContract {
+  traceId: string;
+  turnId: string;
+  iteration: number;
+  basePath: string;
+  unitType?: string;
+  unitId?: string;
+  sidecarKind?: string;
+  startedAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TurnCloseoutRecord {
+  traceId: string;
+  turnId: string;
+  unitType?: string;
+  unitId?: string;
+  status: TurnStatus;
+  failureClass: FailureClass;
+  gitAction: "commit" | "snapshot" | "status-only";
+  gitPushed: boolean;
+  activityFile?: string;
+  finishedAt: string;
+}
+
+export interface TurnResult {
+  traceId: string;
+  turnId: string;
+  iteration: number;
+  unitType?: string;
+  unitId?: string;
+  status: TurnStatus;
+  failureClass: FailureClass;
+  phaseResults: Array<{
+    phase: TurnPhase;
+    action: string;
+    ts: string;
+    data?: Record<string, unknown>;
+  }>;
+  gateResults?: GateResult[];
+  closeout?: TurnCloseoutRecord;
+  error?: string;
+  startedAt: string;
+  finishedAt: string;
+}
+
+export interface AuditEventEnvelope {
+  eventId: string;
+  traceId: string;
+  turnId?: string;
+  causedBy?: string;
+  category:
+    | "orchestration"
+    | "gate"
+    | "model-policy"
+    | "gitops"
+    | "verification"
+    | "metrics"
+    | "plan"
+    | "execution";
+  type: string;
+  ts: string;
+  payload: Record<string, unknown>;
+}
+
+export type UokNodeKind =
+  | "unit"
+  | "hook"
+  | "subagent"
+  | "team-worker"
+  | "verification"
+  | "reprocess"
+  | "refine";
+
+export interface UokGraphNode {
+  id: string;
+  kind: UokNodeKind;
+  dependsOn: string[];
+  writes?: string[];
+  reads?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface UokTurnObserver {
+  onTurnStart(contract: TurnContract): void;
+  onPhaseResult(
+    phase: TurnPhase,
+    action: string,
+    data?: Record<string, unknown>,
+  ): void;
+  onTurnResult(result: TurnResult): void;
+}