gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

package/src/resources/extensions/gsd/uok/dispatch-envelope.ts

@@ -0,0 +1,56 @@
+import type {
+  DispatchExplanation,
+  DispatchReasonCode,
+  GateResult,
+  UokDispatchEnvelope,
+  UokGraphNode,
+} from "./contracts.js";
+
+export interface BuildDispatchEnvelopeInput {
+  action: UokDispatchEnvelope["action"];
+  node?: Pick<UokGraphNode, "kind" | "reads" | "writes" | "dependsOn">;
+  unitType?: string;
+  unitId?: string;
+  prompt?: string;
+  reasonCode: DispatchReasonCode;
+  summary: string;
+  evidence?: Record<string, unknown>;
+  blockedBy?: DispatchExplanation["blockedBy"];
+  gateVerdict?: GateResult;
+  trace?: UokDispatchEnvelope["trace"];
+}
+
+export function buildDispatchEnvelope(input: BuildDispatchEnvelopeInput): UokDispatchEnvelope {
+  return {
+    action: input.action,
+    nodeKind: input.node?.kind,
+    unitType: input.unitType,
+    unitId: input.unitId,
+    prompt: input.prompt,
+    reason: {
+      reasonCode: input.reasonCode,
+      summary: input.summary,
+      evidence: input.evidence,
+      blockedBy: input.blockedBy,
+    },
+    gateVerdict: input.gateVerdict,
+    constraints: input.node
+      ? {
+          reads: input.node.reads,
+          writes: input.node.writes,
+          dependsOn: input.node.dependsOn,
+        }
+      : undefined,
+    trace: input.trace,
+  };
+}
+
+export function explainDispatch(envelope: UokDispatchEnvelope): string {
+  const subject = envelope.unitType && envelope.unitId
+    ? `${envelope.unitType} ${envelope.unitId}`
+    : envelope.nodeKind ?? envelope.action;
+  const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+    ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+    : "";
+  return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

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

@@ -12,6 +12,14 @@ export interface ExecutionGraphResult {
   conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
 }
 
+export interface ExecutionGraphSnapshot {
+  capturedAt: string;
+  phase: "before-unit" | "after-unit";
+  nodes: UokGraphNode[];
+  order: string[];
+  conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
+}
+
 export type ExecutionNodeHandler = (node: UokGraphNode) => Promise<void>;
 
 export interface ConflictFreeBatchInput {
@@ -113,6 +121,20 @@ export function buildSidecarQueueNodes(queue: SidecarItem[]): UokGraphNode[] {
   }));
 }
 
