gsd-opencode 1.22.1 → 1.33.0

package/get-shit-done/bin/lib/workstream.cjs

@@ -0,0 +1,495 @@
+/**
+ * Workstream — CRUD operations for workstream namespacing
+ *
+ * Workstreams enable parallel milestones by scoping ROADMAP.md, STATE.md,
+ * REQUIREMENTS.md, and phases/ into .planning/workstreams/{name}/ directories.
+ *
+ * When no workstreams/ directory exists, GSD operates in "flat mode" with
+ * everything at .planning/ — backward compatible with pre-workstream installs.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, planningPaths, planningRoot, toPosixPath, getMilestoneInfo, generateSlugInternal, setActiveWorkstream, getActiveWorkstream, filterPlanFiles, filterSummaryFiles, readSubdirectories } = require('./core.cjs');
+const { stateExtractField } = require('./state.cjs');
+
+// ─── Migration ──────────────────────────────────────────────────────────────
+
+/**
+ * Migrate flat .planning/ layout to workstream mode.
+ * Moves per-workstream files (ROADMAP.md, STATE.md, REQUIREMENTS.md, phases/)
+ * into .planning/workstreams/{name}/. Shared files (PROJECT.md, config.json,
+ * milestones/, research/, codebase/, todos/) stay in place.
+ */
+function migrateToWorkstreams(cwd, workstreamName) {
+  if (!workstreamName || /[/\\]/.test(workstreamName) || workstreamName === '.' || workstreamName === '..') {
+    throw new Error('Invalid workstream name for migration');
+  }
+
+  const baseDir = planningRoot(cwd);
+  const wsDir = path.join(baseDir, 'workstreams', workstreamName);
+
+  if (fs.existsSync(path.join(baseDir, 'workstreams'))) {
+    throw new Error('Already in workstream mode — .planning/workstreams/ exists');
+  }
+
+  const toMove = [
+    { name: 'ROADMAP.md', type: 'file' },
+    { name: 'STATE.md', type: 'file' },
+    { name: 'REQUIREMENTS.md', type: 'file' },
+    { name: 'phases', type: 'dir' },
+  ];
+
+  fs.mkdirSync(wsDir, { recursive: true });
+
+  const filesMoved = [];
+  try {
+    for (const item of toMove) {
+      const src = path.join(baseDir, item.name);
+      if (fs.existsSync(src)) {
+        const dest = path.join(wsDir, item.name);
+        fs.renameSync(src, dest);
+        filesMoved.push(item.name);
+      }
+    }
+  } catch (err) {
+    for (const name of filesMoved) {
+      try { fs.renameSync(path.join(wsDir, name), path.join(baseDir, name)); } catch {}
+    }
+    try { fs.rmSync(wsDir, { recursive: true }); } catch {}
+    try { fs.rmdirSync(path.join(baseDir, 'workstreams')); } catch {}
+    throw err;
+  }
+
+  return { migrated: true, workstream: workstreamName, files_moved: filesMoved };
+}
+
+// ─── CRUD Commands ──────────────────────────────────────────────────────────
+
+function cmdWorkstreamCreate(cwd, name, options, raw) {
+  if (!name) {
+    error('workstream name required. Usage: workstream create <name>');
+  }
+
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!slug) {
+    error('Invalid workstream name — must contain at least one alphanumeric character');
+  }
+
+  const baseDir = planningRoot(cwd);
+  if (!fs.existsSync(baseDir)) {
+    error('.planning/ directory not found — run /gsd-new-project first');
+  }
+
+  const wsRoot = path.join(baseDir, 'workstreams');
+  const wsDir = path.join(wsRoot, slug);
+
+  if (fs.existsSync(wsDir) && fs.existsSync(path.join(wsDir, 'STATE.md'))) {
+    output({ created: false, error: 'already_exists', workstream: slug, path: toPosixPath(path.relative(cwd, wsDir)) }, raw);
+    return;
+  }
+
+  const isFlatMode = !fs.existsSync(wsRoot);
+  let migration = null;
+  if (isFlatMode && options.migrate !== false) {
+    const hasExistingWork = fs.existsSync(path.join(baseDir, 'ROADMAP.md')) ||
+                            fs.existsSync(path.join(baseDir, 'STATE.md')) ||
+                            fs.existsSync(path.join(baseDir, 'phases'));
+
+    if (hasExistingWork) {
+      const migrateName = options.migrateName || null;
+      let existingWsName;
+      if (migrateName) {
+        existingWsName = migrateName;
+      } else {
+        try {
+          const milestone = getMilestoneInfo(cwd);
+          existingWsName = generateSlugInternal(milestone.name) || 'default';
+        } catch {
+          existingWsName = 'default';
+        }
+      }
+
+      try {
+        migration = migrateToWorkstreams(cwd, existingWsName);
+      } catch (e) {
+        output({ created: false, error: 'migration_failed', message: e.message }, raw);
+        return;
+      }
+    } else {
+      fs.mkdirSync(wsRoot, { recursive: true });
+    }
+  }
+
+  fs.mkdirSync(wsDir, { recursive: true });
+  fs.mkdirSync(path.join(wsDir, 'phases'), { recursive: true });
+
+  const today = new Date().toISOString().split('T')[0];
+  const stateContent = [
+    '---',
+    `workstream: ${slug}`,
+    `created: ${today}`,
+    '---',
+    '',
+    '# Project State',
+    '',
+    '## Current Position',
+    '**Status:** Not started',
+    '**Current Phase:** None',
+    `**Last Activity:** ${today}`,
+    '**Last Activity Description:** Workstream created',
+    '',
+    '## Progress',
+    '**Phases Complete:** 0',
+    '**Current Plan:** N/A',
+    '',
+    '## Session Continuity',
+    '**Stopped At:** N/A',
+    '**Resume File:** None',
+    '',
+  ].join('\n');
+
+  const statePath = path.join(wsDir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    fs.writeFileSync(statePath, stateContent, 'utf-8');
+  }
+
+  setActiveWorkstream(cwd, slug);
+
+  const relPath = toPosixPath(path.relative(cwd, wsDir));
+  output({
+    created: true,
+    workstream: slug,
+    path: relPath,
+    state_path: relPath + '/STATE.md',
+    phases_path: relPath + '/phases',
+    migration: migration || null,
+    active: true,
+  }, raw);
+}
+
+function cmdWorkstreamList(cwd, raw) {
+  const wsRoot = path.join(planningRoot(cwd), 'workstreams');
+
+  if (!fs.existsSync(wsRoot)) {
+    output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw);
+    return;
+  }
+
+  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
+  const workstreams = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const wsDir = path.join(wsRoot, entry.name);
+    const phasesDir = path.join(wsDir, 'phases');
+
+    const phaseDirs = readSubdirectories(phasesDir);
+    const phaseCount = phaseDirs.length;
+    let completedCount = 0;
+    for (const d of phaseDirs) {
+      try {
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
+        const plans = filterPlanFiles(phaseFiles);
+        const summaries = filterSummaryFiles(phaseFiles);
+        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
+      } catch {}
+    }
+
+    let status = 'unknown', currentPhase = null;
+    try {
+      const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8');
+      status = stateExtractField(stateContent, 'Status') || 'unknown';
+      currentPhase = stateExtractField(stateContent, 'Current Phase');
+    } catch {}
+
+    workstreams.push({
+      name: entry.name,
+      path: toPosixPath(path.relative(cwd, wsDir)),
+      has_roadmap: fs.existsSync(path.join(wsDir, 'ROADMAP.md')),
+      has_state: fs.existsSync(path.join(wsDir, 'STATE.md')),
+      status,
+      current_phase: currentPhase,
+      phase_count: phaseCount,
+      completed_phases: completedCount,
+    });
+  }
+
+  output({ mode: 'workstream', workstreams, count: workstreams.length }, raw);
+}
+
+function cmdWorkstreamStatus(cwd, name, raw) {
+  if (!name) error('workstream name required. Usage: workstream status <name>');
+  if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name');
+
+  const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
+  if (!fs.existsSync(wsDir)) {
+    output({ found: false, workstream: name }, raw);
+    return;
+  }
+
+  const p = planningPaths(cwd, name);
+  const relPath = toPosixPath(path.relative(cwd, wsDir));
+
+  const files = {
+    roadmap: fs.existsSync(p.roadmap),
+    state: fs.existsSync(p.state),
+    requirements: fs.existsSync(p.requirements),
+  };
+
+  const phases = [];
+  for (const dir of readSubdirectories(p.phases).sort()) {
+    try {
+      const phaseFiles = fs.readdirSync(path.join(p.phases, dir));
+      const plans = filterPlanFiles(phaseFiles);
+      const summaries = filterSummaryFiles(phaseFiles);
+      phases.push({
+        directory: dir,
+        status: summaries.length >= plans.length && plans.length > 0 ? 'complete' :
+                plans.length > 0 ? 'in_progress' : 'pending',
+        plan_count: plans.length,
+        summary_count: summaries.length,
+      });
+    } catch {}
+  }
+
+  let stateInfo = {};
+  try {
+    const stateContent = fs.readFileSync(p.state, 'utf-8');
+    stateInfo = {
+      status: stateExtractField(stateContent, 'Status') || 'unknown',
+      current_phase: stateExtractField(stateContent, 'Current Phase'),
+      last_activity: stateExtractField(stateContent, 'Last Activity'),
+    };
+  } catch {}
+
+  output({
+    found: true,
+    workstream: name,
+    path: relPath,
+    files,
+    phases,
+    phase_count: phases.length,
+    completed_phases: phases.filter(ph => ph.status === 'complete').length,
+    ...stateInfo,
+  }, raw);
+}
+
+function cmdWorkstreamComplete(cwd, name, options, raw) {
+  if (!name) error('workstream name required. Usage: workstream complete <name>');
+  if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name');
+
+  const root = planningRoot(cwd);
+  const wsRoot = path.join(root, 'workstreams');
+  const wsDir = path.join(wsRoot, name);
+
+  if (!fs.existsSync(wsDir)) {
+    output({ completed: false, error: 'not_found', workstream: name }, raw);
+    return;
+  }
+
+  const active = getActiveWorkstream(cwd);
+  if (active === name) setActiveWorkstream(cwd, null);
+
+  const archiveDir = path.join(root, 'milestones');
+  const today = new Date().toISOString().split('T')[0];
+  let archivePath = path.join(archiveDir, `ws-${name}-${today}`);
+  let suffix = 1;
+  while (fs.existsSync(archivePath)) {
+    archivePath = path.join(archiveDir, `ws-${name}-${today}-${suffix++}`);
+  }
+
+  fs.mkdirSync(archivePath, { recursive: true });
+
+  const filesMoved = [];
+  try {
+    const entries = fs.readdirSync(wsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      fs.renameSync(path.join(wsDir, entry.name), path.join(archivePath, entry.name));
+      filesMoved.push(entry.name);
+    }
+  } catch (err) {
+    for (const fname of filesMoved) {
+      try { fs.renameSync(path.join(archivePath, fname), path.join(wsDir, fname)); } catch {}
+    }
+    try { fs.rmSync(archivePath, { recursive: true }); } catch {}
+    if (active === name) setActiveWorkstream(cwd, name);
+    output({ completed: false, error: 'archive_failed', message: err.message, workstream: name }, raw);
+    return;
+  }
+
+  try { fs.rmdirSync(wsDir); } catch {}
+
+  let remainingWs = 0;
+  try {
+    remainingWs = fs.readdirSync(wsRoot, { withFileTypes: true }).filter(e => e.isDirectory()).length;
+    if (remainingWs === 0) fs.rmdirSync(wsRoot);
+  } catch {}
+
+  output({
+    completed: true,
+    workstream: name,
+    archived_to: toPosixPath(path.relative(cwd, archivePath)),
+    remaining_workstreams: remainingWs,
+    reverted_to_flat: remainingWs === 0,
+  }, raw);
+}
+
+// ─── Active Workstream Commands ──────────────────────────────────────────────
+
+function cmdWorkstreamSet(cwd, name, raw) {
+  if (!name || name === '--clear') {
+    if (name !== '--clear') {
+      error('Workstream name required. Usage: workstream set <name> (or workstream set --clear to unset)');
+    }
+    const previous = getActiveWorkstream(cwd);
+    setActiveWorkstream(cwd, null);
+    output({ active: null, cleared: true, previous: previous || null }, raw);
+    return;
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, and underscores only' }, raw);
+    return;
+  }
+
+  const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
+  if (!fs.existsSync(wsDir)) {
+    output({ active: null, error: 'not_found', workstream: name }, raw);
+    return;
+  }
+
+  setActiveWorkstream(cwd, name);
+  output({ active: name, set: true }, raw, name);
+}
+
+function cmdWorkstreamGet(cwd, raw) {
+  const active = getActiveWorkstream(cwd);
+  const wsRoot = path.join(planningRoot(cwd), 'workstreams');
+  output({ active, mode: fs.existsSync(wsRoot) ? 'workstream' : 'flat' }, raw, active || 'none');
+}
+
+function cmdWorkstreamProgress(cwd, raw) {
+  const root = planningRoot(cwd);
+  const wsRoot = path.join(root, 'workstreams');
+
+  if (!fs.existsSync(wsRoot)) {
+    output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw);
+    return;
+  }
+
+  const active = getActiveWorkstream(cwd);
+  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
+  const workstreams = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const wsDir = path.join(wsRoot, entry.name);
+    const phasesDir = path.join(wsDir, 'phases');
+
+    const phaseDirsProgress = readSubdirectories(phasesDir);
+    const phaseCount = phaseDirsProgress.length;
+    let completedCount = 0, totalPlans = 0, completedPlans = 0;
+    for (const d of phaseDirsProgress) {
+      try {
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
+        const plans = filterPlanFiles(phaseFiles);
+        const summaries = filterSummaryFiles(phaseFiles);
+        totalPlans += plans.length;
+        completedPlans += Math.min(summaries.length, plans.length);
+        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
+      } catch {}
+    }
+
+    let roadmapPhaseCount = phaseCount;
+    try {
+      const roadmapContent = fs.readFileSync(path.join(wsDir, 'ROADMAP.md'), 'utf-8');
+      const phaseMatches = roadmapContent.match(/^###?\s+Phase\s+\d/gm);
+      if (phaseMatches) roadmapPhaseCount = phaseMatches.length;
+    } catch {}
+
+    let status = 'unknown', currentPhase = null;
+    try {
+      const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8');
+      status = stateExtractField(stateContent, 'Status') || 'unknown';
+      currentPhase = stateExtractField(stateContent, 'Current Phase');
+    } catch {}
+
+    workstreams.push({
+      name: entry.name,
+      active: entry.name === active,
+      status,
+      current_phase: currentPhase,
+      phases: `${completedCount}/${roadmapPhaseCount}`,
+      plans: `${completedPlans}/${totalPlans}`,
+      progress_percent: roadmapPhaseCount > 0 ? Math.round((completedCount / roadmapPhaseCount) * 100) : 0,
+    });
+  }
+
+  output({ mode: 'workstream', active, workstreams, count: workstreams.length }, raw);
+}
+
+// ─── Collision Detection ────────────────────────────────────────────────────
+
+/**
+ * Return other workstreams that are NOT complete.
+ * Used to detect whether the milestone has active parallel work
+ * when a workstream finishes its last phase.
+ */
+function getOtherActiveWorkstreams(cwd, excludeWs) {
+  const wsRoot = path.join(planningRoot(cwd), 'workstreams');
+  if (!fs.existsSync(wsRoot)) return [];
+
+  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
+  const others = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === excludeWs) continue;
+
+    const wsDir = path.join(wsRoot, entry.name);
+    const statePath = path.join(wsDir, 'STATE.md');
+
+    let status = 'unknown', currentPhase = null;
+    try {
+      const content = fs.readFileSync(statePath, 'utf-8');
+      status = stateExtractField(content, 'Status') || 'unknown';
+      currentPhase = stateExtractField(content, 'Current Phase');
+    } catch {}
+
+    if (status.toLowerCase().includes('milestone complete') ||
+        status.toLowerCase().includes('archived')) {
+      continue;
+    }
+
+    const phasesDir = path.join(wsDir, 'phases');
+    const phaseDirsOther = readSubdirectories(phasesDir);
+    const phaseCount = phaseDirsOther.length;
+    let completedCount = 0;
+    for (const d of phaseDirsOther) {
+      try {
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
+        const plans = filterPlanFiles(phaseFiles);
+        const summaries = filterSummaryFiles(phaseFiles);
+        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
+      } catch {}
+    }
+
+    others.push({ name: entry.name, status, current_phase: currentPhase, phases: `${completedCount}/${phaseCount}` });
+  }
+
+  return others;
+}
+
+module.exports = {
+  migrateToWorkstreams,
+  cmdWorkstreamCreate,
+  cmdWorkstreamList,
+  cmdWorkstreamStatus,
+  cmdWorkstreamComplete,
+  cmdWorkstreamSet,
+  cmdWorkstreamGet,
+  cmdWorkstreamProgress,
+  getOtherActiveWorkstreams,
+};

