@sienklogic/plan-build-run 2.19.0 → 2.19.2

package/plugins/pbr/scripts/lib/migrate.js

@@ -0,0 +1,298 @@
+/**
+ * lib/migrate.cjs -- Schema migration for Plan-Build-Run config.json.
+ *
+ * Tracks config.json schema version and applies sequential migrations
+ * to bring outdated configs up to the current version.
+ *
+ * Usage:
+ *   const { applyMigrations, CURRENT_SCHEMA_VERSION } = require('./migrate');
+ *   const result = await applyMigrations(planningDir, { dryRun: false });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWrite } = require('./core');
+
+/** The current schema version supported by this version of PBR. */
+const CURRENT_SCHEMA_VERSION = 3;
+
+/**
+ * Migration registry. Each entry describes one schema version step.
+ * Migrations MUST be listed in ascending `from` order.
+ *
+ * @type {Array<{ from: number, to: number, description: string, migrate: function }>}
+ */
+const MIGRATIONS = [
+  {
+    from: 0,
+    to: 1,
+    description: 'Add schema_version field',
+    migrate(config) {
+      config.schema_version = 1;
+    }
+  },
+  {
+    from: 1,
+    to: 2,
+    description: 'Normalize GSD config format to PBR structure',
+    migrate(config) {
+      // mode: "yolo" -> "autonomous"
+      if (config.mode === 'yolo') config.mode = 'autonomous';
+
+      // depth: old names -> new names
+      const depthMap = { lean: 'quick', balanced: 'standard', thorough: 'comprehensive' };
+      if (config.depth && depthMap[config.depth]) {
+        config.depth = depthMap[config.depth];
+      }
+
+      // parallelization: boolean -> object
+      if (typeof config.parallelization === 'boolean') {
+        config.parallelization = { enabled: config.parallelization };
+      }
+
+      // branching_strategy (flat) -> git.branching (nested)
+      if (config.branching_strategy !== undefined) {
+        if (!config.git) config.git = {};
+        config.git.branching = config.branching_strategy;
+        delete config.branching_strategy;
+      }
+
+      // Top-level feature booleans -> features object
+      const featureMap = {
+        research: 'research_phase',
+        plan_checker: 'plan_checking',
+        verifier: 'goal_verification',
+      };
+      if (!config.features) config.features = {};
+      for (const [oldKey, newKey] of Object.entries(featureMap)) {
+        if (config[oldKey] !== undefined) {
+          config.features[newKey] = config[oldKey];
+          delete config[oldKey];
+        }
+      }
+
+      // Top-level commit_docs -> planning.commit_docs
+      if (config.commit_docs !== undefined) {
+        if (!config.planning) config.planning = {};
+        config.planning.commit_docs = config.commit_docs;
+        delete config.commit_docs;
+      }
+
+      // Top-level search_gitignored -> planning.search_gitignored
+      if (config.search_gitignored !== undefined) {
+        if (!config.planning) config.planning = {};
+        config.planning.search_gitignored = config.search_gitignored;
+        delete config.search_gitignored;
+      }
+
+      // Top-level model_profile (string) -> delete (not a PBR field, depth replaces it)
+      if (config.model_profile !== undefined) {
+        // Map old model_profile to depth if depth not set
+        if (!config.depth) {
+          const profileToDepth = { quality: 'comprehensive', balanced: 'standard', budget: 'quick' };
+          config.depth = profileToDepth[config.model_profile] || 'standard';
+        }
+        delete config.model_profile;
+      }
+
+      // Clean up GSD-only fields
+      const gsdOnlyFields = ['brave_search', 'phase_branch_template', 'milestone_branch_template'];
+      for (const f of gsdOnlyFields) {
+        if (config[f] !== undefined) delete config[f];
+      }
+
+      // workflow object: keep if present, it maps well to PBR
+      // (workflow.research, workflow.plan_check, etc. are valid in both)
+
+      // Ensure version is set
+      if (!config.version) config.version = 2;
+
+      config.schema_version = 2;
+    }
+  },
+  {
+    from: 2,
+    to: 3,
+    description: 'Add 1M context adaptation config sections',
+    migrate(config) {
+      // Add new workflow properties with defaults (do NOT overwrite existing)
+      if (!config.workflow) config.workflow = {};
+      const wfDefaults = {
+        inline_execution: false,
+        inline_max_tasks: 2,
+        inline_context_cap_pct: 40,
+        phase_boundary_clear: 'off',
+        autonomous: false,
+        speculative_planning: false,
+        phase_replay: false
+      };
+      for (const [key, val] of Object.entries(wfDefaults)) {
+        if (config.workflow[key] === undefined) config.workflow[key] = val;
+      }
+
+      // Add planning.multi_phase
+      if (!config.planning) config.planning = {};
+      if (config.planning.multi_phase === undefined) config.planning.multi_phase = false;
+
+      // Add gates.checkpoint_auto_resolve
+      if (!config.gates) config.gates = {};
+      if (config.gates.checkpoint_auto_resolve === undefined) {
+        config.gates.checkpoint_auto_resolve = 'none';
+      }
+
+      // Add new top-level sections with defaults
+      if (!config.intel) {
+        config.intel = { enabled: false, auto_update: false, inject_on_start: false };
+      }
+      if (!config.context_ledger) {
+        config.context_ledger = { enabled: false, stale_after_minutes: 60 };
+      }
+      if (!config.learnings) {
+        config.learnings = { enabled: false, read_depth: 3 };
+      }
+      if (!config.verification) {
+        config.verification = { confidence_gate: false, confidence_threshold: 1.0 };
+      }
+      if (!config.context_budget) {
+        config.context_budget = { threshold_curve: 'linear' };
+      }
+
+      config.schema_version = 3;
+    }
+  }
+];
+
+/**
+ * Detect the current schema version from a config object.
+ * Returns 0 if schema_version is absent or non-numeric.
+ *
+ * @param {object} config - Parsed config.json object
+ * @returns {number} Detected schema version
+ */
+function detectSchemaVersion(config) {
+  const v = config && config.schema_version;
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  return 0;
+}
+
+/**
+ * Return the ordered list of migrations needed to go from `fromVersion` to `toVersion`.
+ * Returns an empty array if versions are equal.
+ * Throws if fromVersion > toVersion (downgrade not supported).
+ *
+ * @param {number} fromVersion - Current schema version
+ * @param {number} toVersion - Target schema version
+ * @returns {Array} Ordered migrations to apply
+ */
+function getMigrationPath(fromVersion, toVersion) {
+  if (fromVersion > toVersion) {
+    throw new Error(`Cannot downgrade schema from version ${fromVersion} to ${toVersion}`);
+  }
+  if (fromVersion === toVersion) return [];
+  return MIGRATIONS.filter(m => m.from >= fromVersion && m.to <= toVersion);
+}
+
+/**
+ * Apply pending migrations to config.json in planningDir.
+ *
+ * Options:
+ *   dryRun {boolean} -- If true, simulate migration without writing files (default: false)
+ *   force  {boolean} -- Reserved for future use (default: false)
+ *
+ * Returns:
+ *   { migrated: false, version: N }                          -- already current
+ *   { migrated: false, message: string }                     -- future version, no-op
+ *   { migrated: true, fromVersion, toVersion, applied, backupPath } -- success
+ *   { error: string }                                        -- failure
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} [options] - Options { dryRun, force }
+ * @returns {Promise<object>} Result object
+ */
+async function applyMigrations(planningDir, options) {
+  const opts = options || {};
+  const dryRun = opts.dryRun === true;
+
+  const configPath = path.join(planningDir, 'config.json');
+
+  // Load config.json
+  if (!fs.existsSync(configPath)) {
+    return { error: 'config.json not found in ' + planningDir };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    return { error: 'config.json is not valid JSON: ' + e.message };
+  }
+
+  const currentVersion = detectSchemaVersion(config);
+
+  // Future version -- don't touch it
+  if (currentVersion > CURRENT_SCHEMA_VERSION) {
+    return {
+      migrated: false,
+      version: currentVersion,
+      message: `config.json schema_version (${currentVersion}) is newer than this PBR version supports (${CURRENT_SCHEMA_VERSION}). No migration applied.`
+    };
+  }
+
+  // Already current
+  if (currentVersion === CURRENT_SCHEMA_VERSION) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Determine migrations to apply
+  const migrations = getMigrationPath(currentVersion, CURRENT_SCHEMA_VERSION);
+  if (migrations.length === 0) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Clone config for mutation
+  const updatedConfig = JSON.parse(JSON.stringify(config));
+
+  // Apply each migration in sequence
+  const applied = [];
+  for (const m of migrations) {
+    m.migrate(updatedConfig);
+    applied.push(m.description);
+  }
+
+  if (dryRun) {
+    return {
+      migrated: true,
+      fromVersion: currentVersion,
+      toVersion: CURRENT_SCHEMA_VERSION,
+      applied,
+      dryRun: true
+    };
+  }
+
+  // Create backup
+  const backupDir = path.join(planningDir, '.migration-backup');
+  const backupPath = path.join(backupDir, 'config.json.bak');
+  if (!fs.existsSync(backupDir)) {
+    fs.mkdirSync(backupDir, { recursive: true });
+  }
+  fs.copyFileSync(configPath, backupPath);
+
+  // Write updated config atomically
+  atomicWrite(configPath, JSON.stringify(updatedConfig, null, 2));
+
+  return {
+    migrated: true,
+    fromVersion: currentVersion,
+    toVersion: CURRENT_SCHEMA_VERSION,
+    applied,
+    backupPath
+  };
+}
+
+module.exports = {
+  CURRENT_SCHEMA_VERSION,
+  MIGRATIONS,
+  detectSchemaVersion,
+  getMigrationPath,
+  applyMigrations
+};

