gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

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;
+}

package/src/resources/extensions/gsd/uok/execution-graph.ts

@@ -0,0 +1,241 @@
+import type { UokGraphNode } from "./contracts.js";
+import type { DerivedTaskNode } from "../types.js";
+import type { SidecarItem } from "../auto/session.js";
+
+export interface ExecutionGraphRunOptions {
+  parallel?: boolean;
+  maxWorkers?: number;
+}
+
+export interface ExecutionGraphResult {
+  order: string[];
+  conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
+}
+
+export type ExecutionNodeHandler = (node: UokGraphNode) => Promise<void>;
+
+export interface ConflictFreeBatchInput {
+  orderedIds: string[];
+  maxParallel: number;
+  hasConflict: (leftId: string, rightId: string) => boolean;
+}
+
+export interface ReactiveDispatchSelectionInput {
+  graph: Array<Pick<DerivedTaskNode, "id" | "dependsOn" | "outputFiles">>;
+  readyIds: string[];
+  maxParallel: number;
+  inFlightOutputs?: Set<string>;
+}
+
+export interface ReactiveDispatchSelectionResult {
+  selected: string[];
+  conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
+}
+
+export function selectConflictFreeBatch({
+  orderedIds,
+  maxParallel,
+  hasConflict,
+}: ConflictFreeBatchInput): string[] {
+  if (maxParallel <= 0 || orderedIds.length === 0) return [];
+  const selected: string[] = [];
+  for (const candidate of orderedIds) {
+    if (selected.length >= maxParallel) break;
+    const conflictsExisting = selected.some((existing) => hasConflict(candidate, existing));
+    if (conflictsExisting) continue;
+    selected.push(candidate);
+  }
+  return selected;
+}
+
+function buildReactiveNodes(
+  graph: Array<Pick<DerivedTaskNode, "id" | "dependsOn" | "outputFiles">>,
+): UokGraphNode[] {
+  return graph.map((node) => ({
+    id: node.id,
+    kind: "unit",
+    dependsOn: [...node.dependsOn],
+    writes: [...node.outputFiles],
+  }));
+}
+
+export function selectReactiveDispatchBatch(
+  input: ReactiveDispatchSelectionInput,
+): ReactiveDispatchSelectionResult {
+  const nodeMap = new Map(buildReactiveNodes(input.graph).map((n) => [n.id, n]));
+  const readyNodes = input.readyIds
+    .map((id) => nodeMap.get(id))
+    .filter((node): node is UokGraphNode => !!node);
+  const conflicts = detectFileConflicts(readyNodes);
+  if (readyNodes.length === 0 || input.maxParallel <= 0) {
+    return { selected: [], conflicts };
+  }
+
+  const claimed = new Set(input.inFlightOutputs ?? []);
+  const selected: string[] = [];
+  const selectedSet = new Set<string>();
+  const readySet = new Set(input.readyIds);
+
+  for (const id of input.readyIds) {
+    if (selected.length >= input.maxParallel) break;
+    const node = nodeMap.get(id);
+    if (!node) continue;
+
+    const hasUnmetReadyDependency = node.dependsOn.some(
+      (dep) => readySet.has(dep) && !selectedSet.has(dep),
+    );
+    if (hasUnmetReadyDependency) continue;
+
+    const writes = node.writes ?? [];
+    const conflictsWithClaimed = writes.some((file) => claimed.has(file));
+    if (conflictsWithClaimed) continue;
+
+    selected.push(node.id);
+    selectedSet.add(node.id);
+    for (const file of writes) claimed.add(file);
+  }
+
+  return { selected, conflicts };
+}
+
+function sidecarToNodeKind(kind: SidecarItem["kind"]): UokGraphNode["kind"] {
+  if (kind === "hook") return "hook";
+  if (kind === "triage") return "verification";
+  return "team-worker";
+}
+
+export function buildSidecarQueueNodes(queue: SidecarItem[]): UokGraphNode[] {
+  return queue.map((item, index) => ({
+    id: `sidecar-${String(index).padStart(4, "0")}:${item.kind}:${item.unitType}:${item.unitId}`,
+    kind: sidecarToNodeKind(item.kind),
+    dependsOn: index > 0 ? [`sidecar-${String(index - 1).padStart(4, "0")}:${queue[index - 1].kind}:${queue[index - 1].unitType}:${queue[index - 1].unitId}`] : [],
+    metadata: { index },
+  }));
+}
+
+export async function scheduleSidecarQueue(queue: SidecarItem[]): Promise<SidecarItem[]> {
+  if (queue.length <= 1) return [...queue];
+  const nodes = buildSidecarQueueNodes(queue);
+  const scheduler = new ExecutionGraphScheduler();
+  const orderedIndexes: number[] = [];
+  const seenKinds = new Set<UokGraphNode["kind"]>(nodes.map((n) => n.kind));
+
+  for (const kind of seenKinds) {
+    scheduler.registerHandler(kind, async (node) => {
+      const idx = Number(node.metadata?.index);
+      if (Number.isInteger(idx) && idx >= 0) orderedIndexes.push(idx);
+    });
+  }
+
+  await scheduler.run(nodes, { parallel: false });
+  return orderedIndexes.map((idx) => queue[idx]).filter((item): item is SidecarItem => !!item);
+}
+
+export class ExecutionGraphScheduler {
+  private readonly handlers = new Map<string, ExecutionNodeHandler>();
+
+  registerHandler(kind: UokGraphNode["kind"], handler: ExecutionNodeHandler): void {
+    this.handlers.set(kind, handler);
+  }
+
+  async run(nodes: UokGraphNode[], options?: ExecutionGraphRunOptions): Promise<ExecutionGraphResult> {
+    const sorted = topologicalSort(nodes);
+    const conflicts = detectFileConflicts(nodes);
+
+    // Default deterministic serial execution remains the reference path.
+    if (!options?.parallel) {
+      for (const node of sorted) {
+        const handler = this.handlers.get(node.kind);
+        if (handler) await handler(node);
+      }
+      return { order: sorted.map((n) => n.id), conflicts };
+    }
+
+    // Parallel mode only for nodes whose dependencies are already satisfied.
+    const maxWorkers = Math.max(1, Math.min(8, options.maxWorkers ?? 2));
+    const remaining = new Map(nodes.map((n) => [n.id, n]));
+    const done = new Set<string>();
+    const order: string[] = [];
+
+    while (remaining.size > 0) {
+      const ready = Array.from(remaining.values()).filter((node) =>
+        node.dependsOn.every((dep) => done.has(dep)),
+      );
+      ready.sort((a, b) => a.id.localeCompare(b.id));
+      if (ready.length === 0) {
+        throw new Error("Execution graph deadlock detected: no ready nodes and graph not complete");
+      }
+
+      const batch = ready.slice(0, maxWorkers);
+      await Promise.all(
+        batch.map(async (node) => {
+          const handler = this.handlers.get(node.kind);
+          if (handler) await handler(node);
+          done.add(node.id);
+          order.push(node.id);
+          remaining.delete(node.id);
+        }),
+      );
+    }
+
+    return { order, conflicts };
+  }
+}
+
+function topologicalSort(nodes: UokGraphNode[]): UokGraphNode[] {
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+  const inDegree = new Map(nodes.map((n) => [n.id, 0]));
+
+  for (const node of nodes) {
+    for (const dep of node.dependsOn) {
+      if (nodeMap.has(dep)) {
+        inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+      }
+    }
+  }
+
+  const queue = nodes
+    .filter((n) => (inDegree.get(n.id) ?? 0) === 0)
+    .sort((a, b) => a.id.localeCompare(b.id));
+  const ordered: UokGraphNode[] = [];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    ordered.push(current);
+
+    for (const next of nodes) {
+      if (!next.dependsOn.includes(current.id)) continue;
+      const deg = (inDegree.get(next.id) ?? 0) - 1;
+      inDegree.set(next.id, deg);
+      if (deg === 0) {
+        queue.push(next);
+        queue.sort((a, b) => a.id.localeCompare(b.id));
+      }
+    }
+  }
+
+  if (ordered.length !== nodes.length) {
+    throw new Error("Execution graph has cyclic dependencies");
+  }
+
+  return ordered;
+}
+
+function detectFileConflicts(nodes: UokGraphNode[]): Array<{ nodeA: string; nodeB: string; file: string }> {
+  const conflicts: Array<{ nodeA: string; nodeB: string; file: string }> = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const a = nodes[i];
+    const writesA = new Set(a.writes ?? []);
+    if (writesA.size === 0) continue;
+
+    for (let j = i + 1; j < nodes.length; j++) {
+      const b = nodes[j];
+      for (const file of b.writes ?? []) {
+        if (writesA.has(file)) {
+          conflicts.push({ nodeA: a.id, nodeB: b.id, file });
+        }
+      }
+    }
+  }
+  return conflicts;
+}

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

