gsd-pi 2.18.0 → 2.20.0

package/dist/resources/extensions/gsd/context-store.ts

@@ -0,0 +1,195 @@
+// GSD Context Store — Query Layer & Formatters
+//
+// Typed query functions for decisions and requirements from the DB views,
+// with optional filtering. Format functions produce prompt-injectable markdown.
+// All functions degrade gracefully: return empty results when DB unavailable, never throw.
+
+import { isDbAvailable, _getAdapter } from './gsd-db.js';
+import type { Decision, Requirement } from './types.js';
+
+// ─── Query Functions ───────────────────────────────────────────────────────
+
+export interface DecisionQueryOpts {
+  milestoneId?: string;
+  scope?: string;
+}
+
+export interface RequirementQueryOpts {
+  sliceId?: string;
+  status?: string;
+}
+
+/**
+ * Query active (non-superseded) decisions with optional filters.
+ * - milestoneId: filters where when_context LIKE '%milestoneId%'
+ * - scope: filters where scope = :scope (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryDecisions(opts?: DecisionQueryOpts): Decision[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = ['superseded_by IS NULL'];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.milestoneId) {
+      clauses.push('when_context LIKE :milestone_pattern');
+      params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+    }
+
+    if (opts?.scope) {
+      clauses.push('scope = :scope');
+      params[':scope'] = opts.scope;
+    }
+
+    const sql = `SELECT * FROM decisions WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+    const rows = adapter.prepare(sql).all(params);
+
+    return 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: null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Query active (non-superseded) requirements with optional filters.
+ * - sliceId: filters where primary_owner LIKE '%sliceId%' OR supporting_slices LIKE '%sliceId%'
+ * - status: filters where status = :status (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryRequirements(opts?: RequirementQueryOpts): Requirement[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = ['superseded_by IS NULL'];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.sliceId) {
+      clauses.push('(primary_owner LIKE :slice_pattern OR supporting_slices LIKE :slice_pattern)');
+      params[':slice_pattern'] = `%${opts.sliceId}%`;
+    }
+
+    if (opts?.status) {
+      clauses.push('status = :status');
+      params[':status'] = opts.status;
+    }
+
+    const sql = `SELECT * FROM requirements WHERE ${clauses.join(' AND ')} ORDER BY id`;
+    const rows = adapter.prepare(sql).all(params);
+
+    return 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: null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ─── Format Functions ──────────────────────────────────────────────────────
+
+/**
+ * Format decisions as a markdown table matching DECISIONS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatDecisionsForPrompt(decisions: Decision[]): string {
+  if (decisions.length === 0) return '';
+
+  const header = '| # | When | Scope | Decision | Choice | Rationale | Revisable? |';
+  const separator = '|---|------|-------|----------|--------|-----------|------------|';
+  const rows = decisions.map(d =>
+    `| ${d.id} | ${d.when_context} | ${d.scope} | ${d.decision} | ${d.choice} | ${d.rationale} | ${d.revisable} |`,
+  );
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format requirements as structured H3 sections matching REQUIREMENTS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatRequirementsForPrompt(requirements: Requirement[]): string {
+  if (requirements.length === 0) return '';
+
+  return requirements.map(r => {
+    const lines: string[] = [
+      `### ${r.id}: ${r.description}`,
+      '',
+      `- **Class:** ${r.class}`,
+      `- **Status:** ${r.status}`,
+      `- **Why:** ${r.why}`,
+      `- **Source:** ${r.source}`,
+      `- **Primary Owner:** ${r.primary_owner}`,
+    ];
+
+    if (r.supporting_slices) {
+      lines.push(`- **Supporting Slices:** ${r.supporting_slices}`);
+    }
+
+    lines.push(`- **Validation:** ${r.validation}`);
+
+    if (r.notes) {
+      lines.push(`- **Notes:** ${r.notes}`);
+    }
+
+    return lines.join('\n');
+  }).join('\n\n');
+}
+
+// ─── Artifact Query Functions ──────────────────────────────────────────────
+
+/**
+ * Query a hierarchy artifact by its relative path.
+ * Returns the full_content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryArtifact(path: string): string | null {
+  if (!isDbAvailable()) return null;
+  const adapter = _getAdapter();
+  if (!adapter) return null;
+
+  try {
+    const row = adapter.prepare('SELECT full_content FROM artifacts WHERE path = :path').get({ ':path': path });
+    if (!row) return null;
+    const content = row['full_content'] as string;
+    return content || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query PROJECT.md content from the artifacts table.
+ * PROJECT.md is stored with the relative path 'PROJECT.md' by the importer.
+ * Returns the content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryProject(): string | null {
+  return queryArtifact('PROJECT.md');
+}

package/dist/resources/extensions/gsd/dashboard-overlay.ts

@@ -15,6 +15,7 @@ import { getAutoDashboardData, type AutoDashboardData } from "./auto.js";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, formatCost, formatTokenCount, formatCostProjection,
+  type UnitMetrics,
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getActiveWorktreeName } from "./worktree-command.js";
@@ -39,6 +40,9 @@ function unitLabel(type: string): string {
     case "execute-task": return "Execute";
     case "complete-slice": return "Complete";
     case "reassess-roadmap": return "Reassess";
+    case "triage-captures": return "Triage";
+    case "quick-task": return "Quick Task";
+    case "replan-slice": return "Replan";
     default: return type;
   }
 }
@@ -345,6 +349,13 @@ export class GSDDashboardOverlay {
       lines.push(blank());
     }
 
+    // Pending captures badge — only shown when captures are waiting for triage
+    if (this.dashData.pendingCaptureCount > 0) {
+      const count = this.dashData.pendingCaptureCount;
+      lines.push(row(th.fg("warning", `📌 ${count} pending capture${count === 1 ? "" : "s"} awaiting triage`)));
+      lines.push(blank());
+    }
+
     if (this.loading) {
       lines.push(centered(th.fg("dim", "Loading dashboard…")));
       return lines;
@@ -403,11 +414,33 @@ export class GSDDashboardOverlay {
       lines.push(row(th.fg("text", th.bold("Completed"))));
       lines.push(blank());
 
+      // Build ledger lookup for budget indicators (last entry wins for retries)
+      const ledgerLookup = new Map<string, UnitMetrics>();
+      const currentLedger = getLedger();
+      if (currentLedger) {
+        for (const lu of currentLedger.units) {
+          ledgerLookup.set(`${lu.type}:${lu.id}`, lu);
+        }
+      }
+
       const recent = [...this.dashData.completedUnits].reverse().slice(0, 10);
       for (const u of recent) {
         const left = `  ${th.fg("success", "✓")} ${th.fg("muted", unitLabel(u.type))} ${th.fg("muted", u.id)}`;
+
+        // Budget indicators from ledger
+        const ledgerEntry = ledgerLookup.get(`${u.type}:${u.id}`);
+        let budgetMarkers = "";
+        if (ledgerEntry) {
+          if (ledgerEntry.truncationSections && ledgerEntry.truncationSections > 0) {
+            budgetMarkers += th.fg("warning", ` ▼${ledgerEntry.truncationSections}`);
+          }
+          if (ledgerEntry.continueHereFired === true) {
+            budgetMarkers += th.fg("error", " → wrap-up");
+          }
+        }
+
         const right = th.fg("dim", formatDuration(u.finishedAt - u.startedAt));
-        lines.push(row(joinColumns(left, right, contentWidth)));
+        lines.push(row(joinColumns(`${left}${budgetMarkers}`, right, contentWidth)));
       }
 
       if (this.dashData.completedUnits.length > 10) {
@@ -438,6 +471,18 @@ export class GSDDashboardOverlay {
         `${th.fg("dim", "cache-w:")} ${th.fg("text", formatTokenCount(totals.tokens.cacheWrite))}`,
       ], contentWidth, "  ")));
 
+      // Budget aggregate line — only when data exists
+      if (totals.totalTruncationSections > 0 || totals.continueHereFiredCount > 0) {
+        const budgetParts: string[] = [];
+        if (totals.totalTruncationSections > 0) {
+          budgetParts.push(th.fg("warning", `${totals.totalTruncationSections} sections truncated`));
+        }
+        if (totals.continueHereFiredCount > 0) {
+          budgetParts.push(th.fg("error", `${totals.continueHereFiredCount} continue-here fired`));
+        }
+        lines.push(row(budgetParts.join(`  ${th.fg("dim", "·")}  `)));
+      }
+
       const phases = aggregateByPhase(ledger.units);
       if (phases.length > 0) {
         lines.push(blank());
@@ -482,14 +527,17 @@ export class GSDDashboardOverlay {
       }
 
       const models = aggregateByModel(ledger.units);
-      if (models.length > 1) {
+      if (models.length >= 1) {
         lines.push(blank());
         lines.push(row(th.fg("dim", "By Model")));
         for (const m of models) {
           const pct = totals.cost > 0 ? Math.round((m.cost / totals.cost) * 100) : 0;
           const modelName = truncateToWidth(m.model, 38);
+          const ctxWindow = m.contextWindowTokens !== undefined
+            ? th.fg("dim", ` [${formatTokenCount(m.contextWindowTokens)}]`)
+            : "";
           const left = `  ${th.fg("text", modelName.padEnd(38))}${th.fg("warning", formatCost(m.cost).padStart(8))}`;
-          const right = th.fg("dim", `${String(pct).padStart(3)}%  ${m.units} units`);
+          const right = th.fg("dim", `${String(pct).padStart(3)}%  ${m.units} units`) + ctxWindow;
           lines.push(row(joinColumns(left, right, contentWidth)));
         }
       }

package/dist/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;
+  }
+}