+export function buildExecutionGraphSnapshot(
+  nodes: UokGraphNode[],
+  phase: ExecutionGraphSnapshot["phase"],
+): ExecutionGraphSnapshot {
+  const sorted = topologicalSort(nodes);
+  return {
+    capturedAt: new Date().toISOString(),
+    phase,
+    nodes: sorted,
+    order: sorted.map((node) => node.id),
+    conflicts: detectFileConflicts(nodes),
+  };
+}
+
 export async function scheduleSidecarQueue(queue: SidecarItem[]): Promise<SidecarItem[]> {
   if (queue.length <= 1) return [...queue];
   const nodes = buildSidecarQueueNodes(queue);

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

@@ -52,7 +52,8 @@ export class UokGateRunner {
   async run(id: string, ctx: GateRunnerContext): Promise<GateResult> {
     const gate = this.registry.get(id);
     if (!gate) {
-      return {
+      const now = new Date().toISOString();
+      const unknownResult: GateResult = {
         gateId: id,
         gateType: "unknown",
         outcome: "manual-attention",
@@ -61,18 +62,77 @@ export class UokGateRunner {
         attempt: 1,
         maxAttempts: 1,
         retryable: false,
-        evaluatedAt: new Date().toISOString(),
+        evaluatedAt: now,
       };
+
+      insertGateRun({
+        traceId: ctx.traceId,
+        turnId: ctx.turnId,
+        gateId: unknownResult.gateId,
+        gateType: unknownResult.gateType,
+        unitType: ctx.unitType,
+        unitId: ctx.unitId,
+        milestoneId: ctx.milestoneId,
+        sliceId: ctx.sliceId,
+        taskId: ctx.taskId,
+        outcome: unknownResult.outcome,
+        failureClass: unknownResult.failureClass,
+        rationale: unknownResult.rationale,
+        findings: unknownResult.findings,
+        attempt: unknownResult.attempt,
+        maxAttempts: unknownResult.maxAttempts,
+        retryable: unknownResult.retryable,
+        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,
+          },
+        }),
+      );
+
+      return unknownResult;
     }
 
     let attempt = 0;
     let final: GateResult | null = null;
     const maxAttemptsByFailureClass = RETRY_MATRIX;
+    const maxAttemptsCeiling = Math.max(...Object.values(RETRY_MATRIX)) + 1;
 
-    while (attempt < 3) {
+    while (attempt < maxAttemptsCeiling) {
       attempt += 1;
       const now = new Date().toISOString();
-      const result = await gate.execute(ctx, attempt);
+
+      let result: {
+        outcome: "pass" | "fail" | "retry" | "manual-attention";
+        rationale?: string;
+        findings?: string;
+        failureClass?: FailureClass;
+      };
+
+      try {
+        result = await gate.execute(ctx, attempt);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        result = {
+          outcome: "fail",
+          failureClass: "unknown",
+          rationale: message,
+        };
+      }
       const failureClass = result.failureClass ?? (result.outcome === "pass" ? "none" : "unknown");
       const retryBudget = maxAttemptsByFailureClass[failureClass] ?? 0;
       const retryable = result.outcome !== "pass" && attempt <= retryBudget;
@@ -85,7 +145,7 @@ export class UokGateRunner {
         rationale: result.rationale,
         findings: result.findings,
         attempt,
-        maxAttempts: Math.max(1, retryBudget),
+        maxAttempts: retryBudget + 1,
         retryable,
         evaluatedAt: now,
       };

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

@@ -54,7 +54,11 @@ export function writeTurnGitTransaction(args: GitTxArgs): void {
   );
 }
 
-export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseoutRecord): void {
+export function writeTurnCloseoutGitRecord(
+  basePath: string,
+  record: TurnCloseoutRecord,
+  metadata?: Record<string, unknown>,
+): void {
   writeTurnGitTransaction({
     basePath,
     traceId: record.traceId,
@@ -67,6 +71,7 @@ export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseou
     status: record.failureClass === "git" ? "failed" : "ok",
     error: record.failureClass === "git" ? "git closeout failure" : undefined,
     metadata: {
+      ...(metadata ?? {}),
       turnStatus: record.status,
       finishedAt: record.finishedAt,
       activityFile: record.activityFile,

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -6,6 +6,7 @@ import type {
 } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 
 export interface CreateTurnObserverOptions {
   basePath: string;
@@ -17,12 +18,38 @@ export interface CreateTurnObserverOptions {
 
 export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnObserver {
   let current: TurnContract | null = null;
+  let writerToken: ReturnType<typeof acquireWriterToken> | null = null;
   const phaseResults: TurnResult["phaseResults"] = [];
 
+  function nextSequenceMetadata(
+    category: "audit" | "gitops",
+    operation: "append" | "insert" | "update",
+    metadata?: Record<string, unknown>,
+  ): Record<string, unknown> {
+    if (!writerToken) return metadata ?? {};
+    const record = nextWriteRecord({
+      basePath: options.basePath,
+      token: writerToken,
+      category,
+      operation,
+      metadata,
+    });
+    return {
+      ...(metadata ?? {}),
+      writeSequence: record.sequence.sequence,
+      writerTokenId: record.writerToken.tokenId,
+    };
+  }
+
   return {
     onTurnStart(contract): void {
       current = contract;
       phaseResults.length = 0;
+      writerToken = acquireWriterToken({
+        basePath: options.basePath,
+        traceId: contract.traceId,
+        turnId: contract.turnId,
+      });
 
       if (options.enableGitops) {
         writeTurnGitTransaction({
@@ -35,10 +62,10 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: {
+          metadata: nextSequenceMetadata("gitops", "insert", {
             iteration: contract.iteration,
             sidecarKind: contract.sidecarKind,
-          },
+          }),
         });
       }
 
@@ -50,12 +77,12 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: contract.turnId,
             category: "orchestration",
             type: "turn-start",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               iteration: contract.iteration,
               unitType: contract.unitType,
               unitId: contract.unitId,
               sidecarKind: contract.sidecarKind,
-            },
+            }),
           }),
         );
       }
@@ -81,7 +108,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "unit") {
@@ -95,7 +122,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "finalize") {
@@ -109,7 +136,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
     },
@@ -128,14 +155,14 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: merged.turnId,
             category: "orchestration",
             type: "turn-result",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               unitType: merged.unitType,
               unitId: merged.unitId,
               status: merged.status,
               failureClass: merged.failureClass,
               error: merged.error,
               phaseCount: merged.phaseResults.length,
-            },
+            }),
           }),
         );
       }