package/plugins/pbr/scripts/lib/milestone.js

@@ -0,0 +1,306 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core');
+const { extractFrontmatter } = require('./frontmatter');
+
+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 = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+  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 notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    if (checkboxPattern.test(reqContent)) {
+      reqContent = reqContent.replace(checkboxPattern, '$1x$2');
+      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');
+    if (tablePattern.test(reqContent)) {
+      // Re-read since test() advances lastIndex for global regex
+      reqContent = reqContent.replace(
+        new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+        '$1 Complete $2'
+      );
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      notFound.push(reqId);
+    }
+  }
+
+  if (updated.length > 0) {
+    fs.writeFileSync(reqPath, reqContent, 'utf-8');
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    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 = path.join(cwd, '.planning', 'ROADMAP.md');
+  const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+  const statePath = path.join(cwd, '.planning', 'STATE.md');
+  const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md');
+  const archiveDir = path.join(cwd, '.planning', 'milestones');
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  // 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);
+
+  // 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);
+          if (fm['one-liner']) {
+            accomplishments.push(fm['one-liner']);
+          }
+          // Count tasks
+          const taskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+          totalTasks += taskMatches.length;
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    fs.writeFileSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent, 'utf-8');
+  }
+
+  // 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`;
+    fs.writeFileSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent, 'utf-8');
+  }
+
+  // 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
+      fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+    } 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);
+        fs.writeFileSync(milestonesPath, header + milestoneEntry + rest, 'utf-8');
+      } else {
+        // No recognizable header — prepend the entry
+        fs.writeFileSync(milestonesPath, milestoneEntry + existing, 'utf-8');
+      }
+    }
+  } else {
+    fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+  }
+
+  // Create/append RETROSPECTIVE.md
+  const retroPath = path.join(cwd, '.planning', 'RETROSPECTIVE.md');
+  const retroEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n### What Was Built\n${accomplishmentsList || '(see MILESTONES.md)'}\n\n### What Worked\n- (to be filled by user)\n\n### What Was Inefficient\n- (to be filled by user)\n\n### Patterns Established\n- (to be filled by user)\n\n### Key Lessons\n- (to be filled by user)\n\n---\n\n`;
+
+  if (fs.existsSync(retroPath)) {
+    const existingRetro = fs.readFileSync(retroPath, 'utf-8');
+    // Insert after the header for reverse chronological order
+    const retroHeaderMatch = existingRetro.match(/^(#[^\n]*\n(?:>[^\n]*\n)*\n?)/);
+    if (retroHeaderMatch) {
+      const retroHeader = retroHeaderMatch[1];
+      const retroRest = existingRetro.slice(retroHeader.length);
+      fs.writeFileSync(retroPath, retroHeader + retroEntry + retroRest, 'utf-8');
+    } else {
+      fs.writeFileSync(retroPath, retroEntry + existingRetro, 'utf-8');
+    }
+  } else {
+    fs.writeFileSync(retroPath, `# Retrospective\n\n> Living document updated after each milestone.\n> Cross-milestone trends help improve the development process.\n\n${retroEntry}`, 'utf-8');
+  }
+
+  // Collapse completed milestone section in ROADMAP.md with <details> tags
+  if (fs.existsSync(roadmapPath)) {
+    let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+
+    // Find the milestone section by name and wrap it
+    const milestoneHeadingPattern = new RegExp(
+      `(## Milestone:\\s*${escapeRegex(milestoneName)}[^\\n]*\\n)([\\s\\S]*?)(?=\\n## |$)`
+    );
+    const milestoneMatch = roadmapContent.match(milestoneHeadingPattern);
+    if (milestoneMatch) {
+      const fullMatch = milestoneMatch[0];
+      const collapsed = `<details>\n<summary>## Milestone: ${milestoneName} (${version}) — SHIPPED ${today}</summary>\n\n${fullMatch}\n</details>\n`;
+      roadmapContent = roadmapContent.replace(fullMatch, collapsed);
+    }
+
+    // Update or create milestone index section at top of ROADMAP.md
+    const indexRow = `| ${version} | ${milestoneName} | SHIPPED | ${today} |`;
+    const indexTableHeader = '| Version | Name | Status | Date |\n|---------|------|--------|------|\n';
+    const indexPattern = /## Milestones\n\n\| Version \| Name \| Status \| Date \|\n\|[-|]+\|\n((?:\|[^\n]*\n)*)/;
+    const indexMatch = roadmapContent.match(indexPattern);
+
+    if (indexMatch) {
+      // Append row to existing index table
+      const existingRows = indexMatch[1];
+      roadmapContent = roadmapContent.replace(
+        indexMatch[0],
+        `## Milestones\n\n${indexTableHeader}${indexRow}\n${existingRows}`
+      );
+    } else {
+      // Create index section after the title line
+      const titleMatch = roadmapContent.match(/^(#[^\n]*\n\n?)/);
+      if (titleMatch) {
+        const titleEnd = titleMatch[0].length;
+        roadmapContent = roadmapContent.slice(0, titleEnd) +
+          `## Milestones\n\n${indexTableHeader}${indexRow}\n\n` +
+          roadmapContent.slice(titleEnd);
+      }
+    }
+
+    fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+  }
+
+  // Update STATE.md
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+    stateContent = stateContent.replace(
+      /(\*\*Status:\*\*\s*).*/,
+      `$1${version} milestone complete`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity:\*\*\s*).*/,
+      `$1${today}`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity Description:\*\*\s*).*/,
+      `$1${version} milestone completed and archived`
+    );
+    fs.writeFileSync(statePath, stateContent, 'utf-8');
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      fs.mkdirSync(phaseArchiveDir, { recursive: true });
+
+      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 {}
+  }
+
+  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,
+    retrospective_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+// Delegate milestoneStats to phase.cjs where it was consolidated
+const milestoneStats = (...args) => require('./phase').milestoneStats(...args);
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+  milestoneStats,
+};