gsd-pi 0.2.9 → 0.3.0

package/src/resources/extensions/gsd/migrate/writer.ts

@@ -0,0 +1,539 @@
+// GSD Directory Writer — Format Functions & Directory Orchestrator
+// Format functions: pure string-returning functions that serialize GSD types into the exact markdown
+// format that GSD-2's parsers expect (parseRoadmap, parsePlan, parseSummary, parseRequirementCounts).
+// writeGSDDirectory: orchestrator that writes a complete .gsd directory tree from a GSDProject.
+
+import { join } from 'node:path';
+import { saveFile } from '../files.ts';
+
+import type {
+  GSDMilestone,
+  GSDSlice,
+  GSDTask,
+  GSDRequirement,
+  GSDProject,
+} from './types.ts';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/** Result of writeGSDDirectory — lists all files that were written. */
+export interface WrittenFiles {
+  /** Absolute paths of all files written */
+  paths: string[];
+  /** Count by category */
+  counts: {
+    roadmaps: number;
+    plans: number;
+    taskPlans: number;
+    taskSummaries: number;
+    sliceSummaries: number;
+    research: number;
+    requirements: number;
+    contexts: number;
+    other: number;
+  };
+}
+
+/** Pre-write statistics computed from a GSDProject without I/O. */
+export interface MigrationPreview {
+  milestoneCount: number;
+  totalSlices: number;
+  totalTasks: number;
+  doneSlices: number;
+  doneTasks: number;
+  sliceCompletionPct: number;
+  taskCompletionPct: number;
+  requirements: {
+    active: number;
+    validated: number;
+    deferred: number;
+    outOfScope: number;
+    total: number;
+  };
+}
+
+// ─── Local Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Serialize a flat key-value map into YAML frontmatter block.
+ * Matches parseFrontmatterMap() expectations:
+ * - Scalars: `key: value`
+ * - Arrays of strings: `key:\n  - item`
+ * - Empty arrays: `key: []`
+ * - Arrays of objects: `key:\n  - field1: val\n    field2: val`
+ * - Boolean: `key: true/false`
+ */
+function serializeFrontmatter(data: Record<string, unknown>): string {
+  const lines: string[] = ['---'];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) continue;
+
+    if (typeof value === 'boolean') {
+      lines.push(`${key}: ${value}`);
+    } else if (typeof value === 'string' || typeof value === 'number') {
+      lines.push(`${key}: ${value}`);
+    } else if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else if (typeof value[0] === 'object' && value[0] !== null) {
+        // Array of objects
+        lines.push(`${key}:`);
+        for (const obj of value) {
+          const entries = Object.entries(obj as Record<string, string>);
+          if (entries.length > 0) {
+            lines.push(`  - ${entries[0][0]}: ${entries[0][1]}`);
+            for (let i = 1; i < entries.length; i++) {
+              lines.push(`    ${entries[i][0]}: ${entries[i][1]}`);
+            }
+          }
+        }
+      } else {
+        // Array of scalars
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${item}`);
+        }
+      }
+    }
+  }
+
+  lines.push('---');
+  return lines.join('\n');
+}
+
+// ─── Format Functions ──────────────────────────────────────────────────────
+
+/**
+ * Format a milestone's ROADMAP.md content.
+ * Output must parse correctly through parseRoadmap().
+ */
+export function formatRoadmap(milestone: GSDMilestone): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${milestone.id}: ${milestone.title}`);
+  lines.push('');
+  lines.push(`**Vision:** ${milestone.vision || '(migrated project)'}`);
+  lines.push('');
+
+  lines.push('## Success Criteria');
+  lines.push('');
+  if (milestone.successCriteria.length > 0) {
+    for (const criterion of milestone.successCriteria) {
+      lines.push(`- ${criterion}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Slices');
+  lines.push('');
+  for (const slice of milestone.slices) {
+    const check = slice.done ? 'x' : ' ';
+    const depsStr = slice.depends.length > 0 ? slice.depends.join(', ') : '';
+    lines.push(`- [${check}] **${slice.id}: ${slice.title}** \`risk:${slice.risk}\` \`depends:[${depsStr}]\``);
+    if (slice.demo) {
+      lines.push(`  > After this: ${slice.demo}`);
+    }
+  }
+
+  // Skip Boundary Map section entirely per D004
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Format a slice's PLAN.md (S01-PLAN.md).
+ * Output must parse correctly through parsePlan().
+ */
+export function formatPlan(slice: GSDSlice): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${slice.id}: ${slice.title}`);
+  lines.push('');
+  lines.push(`**Goal:** ${slice.goal || slice.title}`);
+  lines.push(`**Demo:** ${slice.demo || slice.title}`);
+  lines.push('');
+
+  lines.push('## Must-Haves');
+  lines.push('');
+  // No must-haves in migrated data — empty section
+  lines.push('');
+
+  lines.push('## Tasks');
+  lines.push('');
+  for (const task of slice.tasks) {
+    const check = task.done ? 'x' : ' ';
+    const estPart = task.estimate ? ` \`est:${task.estimate}\`` : '';
+    lines.push(`- [${check}] **${task.id}: ${task.title}**${estPart}`);
+    if (task.description) {
+      lines.push(`  - ${task.description}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Files Likely Touched');
+  lines.push('');
+  for (const task of slice.tasks) {
+    for (const file of task.files) {
+      lines.push(`- \`${file}\``);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Format a slice summary (S01-SUMMARY.md).
+ * Output must parse correctly through parseSummary().
+ */
+export function formatSliceSummary(slice: GSDSlice, milestoneId: string): string {
+  if (!slice.summary) return '';
+
+  const s = slice.summary;
+  const fm = serializeFrontmatter({
+    id: slice.id,
+    parent: milestoneId,
+    milestone: milestoneId,
+    provides: s.provides,
+    requires: [],
+    affects: [],
+    key_files: s.keyFiles,
+    key_decisions: s.keyDecisions,
+    patterns_established: s.patternsEstablished,
+    observability_surfaces: [],
+    drill_down_paths: [],
+    duration: s.duration || '',
+    verification_result: 'passed',
+    completed_at: s.completedAt || '',
+    blocker_discovered: false,
+  });
+
+  const body = [
+    '',
+    `# ${slice.id}: ${slice.title}`,
+    '',
+    `**${s.whatHappened ? s.whatHappened.split('\n')[0] : 'Migrated from legacy format'}**`,
+    '',
+    '## What Happened',
+    '',
+    s.whatHappened || 'Migrated from legacy planning format.',
+  ];
+
+  return fm + body.join('\n') + '\n';
+}
+
+/**
+ * Format a task summary (T01-SUMMARY.md).
+ * Output must parse correctly through parseSummary().
+ */
+export function formatTaskSummary(task: GSDTask, sliceId: string, milestoneId: string): string {
+  if (!task.summary) return '';
+
+  const s = task.summary;
+  const fm = serializeFrontmatter({
+    id: task.id,
+    parent: sliceId,
+    milestone: milestoneId,
+    provides: s.provides,
+    requires: [],
+    affects: [],
+    key_files: s.keyFiles,
+    key_decisions: [],
+    patterns_established: [],
+    observability_surfaces: [],
+    drill_down_paths: [],
+    duration: s.duration || '',
+    verification_result: 'passed',
+    completed_at: s.completedAt || '',
+    blocker_discovered: false,
+  });
+
+  const body = [
+    '',
+    `# ${task.id}: ${task.title}`,
+    '',
+    `**${s.whatHappened ? s.whatHappened.split('\n')[0] : 'Migrated from legacy format'}**`,
+    '',
+    '## What Happened',
+    '',
+    s.whatHappened || 'Migrated from legacy planning format.',
+  ];
+
+  return fm + body.join('\n') + '\n';
+}
+
+/**
+ * Format a task plan (T01-PLAN.md).
+ * deriveState() only checks for file existence, not content.
+ * Keep it minimal but valid markdown.
+ */
+export function formatTaskPlan(task: GSDTask, sliceId: string, milestoneId: string): string {
+  const lines: string[] = [];
+  lines.push(`# ${task.id}: ${task.title}`);
+  lines.push('');
+  lines.push(`**Slice:** ${sliceId} — **Milestone:** ${milestoneId}`);
+  lines.push('');
+  lines.push('## Description');
+  lines.push('');
+  lines.push(task.description || 'Migrated from legacy planning format.');
+  lines.push('');
+
+  if (task.mustHaves.length > 0) {
+    lines.push('## Must-Haves');
+    lines.push('');
+    for (const mh of task.mustHaves) {
+      lines.push(`- [ ] ${mh}`);
+    }
+    lines.push('');
+  }
+
+  if (task.files.length > 0) {
+    lines.push('## Files');
+    lines.push('');
+    for (const f of task.files) {
+      lines.push(`- \`${f}\``);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format REQUIREMENTS.md grouped by status.
+ * Output must parse correctly through parseRequirementCounts().
+ * parseRequirementCounts expects: ## Active/## Validated/## Deferred/## Out of Scope sections
+ * with ### R001 — Title headings under each section.
+ */
+export function formatRequirements(requirements: GSDRequirement[]): string {
+  const lines: string[] = [];
+  lines.push('# Requirements');
+  lines.push('');
+
+  const groups: Record<string, GSDRequirement[]> = {
+    active: [],
+    validated: [],
+    deferred: [],
+    'out-of-scope': [],
+  };
+
+  for (const req of requirements) {
+    const status = req.status.toLowerCase();
+    if (status in groups) {
+      groups[status].push(req);
+    } else {
+      groups.active.push(req);
+    }
+  }
+
+  const sectionMap: [string, string][] = [
+    ['active', 'Active'],
+    ['validated', 'Validated'],
+    ['deferred', 'Deferred'],
+    ['out-of-scope', 'Out of Scope'],
+  ];
+
+  for (const [key, heading] of sectionMap) {
+    lines.push(`## ${heading}`);
+    lines.push('');
+    for (const req of groups[key]) {
+      lines.push(`### ${req.id} — ${req.title}`);
+      lines.push('');
+      lines.push(`- Status: ${req.status}`);
+      lines.push(`- Class: ${req.class}`);
+      lines.push(`- Source: ${req.source}`);
+      lines.push(`- Primary Slice: ${req.primarySlice}`);
+      lines.push('');
+      if (req.description) {
+        lines.push(req.description);
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Passthrough Format Helpers ────────────────────────────────────────────
+
+/**
+ * Format PROJECT.md content.
+ * If content is empty, produce a minimal valid stub.
+ */
+export function formatProject(content: string): string {
+  if (!content || !content.trim()) {
+    return '# Project\n\n(Migrated project — no description available.)\n';
+  }
+  return content.endsWith('\n') ? content : content + '\n';
+}
+
+/**
+ * Format DECISIONS.md content.
+ * If content is empty, produce the standard header.
+ */
+export function formatDecisions(content: string): string {
+  if (!content || !content.trim()) {
+    return '# Decisions\n\n<!-- Append-only register of architectural and pattern decisions -->\n\n| ID | Decision | Rationale | Date |\n|----|----------|-----------|------|\n';
+  }
+  return content.endsWith('\n') ? content : content + '\n';
+}
+
+/**
+ * Format a milestone CONTEXT.md.
+ * Minimal context with no depends — migrated milestones have no upstream dependencies.
+ */
+export function formatContext(milestoneId: string): string {
+  return `# ${milestoneId} Context\n\nMigrated milestone — no upstream dependencies.\n`;
+}
+
+/**
+ * Format STATE.md.
+ * deriveState() does not read STATE.md — it recomputes from scratch.
+ * Write a minimal stub that will be overwritten on first /gsd status.
+ */
+export function formatState(milestones: GSDMilestone[]): string {
+  const lines: string[] = [];
+  lines.push('# GSD State');
+  lines.push('');
+  lines.push('<!-- Auto-generated. Updated by deriveState(). -->');
+  lines.push('');
+  for (const m of milestones) {
+    const doneSlices = m.slices.filter(s => s.done).length;
+    const totalSlices = m.slices.length;
+    lines.push(`## ${m.id}: ${m.title}`);
+    lines.push('');
+    lines.push(`- Slices: ${doneSlices}/${totalSlices}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+// ─── Directory Writer Orchestrator ─────────────────────────────────────────
+
+/**
+ * Write a complete .gsd directory tree from a GSDProject.
+ * Iterates milestones → slices → tasks, calls format functions,
+ * and writes each file via saveFile(). Returns a manifest of written paths.
+ *
+ * Skips research/summary files when null (does not write empty stubs).
+ */
+export async function writeGSDDirectory(
+  project: GSDProject,
+  targetPath: string,
+): Promise<WrittenFiles> {
+  const gsdDir = join(targetPath, '.gsd');
+  const milestonesBase = join(gsdDir, 'milestones');
+  const paths: string[] = [];
+  const counts: WrittenFiles['counts'] = {
+    roadmaps: 0,
+    plans: 0,
+    taskPlans: 0,
+    taskSummaries: 0,
+    sliceSummaries: 0,
+    research: 0,
+    requirements: 0,
+    contexts: 0,
+    other: 0,
+  };
+
+  // Root-level files
+  const projectPath = join(gsdDir, 'PROJECT.md');
+  await saveFile(projectPath, formatProject(project.projectContent));
+  paths.push(projectPath);
+  counts.other++;
+
+  const decisionsPath = join(gsdDir, 'DECISIONS.md');
+  await saveFile(decisionsPath, formatDecisions(project.decisionsContent));
+  paths.push(decisionsPath);
+  counts.other++;
+
+  const statePath = join(gsdDir, 'STATE.md');
+  await saveFile(statePath, formatState(project.milestones));
+  paths.push(statePath);
+  counts.other++;
+
+  if (project.requirements.length > 0) {
+    const reqPath = join(gsdDir, 'REQUIREMENTS.md');
+    await saveFile(reqPath, formatRequirements(project.requirements));
+    paths.push(reqPath);
+    counts.requirements++;
+  }
+
+  // Milestones
+  for (const milestone of project.milestones) {
+    const mDir = join(milestonesBase, milestone.id);
+
+    // Roadmap (always written, even for empty milestones)
+    const roadmapPath = join(mDir, `${milestone.id}-ROADMAP.md`);
+    await saveFile(roadmapPath, formatRoadmap(milestone));
+    paths.push(roadmapPath);
+    counts.roadmaps++;
+
+    // Context
+    const contextPath = join(mDir, `${milestone.id}-CONTEXT.md`);
+    await saveFile(contextPath, formatContext(milestone.id));
+    paths.push(contextPath);
+    counts.contexts++;
+
+    // Research (skip if null)
+    if (milestone.research !== null) {
+      const researchPath = join(mDir, `${milestone.id}-RESEARCH.md`);
+      await saveFile(researchPath, milestone.research);
+      paths.push(researchPath);
+      counts.research++;
+    }
+
+    // Slices
+    for (const slice of milestone.slices) {
+      const sDir = join(mDir, 'slices', slice.id);
+      const tasksDir = join(sDir, 'tasks');
+
+      // Slice plan
+      const planPath = join(sDir, `${slice.id}-PLAN.md`);
+      await saveFile(planPath, formatPlan(slice));
+      paths.push(planPath);
+      counts.plans++;
+
+      // Slice research (skip if null)
+      if (slice.research !== null) {
+        const sliceResearchPath = join(sDir, `${slice.id}-RESEARCH.md`);
+        await saveFile(sliceResearchPath, slice.research);
+        paths.push(sliceResearchPath);
+        counts.research++;
+      }
+
+      // Slice summary (skip if null)
+      if (slice.summary !== null) {
+        const summaryContent = formatSliceSummary(slice, milestone.id);
+        if (summaryContent) {
+          const summaryPath = join(sDir, `${slice.id}-SUMMARY.md`);
+          await saveFile(summaryPath, summaryContent);
+          paths.push(summaryPath);
+          counts.sliceSummaries++;
+        }
+      }
+
+      // Tasks
+      for (const task of slice.tasks) {
+        // Task plan (always written)
+        const taskPlanPath = join(tasksDir, `${task.id}-PLAN.md`);
+        await saveFile(taskPlanPath, formatTaskPlan(task, slice.id, milestone.id));
+        paths.push(taskPlanPath);
+        counts.taskPlans++;
+
+        // Task summary (skip if null)
+        if (task.summary !== null) {
+          const taskSummaryContent = formatTaskSummary(task, slice.id, milestone.id);
+          if (taskSummaryContent) {
+            const taskSummaryPath = join(tasksDir, `${task.id}-SUMMARY.md`);
+            await saveFile(taskSummaryPath, taskSummaryContent);
+            paths.push(taskSummaryPath);
+            counts.taskSummaries++;
+          }
+        }
+      }
+    }
+  }
+
+  return { paths, counts };
+}

package/src/resources/extensions/gsd/prompts/review-migration.md

@@ -0,0 +1,66 @@
+## Review Migrated .gsd Directory
+
+A `/gsd migrate` command just wrote a `.gsd/` directory from an old `.planning` source. Your job is to audit the output and verify it meets GSD-2 standards before the user starts working with it.
+
+### Source
+- Old `.planning` directory: `{{sourcePath}}`
+- Written `.gsd` directory: `{{gsdPath}}`
+
+### Migration Stats
+{{previewStats}}
+
+### Review Checklist
+
+Work through each check. Report PASS/FAIL with specifics. Fix anything fixable in-place.
+
+#### 1. Structure Validation
+- Run `deriveState()` on the `.gsd` directory (import from `state.ts`, pass the **project root** as basePath)
+- Confirm it returns a coherent phase (not `pre-planning` unless the project is truly empty)
+- Confirm activeMilestone, activeSlice, activeTask are sensible for the project's completion state
+- Confirm progress counts match the migration preview stats
+
+#### 2. Roadmap Quality
+- Read `M001-ROADMAP.md` (and any other milestone roadmaps)
+- Confirm slice entries have meaningful titles (not file paths or garbled text)
+- Confirm `[x]`/`[ ]` completion markers are correct relative to the old roadmap
+- Confirm vision statement is present and meaningful (not empty or "Migration")
+
+#### 3. Content Spot-Check
+- Pick 2-3 slices with the most tasks and read their plan files
+- Confirm task titles and descriptions carry over meaningfully from the old plans
+- Confirm summary files exist for completed tasks and contain relevant content
+- Check that research files (if present) contain consolidated content, not empty stubs
+
+#### 4. Requirements (if any)
+- Read REQUIREMENTS.md
+- Confirm requirement IDs are present and non-duplicate
+- Confirm statuses make sense: completed old requirements should be `validated`, in-progress should be `active`
+
+#### 5. PROJECT.md
+- Read the written PROJECT.md
+- Confirm it contains the old project's description, not boilerplate
+- Confirm it reads like a useful project summary
+
+#### 6. Decisions
+- If DECISIONS.md was written, confirm it contains extracted decisions from old summaries (or is empty if no decisions existed)
+
+### Output Format
+
+Summarize your findings as:
+
+```
+Migration Review: <project name>
+================================
+Structure:     PASS/FAIL — <details>
+Roadmap:       PASS/FAIL — <details>
+Content:       PASS/FAIL — <details>
+Requirements:  PASS/FAIL/SKIP — <details>
+Project:       PASS/FAIL — <details>
+Decisions:     PASS/FAIL/SKIP — <details>
+
+Overall: PASS / PASS WITH NOTES / FAIL
+Issues: <list any problems found>
+Fixes applied: <list any in-place fixes made>
+```
+
+If the overall result is FAIL, explain what needs manual attention. If PASS WITH NOTES, explain what's imperfect but acceptable. If PASS, confirm the `.gsd` directory is ready for GSD-2 auto-mode.

package/src/resources/extensions/gsd/prompts/worktree-merge.md

@@ -0,0 +1,89 @@
+You are merging GSD artifacts from worktree **{{worktreeName}}** (branch `{{worktreeBranch}}`) into target branch `{{mainBranch}}`.
+
+## Context
+
+The worktree was created as a parallel workspace. It may contain new milestones, updated roadmaps, new plans, research, decisions, or other GSD artifacts that need to be reconciled with the main branch.
+
+### Commit History (worktree)
+
+```
+{{commitLog}}
+```
+
+### GSD Artifact Changes
+
+**Added files:**
+{{addedFiles}}
+
+**Modified files:**
+{{modifiedFiles}}
+
+**Removed files:**
+{{removedFiles}}
+
+### Full Diff
+
+```diff
+{{fullDiff}}
+```
+
+## Your Task
+
+Analyze the changes and guide the merge. Follow these steps exactly:
+
+### Step 1: Categorize Changes
+
+Classify each changed GSD artifact:
+- **New milestones** — entirely new M###/ directories with roadmaps
+- **New slices/tasks** — new planning artifacts within existing milestones
+- **Updated roadmaps** — modifications to existing M###-ROADMAP.md files
+- **Updated plans** — modifications to existing slice or task plans
+- **Research/context** — new or updated RESEARCH.md, CONTEXT.md files
+- **Decisions** — changes to DECISIONS.md
+- **Requirements** — changes to REQUIREMENTS.md
+- **Other** — anything else
+
+### Step 2: Conflict Assessment
+
+For each **modified** file, check whether the main branch version has also changed since the worktree branched off. Flag any files where both branches have diverged — these need manual reconciliation.
+
+Read the current main-branch version of each modified file and compare it against both the worktree version and the common ancestor to identify:
+- **Clean merges** — main hasn't changed, worktree changes can apply directly
+- **Conflicts** — both branches changed the same file; needs reconciliation
+- **Stale changes** — worktree modified a file that main has since replaced or removed
+
+### Step 3: Merge Strategy
+
+Present a merge plan to the user:
+
+1. For **clean merges**: list files that will merge without conflict
+2. For **conflicts**: show both versions side-by-side and propose a reconciled version
+3. For **new artifacts**: confirm they should be added to the main branch
+4. For **removed artifacts**: confirm the removals are intentional
+
+Ask the user to confirm the merge plan before proceeding.
+
+### Step 4: Execute Merge
+
+Once confirmed:
+
+1. If there are conflicts requiring manual reconciliation, apply the reconciled versions to the main branch working tree
+2. Run `git merge --squash {{worktreeBranch}}` to bring in all changes
+3. Review the staged changes — if any reconciled files need adjustment, apply them now
+4. Commit with message: `merge(worktree/{{worktreeName}}): <summary of what was merged>`
+5. Report what was merged
+
+### Step 5: Cleanup Prompt
+
+After a successful merge, ask the user whether to:
+- **Remove the worktree** — delete `.gsd/worktrees/{{worktreeName}}/` and the `{{worktreeBranch}}` branch
+- **Keep the worktree** — leave it for continued parallel work
+
+If the user chooses to remove it, run `/worktree remove {{worktreeName}}`.
+
+## Important
+
+- Never silently discard changes from either branch
+- When in doubt about a conflict, show both versions and ask the user
+- Preserve all GSD artifact formatting conventions (frontmatter, section structure, checkbox states)
+- If the worktree introduced new milestone IDs that conflict with main, flag this immediately