@@ -152,9 +179,17 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           gitPushed: options.gitPush,
           finishedAt: merged.finishedAt,
         };
-        writeTurnCloseoutGitRecord(options.basePath, closeout);
+        writeTurnCloseoutGitRecord(
+          options.basePath,
+          closeout,
+          nextSequenceMetadata("gitops", "update", { action: "record" }),
+        );
       }
 
+      if (writerToken) {
+        releaseWriterToken(options.basePath, writerToken);
+      }
+      writerToken = null;
       current = null;
       phaseResults.length = 0;
     },

package/src/resources/extensions/gsd/uok/parity-report.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdRoot } from "../paths.js";
+
+export interface UokParityEvent {
+  ts?: string;
+  path?: string;
+  phase?: string;
+  status?: string;
+  error?: string;
+  flags?: Record<string, unknown>;
+}
+
+export interface UokParityReport {
+  generatedAt: string;
+  sourcePath: string;
+  totalEvents: number;
+  paths: Record<string, number>;
+  statuses: Record<string, number>;
+  criticalMismatches: string[];
+  fallbackInvocations: number;
+}
+
+function parityLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+
+function reportPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+
+function increment(bucket: Record<string, number>, key: string | undefined): void {
+  const normalized = key && key.trim().length > 0 ? key : "unknown";
+  bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+
+export function parseParityEvents(raw: string): UokParityEvent[] {
+  return raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as UokParityEvent;
+      } catch {
+        return { status: "error", error: "invalid parity json line" };
+      }
+    });
+}
+
+export function buildParityReport(events: readonly UokParityEvent[], sourcePath: string): UokParityReport {
+  const paths: Record<string, number> = {};
+  const statuses: Record<string, number> = {};
+  const criticalMismatches: string[] = [];
+  let fallbackInvocations = 0;
+
+  for (const event of events) {
+    increment(paths, event.path);
+    increment(statuses, event.status);
+    if (event.path === "legacy-fallback") fallbackInvocations += 1;
+    if (event.status === "error") {
+      criticalMismatches.push(event.error ?? "parity event reported error");
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    sourcePath,
+    totalEvents: events.length,
+    paths,
+    statuses,
+    criticalMismatches,
+    fallbackInvocations,
+  };
+}
+
+export function writeParityReport(basePath: string): UokParityReport {
+  const sourcePath = parityLogPath(basePath);
+  const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+  const report = buildParityReport(parseParityEvents(raw), sourcePath);
+  mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+  writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+  return report;
+}

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -7,13 +7,17 @@ import { isDbAvailable, getMilestoneSlices, getSliceTasks, type SliceRow } from
 import type { UokGraphNode } from "./contracts.js";
 
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
-const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
+export const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
   "executing",
   "summarizing",
   "validating-milestone",
   "completing-milestone",
 ]);
 
+export function isExecutionEntryPhase(phase: Phase): boolean {
+  return EXECUTION_ENTRY_PHASES.has(phase);
+}
+
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
@@ -61,6 +65,14 @@ function hasMilestoneFileContent(
   return false;
 }
 
+export function hasFinalizedMilestoneContext(basePath: string, milestoneId: string): boolean {
+  return hasMilestoneFileContent(basePath, milestoneId, "CONTEXT");
+}
+
+export function isMissingFinalizedContextResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.finalizedContextIncluded === false;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -71,10 +83,6 @@ function countSliceResearchArtifacts(basePath: string, milestoneId: string, slic
   return count;
 }
 
