gsd-pi 0.1.0

package/src/resources/extensions/gsd/templates/task-summary.md

@@ -0,0 +1,57 @@
+---
+id: {{taskId}}
+parent: {{sliceId}}
+milestone: {{milestoneId}}
+provides:
+  - {{whatThisTaskProvides}}
+key_files:
+  - {{filePath}}
+key_decisions:
+  - {{decision}}
+patterns_established:
+  - {{pattern}}
+observability_surfaces:
+  - {{status endpoint, structured log, persisted failure state, diagnostic command, or none}}
+duration: {{duration}}
+verification_result: passed
+completed_at: {{date}}
+# Set blocker_discovered: true only if execution revealed the remaining slice plan
+# is fundamentally invalid (wrong API, missing capability, architectural mismatch).
+# Do NOT set true for ordinary bugs, minor deviations, or fixable issues.
+blocker_discovered: false
+---
+
+# {{taskId}}: {{taskTitle}}
+
+<!-- One-liner must say what actually shipped, not just that work completed.
+     Good: "Added retry-aware worker status logging"
+     Bad: "Implemented logging improvements" -->
+
+**{{oneLiner}}**
+
+## What Happened
+
+{{narrative}}
+
+## Verification
+
+{{whatWasVerifiedAndHow — commands run, tests passed, behavior confirmed}}
+
+## Diagnostics
+
+{{howToInspectWhatThisTaskBuiltLater — status surfaces, logs, error shapes, failure artifacts, or none}}
+
+## Deviations
+
+<!-- Deviations are unplanned changes to the written task plan, not ordinary debugging during implementation. -->
+
+{{deviationsFromPlan_OR_none}}
+
+## Known Issues
+
+{{issuesDiscoveredButNotFixed_OR_none}}
+
+## Files Created/Modified
+
+- `{{filePath}}` — {{description}}
+- `{{filePath}}` — {{description}}

package/src/resources/extensions/gsd/templates/uat.md

@@ -0,0 +1,54 @@
+# {{sliceId}}: {{sliceTitle}} — UAT
+
+**Milestone:** {{milestoneId}}
+**Written:** {{date}}
+
+## UAT Type
+
+- UAT mode: {{artifact-driven | live-runtime | human-experience | mixed}}
+- Why this mode is sufficient: {{reason}}
+
+## Preconditions
+
+{{whatMustBeTrueBeforeTesting — server running, data seeded, etc.}}
+
+## Smoke Test
+
+{{oneQuickCheckThatConfirmsTheSliceBasicallyWorks}}
+
+## Test Cases
+
+### 1. {{testName}}
+
+1. {{step}}
+2. {{step}}
+3. **Expected:** {{expected}}
+
+### 2. {{testName}}
+
+1. {{step}}
+2. **Expected:** {{expected}}
+
+## Edge Cases
+
+### {{edgeCaseName}}
+
+1. {{step}}
+2. **Expected:** {{expected}}
+
+## Failure Signals
+
+- {{whatWouldIndicateSomethingIsBroken — errors, missing UI, wrong data}}
+
+## Requirements Proved By This UAT
+
+- {{requirementIdOr_none}} — {{what this UAT proves}}
+
+## Not Proven By This UAT
+
+- {{what this UAT intentionally does not prove}}
+- {{remaining live/runtime/operational gaps, if any}}
+
+## Notes for Tester
+
+{{anythingTheHumanShouldKnow — known rough edges, things to ignore, areas needing gut check}}

package/src/resources/extensions/gsd/types.ts

