@opengsd/get-shit-done-redux 1.0.0

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

@@ -0,0 +1,379 @@
+/**
+ * Learnings — Global knowledge store with CRUD operations
+ *
+ * Provides a cross-project learnings store at ~/.gsd/knowledge/.
+ * Each learning is stored as an individual JSON file with content-hash
+ * deduplication. Supports write, read, list, query, delete, copy-from-project,
+ * and prune operations.
+ *
+ * Storage format: { id, source_project, date, context, learning, tags, content_hash }
+ * File naming: {id}.json
+ * Deduplication: SHA-256 of learning text + source_project
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+const { output, error: coreError } = require('./core.cjs');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_STORE_DIR = path.join(os.homedir(), '.gsd', 'knowledge');
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Get the store directory, allowing override for testing.
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {string}
+ */
+function getStoreDir(opts) {
+  return (opts && opts.storeDir) || DEFAULT_STORE_DIR;
+}
+
+/**
+ * Ensure the store directory exists. Created on first write, not on install.
+ * @param {string} dir
+ */
+function ensureStoreDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Generate a content hash for deduplication.
+ * Uses SHA-256 of learning text combined with source_project.
+ * @param {string} learning
+ * @param {string} sourceProject
+ * @returns {string}
+ */
+function contentHash(learning, sourceProject) {
+  return crypto.createHash('sha256')
+    .update(learning + '\n' + sourceProject)
+    .digest('hex');
+}
+
+/**
+ * Generate a unique ID based on timestamp + random suffix.
+ * @returns {string}
+ */
+function generateId() {
+  const ts = Date.now().toString(36);
+  const rand = crypto.randomBytes(4).toString('hex');
+  return `${ts}-${rand}`;
+}
+
+/**
+ * Read and parse a single learning JSON file.
+ * Returns null (with stderr warning) for malformed files.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function readLearningFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    process.stderr.write(`Warning: skipping malformed file ${filePath}: ${err.message}\n`);
+    return null;
+  }
+}
+
+// ─── CRUD Operations ─────────────────────────────────────────────────────────
+
+/**
+ * Write a learning to the global store.
+ * Deduplicates by content hash — same content from same project is not stored twice.
+ *
+ * @param {object} entry
+ * @param {string} entry.source_project - Project name or path
+ * @param {string} entry.learning - The learning text
+ * @param {string} [entry.context] - Additional context
+ * @param {string[]} [entry.tags] - Tags for querying
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {{ id: string, created: boolean, content_hash: string }}
+ */
+function learningsWrite(entry, opts) {
+  const dir = getStoreDir(opts);
+  ensureStoreDir(dir);
+
+  const hash = contentHash(entry.learning, entry.source_project);
+
+  // Check for duplicate by scanning existing files
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    const existing = readLearningFile(path.join(dir, file));
+    if (existing && existing.content_hash === hash) {
+      return { id: existing.id, created: false, content_hash: hash };
+    }
+  }
+
+  const id = generateId();
+  const record = {
+    id,
+    source_project: entry.source_project,
+    date: new Date().toISOString(),
+    context: entry.context || '',
+    learning: entry.learning,
+    tags: entry.tags || [],
+    content_hash: hash,
+  };
+
+  platformWriteSync(path.join(dir, `${id}.json`), JSON.stringify(record, null, 2));
+  return { id, created: true, content_hash: hash };
+}
+
+/**
+ * Read a single learning by ID.
+ *
+ * @param {string} id
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {object|null}
+ */
+function learningsRead(id, opts) {
+  if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id)) return null;
+  const dir = getStoreDir(opts);
+  const filePath = path.join(dir, `${id}.json`);
+  if (!fs.existsSync(filePath)) return null;
+  return readLearningFile(filePath);
+}
+
+/**
+ * List all learnings, sorted by date (newest first).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {object[]}
+ */
+function learningsList(opts) {
+  const dir = getStoreDir(opts);
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  const results = [];
+  for (const file of files) {
+    const record = readLearningFile(path.join(dir, file));
+    if (record) results.push(record);
+  }
+
+  // Sort by date descending (newest first)
+  results.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  return results;
+}
+
+/**
+ * Query learnings by tag.
+ *
+ * @param {object} query
+ * @param {string} [query.tag] - Tag to filter by
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {object[]}
+ */
+function learningsQuery(query, opts) {
+  const all = learningsList(opts);
+  if (query && query.tag) {
+    return all.filter(r => r.tags && r.tags.includes(query.tag));
+  }
+  return all;
+}
+
+/**
+ * Delete a learning by ID.
+ *
+ * @param {string} id
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {boolean} true if deleted, false if not found
+ */
+function learningsDelete(id, opts) {
+  if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id)) return false;
+  const dir = getStoreDir(opts);
+  const filePath = path.join(dir, `${id}.json`);
+  if (!fs.existsSync(filePath)) return false;
+  fs.unlinkSync(filePath);
+  return true;
+}
+
+/**
+ * Copy learnings from a project's LEARNINGS.md into the global store.
+ * Parses markdown sections as individual learnings. Deduplicates by content hash.
+ *
+ * Expected LEARNINGS.md format:
+ *   ## Section Title
+ *   Learning content paragraph(s)...
+ *
+ *   ## Another Section
+ *   More content...
+ *
+ * @param {string} planningDir - Path to .planning/ directory (or directory containing LEARNINGS.md)
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @param {string} [opts.sourceProject] - Project name (defaults to directory basename)
+ * @returns {{ total: number, created: number, skipped: number }}
+ */
+function learningsCopyFromProject(planningDir, opts) {
+  const learningsPath = path.join(planningDir, 'LEARNINGS.md');
+  if (!fs.existsSync(learningsPath)) {
+    return { total: 0, created: 0, skipped: 0 };
+  }
+
+  const content = fs.readFileSync(learningsPath, 'utf-8');
+  const sourceProject = (opts && opts.sourceProject) || path.basename(path.resolve(planningDir, '..'));
+
+  // Parse markdown: split on ## headings
+  const sections = content.split(/^## /m).slice(1); // skip preamble before first ##
+  let created = 0;
+  let skipped = 0;
+
+  for (const section of sections) {
+    const lines = section.trim().split('\n');
+    const title = lines[0].trim();
+    const body = lines.slice(1).join('\n').trim();
+    if (!body) continue;
+
+    // Extract tags from title (simple: use words as tags)
+    const tags = title.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+
+    const result = learningsWrite({
+      source_project: sourceProject,
+      learning: body,
+      context: title,
+      tags,
+    }, opts);
+
+    if (result.created) {
+      created++;
+    } else {
+      skipped++;
+    }
+  }
+
+  return { total: created + skipped, created, skipped };
+}
+
+/**
+ * Prune learnings older than a given threshold.
+ *
+ * @param {string} olderThan - Duration string like "90d", "30d", "7d"
+ * @param {object} [opts]
+ * @param {string} [opts.storeDir] - Override store directory
+ * @returns {{ removed: number, kept: number }}
+ */
+function learningsPrune(olderThan, opts) {
+  const match = /^(\d+)d$/.exec(olderThan);
+  if (!match) {
+    throw new Error(`Invalid duration format: "${olderThan}" — expected format like "90d"`);
+  }
+
+  const days = parseInt(match[1], 10);
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+  const dir = getStoreDir(opts);
+
+  if (!fs.existsSync(dir)) return { removed: 0, kept: 0 };
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  let removed = 0;
+  let kept = 0;
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const record = readLearningFile(filePath);
+    if (!record) continue;
+
+    const recordDate = new Date(record.date);
+    if (recordDate < cutoff) {
+      fs.unlinkSync(filePath);
+      removed++;
+    } else {
+      kept++;
+    }
+  }
+
+  return { removed, kept };
+}
+
+// ─── CLI Command Handlers ────────────────────────────────────────────────────
+
+/**
+ * Handle `gsd-tools learnings list`
+ * @param {boolean} raw - Raw output flag
+ */
+function cmdLearningsList(raw) {
+  const results = learningsList();
+  output({ learnings: results, count: results.length }, raw);
+}
+
+/**
+ * Handle `gsd-tools learnings query --tag <tag>`
+ * @param {string} tag
+ * @param {boolean} raw - Raw output flag
+ */
+function cmdLearningsQuery(tag, raw) {
+  const results = learningsQuery({ tag });
+  output({ learnings: results, count: results.length, tag }, raw);
+}
+
+/**
+ * Handle `gsd-tools learnings copy`
+ * @param {string} cwd - Current working directory
+ * @param {boolean} raw - Raw output flag
+ */
+function cmdLearningsCopy(cwd, raw) {
+  const planningDir = path.join(cwd, '.planning');
+  const result = learningsCopyFromProject(planningDir);
+  output(result, raw);
+}
+
+/**
+ * Handle `gsd-tools learnings prune --older-than <duration>`
+ * @param {string} olderThan - Duration string like "90d"
+ * @param {boolean} raw - Raw output flag
+ */
+function cmdLearningsPrune(olderThan, raw) {
+  try {
+    const result = learningsPrune(olderThan);
+    output(result, raw);
+  } catch (err) {
+    coreError(err.message);
+  }
+}
+
+/**
+ * Handle `gsd-tools learnings delete <id>`
+ * @param {string} id
+ * @param {boolean} raw - Raw output flag
+ */
+function cmdLearningsDelete(id, raw) {
+  if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id)) {
+    coreError(`Invalid learning ID: "${id}"`);
+  }
+  const deleted = learningsDelete(id);
+  output({ id, deleted }, raw);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  learningsWrite,
+  learningsRead,
+  learningsList,
+  learningsQuery,
+  learningsDelete,
+  learningsCopyFromProject,
+  learningsPrune,
+  cmdLearningsList,
+  cmdLearningsQuery,
+  cmdLearningsCopy,
+  cmdLearningsPrune,
+  cmdLearningsDelete,
+  DEFAULT_STORE_DIR,
+};

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