-function isExecutionEntryPhase(phase: Phase): boolean {
-  return EXECUTION_ENTRY_PHASES.has(phase);
-}
-
 export function compileUnitGraphFromState(basePath: string, state: GSDState): PlanV2CompileResult {
   const mid = state.activeMilestone?.id;
   if (!mid) return { ok: false, reason: "no active milestone" };

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

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { atomicWriteSync } from "../atomic-write.js";
+import { gsdRoot } from "../paths.js";
+import type { WriteRecord, WriterToken } from "./contracts.js";
+
+interface SequenceState {
+  lastSequence: number;
+  updatedAt: string;
+}
+
+const activeTokens = new Map<string, WriterToken>();
+
+function tokenKey(basePath: string, turnId: string): string {
+  return `${basePath}:${turnId}`;
+}
+
+function sequencePath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-writer-sequence.json");
+}
+
+function readSequenceState(basePath: string): SequenceState {
+  const path = sequencePath(basePath);
+  if (!existsSync(path)) {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<SequenceState>;
+    return {
+      lastSequence: Number.isInteger(parsed.lastSequence) ? Number(parsed.lastSequence) : 0,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString(),
+    };
+  } catch {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+}
+
+function writeSequenceState(basePath: string, state: SequenceState): void {
+  atomicWriteSync(sequencePath(basePath), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+export function acquireWriterToken(args: {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  owner?: WriterToken["owner"];
+}): WriterToken {
+  const key = tokenKey(args.basePath, args.turnId);
+  const existing = activeTokens.get(key);
+  if (existing) {
+    throw new Error(`Writer token already active for turn ${args.turnId}`);
+  }
+
+  const token: WriterToken = {
+    tokenId: randomUUID(),
+    traceId: args.traceId,
+    turnId: args.turnId,
+    acquiredAt: new Date().toISOString(),
+    owner: args.owner ?? "uok",
+  };
+  activeTokens.set(key, token);
+  return token;
+}
+
+export function releaseWriterToken(basePath: string, token: WriterToken): void {
+  const key = tokenKey(basePath, token.turnId);
+  const current = activeTokens.get(key);
+  if (current?.tokenId === token.tokenId) {
+    activeTokens.delete(key);
+  }
+}
+
+export function hasActiveWriterToken(basePath: string, turnId: string): boolean {
+  return activeTokens.has(tokenKey(basePath, turnId));
+}
+
+export function nextWriteRecord(args: {
+  basePath: string;
+  token: WriterToken;
+  category: WriteRecord["category"];
+  operation: WriteRecord["operation"];
+  path?: string;
+  metadata?: Record<string, unknown>;
+}): WriteRecord {
+  if (!hasActiveWriterToken(args.basePath, args.token.turnId)) {
+    throw new Error(`Writer token is not active for turn ${args.token.turnId}`);
+  }
+
+  const state = readSequenceState(args.basePath);
+  const sequence = state.lastSequence + 1;
+  const updatedAt = new Date().toISOString();
+  writeSequenceState(args.basePath, { lastSequence: sequence, updatedAt });
+
+  return {
+    writerToken: args.token,
+    sequence: {
+      traceId: args.token.traceId,
+      turnId: args.token.turnId,
+      sequence,
+    },
+    category: args.category,
+    operation: args.operation,
+    path: args.path,
+    ts: updatedAt,
+    metadata: args.metadata,
+  };
+}
+
+export function resetWriterTokensForTests(): void {
+  activeTokens.clear();
+}

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -33,6 +33,7 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "gsd_journal_query",
   "gsd_milestone_complete",
   "gsd_milestone_generate_id",
+  "gsd_milestone_reopen",
   "gsd_checkpoint_db",
   "gsd_milestone_status",
   "gsd_milestone_validate",
@@ -41,6 +42,9 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "gsd_plan_slice",
   "gsd_replan_slice",
   "gsd_reassess_roadmap",
+  "gsd_reopen_milestone",
+  "gsd_reopen_slice",
+  "gsd_reopen_task",
   "gsd_requirement_save",
   "gsd_requirement_update",
   "gsd_roadmap_reassess",
@@ -50,9 +54,11 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "gsd_skip_slice",
   "gsd_slice_replan",
   "gsd_slice_complete",
+  "gsd_slice_reopen",
   "gsd_summary_save",
   "gsd_task_plan",
   "gsd_task_complete",
+  "gsd_task_reopen",
   "gsd_update_requirement",
   "gsd_validate_milestone",
 ]);