@@ -0,0 +1,45 @@
+import type { GSDPreferences } from "../preferences.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+
+export interface UokFlags {
+  enabled: boolean;
+  legacyFallback: boolean;
+  gates: boolean;
+  modelPolicy: boolean;
+  executionGraph: boolean;
+  gitops: boolean;
+  gitopsTurnAction: "commit" | "snapshot" | "status-only";
+  gitopsTurnPush: boolean;
+  auditUnified: boolean;
+  planV2: boolean;
+}
+
+function envForcesLegacyFallback(): boolean {
+  const raw = process.env.GSD_UOK_FORCE_LEGACY ?? process.env.GSD_UOK_LEGACY_FALLBACK;
+  if (!raw) return false;
+  const normalized = raw.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+export function resolveUokFlags(prefs: GSDPreferences | undefined): UokFlags {
+  const uok = prefs?.uok;
+  const legacyFallback = uok?.legacy_fallback?.enabled === true || envForcesLegacyFallback();
+  const enabledByPreference = uok?.enabled ?? true;
+  return {
+    enabled: enabledByPreference && !legacyFallback,
+    legacyFallback,
+    gates: uok?.gates?.enabled ?? true,
+    modelPolicy: uok?.model_policy?.enabled ?? true,
+    executionGraph: uok?.execution_graph?.enabled ?? true,
+    gitops: uok?.gitops?.enabled ?? true,
+    gitopsTurnAction: uok?.gitops?.turn_action ?? "commit",
+    gitopsTurnPush: uok?.gitops?.turn_push === true,
+    auditUnified: uok?.audit_unified?.enabled ?? true,
+    planV2: uok?.plan_v2?.enabled ?? true,
+  };
+}
+
+export function loadUokFlags(): UokFlags {
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  return resolveUokFlags(prefs);
+}

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

@@ -0,0 +1,146 @@
+import type { FailureClass, GateResult } from "./contracts.js";
+import { insertGateRun } from "../gsd-db.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+
+export interface GateRunnerContext {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  milestoneId?: string;
+  sliceId?: string;
+  taskId?: string;
+  unitType?: string;
+  unitId?: string;
+}
+
+export interface GateExecutionInput {
+  id: string;
+  type: string;
+  execute: (ctx: GateRunnerContext, attempt: number) => Promise<{
+    outcome: "pass" | "fail" | "retry" | "manual-attention";
+    rationale?: string;
+    findings?: string;
+    failureClass?: FailureClass;
+  }>;
+}
+
+const RETRY_MATRIX: Record<FailureClass, number> = {
+  none: 0,
+  policy: 0,
+  input: 0,
+  execution: 1,
+  artifact: 1,
+  verification: 1,
+  closeout: 1,
+  git: 1,
+  timeout: 2,
+  "manual-attention": 0,
+  unknown: 0,
+};
+
+export class UokGateRunner {
+  private readonly registry = new Map<string, GateExecutionInput>();
+
+  register(gate: GateExecutionInput): void {
+    this.registry.set(gate.id, gate);
+  }
+
+  list(): GateExecutionInput[] {
+    return Array.from(this.registry.values());
+  }
+
+  async run(id: string, ctx: GateRunnerContext): Promise<GateResult> {
+    const gate = this.registry.get(id);
+    if (!gate) {
+      return {
+        gateId: id,
+        gateType: "unknown",
+        outcome: "manual-attention",
+        failureClass: "unknown",
+        rationale: `Gate ${id} not registered`,
+        attempt: 1,
+        maxAttempts: 1,
+        retryable: false,
+        evaluatedAt: new Date().toISOString(),
+      };
+    }
+
+    let attempt = 0;
+    let final: GateResult | null = null;
+    const maxAttemptsByFailureClass = RETRY_MATRIX;
+
+    while (attempt < 3) {
+      attempt += 1;
+      const now = new Date().toISOString();
+      const result = await gate.execute(ctx, attempt);
+      const failureClass = result.failureClass ?? (result.outcome === "pass" ? "none" : "unknown");
+      const retryBudget = maxAttemptsByFailureClass[failureClass] ?? 0;
+      const retryable = result.outcome !== "pass" && attempt <= retryBudget;
+
+      final = {
+        gateId: gate.id,
+        gateType: gate.type,
+        outcome: retryable ? "retry" : result.outcome,
+        failureClass,
+        rationale: result.rationale,
+        findings: result.findings,
+        attempt,
+        maxAttempts: Math.max(1, retryBudget),
+        retryable,
+        evaluatedAt: now,
+      };
+
+      insertGateRun({
+        traceId: ctx.traceId,
+        turnId: ctx.turnId,
+        gateId: final.gateId,
+        gateType: final.gateType,
+        unitType: ctx.unitType,
+        unitId: ctx.unitId,
+        milestoneId: ctx.milestoneId,
+        sliceId: ctx.sliceId,
+        taskId: ctx.taskId,
+        outcome: final.outcome,
+        failureClass: final.failureClass,
+        rationale: final.rationale,
+        findings: final.findings,
+        attempt: final.attempt,
+        maxAttempts: final.maxAttempts,
+        retryable: final.retryable,
+        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,
+          },
+        }),
+      );
+
+      if (!retryable) break;
+    }
+
+    return final ?? {
+      gateId: gate.id,
+      gateType: gate.type,
+      outcome: "manual-attention",
+      failureClass: "unknown",
+      attempt: 1,
+      maxAttempts: 1,
+      retryable: false,
+      evaluatedAt: new Date().toISOString(),
+    };
+  }
+}

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

