gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

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/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;
@@ -38,6 +42,37 @@ function hasFileContent(path: string | null): boolean {
   }
 }
 
+function getArtifactLookupBases(basePath: string): string[] {
+  const bases = [basePath];
+  const projectRoot = process.env.GSD_PROJECT_ROOT;
+  if (projectRoot && projectRoot.trim().length > 0 && projectRoot !== basePath) {
+    bases.push(projectRoot);
+  }
+  return bases;
+}
+
+function hasMilestoneFileContent(
+  basePath: string,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  const bases = getArtifactLookupBases(basePath);
+  for (const candidateBase of bases) {
+    if (hasFileContent(resolveMilestoneFile(candidateBase, milestoneId, suffix))) {
+      return true;
+    }
+  }
+  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) {
@@ -48,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" };
@@ -60,9 +91,9 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
   const slices = getMilestoneSlices(mid).sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
   const nodes: UokGraphNode[] = [];
   const clarifyRoundLimit = PLAN_V2_CLARIFY_ROUND_LIMIT;
-  const draftContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"));
-  const finalizedContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT"));
-  const researchSynthesized = hasFileContent(resolveMilestoneFile(basePath, mid, "RESEARCH"))
+  const draftContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT-DRAFT");
+  const finalizedContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT");
+  const researchSynthesized = hasMilestoneFileContent(basePath, mid, "RESEARCH")
     || countSliceResearchArtifacts(basePath, mid, slices) > 0;
 
   if (isExecutionEntryPhase(state.phase) && !finalizedContextIncluded) {

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-logger.ts

@@ -16,9 +16,17 @@
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
 
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
+import { withFileLockSync } from "./file-lock.js";
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -56,7 +64,11 @@ export type LogComponent =
   | "safety"        // LLM safety harness
   | "ecosystem"     // GSD ecosystem extension loader and dispatch
   | "memory-embeddings" // Memory layer embedding generation
-  | "memory-ingest";    // Memory layer ingestion pipeline
+  | "memory-ingest"     // Memory layer ingestion pipeline
+  | "memory-backfill"   // ADR-013: decisions->memories backfill
+  | "context-mode"     // Context-mode exec sandbox and compaction snapshot
+  | "preflight"        // Clean-root preflight gate at milestone completion
+  | "postUnit";     // Post-unit processing (abandon detection, overrides)
 
 export interface LogEntry {
   ts: string;
@@ -310,8 +322,18 @@ function _push(
     try {
       const auditDir = join(_auditBasePath, ".gsd");
       mkdirSync(auditDir, { recursive: true });
+      const auditPath = join(auditDir, "audit-log.jsonl");
       const sanitized = _sanitizeForAudit(entry);
-      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8");
+      // Ensure file exists so proper-lockfile can acquire a lock against it.
+      if (!existsSync(auditPath)) closeSync(openSync(auditPath, "a"));
+      // onLocked: "skip" — never block error logging on lock contention.
+      withFileLockSync(
+        auditPath,
+        () => {
+          appendFileSync(auditPath, JSON.stringify(sanitized) + "\n", "utf-8");
+        },
+        { onLocked: "skip" },
+      );
     } catch (auditErr) {
       // Best-effort — never let audit write failures bubble up
       _writeStderr(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);

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

@@ -23,6 +23,9 @@ export interface WorkflowCapabilityOptions {
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "ask_user_questions",
   "gsd_decision_save",
+  "gsd_exec",
+  "gsd_exec_search",
+  "gsd_resume",
   "gsd_complete_milestone",
   "gsd_complete_task",
   "gsd_complete_slice",

package/src/resources/extensions/gsd/workflow-templates/spike.md

@@ -66,5 +66,11 @@ Use for: technology evaluation, architecture decisions, "should we X?" questions
    - Recommendation with rationale
    - Next steps if the recommendation is accepted
 4. **Present** the recommendation to the user for discussion
+5. **Offer wrap-up:** If the findings are reusable on future work, offer to run
+   the `spike-wrap-up` skill to package them as a project-local skill at
+   `.claude/skills/<name>/SKILL.md`. That skill will auto-load on future
+   similar tasks via `skill-discovery.ts`. If the recommendation is
+   decision-only (no reusable guidance), suggest appending a one-liner to
+   `.gsd/DECISIONS.md` instead.
 
 </process>

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -37,6 +37,7 @@ import {
   nativeWorktreePrune,
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -132,6 +133,58 @@ export function isInsideWorktreesDir(basePath: string, targetPath: string): bool
   return resolved === wtDir || resolved.startsWith(wtDir + sep);
 }
 
+/**
+ * Return the canonical path from which a milestone's artifacts should be read.
+ *
+ * If a live git worktree exists for this milestone at `.gsd/worktrees/<MID>/`
+ * (directory present AND a `.git` file indicating a registered worktree),
+ * returns that worktree path. Otherwise returns `basePath` unchanged.
+ *
+ * Readers that cross the session/worktree boundary (validators, the bootstrap
+ * audit, cross-session state queries) should route through this helper so they
+ * don't silently read stale project-root state while live work sits in the
+ * worktree. Writers and tools whose contract is "operate on the path I was
+ * given" should NOT use this helper — they preserve the legacy behavior.
+ *
+ * A stale worktree directory (no `.git` file) is treated as absent. The
+ * createWorktree() path already cleans these up, but readers must not trust
+ * them in the window before cleanup runs.
+ *
+ * Fixes #4761. Used by the #4762 audit for the pre-completion orphan case.
+ */
+export function resolveCanonicalMilestoneRoot(
+  basePath: string,
+  milestoneId: string,
+): string {
+  if (!milestoneId || /[\/\\]|\.\./.test(milestoneId)) return basePath;
+
+  const wtPath = worktreePath(basePath, milestoneId);
+  if (!existsSync(wtPath)) return basePath;
+
+  // A registered git worktree has a .git *file* (not directory) containing
+  // "gitdir: <path>". A standalone .git directory indicates a copied repo
+  // or nested standalone repo — not a worktree registered with this project —
+  // and must not be treated as the canonical root.
+  const gitPath = join(wtPath, ".git");
+  if (!existsSync(gitPath)) return basePath;
+  try {
+    const stat = lstatSync(gitPath);
+    if (!stat.isFile()) return basePath;
+  } catch {
+    return basePath;
+  }
+
+  // #4764 — record the redirect so we can measure how often the #4761 fix
+  // would have mattered. Best-effort; emit is silent on any failure.
+  try {
+    emitCanonicalRootRedirect(basePath, milestoneId, wtPath);
+  } catch (err) {
+    logWarning("worktree", `canonical-root-redirect telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return wtPath;
+}
+
 // ─── Core Operations ───────────────────────────────────────────────────────
 
 /**
@@ -559,6 +612,7 @@ const SKIP_PATHS = [
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/parallel/",
   ".gsd/journal/",