gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

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

@@ -1,9 +1,12 @@
+// GSD2 UOK Turn Observer and DB-Backed Lifecycle Emission
+
 import type {
   TurnCloseoutRecord,
   TurnContract,
   TurnResult,
   UokTurnObserver,
 } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateTurnResult } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
 import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
@@ -142,56 +145,68 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
     },
 
     onTurnResult(result): void {
-      const merged: TurnResult = {
-        ...result,
-        phaseResults: result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+      const cleanup = (): void => {
+        if (writerToken) {
+          releaseWriterToken(options.basePath, writerToken);
+        }
+        writerToken = null;
+        current = null;
+        phaseResults.length = 0;
       };
 
-      if (options.enableAudit) {
-        emitUokAuditEvent(
-          options.basePath,
-          buildAuditEnvelope({
-            traceId: merged.traceId,
-            turnId: merged.turnId,
-            category: "orchestration",
-            type: "turn-result",
-            payload: nextSequenceMetadata("audit", "append", {
-              unitType: merged.unitType,
-              unitId: merged.unitId,
-              status: merged.status,
-              failureClass: merged.failureClass,
-              error: merged.error,
-              phaseCount: merged.phaseResults.length,
-            }),
-          }),
-        );
-      }
-
-      if (options.enableGitops) {
-        const closeout: TurnCloseoutRecord = merged.closeout ?? {
-          traceId: merged.traceId,
-          turnId: merged.turnId,
-          unitType: merged.unitType,
-          unitId: merged.unitId,
-          status: merged.status,
-          failureClass: merged.failureClass,
-          gitAction: options.gitAction,
-          gitPushed: options.gitPush,
-          finishedAt: merged.finishedAt,
+      try {
+        const merged: TurnResult = {
+          ...result,
+          version: CURRENT_UOK_CONTRACT_VERSION,
+          phaseResults: Array.isArray(result.phaseResults) && result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
         };
-        writeTurnCloseoutGitRecord(
-          options.basePath,
-          closeout,
-          nextSequenceMetadata("gitops", "update", { action: "record" }),
-        );
-      }
+        const validation = validateTurnResult(merged);
+        if (!validation.ok) {
+          throw new Error(`Invalid UOK turn result: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+        }
 
-      if (writerToken) {
-        releaseWriterToken(options.basePath, writerToken);
+        if (options.enableAudit) {
+          emitUokAuditEvent(
+            options.basePath,
+            buildAuditEnvelope({
+              traceId: validation.value.traceId,
+              turnId: validation.value.turnId,
+              category: "orchestration",
+              type: "turn-result",
+              payload: nextSequenceMetadata("audit", "append", {
+                contractVersion: validation.value.version,
+                unitType: validation.value.unitType,
+                unitId: validation.value.unitId,
+                status: validation.value.status,
+                failureClass: validation.value.failureClass,
+                error: validation.value.error,
+                phaseCount: validation.value.phaseResults.length,
+              }),
+            }),
+          );
+        }
+
+        if (options.enableGitops) {
+          const closeout: TurnCloseoutRecord = merged.closeout ?? {
+            traceId: merged.traceId,
+            turnId: merged.turnId,
+            unitType: merged.unitType,
+            unitId: merged.unitId,
+            status: merged.status,
+            failureClass: merged.failureClass,
+            gitAction: options.gitAction,
+            gitPushed: options.gitPush,
+            finishedAt: merged.finishedAt,
+          };
+          writeTurnCloseoutGitRecord(
+            options.basePath,
+            closeout,
+            nextSequenceMetadata("gitops", "update", { action: "record" }),
+          );
+        }
+      } finally {
+        cleanup();
       }
-      writerToken = null;
-      current = null;
-      phaseResults.length = 0;
     },
   };
 }

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

@@ -1,9 +1,13 @@
+// Project/App: GSD-2
+// File Purpose: UOK plan v2 graph compilation from GSD workflow state.
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { GSDState, Phase } from "../types.js";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks, type SliceRow } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import type { SliceRow } from "../db-task-slice-rows.js";
 import type { UokGraphNode } from "./contracts.js";
 
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;

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

@@ -0,0 +1,158 @@
+// GSD2 UOK Timeline Reconstruction from Authoritative DB Records
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { _getAdapter, isDbAvailable } from "../gsd-db.js";
+import { gsdRoot } from "../paths.js";
+
+export interface TurnTimelineFilter {
+  traceId?: string;
+  turnId?: string;
+}
+
+export interface TurnTimelineEntry {
+  source: "audit_events" | "unit_dispatches" | "turn_git_transactions" | "audit_jsonl";
+  ts: string;
+  traceId?: string;
+  turnId?: string | null;
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export interface TurnTimeline {
+  authoritative: "db" | "degraded-fallback";
+  degraded: boolean;
+  entries: TurnTimelineEntry[];
+}
+
+function parseJsonRecord(value: unknown): Record<string, unknown> {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value !== "string" || value.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function matchesFilter(entry: Pick<TurnTimelineEntry, "traceId" | "turnId">, filter: TurnTimelineFilter): boolean {
+  if (filter.traceId && entry.traceId !== filter.traceId) return false;
+  if (filter.turnId && entry.turnId !== filter.turnId) return false;
+  return true;
+}
+
+function byTimestamp(a: TurnTimelineEntry, b: TurnTimelineEntry): number {
+  return a.ts.localeCompare(b.ts);
+}
+
+function readDbTimeline(filter: TurnTimelineFilter): TurnTimelineEntry[] {
+  const db = _getAdapter();
+  if (!db) return [];
+  const entries: TurnTimelineEntry[] = [];
+  const where: string[] = [];
+  const params: Record<string, string> = {};
+  if (filter.traceId) {
+    where.push("trace_id = :trace_id");
+    params[":trace_id"] = filter.traceId;
+  }
+  if (filter.turnId) {
+    where.push("turn_id = :turn_id");
+    params[":turn_id"] = filter.turnId;
+  }
+  const suffix = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+
+  const auditRows = db.prepare(
+    `SELECT trace_id, turn_id, type, ts, payload_json FROM audit_events${suffix}`,
+  ).all(params) as Array<{ trace_id: string; turn_id: string | null; type: string; ts: string; payload_json: string }>;
+  for (const row of auditRows) {
+    entries.push({
+      source: "audit_events",
+      ts: row.ts,
+      traceId: row.trace_id,
+      turnId: row.turn_id,
+      type: row.type,
+      payload: parseJsonRecord(row.payload_json),
+    });
+  }
+
+  const dispatchRows = db.prepare(
+    `SELECT trace_id, turn_id, unit_type, unit_id, status, started_at, ended_at, exit_reason,
+            error_summary, retry_after_ms, attempt_n, max_attempts
+     FROM unit_dispatches${suffix}`,
+  ).all(params) as Array<Record<string, unknown>>;
+  for (const row of dispatchRows) {
+    entries.push({
+      source: "unit_dispatches",
+      ts: String(row.ended_at ?? row.started_at ?? ""),
+      traceId: String(row.trace_id ?? ""),
+      turnId: typeof row.turn_id === "string" ? row.turn_id : null,
+      type: `dispatch-${String(row.status ?? "unknown")}`,
+      payload: { ...row },
+    });
+  }
+
+  const gitRows = db.prepare(
+    `SELECT trace_id, turn_id, unit_type, unit_id, stage, action, push, status, error,
+            metadata_json, updated_at
+     FROM turn_git_transactions${suffix}`,
+  ).all(params) as Array<Record<string, unknown>>;
+  for (const row of gitRows) {
+    entries.push({
+      source: "turn_git_transactions",
+      ts: String(row.updated_at ?? ""),
+      traceId: String(row.trace_id ?? ""),
+      turnId: typeof row.turn_id === "string" ? row.turn_id : null,
+      type: `gitops-${String(row.stage ?? "unknown")}`,
+      payload: {
+        ...row,
+        metadata: parseJsonRecord(row.metadata_json),
+      },
+    });
+  }
+
+  return entries.filter((entry) => entry.ts !== "").sort(byTimestamp);
+}
+
+function readJsonlTimeline(basePath: string, filter: TurnTimelineFilter): TurnTimelineEntry[] {
+  const path = join(gsdRoot(basePath), "audit", "events.jsonl");
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line): TurnTimelineEntry | null => {
+      const event = parseJsonRecord(line);
+      const entry: TurnTimelineEntry = {
+        source: "audit_jsonl",
+        ts: String(event.ts ?? ""),
+        traceId: typeof event.traceId === "string" ? event.traceId : undefined,
+        turnId: typeof event.turnId === "string" ? event.turnId : null,
+        type: String(event.type ?? "audit"),
+        payload: parseJsonRecord(event.payload),
+      };
+      return entry.ts && matchesFilter(entry, filter) ? entry : null;
+    })
+    .filter((entry): entry is TurnTimelineEntry => entry !== null)
+    .sort(byTimestamp);
+}
+
+export function buildTurnTimeline(basePath: string, filter: TurnTimelineFilter = {}): TurnTimeline {
+  if (isDbAvailable()) {
+    return {
+      authoritative: "db",
+      degraded: false,
+      entries: readDbTimeline(filter),
+    };
+  }
+
+  return {
+    authoritative: "degraded-fallback",
+    degraded: true,
+    entries: readJsonlTimeline(basePath, filter),
+  };
+}

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

@@ -3,13 +3,12 @@
 // Captures structured entries that the auto-loop can drain after each unit
 // to surface root causes for stuck loops, silent degradation, and blocked writes.
 // Error-severity entries are persisted to .gsd/audit-log.jsonl (sanitized) for
-// post-mortem analysis. Warnings are ephemeral (stderr + buffer only) to avoid
-// log amplification from expected-control-flow catch paths.
+// post-mortem analysis. Warnings persist to notifications and remain available
+// in the in-memory buffer, but are not printed to stderr.
 //
-// Stderr policy: every logWarning/logError call writes immediately to stderr
-// for terminal visibility. This is intentional — unlike debug-logger (which is
-// opt-in and zero-overhead when disabled), workflow-logger covers operational
-// warnings/errors that should always be visible. There is no disable flag.
+// Stderr policy: logError writes immediately to stderr for terminal visibility.
+// logWarning stays out of the TUI/stdout stream and is surfaced through the
+// notification store plus the auto-loop issue buffer.
 //
 // Singleton safety: _buffer is module-level and shared across all calls within
 // a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
@@ -109,7 +108,8 @@ export function setStderrLoggingEnabled(enabled: boolean): boolean {
 // ─── Public API ─────────────────────────────────────────────────────────
 
 /**
- * Record a warning. Also writes to stderr for terminal visibility.
+ * Record a warning. Warnings are persisted to notifications and buffered for
+ * auto-loop issue summaries, but they are intentionally not written to stderr.
  */
 export function logWarning(
   component: LogComponent,
@@ -271,10 +271,10 @@ function _push(
     ...(context ? { context } : {}),
   };
 
-  // Always forward to stderr so terminal watchers see it (see module header for policy)
-  const prefix = severity === "error" ? "ERROR" : "WARN";
-  const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
-  _writeStderr(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`);
+  if (severity === "error") {
+    const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
+    _writeStderr(`[gsd:${component}] ERROR: ${message}${ctxStr}\n`);
+  }
 
   // Persist to notification store (both warnings and errors)
   try {
@@ -317,8 +317,8 @@ function _push(
   }
 
   // Persist errors to .gsd/audit-log.jsonl so they survive context resets.
-  // Only error-severity entries are persisted — warnings are ephemeral (stderr + buffer)
-  // to avoid log amplification from expected-control-flow catch paths.
+  // Warnings are already persisted to notifications and buffered for the
+  // current auto-loop unit.
   if (_auditBasePath && severity === "error") {
     try {
       const auditDir = join(_auditBasePath, ".gsd");

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

@@ -1,11 +1,14 @@
+// Project/App: GSD-2
+// File Purpose: State manifest snapshot and restore orchestration for GSD workflow data.
+
 import {
   _getAdapter,
   readTransaction,
   restoreManifest,
-  type MilestoneRow,
-  type SliceRow,
-  type TaskRow,
 } from "./gsd-db.js";
+import type { MilestoneRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
+import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import type { Decision } from "./types.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
@@ -13,18 +16,6 @@ import { join } from "node:path";
 
 // ─── Manifest Types ──────────────────────────────────────────────────────
 
-export interface VerificationEvidenceRow {
-  id: number;
-  task_id: string;
-  slice_id: string;
-  milestone_id: string;
-  command: string;
-  exit_code: number | null;
-  verdict: string;
-  duration_ms: number | null;
-  created_at: string;
-}
-
 export interface StateManifest {
   version: 1;
   exported_at: string; // ISO 8601

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Projection renderers for GSD workflow database rows.
 // GSD Extension — Projection Renderers (DB -> Markdown)
 // Renders PLAN.md, ROADMAP.md, SUMMARY.md, and STATE.md from database rows.
 // Projections are read-only views of engine state (Layer 3 of the architecture).
@@ -11,7 +13,9 @@ import {
   getSliceTasks,
   getVerificationEvidence,
 } from "./gsd-db.js";
-import type { MilestoneRow, SliceRow, TaskRow, VerificationEvidenceRow } from "./gsd-db.js";
+import type { MilestoneRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
+import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { join } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Workflow template registry loading, matching, and display helpers.
+
 /**
  * GSD Workflow Templates — Registry & Resolution
  *
@@ -9,6 +12,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdHome } from "./gsd-home.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
 
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
@@ -30,6 +34,10 @@ export type WorkflowMode =
   | "markdown-phase"
   | "auto-milestone";
 
+export function isLegacyWorkflowMode(mode: WorkflowMode | undefined): boolean {
+  return (mode ?? "markdown-phase") !== "auto-milestone";
+}
+
 export interface TemplateEntry {
   name: string;
   description: string;
@@ -213,6 +221,9 @@ export function listTemplates(): string {
 
   lines.push("Usage: /gsd start <template> [description]");
   lines.push("       /gsd templates info <name>");
+  lines.push("");
+  lines.push("Recommended Task Paths:");
+  lines.push(formatRecommendedProcessPaths());
 
   return lines.join("\n");
 }

package/src/resources/extensions/gsd/working-output-messages.ts

@@ -0,0 +1,120 @@
+// GSD-2 + src/resources/extensions/gsd/working-output-messages.ts - Formats and audits user-facing working-state messages.
+
+export type WorkingOutputSurface =
+  | "loader"
+  | "dashboard"
+  | "status"
+  | "notification"
+  | "assistant"
+  | "tool";
+
+export type WorkingHealthState =
+  | "healthy"
+  | "waiting"
+  | "recovering"
+  | "stalled"
+  | "provider-error"
+  | "timeout"
+  | "stopped";
+
+export interface WorkingOutputContext {
+  unitType?: string;
+  unitId?: string;
+  health?: WorkingHealthState;
+  elapsedMs?: number;
+  recoveryAttempts?: number;
+}
+
+export interface WorkingOutputMessage {
+  surface: WorkingOutputSurface;
+  message: string;
+  context?: WorkingOutputContext;
+}
+
+export interface WorkingOutputFinding {
+  code:
+    | "empty-message"
+    | "generic-working-message"
+    | "misleading-healthy-message"
+    | "fake-zero-progress"
+    | "missing-action";
+  severity: "error" | "warning";
+  detail: string;
+}
+
+const ACTION_RE = /\b(?:wait|pause|paused|retry|retrying|recover|recovering|resume|stop|stopped|run|press|type|configure|restart)\b/i;
+
+export function formatAutoUnitWorkingMessage(unitType: string, unitId: string): string {
+  switch (unitType) {
+    case "research-milestone":
+    case "research-slice":
+      return `Researching ${unitId}: waiting for provider response`;
+    case "plan-milestone":
+    case "plan-slice":
+      return `Planning ${unitId}: waiting for provider response`;
+    case "execute-task":
+      return `Executing ${unitId}: waiting for provider response`;
+    case "complete-slice":
+    case "complete-milestone":
+      return `Completing ${unitId}: waiting for provider response`;
+    default:
+      return `${unitType} ${unitId}: waiting for provider response`;
+  }
+}
+
+export function evaluateWorkingOutputMessage(
+  item: WorkingOutputMessage,
+): WorkingOutputFinding[] {
+  const findings: WorkingOutputFinding[] = [];
+  const message = item.message.trim();
+  const health = item.context?.health;
+
+  if (!message) {
+    findings.push({
+      code: "empty-message",
+      severity: "error",
+      detail: `${item.surface} message is empty`,
+    });
+    return findings;
+  }
+
+  if (/^Working(?:\.\.\.)?(?:\s|\(|$)/i.test(message)) {
+    findings.push({
+      code: "generic-working-message",
+      severity: "warning",
+      detail: `${item.surface} message should say what work is running`,
+    });
+  }
+
+  if (/Progressing well/i.test(message) && health && health !== "healthy") {
+    findings.push({
+      code: "misleading-healthy-message",
+      severity: "error",
+      detail: `${item.surface} says progress is healthy while runtime health is ${health}`,
+    });
+  }
+
+  if (/\b0\s*\/\s*0\s+slices\b/i.test(message)) {
+    findings.push({
+      code: "fake-zero-progress",
+      severity: "warning",
+      detail: `${item.surface} should hide roadmap progress before roadmap slices exist`,
+    });
+  }
+
+  if ((health === "stalled" || health === "provider-error" || health === "timeout") && !ACTION_RE.test(message)) {
+    findings.push({
+      code: "missing-action",
+      severity: "warning",
+      detail: `${item.surface} should give the user a next action for ${health}`,
+    });
+  }
+
+  return findings;
+}
+
+export function evaluateWorkingOutputMessages(
+  items: WorkingOutputMessage[],
+): WorkingOutputFinding[] {
+  return items.flatMap(evaluateWorkingOutputMessage);
+}

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

@@ -70,6 +70,15 @@ export interface WorktreeDiffSummary {
   removed: string[];
 }
 
+function deleteBranchIfPresent(basePath: string, branch: string, warningPrefix: string): void {
+  try {
+    if (!nativeBranchExists(basePath, branch)) return;
+    nativeBranchDelete(basePath, branch, true);
+  } catch (e) {
+    logWarning("worktree", `${warningPrefix}: ${(e as Error).message}`);
+  }
+}
+
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 
 function normalizePathForComparison(path: string): string {
@@ -408,7 +417,7 @@ export function listWorktrees(basePath: string): WorktreeInfo[] {
 
 /** Directories to skip when scanning for nested .git dirs. */
 const NESTED_GIT_SKIP_DIRS = new Set([
-  ".git", ".gsd", "node_modules", ".next", ".nuxt", "dist", "build",
+  ".git", ".gsd", ".bg-shell", "node_modules", ".next", ".nuxt", "dist", "build",
   "__pycache__", ".tox", ".venv", "venv", "target", "vendor",
 ]);
 
@@ -462,7 +471,9 @@ export function findNestedGitDirs(rootPath: string): string[] {
           continue;
         }
       } catch (e) {
-        logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${(e as Error).message}`);
+        if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
+          logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${(e as Error).message}`);
+        }
       }
 
       walk(fullPath, depth + 1);
@@ -535,7 +546,7 @@ export function removeWorktree(
   if (!existsSync(wtPath)) {
     nativeWorktreePrune(basePath);
     if (deleteBranch) {
-      try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `nativeBranchDelete failed: ${(e as Error).message}`); }
+      deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
     }
     return;
   }
@@ -670,7 +681,7 @@ export function removeWorktree(
   nativeWorktreePrune(basePath);
 
   if (deleteBranch) {
-    try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `final branch delete failed: ${(e as Error).message}`); }
+    deleteBranchIfPresent(basePath, branch, "final branch delete failed");
   }
 }