gsd-pi 2.19.0 → 2.20.0

package/src/resources/extensions/gsd/db-writer.ts

@@ -0,0 +1,341 @@
+// GSD DB Writer — Markdown generators + DB-first write helpers
+//
+// The missing DB→markdown direction. S03 established markdown→DB (md-importer.ts).
+// This module generates DECISIONS.md and REQUIREMENTS.md from DB state,
+// computes next decision IDs, and provides write helpers that upsert to DB
+// then regenerate the corresponding markdown file.
+//
+// Critical invariant: generated markdown must round-trip through
+// parseDecisionsTable() and parseRequirementsSections() with field fidelity.
+
+import { join, resolve } from 'node:path';
+import type { Decision, Requirement } from './types.js';
+import { resolveGsdRootFile } from './paths.js';
+import { saveFile } from './files.js';
+
+// ─── Markdown Generators ──────────────────────────────────────────────────
+
+/**
+ * Generate full DECISIONS.md content from an array of Decision objects.
+ * Produces the canonical format: H1 header, HTML comment block, table header,
+ * separator, and one data row per decision.
+ *
+ * Column order: #, When, Scope, Decision, Choice, Rationale, Revisable?
+ */
+export function generateDecisionsMd(decisions: Decision[]): string {
+  const lines: string[] = [];
+
+  lines.push('# Decisions Register');
+  lines.push('');
+  lines.push('<!-- Append-only. Never edit or remove existing rows.');
+  lines.push('     To reverse a decision, add a new row that supersedes it.');
+  lines.push('     Read this file at the start of any planning or research phase. -->');
+  lines.push('');
+  lines.push('| # | When | Scope | Decision | Choice | Rationale | Revisable? |');
+  lines.push('|---|------|-------|----------|--------|-----------|------------|');
+
+  for (const d of decisions) {
+    // Escape pipe characters within cell values to preserve table structure
+    const cells = [
+      d.id,
+      d.when_context,
+      d.scope,
+      d.decision,
+      d.choice,
+      d.rationale,
+      d.revisable,
+    ].map(cell => (cell ?? '').replace(/\|/g, '\\|'));
+
+    lines.push(`| ${cells.join(' | ')} |`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+// ─── Requirements Markdown Generator ──────────────────────────────────────
+
+/** Status values that map to specific sections, in display order. */
+const STATUS_SECTION_MAP: Array<{ status: string; heading: string }> = [
+  { status: 'active', heading: 'Active' },
+  { status: 'validated', heading: 'Validated' },
+  { status: 'deferred', heading: 'Deferred' },
+  { status: 'out-of-scope', heading: 'Out of Scope' },
+];
+
+/**
+ * Generate full REQUIREMENTS.md content from an array of Requirement objects.
+ * Groups requirements by status into sections (## Active, ## Validated, etc.),
+ * each containing ### RXXX — Description headings with bullet fields.
+ * Only emits sections that have content. Appends Traceability table and
+ * Coverage Summary at the bottom.
+ */
+export function generateRequirementsMd(requirements: Requirement[]): string {
+  const lines: string[] = [];
+
+  lines.push('# Requirements');
+  lines.push('');
+  lines.push('This file is the explicit capability and coverage contract for the project.');
+  lines.push('');
+
+  // Group by status
+  const byStatus = new Map<string, Requirement[]>();
+  for (const r of requirements) {
+    const status = (r.status || 'active').toLowerCase();
+    if (!byStatus.has(status)) byStatus.set(status, []);
+    byStatus.get(status)!.push(r);
+  }
+
+  // Emit sections in canonical order
+  for (const { status, heading } of STATUS_SECTION_MAP) {
+    const reqs = byStatus.get(status);
+    if (!reqs || reqs.length === 0) continue;
+
+    lines.push(`## ${heading}`);
+    lines.push('');
+
+    for (const r of reqs) {
+      lines.push(`### ${r.id} — ${r.description || 'Untitled'}`);
+
+      // Emit bullet fields — only those with content
+      if (r.class) lines.push(`- Class: ${r.class}`);
+      if (r.status) lines.push(`- Status: ${r.status}`);
+      if (r.description) lines.push(`- Description: ${r.description}`);
+      if (r.why) lines.push(`- Why it matters: ${r.why}`);
+      if (r.source) lines.push(`- Source: ${r.source}`);
+      if (r.primary_owner) lines.push(`- Primary owning slice: ${r.primary_owner}`);
+      if (r.supporting_slices) lines.push(`- Supporting slices: ${r.supporting_slices}`);
+      if (r.validation) lines.push(`- Validation: ${r.validation}`);
+      if (r.notes) lines.push(`- Notes: ${r.notes}`);
+      lines.push('');
+    }
+  }
+
+  // Traceability table
+  lines.push('## Traceability');
+  lines.push('');
+  lines.push('| ID | Class | Status | Primary owner | Supporting | Proof |');
+  lines.push('|---|---|---|---|---|---|');
+
+  for (const r of requirements) {
+    const proof = r.validation || 'unmapped';
+    lines.push(
+      `| ${r.id} | ${r.class || ''} | ${r.status || ''} | ${r.primary_owner || 'none'} | ${r.supporting_slices || 'none'} | ${proof} |`,
+    );
+  }
+
+  lines.push('');
+
+  // Coverage Summary
+  const activeCount = byStatus.get('active')?.length ?? 0;
+  const validatedReqs = byStatus.get('validated') ?? [];
+  const validatedIds = validatedReqs.map(r => r.id).join(', ');
+
+  lines.push('## Coverage Summary');
+  lines.push('');
+  lines.push(`- Active requirements: ${activeCount}`);
+  lines.push(`- Mapped to slices: ${activeCount}`);
+  lines.push(`- Validated: ${validatedReqs.length}${validatedIds ? ` (${validatedIds})` : ''}`);
+  lines.push(`- Unmapped active requirements: 0`);
+
+  return lines.join('\n') + '\n';
+}
+
+// ─── Next Decision ID ─────────────────────────────────────────────────────
+
+/**
+ * Compute the next decision ID from the current DB state.
+ * Queries MAX(CAST(SUBSTR(id, 2) AS INTEGER)) from decisions table.
+ * Returns D001 if no decisions exist. Zero-pads to 3 digits.
+ */
+export async function nextDecisionId(): Promise<string> {
+  try {
+    const db = await import('./gsd-db.js');
+    const adapter = db._getAdapter();
+    if (!adapter) return 'D001';
+
+    const row = adapter
+      .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
+      .get();
+
+    const maxNum = row ? (row['max_num'] as number | null) : null;
+    if (maxNum == null || isNaN(maxNum)) return 'D001';
+
+    const next = maxNum + 1;
+    return `D${String(next).padStart(3, '0')}`;
+  } catch (err) {
+    process.stderr.write(`gsd-db: nextDecisionId failed: ${(err as Error).message}\n`);
+    return 'D001';
+  }
+}
+
+// ─── Save Decision to DB + Regenerate Markdown ────────────────────────────
+
+export interface SaveDecisionFields {
+  scope: string;
+  decision: string;
+  choice: string;
+  rationale: string;
+  revisable?: string;
+  when_context?: string;
+}
+
+/**
+ * Save a new decision to DB and regenerate DECISIONS.md.
+ * Auto-assigns the next ID via nextDecisionId().
+ * Returns the assigned ID.
+ */
+export async function saveDecisionToDb(
+  fields: SaveDecisionFields,
+  basePath: string,
+): Promise<{ id: string }> {
+  try {
+    const db = await import('./gsd-db.js');
+
+    const id = await nextDecisionId();
+
+    db.upsertDecision({
+      id,
+      when_context: fields.when_context ?? '',
+      scope: fields.scope,
+      decision: fields.decision,
+      choice: fields.choice,
+      rationale: fields.rationale,
+      revisable: fields.revisable ?? 'Yes',
+      superseded_by: null,
+    });
+
+    // Fetch all decisions (including superseded for the full register)
+    const adapter = db._getAdapter();
+    let allDecisions: Decision[] = [];
+    if (adapter) {
+      const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
+      allDecisions = rows.map(row => ({
+        seq: row['seq'] as number,
+        id: row['id'] as string,
+        when_context: row['when_context'] as string,
+        scope: row['scope'] as string,
+        decision: row['decision'] as string,
+        choice: row['choice'] as string,
+        rationale: row['rationale'] as string,
+        revisable: row['revisable'] as string,
+        superseded_by: (row['superseded_by'] as string) ?? null,
+      }));
+    }
+
+    const md = generateDecisionsMd(allDecisions);
+    const filePath = resolveGsdRootFile(basePath, 'DECISIONS');
+    await saveFile(filePath, md);
+
+    return { id };
+  } catch (err) {
+    process.stderr.write(`gsd-db: saveDecisionToDb failed: ${(err as Error).message}\n`);
+    throw err;
+  }
+}
+
+// ─── Update Requirement in DB + Regenerate Markdown ───────────────────────
+
+/**
+ * Update a requirement in DB and regenerate REQUIREMENTS.md.
+ * Fetches existing requirement, merges updates, upserts, then regenerates.
+ */
+export async function updateRequirementInDb(
+  id: string,
+  updates: Partial<Requirement>,
+  basePath: string,
+): Promise<void> {
+  try {
+    const db = await import('./gsd-db.js');
+
+    const existing = db.getRequirementById(id);
+    if (!existing) {
+      throw new Error(`Requirement ${id} not found`);
+    }
+
+    // Merge updates into existing
+    const merged: Requirement = {
+      ...existing,
+      ...updates,
+      id: existing.id, // ID cannot be changed
+    };
+
+    db.upsertRequirement(merged);
+
+    // Fetch ALL requirements (including superseded) for full file regeneration
+    const adapter = db._getAdapter();
+    let allRequirements: Requirement[] = [];
+    if (adapter) {
+      const rows = adapter.prepare('SELECT * FROM requirements ORDER BY id').all();
+      allRequirements = rows.map(row => ({
+        id: row['id'] as string,
+        class: row['class'] as string,
+        status: row['status'] as string,
+        description: row['description'] as string,
+        why: row['why'] as string,
+        source: row['source'] as string,
+        primary_owner: row['primary_owner'] as string,
+        supporting_slices: row['supporting_slices'] as string,
+        validation: row['validation'] as string,
+        notes: row['notes'] as string,
+        full_content: row['full_content'] as string,
+        superseded_by: (row['superseded_by'] as string) ?? null,
+      }));
+    }
+
+    // Filter to non-superseded for the markdown file
+    // (superseded requirements don't appear in section headings)
+    const nonSuperseded = allRequirements.filter(r => r.superseded_by == null);
+
+    const md = generateRequirementsMd(nonSuperseded);
+    const filePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
+    await saveFile(filePath, md);
+  } catch (err) {
+    process.stderr.write(`gsd-db: updateRequirementInDb failed: ${(err as Error).message}\n`);
+    throw err;
+  }
+}
+
+// ─── Save Artifact to DB + Disk ───────────────────────────────────────────
+
+export interface SaveArtifactOpts {
+  path: string;
+  artifact_type: string;
+  content: string;
+  milestone_id?: string;
+  slice_id?: string;
+  task_id?: string;
+}
+
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk.
+ * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
+ * The full file path is computed as basePath + '.gsd/' + path.
+ */
+export async function saveArtifactToDb(
+  opts: SaveArtifactOpts,
+  basePath: string,
+): Promise<void> {
+  try {
+    const db = await import('./gsd-db.js');
+
+    db.insertArtifact({
+      path: opts.path,
+      artifact_type: opts.artifact_type,
+      milestone_id: opts.milestone_id ?? null,
+      slice_id: opts.slice_id ?? null,
+      task_id: opts.task_id ?? null,
+      full_content: opts.content,
+    });
+
+    // Write the file to disk (guard against path traversal)
+    const gsdDir = resolve(basePath, '.gsd');
+    const fullPath = resolve(basePath, '.gsd', opts.path);
+    if (!fullPath.startsWith(gsdDir)) {
+      throw new Error(`saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+    }
+    await saveFile(fullPath, opts.content);
+  } catch (err) {
+    process.stderr.write(`gsd-db: saveArtifactToDb failed: ${(err as Error).message}\n`);
+    throw err;
+  }
+}

package/src/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/src/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/src/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: