gsd-pi 2.18.0 → 2.20.0

package/dist/resources/extensions/gsd/debug-logger.ts

@@ -0,0 +1,178 @@
+// GSD Extension — Debug Logger
+// Structured JSONL debug logging for diagnosing stuck/slow GSD sessions.
+// Zero overhead when disabled — all public functions are no-ops.
+
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { gsdRoot } from './paths.js';
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+let _enabled = false;
+let _logPath: string | null = null;
+let _startTime = 0;
+
+/** Rolling counters for the debug summary written on stop. */
+const _counters = {
+  deriveStateCalls: 0,
+  deriveStateTotalMs: 0,
+  ttsrChecks: 0,
+  ttsrTotalMs: 0,
+  ttsrPeakBuffer: 0,
+  parseRoadmapCalls: 0,
+  parseRoadmapTotalMs: 0,
+  parsePlanCalls: 0,
+  parsePlanTotalMs: 0,
+  dispatches: 0,
+  renders: 0,
+};
+
+/** Max debug log files to keep. Older ones are pruned on enable. */
+const MAX_DEBUG_LOGS = 5;
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Enable debug logging. Creates the log file and prunes old logs.
+ * Can be activated via `--debug` flag or `GSD_DEBUG=1` env var.
+ */
+export function enableDebug(basePath: string): void {
+  const debugDir = join(gsdRoot(basePath), 'debug');
+  mkdirSync(debugDir, { recursive: true });
+
+  // Prune old debug logs
+  try {
+    const files = readdirSync(debugDir)
+      .filter(f => f.startsWith('debug-') && f.endsWith('.log'))
+      .sort();
+    while (files.length >= MAX_DEBUG_LOGS) {
+      const oldest = files.shift()!;
+      try { unlinkSync(join(debugDir, oldest)); } catch { /* ignore */ }
+    }
+  } catch { /* non-fatal */ }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  _logPath = join(debugDir, `debug-${timestamp}.log`);
+  _startTime = Date.now();
+  _enabled = true;
+
+  // Reset counters
+  for (const key of Object.keys(_counters) as (keyof typeof _counters)[]) {
+    _counters[key] = 0;
+  }
+}
+
+/** Disable debug logging and return the log file path (if any). */
+export function disableDebug(): string | null {
+  const path = _logPath;
+  _enabled = false;
+  _logPath = null;
+  _startTime = 0;
+  return path;
+}
+
+/** Check if debug mode is active. */
+export function isDebugEnabled(): boolean {
+  return _enabled;
+}
+
+/** Return the current log file path (or null). */
+export function getDebugLogPath(): string | null {
+  return _logPath;
+}
+
+/**
+ * Log a structured debug event. No-op when debug is disabled.
+ *
+ * Each event is one JSON line: `{ ts, event, ...data }`
+ */
+export function debugLog(event: string, data?: Record<string, unknown>): void {
+  if (!_enabled || !_logPath) return;
+
+  const entry = {
+    ts: new Date().toISOString(),
+    event,
+    ...data,
+  };
+
+  try {
+    appendFileSync(_logPath, JSON.stringify(entry) + '\n');
+  } catch {
+    // Silently ignore write failures — debug logging must never break GSD
+  }
+}
+
+/**
+ * Start a timer for a named operation. Returns a stop function that logs
+ * the elapsed time and optional result data.
+ *
+ * Usage:
+ * ```ts
+ * const stop = debugTime('derive-state');
+ * const result = await deriveState(base);
+ * stop({ phase: result.phase });
+ * ```
+ */
+export function debugTime(event: string): (data?: Record<string, unknown>) => void {
+  if (!_enabled) return _noop;
+
+  const start = performance.now();
+  return (data?: Record<string, unknown>) => {
+    const elapsed_ms = Math.round((performance.now() - start) * 100) / 100;
+    debugLog(event, { elapsed_ms, ...data });
+  };
+}
+
+// ─── Counter Helpers ──────────────────────────────────────────────────────────
+
+/** Increment a debug counter (used by instrumentation points). */
+export function debugCount(counter: keyof typeof _counters, value = 1): void {
+  if (!_enabled) return;
+  _counters[counter] += value;
+}
+
+/** Record a peak value (only updates if new value is higher). */
+export function debugPeak(counter: keyof typeof _counters, value: number): void {
+  if (!_enabled) return;
+  if (value > _counters[counter]) {
+    _counters[counter] = value;
+  }
+}
+
+/**
+ * Write the debug summary and disable logging. Call this when auto-mode stops.
+ * Returns the log file path for user notification.
+ */
+export function writeDebugSummary(): string | null {
+  if (!_enabled || !_logPath) return null;
+
+  const totalElapsed_ms = Date.now() - _startTime;
+  const avgDeriveState_ms = _counters.deriveStateCalls > 0
+    ? Math.round((_counters.deriveStateTotalMs / _counters.deriveStateCalls) * 100) / 100
+    : 0;
+  const avgTtsrCheck_ms = _counters.ttsrChecks > 0
+    ? Math.round((_counters.ttsrTotalMs / _counters.ttsrChecks) * 100) / 100
+    : 0;
+
+  debugLog('debug-summary', {
+    totalElapsed_ms,
+    dispatches: _counters.dispatches,
+    deriveStateCalls: _counters.deriveStateCalls,
+    avgDeriveState_ms,
+    parseRoadmapCalls: _counters.parseRoadmapCalls,
+    avgParseRoadmap_ms: _counters.parseRoadmapCalls > 0
+      ? Math.round((_counters.parseRoadmapTotalMs / _counters.parseRoadmapCalls) * 100) / 100
+      : 0,
+    parsePlanCalls: _counters.parsePlanCalls,
+    ttsrChecks: _counters.ttsrChecks,
+    avgTtsrCheck_ms,
+    ttsrPeakBuffer: _counters.ttsrPeakBuffer,
+    renders: _counters.renders,
+  });
+
+  return disableDebug();
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────────
+
+function _noop(_data?: Record<string, unknown>): void { /* no-op */ }

package/dist/resources/extensions/gsd/dispatch-guard.ts

@@ -1,5 +1,4 @@
 // GSD Dispatch Guard — prevents out-of-order slice dispatch
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import { readFileSync } from "node:fs";
 import { readdirSync } from "node:fs";

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -72,6 +72,20 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `version`: schema version. Start at `1`.
 
+- `mode`: workflow mode — `"solo"` or `"team"`. Sets sensible defaults for git and project settings based on your workflow. Mode defaults are the lowest priority layer — any explicit preference overrides them. Omit to configure everything manually.
+
+  | Setting | `solo` | `team` |
+  |---|---|---|
+  | `git.auto_push` | `true` | `false` |
+  | `git.push_branches` | `false` | `true` |
+  | `git.pre_merge_check` | `false` | `true` |
+  | `git.merge_strategy` | `"squash"` | `"squash"` |
+  | `git.isolation` | `"worktree"` | `"worktree"` |
+  | `git.commit_docs` | `true` | `true` |
+  | `unique_milestone_ids` | `false` | `true` |
+
+  Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
+
 - `always_use_skills`: skills GSD should use whenever they are relevant.
 
 - `prefer_skills`: soft defaults GSD should prefer when relevant.
@@ -111,6 +125,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
   - `isolation`: `"worktree"` or `"branch"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root (useful for submodule-heavy repos). Default: `"worktree"`.
   - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
+  - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
@@ -189,6 +204,45 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 ---
 
+## Workflow Mode Examples
+
+**Solo developer — auto-push, simple IDs:**
+
+```yaml
+---
+version: 1
+mode: solo
+---
+```
+
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: false`.
+
+**Team — unique IDs, push branches, pre-merge checks:**
+
+```yaml
+---
+version: 1
+mode: team
+---
+```
+
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: true`.
+
+**Mode with overrides — team mode but with auto-push:**
+
+```yaml
+---
+version: 1
+mode: team
+git:
+  auto_push: true
+---
+```
+
+Gets all team defaults except `auto_push`, which is explicitly overridden to `true`. Any explicit setting always wins over the mode default.
+
+---
+
 ## Minimal Example
 
 The cleanest preferences file only specifies what you actually want:

package/dist/resources/extensions/gsd/doctor-proactive.ts

@@ -0,0 +1,286 @@
+/**
+ * GSD Doctor — Proactive Healing Layer
+ *
+ * Three mechanisms for automatic health monitoring during auto-mode:
+ *
+ * 1. Pre-dispatch health gate: lightweight check before each unit dispatch.
+ *    Returns blocking issues that should pause auto-mode rather than
+ *    dispatching into a broken state.
+ *
+ * 2. Health score tracking: tracks issue counts over time to detect
+ *    degradation trends. If health is declining, surfaces a warning.
+ *
+ * 3. Auto-heal escalation: if deterministic fix can't resolve issues
+ *    after N units, escalates to LLM-assisted heal dispatch.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot, resolveGsdRootFile } from "./paths.js";
+import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
+import { abortAndReset } from "./git-self-heal.js";
+
+// ── Health Score Tracking ──────────────────────────────────────────────────
+
+export interface HealthSnapshot {
+  timestamp: number;
+  errors: number;
+  warnings: number;
+  fixesApplied: number;
+  unitIndex: number; // which unit dispatch triggered this snapshot
+}
+
+/** In-memory health history for the current auto-mode session. */
+let healthHistory: HealthSnapshot[] = [];
+
+/** Count of consecutive units with unresolved errors. */
+let consecutiveErrorUnits = 0;
+
+/** Unit index counter for health tracking. */
+let healthUnitIndex = 0;
+
+/**
+ * Record a health snapshot after a doctor run.
+ * Called from the post-unit hook in auto.ts.
+ */
+export function recordHealthSnapshot(errors: number, warnings: number, fixesApplied: number): void {
+  healthUnitIndex++;
+  healthHistory.push({
+    timestamp: Date.now(),
+    errors,
+    warnings,
+    fixesApplied,
+    unitIndex: healthUnitIndex,
+  });
+
+  // Keep only the last 50 snapshots to bound memory
+  if (healthHistory.length > 50) {
+    healthHistory = healthHistory.slice(-50);
+  }
+
+  if (errors > 0) {
+    consecutiveErrorUnits++;
+  } else {
+    consecutiveErrorUnits = 0;
+  }
+}
+
+/**
+ * Get the current health trend.
+ * Returns "improving", "stable", "degrading", or "unknown" (not enough data).
+ */
+export function getHealthTrend(): "improving" | "stable" | "degrading" | "unknown" {
+  if (healthHistory.length < 3) return "unknown";
+
+  const recent = healthHistory.slice(-5);
+  const older = healthHistory.slice(-10, -5);
+
+  if (older.length === 0) return "unknown";
+
+  const recentAvg = recent.reduce((sum, s) => sum + s.errors + s.warnings, 0) / recent.length;
+  const olderAvg = older.reduce((sum, s) => sum + s.errors + s.warnings, 0) / older.length;
+
+  const delta = recentAvg - olderAvg;
+  if (delta > 1) return "degrading";
+  if (delta < -1) return "improving";
+  return "stable";
+}
+
+/**
+ * Get the number of consecutive units with unresolved errors.
+ */
+export function getConsecutiveErrorUnits(): number {
+  return consecutiveErrorUnits;
+}
+
+/**
+ * Get health history for display (e.g., dashboard overlay).
+ */
+export function getHealthHistory(): readonly HealthSnapshot[] {
+  return healthHistory;
+}
+
+/**
+ * Reset health tracking state. Called on auto-mode start/stop.
+ */
+export function resetHealthTracking(): void {
+  healthHistory = [];
+  consecutiveErrorUnits = 0;
+  healthUnitIndex = 0;
+}
+
+// ── Pre-Dispatch Health Gate ───────────────────────────────────────────────
+
+export interface PreDispatchHealthResult {
+  /** Whether the dispatch should proceed. */
+  proceed: boolean;
+  /** If blocked, the reason to show the user. */
+  reason?: string;
+  /** Issues found (for logging). */
+  issues: string[];
+  /** Whether fix was applied. */
+  fixesApplied: string[];
+}
+
+/**
+ * Lightweight pre-dispatch health check. Runs fast checks that should
+ * block dispatch if they fail — avoids dispatching into a broken state.
+ *
+ * This is NOT a full doctor run — it only checks critical, fast-to-evaluate
+ * conditions that would cause the next unit to fail or corrupt state.
+ *
+ * Returns { proceed: true } if dispatch should continue.
+ */
+export function preDispatchHealthGate(basePath: string): PreDispatchHealthResult {
+  const issues: string[] = [];
+  const fixesApplied: string[] = [];
+
+  // ── Stale crash lock blocks dispatch ──
+  // If a stale lock exists, the crash recovery path should handle it,
+  // not a new dispatch. This prevents double-dispatch after crashes.
+  try {
+    const lock = readCrashLock(basePath);
+    if (lock && !isLockProcessAlive(lock)) {
+      // Auto-clear it since we're about to dispatch anyway
+      clearLock(basePath);
+      fixesApplied.push("cleared stale auto.lock before dispatch");
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // ── Corrupt merge/rebase state blocks dispatch ──
+  // Dispatching a unit with MERGE_HEAD present will cause git operations to fail.
+  try {
+    const gitDir = join(basePath, ".git");
+    if (existsSync(gitDir)) {
+      const blockers = ["MERGE_HEAD", "rebase-apply", "rebase-merge"].filter(
+        f => existsSync(join(gitDir, f)),
+      );
+      if (blockers.length > 0) {
+        // Try to auto-heal
+        try {
+          const result = abortAndReset(basePath);
+          fixesApplied.push(`pre-dispatch: cleaned merge state (${result.cleaned.join(", ")})`);
+        } catch {
+          issues.push(`Corrupt git state: ${blockers.join(", ")}. Run /gsd doctor fix.`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // ── STATE.md existence check ──
+  // If STATE.md is missing, deriveState will still work but the LLM
+  // may get confused. Rebuild it silently.
+  try {
+    const stateFile = resolveGsdRootFile(basePath, "STATE");
+    const milestonesDir = join(gsdRoot(basePath), "milestones");
+    if (existsSync(milestonesDir) && !existsSync(stateFile)) {
+      issues.push("STATE.md missing — will rebuild after this unit");
+      // Don't block dispatch — rebuilding happens in post-hook
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // If we had critical issues that couldn't be auto-healed, block dispatch
+  if (issues.length > 0) {
+    return {
+      proceed: false,
+      reason: `Pre-dispatch health check failed:\n${issues.map(i => `  - ${i}`).join("\n")}\nRun /gsd doctor fix to resolve.`,
+      issues,
+      fixesApplied,
+    };
+  }
+
+  return { proceed: true, issues, fixesApplied };
+}
+
+// ── Auto-Heal Escalation ──────────────────────────────────────────────────
+
+/** Threshold: escalate to LLM heal after this many consecutive error units. */
+const ESCALATION_THRESHOLD = 5;
+
+/** Whether an escalation has already been triggered this session (prevent spam). */
+let escalationTriggered = false;
+
+/**
+ * Check whether auto-heal should escalate from deterministic fix to
+ * LLM-assisted heal. Called after each post-unit doctor run.
+ *
+ * Returns the structured issue text for LLM dispatch, or null if
+ * escalation is not needed.
+ */
+export function checkHealEscalation(
+  errors: number,
+  unresolvedIssues: Array<{ code: string; message: string; unitId: string }>,
+): { shouldEscalate: boolean; reason: string; issues: typeof unresolvedIssues } {
+  if (escalationTriggered) {
+    return { shouldEscalate: false, reason: "already escalated this session", issues: [] };
+  }
+
+  if (consecutiveErrorUnits < ESCALATION_THRESHOLD) {
+    return {
+      shouldEscalate: false,
+      reason: `${consecutiveErrorUnits}/${ESCALATION_THRESHOLD} consecutive error units`,
+      issues: [],
+    };
+  }
+
+  if (errors === 0) {
+    return { shouldEscalate: false, reason: "no errors to escalate", issues: [] };
+  }
+
+  const trend = getHealthTrend();
+  if (trend === "improving") {
+    return { shouldEscalate: false, reason: "health is improving — deferring escalation", issues: [] };
+  }
+
+  escalationTriggered = true;
+  return {
+    shouldEscalate: true,
+    reason: `${consecutiveErrorUnits} consecutive units with unresolved errors (trend: ${trend})`,
+    issues: unresolvedIssues,
+  };
+}
+
+/**
+ * Reset escalation state. Called on auto-mode start/stop.
+ */
+export function resetEscalation(): void {
+  escalationTriggered = false;
+}
+
+/**
+ * Format a health summary for display in the auto-mode dashboard.
+ */
+export function formatHealthSummary(): string {
+  if (healthHistory.length === 0) return "No health data yet.";
+
+  const latest = healthHistory[healthHistory.length - 1]!;
+  const trend = getHealthTrend();
+  const trendIcon = trend === "improving" ? "+" : trend === "degrading" ? "-" : "=";
+  const totalFixes = healthHistory.reduce((sum, s) => sum + s.fixesApplied, 0);
+
+  const parts = [
+    `Health: ${latest.errors}E/${latest.warnings}W`,
+    `trend:${trendIcon}`,
+    `fixes:${totalFixes}`,
+  ];
+
+  if (consecutiveErrorUnits > 0) {
+    parts.push(`streak:${consecutiveErrorUnits}/${ESCALATION_THRESHOLD}`);
+  }
+
+  return parts.join(" | ");
+}
+
+/**
+ * Reset all proactive healing state. Called on auto-mode start/stop.
+ */
+export function resetProactiveHealing(): void {
+  resetHealthTracking();
+  resetEscalation();
+}