package/get-shit-done/references/agent-contracts.md

@@ -0,0 +1,79 @@
+# Agent Contracts
+
+Completion markers and handoff schemas for all GSD agents. Workflows use these markers to detect agent completion and route accordingly.
+
+This doc describes what IS, not what should be. Casing inconsistencies are documented as they appear in agent source files.
+
+---
+
+## Agent Registry
+
+| Agent | Role | Completion Markers |
+|-------|------|--------------------|
+| gsd-planner | Plan creation | `## PLANNING COMPLETE` |
+| gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` |
+| gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` |
+| gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` |
+| gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED` |
+| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` |
+| gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` |
+| gsd-ui-checker | UI validation | `## ISSUES FOUND` |
+| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` |
+| gsd-verifier | Post-execution verification | `## Verification Complete` (title case) |
+| gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (title case) |
+| gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE` (non-standard) |
+| gsd-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE` (non-standard) |
+| gsd-codebase-mapper | Codebase analysis | No marker (writes docs directly) |
+| gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) |
+| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) |
+| gsd-doc-writer | Doc generation | No marker (writes docs directly) |
+| gsd-advisor-researcher | Advisory research | No marker (utility agent) |
+| gsd-user-profiler | User profiling | No marker (returns JSON in analysis tags) |
+| gsd-intel-updater | Codebase intelligence analysis | `## INTEL UPDATE COMPLETE`, `## INTEL UPDATE FAILED` |
+
+## Marker Rules
+
+1. **ALL-CAPS markers** (e.g., `## PLANNING COMPLETE`) are the standard convention
+2. **Title-case markers** (e.g., `## Verification Complete`) exist in gsd-verifier and gsd-integration-checker -- these are intentional as-is, not bugs
+3. **Non-standard markers** (e.g., `## PARTIAL`, `## ESCALATE`) in audit agents indicate partial results requiring orchestrator judgment
+4. **Agents without markers** either write artifacts directly to disk or return structured data (JSON/sections) that the caller parses
+5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
+
+## Key Handoff Contracts
+
+### Planner -> Executor (via PLAN.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, type, wave, depends_on, files_modified, autonomous, requirements |
+| `<objective>` | Yes | What the plan achieves |
+| `<tasks>` | Yes | Ordered task list with type, files, action, verify, acceptance_criteria |
+| `<verification>` | Yes | Overall verification steps |
+| `<success_criteria>` | Yes | Measurable completion criteria |
+
+### Executor -> Verifier (via SUMMARY.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, subsystem, tags, key-files, metrics |
+| Commits table | Yes | Per-task commit hashes and descriptions |
+| Deviations section | Yes | Auto-fixed issues or "None" |
+| Self-Check | Yes | PASSED or FAILED with details |
+
+## Workflow Regex Patterns
+
+Workflows match these markers to detect agent completion:
+
+**plan-phase.md matches:**
+- `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` (researcher output)
+- `## PLANNING COMPLETE` (planner output)
+- `## CHECKPOINT REACHED` (planner/executor pause)
+- `## VERIFICATION PASSED` / `## ISSUES FOUND` (plan-checker output)
+
+**execute-phase.md matches:**
+- `## PHASE COMPLETE` (all plans in phase done)
+- `## Self-Check: FAILED` (summary self-check)
+
+> **NOTE:** `## PLAN COMPLETE` is the gsd-executor's completion marker but execute-phase.md does not regex-match it. Instead, it detects executor completion via spot-checks (SUMMARY.md existence, git commit state). This is intentional behavior, not a mismatch.