@@ -0,0 +1,314 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, output, error } = require('./core.cjs');
+const { platformWriteSync, platformEnsureDir } = require('./shell-command-projection.cjs');
+const { planningPaths } = require('./planning-workspace.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { writeStateMd, stateReplaceFieldWithFallback } = require('./state.cjs');
+const { formatGsdSlash, resolveRuntime } = require('./runtime-slash.cjs');
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const reqPath = planningPaths(cwd).requirements;
+  if (!fs.existsSync(reqPath)) {
+    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+    return;
+  }
+
+  let reqContent = fs.readFileSync(reqPath, 'utf-8');
+  const updated = [];
+  const alreadyComplete = [];
+  const notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    // Use replace() directly and compare — avoids test()+replace() global regex
+    // lastIndex bug where test() advances state and replace() misses matches.
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
+    if (afterCheckbox !== reqContent) {
+      reqContent = afterCheckbox;
+      found = true;
+    }
+
+    // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+    const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    const afterTable = reqContent.replace(tablePattern, '$1 Complete $2');
+    if (afterTable !== reqContent) {
+      reqContent = afterTable;
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      // Check if already complete before declaring not_found.
+      // Non-global flag is fine here — we only need to know if a match exists.
+      const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i');
+      const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'i');
+      if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
+        alreadyComplete.push(reqId);
+      } else {
+        notFound.push(reqId);
+      }
+    }
+  }
+
+  if (updated.length > 0) {
+    platformWriteSync(reqPath, reqContent);
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    already_complete: alreadyComplete,
+    not_found: notFound,
+    total: reqIds.length,
+  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+
+function cmdMilestoneComplete(cwd, version, options, raw) {
+  if (!version) {
+    error('version required for milestone complete (e.g., v1.0)');
+  }
+
+  const roadmapPath = planningPaths(cwd).roadmap;
+  const reqPath = planningPaths(cwd).requirements;
+  const statePath = planningPaths(cwd).state;
+  const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md');
+  const archiveDir = path.join(cwd, '.planning', 'milestones');
+  const phasesDir = planningPaths(cwd).phases;
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  platformEnsureDir(archiveDir);
+
+  // Scope stats and accomplishments to only the phases belonging to the
+  // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+  // (same logic used by cmdPhasesList and other callers).
+  const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+  if (isDirInMilestone.missingExplicitVersion) {
+    error(`no phases found for milestone ${version} in ROADMAP.md`);
+  }
+
+  // Gather stats from phases (scoped to current milestone only)
+  let phaseCount = 0;
+  let totalPlans = 0;
+  let totalTasks = 0;
+  const accomplishments = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    for (const dir of dirs) {
+      if (!isDirInMilestone(dir)) continue;
+
+      phaseCount++;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+      totalPlans += plans.length;
+
+      // Extract one-liners from summaries
+      for (const s of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const fm = extractFrontmatter(content);
+          const oneLiner = fm['one-liner'] || extractOneLinerFromBody(content);
+          if (oneLiner) {
+            accomplishments.push(oneLiner);
+          }
+          // Count tasks: prefer **Tasks:** N from Performance section,
+          // then <task XML tags, then ## Task N markdown headers
+          const tasksFieldMatch = content.match(/\*\*Tasks:\*\*\s*(\d+)/);
+          if (tasksFieldMatch) {
+            totalTasks += parseInt(tasksFieldMatch[1], 10);
+          } else {
+            const xmlTaskMatches = content.match(/<task[\s>]/gi) || [];
+            const mdTaskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+            totalTasks += xmlTaskMatches.length || mdTaskMatches.length;
+          }
+        } catch { /* intentionally empty */ }
+      }
+    }
+  } catch { /* intentionally empty */ }
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    platformWriteSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent);
+  }
+
+  // Archive REQUIREMENTS.md
+  if (fs.existsSync(reqPath)) {
+    const reqContent = fs.readFileSync(reqPath, 'utf-8');
+    const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+    platformWriteSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
+  }
+
+  // Archive audit file if exists
+  const auditFile = path.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+  if (fs.existsSync(auditFile)) {
+    fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+  }
+
+  // Create/append MILESTONES.md entry
+  const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+
+  if (fs.existsSync(milestonesPath)) {
+    const existing = fs.readFileSync(milestonesPath, 'utf-8');
+    if (!existing.trim()) {
+      // Empty file — treat like new
+      platformWriteSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+    } else {
+      // Insert after the header line(s) for reverse chronological order (newest first)
+      const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+      if (headerMatch) {
+        const header = headerMatch[1];
+        const rest = existing.slice(header.length);
+        platformWriteSync(milestonesPath, header + milestoneEntry + rest);
+      } else {
+        // No recognizable header — prepend the entry
+        platformWriteSync(milestonesPath, milestoneEntry + existing);
+      }
+    }
+  } else {
+    platformWriteSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+  }
+
+  // Update STATE.md — keep frontmatter/body semantically aligned after closure
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null,
+      `${version} milestone completed and archived`);
+
+    // Reset Current Position narrative so resume/progress flows do not keep
+    // pointing at closed-phase execution instructions.
+    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    const closedPositionBody =
+      `\nPhase: Milestone ${version} complete\n` +
+      `Plan: —\n` +
+      `Status: Awaiting next milestone\n` +
+      `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
+    if (positionPattern.test(stateContent)) {
+      stateContent = stateContent.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+    } else {
+      stateContent = `${stateContent.trimEnd()}\n\n## Current Position\n${closedPositionBody}`;
+    }
+
+    // Normalize operator-next-step tails that can become stale after close.
+    const operatorPattern = /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    if (operatorPattern.test(stateContent)) {
+      stateContent = stateContent.replace(
+        operatorPattern,
+        `$1\n- Start the next milestone with ${formatGsdSlash('new-milestone', resolveRuntime(cwd))}\n\n`,
+      );
+    } else {
+      stateContent = `${stateContent.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${formatGsdSlash('new-milestone', resolveRuntime(cwd))}\n`;
+    }
+
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      platformEnsureDir(phaseArchiveDir);
+
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of phaseDirNames) {
+        if (!isDirInMilestone(dir)) continue;
+        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
+        archivedCount++;
+      }
+      phasesArchived = archivedCount > 0;
+    } catch { /* intentionally empty */ }
+  }
+
+  const result = {
+    version,
+    name: milestoneName,
+    date: today,
+    phases: phaseCount,
+    plans: totalPlans,
+    tasks: totalTasks,
+    accomplishments,
+    archived: {
+      roadmap: fs.existsSync(path.join(archiveDir, `${version}-ROADMAP.md`)),
+      requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+      audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+      phases: phasesArchived,
+    },
+    milestones_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+function cmdPhasesClear(cwd, raw, args) {
+  const phasesDir = planningPaths(cwd).phases;
+  const confirm = Array.isArray(args) && args.includes('--confirm');
+  let cleared = 0;
+
+  if (fs.existsSync(phasesDir)) {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory() && !/^999(?:\.|$)/.test(e.name));
+
+    if (dirs.length > 0 && !confirm) {
+      error(
+        `phases clear would delete ${dirs.length} phase director${dirs.length === 1 ? 'y' : 'ies'}. ` +
+        `Pass --confirm to proceed.`
+      );
+    }
+
+    try {
+      for (const entry of dirs) {
+        fs.rmSync(path.join(phasesDir, entry.name), { recursive: true, force: true });
+        cleared++;
+      }
+    } catch (e) {
+      error('Failed to clear phases directory: ' + e.message);
+    }
+  }
+
+  output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+  cmdPhasesClear,
+};