@@ -0,0 +1,159 @@
+// GSD Extension — Core Type Definitions
+// Types consumed by state derivation, file parsing, and status display.
+// Pure interfaces — no logic, no runtime dependencies.
+
+// ─── Enums & Literal Unions ────────────────────────────────────────────────
+
+export type RiskLevel = 'low' | 'medium' | 'high';
+export type Phase = 'pre-planning' | 'discussing' | 'researching' | 'planning' | 'executing' | 'verifying' | 'summarizing' | 'advancing' | 'completing-milestone' | 'replanning-slice' | 'complete' | 'paused' | 'blocked';
+export type ContinueStatus = 'in_progress' | 'interrupted' | 'compacted';
+
+// ─── Roadmap (Milestone-level) ─────────────────────────────────────────────
+
+export interface RoadmapSliceEntry {
+  id: string;          // e.g. "S01"
+  title: string;       // e.g. "Types + File I/O + Git Operations"
+  risk: RiskLevel;
+  depends: string[];   // e.g. ["S01", "S02"]
+  done: boolean;
+  demo: string;        // the "After this:" sentence
+}
+
+export interface BoundaryMapEntry {
+  fromSlice: string;   // e.g. "S01"
+  toSlice: string;     // e.g. "S02" or "terminal"
+  produces: string;    // raw text block of what this slice produces
+  consumes: string;    // raw text block of what it consumes (or "nothing")
+}
+
+export interface Roadmap {
+  title: string;       // e.g. "M001: GSD Extension — Hierarchical Planning with Auto Mode"
+  vision: string;
+  successCriteria: string[];
+  slices: RoadmapSliceEntry[];
+  boundaryMap: BoundaryMapEntry[];
+}
+
+// ─── Slice Plan ────────────────────────────────────────────────────────────
+
+export interface TaskPlanEntry {
+  id: string;          // e.g. "T01"
+  title: string;       // e.g. "Core Type Definitions"
+  description: string;
+  done: boolean;
+  estimate: string;    // e.g. "30m", "2h" — informational only
+  files?: string[];    // e.g. ["types.ts", "files.ts"] — extracted from "- Files:" subline
+  verify?: string;     // e.g. "run tests" — extracted from "- Verify:" subline
+}
+
+export interface SlicePlan {
+  id: string;          // e.g. "S01"
+  title: string;       // from the H1
+  goal: string;
+  demo: string;
+  mustHaves: string[]; // top-level must-have bullet points
+  tasks: TaskPlanEntry[];
+  filesLikelyTouched: string[];
+}
+
+// ─── Summary (Task & Slice level) ──────────────────────────────────────────
+
+export interface SummaryRequires {
+  slice: string;
+  provides: string;
+}
+
+export interface SummaryFrontmatter {
+  id: string;
+  parent: string;
+  milestone: string;
+  provides: string[];
+  requires: SummaryRequires[];
+  affects: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  drill_down_paths: string[];
+  observability_surfaces: string[];
+  duration: string;
+  verification_result: string;
+  completed_at: string;
+  blocker_discovered: boolean;
+}
+
+export interface FileModified {
+  path: string;
+  description: string;
+}
+
+export interface Summary {
+  frontmatter: SummaryFrontmatter;
+  title: string;
+  oneLiner: string;
+  whatHappened: string;
+  deviations: string;
+  filesModified: FileModified[];
+}
+
+// ─── Continue-Here ─────────────────────────────────────────────────────────
+
+export interface ContinueFrontmatter {
+  milestone: string;
+  slice: string;
+  task: string;
+  step: number;
+  totalSteps: number;
+  status: ContinueStatus;
+  savedAt: string;
+}
+
+export interface Continue {
+  frontmatter: ContinueFrontmatter;
+  completedWork: string;
+  remainingWork: string;
+  decisions: string;
+  context: string;
+  nextAction: string;
+}
+
+// ─── GSD State (Derived Dashboard) ────────────────────────────────────────
+
+export interface ActiveRef {
+  id: string;
+  title: string;
+}
+
+export interface MilestoneRegistryEntry {
+  id: string;
+  title: string;
+  status: 'complete' | 'active' | 'pending';
+  /** Milestone IDs that must be complete before this milestone becomes active. Populated from CONTEXT.md YAML frontmatter. */
+  dependsOn?: string[];
+}
+
+export interface RequirementCounts {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+}
+
+export interface GSDState {
+  activeMilestone: ActiveRef | null;
+  activeSlice: ActiveRef | null;
+  activeTask: ActiveRef | null;
+  phase: Phase;
+  recentDecisions: string[];
+  blockers: string[];
+  nextAction: string;
+  activeBranch?: string;
+  registry: MilestoneRegistryEntry[];
+  requirements?: RequirementCounts;
+  progress?: {
+    milestones: { done: number; total: number };
+    slices?: { done: number; total: number };
+    tasks?: { done: number; total: number };
+  };
+}

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  gsdRoot,
+  relSliceFile,
+  relTaskFile,
+  resolveSliceFile,
+  resolveTaskFile,
+} from "./paths.ts";
+import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.ts";
+
+export type UnitRuntimePhase =
+  | "dispatched"
+  | "wrapup-warning-sent"
+  | "timeout"
+  | "recovered"
+  | "finalized"
+  | "paused";
+
+export interface ExecuteTaskRecoveryStatus {
+  planPath: string;
+  summaryPath: string;
+  summaryExists: boolean;
+  taskChecked: boolean;
+  nextActionAdvanced: boolean;
+  mustHaveCount: number;
+  mustHavesMentionedInSummary: number;
+}
+
+export interface AutoUnitRuntimeRecord {
+  version: 1;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  updatedAt: number;
+  phase: UnitRuntimePhase;
+  wrapupWarningSent: boolean;
+  timeoutAt: number | null;
+  lastProgressAt: number;
+  progressCount: number;
+  lastProgressKind: string;
+  recovery?: ExecuteTaskRecoveryStatus;
+  recoveryAttempts?: number;
+  lastRecoveryReason?: "idle" | "hard";
+}
+
+function runtimeDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "units");
+}
+
+function runtimePath(basePath: string, unitType: string, unitId: string): string {
+  return join(runtimeDir(basePath), `${unitType}-${unitId.replace(/[\/]/g, "-")}.json`);
+}
+
+export function writeUnitRuntimeRecord(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  updates: Partial<AutoUnitRuntimeRecord> = {},
+): AutoUnitRuntimeRecord {
+  const dir = runtimeDir(basePath);
+  mkdirSync(dir, { recursive: true });
+  const path = runtimePath(basePath, unitType, unitId);
+  const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+  const next: AutoUnitRuntimeRecord = {
+    version: 1,
+    unitType,
+    unitId,
+    startedAt,
+    updatedAt: Date.now(),
+    phase: updates.phase ?? prev?.phase ?? "dispatched",
+    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+    recovery: updates.recovery ?? prev?.recovery,
+    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+  };
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  return next;
+}
+
+export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as AutoUnitRuntimeRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export async function inspectExecuteTaskDurability(
+  basePath: string,
+  unitId: string,
+): Promise<ExecuteTaskRecoveryStatus | null> {
+  const [mid, sid, tid] = unitId.split("/");
+  if (!mid || !sid || !tid) return null;
+
+  const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const summaryAbs = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+  const stateAbs = join(gsdRoot(basePath), "STATE.md");
+
+  const planPath = relSliceFile(basePath, mid, sid, "PLAN");
+  const summaryPath = relTaskFile(basePath, mid, sid, tid, "SUMMARY");
+
+  const planContent = planAbs ? await loadFile(planAbs) : null;
+  const stateContent = existsSync(stateAbs) ? readFileSync(stateAbs, "utf-8") : "";
+  const summaryExists = !!(summaryAbs && existsSync(summaryAbs));
+
+  const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
+  const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+
+  // Must-have coverage: load task plan and count mentions in summary
+  let mustHaveCount = 0;
+  let mustHavesMentionedInSummary = 0;
+
+  const taskPlanAbs = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+  if (taskPlanAbs) {
+    const taskPlanContent = await loadFile(taskPlanAbs);
+    if (taskPlanContent) {
+      const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+      mustHaveCount = mustHaves.length;
+      if (mustHaveCount > 0 && summaryExists && summaryAbs) {
+        const summaryContent = await loadFile(summaryAbs);
+        if (summaryContent) {
+          mustHavesMentionedInSummary = countMustHavesMentionedInSummary(mustHaves, summaryContent);
+        }
+      }
+    }
+  }
+
+  return {
+    planPath,
+    summaryPath,
+    summaryExists,
+    taskChecked,
+    nextActionAdvanced,
+    mustHaveCount,
+    mustHavesMentionedInSummary,
+  };
+}
+
+export function formatExecuteTaskRecoveryStatus(status: ExecuteTaskRecoveryStatus): string {
+  const missing = [] as string[];
+  if (!status.summaryExists) missing.push(`summary missing (${status.summaryPath})`);
+  if (!status.taskChecked) missing.push(`task checkbox unchecked in ${status.planPath}`);
+  if (!status.nextActionAdvanced) missing.push("state next action still points at the timed-out task");
+  if (status.mustHaveCount > 0 && status.mustHavesMentionedInSummary < status.mustHaveCount) {
+    missing.push(`must-have gap: ${status.mustHavesMentionedInSummary} of ${status.mustHaveCount} must-haves addressed in summary`);
+  }
+  return missing.length > 0 ? missing.join("; ") : "all durable task artifacts present";
+}