package/get-shit-done/references/artifact-types.md

@@ -0,0 +1,113 @@
+# GSD Artifact Types
+
+This reference documents all artifact types in the GSD planning taxonomy. Each type has a defined
+shape, lifecycle, location, and consumption mechanism. A well-formatted artifact that no workflow
+reads is inert — the consumption mechanism is what gives an artifact meaning.
+
+---
+
+## Core Artifacts
+
+### ROADMAP.md
+- **Shape**: Milestone + phase listing with goals and canonical refs
+- **Lifecycle**: Created → Updated per milestone → Archived
+- **Location**: `.planning/ROADMAP.md`
+- **Consumed by**: `plan-phase`, `discuss-phase`, `execute-phase`, `progress`, `state` commands
+
+### STATE.md
+- **Shape**: Current position tracker (phase, plan, progress, decisions)
+- **Lifecycle**: Continuously updated throughout the project
+- **Location**: `.planning/STATE.md`
+- **Consumed by**: All orchestration workflows; `resume-project`, `progress`, `next` commands
+
+### REQUIREMENTS.md
+- **Shape**: Numbered acceptance criteria with traceability table
+- **Lifecycle**: Created at project start → Updated as requirements are satisfied
+- **Location**: `.planning/REQUIREMENTS.md`
+- **Consumed by**: `discuss-phase`, `plan-phase`, CONTEXT.md generation; executor marks complete
+
+### CONTEXT.md (per-phase)
+- **Shape**: 6-section format: domain, decisions, canonical_refs, code_context, specifics, deferred
+- **Lifecycle**: Created before planning → Used during planning and execution → Superseded by next phase
+- **Location**: `.planning/phases/XX-name/XX-CONTEXT.md`
+- **Consumed by**: `plan-phase` (reads decisions), `execute-phase` (reads code_context and canonical_refs)
+
+### PLAN.md (per-plan)
+- **Shape**: Frontmatter + objective + tasks with types + success criteria + output spec
+- **Lifecycle**: Created by planner → Executed → SUMMARY.md produced
+- **Location**: `.planning/phases/XX-name/XX-YY-PLAN.md`
+- **Consumed by**: `execute-phase` executor; task commits reference plan IDs
+
+### SUMMARY.md (per-plan)
+- **Shape**: Frontmatter with dependency graph + narrative + deviations + self-check
+- **Lifecycle**: Created at plan completion → read by subsequent plans in same phase
+- **Location**: `.planning/phases/XX-name/XX-YY-SUMMARY.md`
+- **Consumed by**: Orchestrator (progress), planner (context for future plans), `milestone-summary`
+
+### HANDOFF.json / .continue-here.md
+- **Shape**: Structured pause state (JSON machine-readable + Markdown human-readable)
+- **Lifecycle**: Created on pause → Consumed on resume → Replaced by next pause
+- **Location**: `.planning/HANDOFF.json` + `.planning/phases/XX-name/.continue-here.md` (or spike/deliberation path)
+- **Consumed by**: `resume-project` workflow
+
+---
+
+## Extended Artifacts
+
+### DISCUSSION-LOG.md (per-phase)
+- **Shape**: Audit trail of assumptions and corrections from discuss-phase
+- **Lifecycle**: Created at discussion time → read-only audit record
+- **Location**: `.planning/phases/XX-name/XX-DISCUSSION-LOG.md`
+- **Consumed by**: Human review; not read by automated workflows
+
+### USER-PROFILE.md
+- **Shape**: Calibration tier and preferences profile
+- **Lifecycle**: Created by `profile-user` → Updated as preferences are observed
+- **Location**: `$HOME/.config/opencode/get-shit-done/USER-PROFILE.md`
+- **Consumed by**: `discuss-phase-assumptions` (calibration tier), `plan-phase`
+
+### SPIKE.md / DESIGN.md (per-spike)
+- **Shape**: Research question + methodology + findings + recommendation
+- **Lifecycle**: Created → Investigated → Decided → Archived
+- **Location**: `.planning/spikes/SPIKE-NNN/`
+- **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
+
+---
+
+## Standing Reference Artifacts
+
+### METHODOLOGY.md
+
+- **Shape**: Standing reference — reusable interpretive frameworks (lenses) that apply across phases
+- **Lifecycle**: Created → Active → Superseded (when a lens is replaced by a better one)
+- **Location**: `.planning/METHODOLOGY.md` (project-scoped, not phase-scoped)
+- **Contents**: Named lenses, each documenting:
+  - What it diagnoses (the class of problem it detects)
+  - What it recommends (the class of response it prescribes)
+  - When to apply (triggering conditions)
+  - Example: Bayesian updating, STRIDE threat modeling, Cost-of-delay prioritization
+- **Consumed by**:
+  - `discuss-phase-assumptions` — reads METHODOLOGY.md (if it exists) and applies active lenses
+    to the current assumption analysis before surfacing findings to the user
+  - `plan-phase` — reads METHODOLOGY.md to inform methodology selection for each plan
+  - `pause-work` — includes METHODOLOGY.md in the Required Reading section of `.continue-here.md`
+    so resuming agents inherit the project's analytical orientation
+
+**Why consumption matters:** A METHODOLOGY.md that no workflow reads is inert. The lenses only
+take effect when an agent loads them into its reasoning context before analysis. This is why
+both the discuss-phase-assumptions and pause-work workflows explicitly reference this file.
+
+**Example lens entry:**
+
+```markdown
+## Bayesian Updating
+
+**Diagnoses:** Decisions made with stale priors — assumptions formed early that evidence has since
+contradicted, but which remain embedded in the plan.
+
+**Recommends:** Before confirming an assumption, ask: "What evidence would make me change this?"
+If no evidence could change it, it's a belief, not an assumption. Flag for user review.
+
+**Apply when:** Any assumption carries Confident label but was formed before recent architectural
+changes, library upgrades, or scope corrections.
+```