@@ -0,0 +1,75 @@
+import { isDbAvailable, upsertTurnGitTransaction } from "../gsd-db.js";
+import type { TurnCloseoutRecord } from "./contracts.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+
+export type TurnGitStage = "turn-start" | "stage" | "checkpoint" | "publish" | "record";
+
+interface GitTxArgs {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  unitType?: string;
+  unitId?: string;
+  stage: TurnGitStage;
+  action: "commit" | "snapshot" | "status-only";
+  push: boolean;
+  status: "ok" | "failed";
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function writeTurnGitTransaction(args: GitTxArgs): void {
+  if (!isDbAvailable()) return;
+  upsertTurnGitTransaction({
+    traceId: args.traceId,
+    turnId: args.turnId,
+    unitType: args.unitType,
+    unitId: args.unitId,
+    stage: args.stage,
+    action: args.action,
+    push: args.push,
+    status: args.status,
+    error: args.error,
+    metadata: args.metadata,
+    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 ?? {}),
+      },
+    }),
+  );
+}
+
+export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseoutRecord): void {
+  writeTurnGitTransaction({
+    basePath,
+    traceId: record.traceId,
+    turnId: record.turnId,
+    unitType: record.unitType,
+    unitId: record.unitId,
+    stage: "record",
+    action: record.gitAction,
+    push: record.gitPushed,
+    status: record.failureClass === "git" ? "failed" : "ok",
+    error: record.failureClass === "git" ? "git closeout failure" : undefined,
+    metadata: {
+      turnStatus: record.status,
+      finishedAt: record.finishedAt,
+      activityFile: record.activityFile,
+    },
+  });
+}