package/src/resources/extensions/gsd/workspace-index.ts

@@ -0,0 +1,203 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadFile, parsePlan, parseRoadmap } from "./files.ts";
+import {
+  milestonesDir,
+  resolveMilestoneFile,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveTaskFile,
+  resolveTasksDir,
+} from "./paths.ts";
+import { deriveState } from "./state.ts";
+import { type ValidationIssue, validateCompleteBoundary, validatePlanBoundary } from "./observability-validator.ts";
+import { getSliceBranchName } from "./worktree.ts";
+
+export interface WorkspaceTaskTarget {
+  id: string;
+  title: string;
+  done: boolean;
+  planPath?: string;
+  summaryPath?: string;
+}
+
+export interface WorkspaceSliceTarget {
+  id: string;
+  title: string;
+  done: boolean;
+  planPath?: string;
+  summaryPath?: string;
+  uatPath?: string;
+  tasksDir?: string;
+  branch?: string;
+  tasks: WorkspaceTaskTarget[];
+}
+
+export interface WorkspaceMilestoneTarget {
+  id: string;
+  title: string;
+  roadmapPath?: string;
+  slices: WorkspaceSliceTarget[];
+}
+
+export interface WorkspaceScopeTarget {
+  scope: string;
+  label: string;
+  kind: "project" | "milestone" | "slice" | "task";
+}
+
+export interface GSDWorkspaceIndex {
+  milestones: WorkspaceMilestoneTarget[];
+  active: {
+    milestoneId?: string;
+    sliceId?: string;
+    taskId?: string;
+    phase: string;
+  };
+  scopes: WorkspaceScopeTarget[];
+  validationIssues: ValidationIssue[];
+}
+
+function findMilestoneIds(basePath: string): string[] {
+  try {
+    return readdirSync(milestonesDir(basePath), { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => {
+        const match = entry.name.match(/^(M\d+)/);
+        return match ? match[1] : entry.name;
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function titleFromRoadmapHeader(content: string, fallbackId: string): string {
+  const roadmap = parseRoadmap(content);
+  return roadmap.title.replace(/^M\d+[^:]*:\s*/, "") || fallbackId;
+}
+
+async function indexSlice(basePath: string, milestoneId: string, sliceId: string, fallbackTitle: string, done: boolean): Promise<WorkspaceSliceTarget> {
+  const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? undefined;
+  const summaryPath = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY") ?? undefined;
+  const uatPath = resolveSliceFile(basePath, milestoneId, sliceId, "UAT") ?? undefined;
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId) ?? undefined;
+
+  const tasks: WorkspaceTaskTarget[] = [];
+  let title = fallbackTitle;
+
+  if (planPath) {
+    const content = await loadFile(planPath);
+    if (content) {
+      const plan = parsePlan(content);
+      title = plan.title || fallbackTitle;
+      for (const task of plan.tasks) {
+        tasks.push({
+          id: task.id,
+          title: task.title,
+          done: task.done,
+          planPath: resolveTaskFile(basePath, milestoneId, sliceId, task.id, "PLAN") ?? undefined,
+          summaryPath: resolveTaskFile(basePath, milestoneId, sliceId, task.id, "SUMMARY") ?? undefined,
+        });
+      }
+    }
+  }
+
+  return {
+    id: sliceId,
+    title,
+    done,
+    planPath,
+    summaryPath,
+    uatPath,
+    tasksDir,
+    branch: getSliceBranchName(milestoneId, sliceId),
+    tasks,
+  };
+}
+
+export async function indexWorkspace(basePath: string): Promise<GSDWorkspaceIndex> {
+  const milestoneIds = findMilestoneIds(basePath);
+  const milestones: WorkspaceMilestoneTarget[] = [];
+  const validationIssues: ValidationIssue[] = [];
+
+  for (const milestoneId of milestoneIds) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP") ?? undefined;
+    let title = milestoneId;
+    const slices: WorkspaceSliceTarget[] = [];
+
+    if (roadmapPath) {
+      const roadmapContent = await loadFile(roadmapPath);
+      if (roadmapContent) {
+        const roadmap = parseRoadmap(roadmapContent);
+        title = titleFromRoadmapHeader(roadmapContent, milestoneId);
+        for (const slice of roadmap.slices) {
+          const indexedSlice = await indexSlice(basePath, milestoneId, slice.id, slice.title, slice.done);
+          slices.push(indexedSlice);
+          validationIssues.push(...await validatePlanBoundary(basePath, milestoneId, slice.id));
+          validationIssues.push(...await validateCompleteBoundary(basePath, milestoneId, slice.id));
+        }
+      }
+    }
+
+    milestones.push({ id: milestoneId, title, roadmapPath, slices });
+  }
+
+  const state = await deriveState(basePath);
+  const active = {
+    milestoneId: state.activeMilestone?.id,
+    sliceId: state.activeSlice?.id,
+    taskId: state.activeTask?.id,
+    phase: state.phase,
+  };
+
+  const scopes: WorkspaceScopeTarget[] = [{ scope: "project", label: "project", kind: "project" }];
+  for (const milestone of milestones) {
+    scopes.push({ scope: milestone.id, label: `${milestone.id}: ${milestone.title}`, kind: "milestone" });
+    for (const slice of milestone.slices) {
+      scopes.push({ scope: `${milestone.id}/${slice.id}`, label: `${milestone.id}/${slice.id}: ${slice.title}`, kind: "slice" });
+      for (const task of slice.tasks) {
+        scopes.push({
+          scope: `${milestone.id}/${slice.id}/${task.id}`,
+          label: `${milestone.id}/${slice.id}/${task.id}: ${task.title}`,
+          kind: "task",
+        });
+      }
+    }
+  }
+
+  return { milestones, active, scopes, validationIssues };
+}
+
+export async function listDoctorScopeSuggestions(basePath: string): Promise<Array<{ value: string; label: string }>> {
+  const index = await indexWorkspace(basePath);
+  const activeSliceScope = index.active.milestoneId && index.active.sliceId
+    ? `${index.active.milestoneId}/${index.active.sliceId}`
+    : null;
+
+  const ordered = [...index.scopes].filter(scope => scope.kind !== "project");
+  ordered.sort((a, b) => {
+    if (activeSliceScope && a.scope === activeSliceScope) return -1;
+    if (activeSliceScope && b.scope === activeSliceScope) return 1;
+    return a.scope.localeCompare(b.scope);
+  });
+
+  return ordered.map(scope => ({ value: scope.scope, label: scope.label }));
+}
+
+export async function getSuggestedNextCommands(basePath: string): Promise<string[]> {
+  const index = await indexWorkspace(basePath);
+  const scope = index.active.milestoneId && index.active.sliceId
+    ? `${index.active.milestoneId}/${index.active.sliceId}`
+    : index.active.milestoneId;
+
+  const commands = new Set<string>();
+  if (index.active.phase === "planning") commands.add("/gsd");
+  if (index.active.phase === "executing" || index.active.phase === "summarizing") commands.add("/gsd auto");
+  if (scope) commands.add(`/gsd doctor ${scope}`);
+  if (scope) commands.add(`/gsd doctor fix ${scope}`);
+  if (index.validationIssues.length > 0 && scope) commands.add(`/gsd doctor audit ${scope}`);
+  commands.add("/gsd status");
+  return [...commands];
+}