@sienklogic/plan-build-run 2.0.2 → 2.1.1

package/plan-build-run/bin/lib/local-llm/index.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * local-llm/index.cjs — Local LLM subsystem stub for PBR v2.0.
+ *
+ * Full implementation deferred to v3 (ADV-01: Local LLM shadow mode).
+ * See REQUIREMENTS.md ADV-01 for v3 plans.
+ *
+ * This stub ensures the dispatcher does not crash when LLM commands are
+ * invoked. All functions return graceful "not available" responses instead
+ * of throwing errors.
+ */
+
+const STUB_MESSAGE = 'Local LLM subsystem not available in v2.0. See ADV-01 for v3 plans.';
+
+/**
+ * Check LLM availability and health.
+ * @returns {{ available: boolean, message: string }}
+ */
+function llmHealth() {
+  return { available: false, message: STUB_MESSAGE };
+}
+
+/**
+ * Get LLM subsystem status.
+ * @returns {{ status: string, message: string }}
+ */
+function llmStatus() {
+  return { status: 'disabled', message: STUB_MESSAGE };
+}
+
+/**
+ * Classify input using local LLM.
+ * @returns {{ error: string }}
+ */
+function llmClassify() {
+  return { error: STUB_MESSAGE };
+}
+
+/**
+ * Score a source file using local LLM.
+ * @returns {{ error: string }}
+ */
+function llmScoreSource() {
+  return { error: STUB_MESSAGE };
+}
+
+/**
+ * Classify an error using local LLM.
+ * @returns {{ error: string }}
+ */
+function llmClassifyError() {
+  return { error: STUB_MESSAGE };
+}
+
+/**
+ * Summarize content using local LLM.
+ * @returns {{ error: string }}
+ */
+function llmSummarize() {
+  return { error: STUB_MESSAGE };
+}
+
+/**
+ * Get LLM usage metrics.
+ * @returns {{ metrics: Array, message: string }}
+ */
+function llmMetrics() {
+  return { metrics: [], message: STUB_MESSAGE };
+}
+
+/**
+ * Adjust classification thresholds using local LLM.
+ * @returns {{ error: string }}
+ */
+function llmAdjustThresholds() {
+  return { error: STUB_MESSAGE };
+}
+
+module.exports = {
+  llmHealth,
+  llmStatus,
+  llmClassify,
+  llmScoreSource,
+  llmClassifyError,
+  llmSummarize,
+  llmMetrics,
+  llmAdjustThresholds
+};

package/plan-build-run/bin/lib/local-llm/metrics.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * local-llm/metrics.cjs — Stub for LLM metrics subsystem.
+ * Full implementation deferred to v3 (ADV-01).
+ */
+
+function computeLifetimeMetrics(_planningDir) {
+  return { total_calls: 0, tokens_saved: 0 };
+}
+
+function readSessionMetrics(_planningDir, _since) {
+  return [];
+}
+
+function summarizeMetrics(_entries) {
+  return { total_calls: 0, tokens_saved: 0 };
+}
+
+module.exports = { computeLifetimeMetrics, readSessionMetrics, summarizeMetrics };

package/plan-build-run/bin/lib/local-llm/operations/classify-artifact.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Stub: local-llm classify-artifact (deferred to v3 ADV-01)
+async function classifyArtifact() { return { classification: 'unknown', confidence: 0 }; }
+module.exports = { classifyArtifact };

package/plan-build-run/bin/lib/local-llm/operations/classify-commit.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Stub: local-llm classify-commit (deferred to v3 ADV-01)
+async function classifyCommit() { return { type: 'unknown', confidence: 0 }; }
+module.exports = { classifyCommit };

package/plan-build-run/bin/lib/local-llm/operations/classify-error.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Stub: local-llm classify-error (deferred to v3 ADV-01)
+async function classifyError() { return { category: 'unknown', confidence: 0 }; }
+module.exports = { classifyError };

package/plan-build-run/bin/lib/local-llm/operations/classify-file-intent.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Stub: local-llm classify-file-intent (deferred to v3 ADV-01)
+async function classifyFileIntent() { return { intent: 'unknown', confidence: 0 }; }
+module.exports = { classifyFileIntent };

package/plan-build-run/bin/lib/local-llm/operations/triage-test-output.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+/**
+ * local-llm/operations/triage-test-output.cjs — Stub for test output triage.
+ * Full implementation deferred to v3 (ADV-01).
+ */
+
+async function triageTestOutput(_config, _planningDir, _output, _runner, _sessionId) {
+  return { category: 'unknown', confidence: 0, file_hint: null };
+}
+
+module.exports = { triageTestOutput };

package/plan-build-run/bin/lib/local-llm/operations/validate-task.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Stub: local-llm validate-task (deferred to v3 ADV-01)
+async function validateTask() { return { valid: true, confidence: 0 }; }
+module.exports = { validateTask };

package/plan-build-run/bin/lib/migrate.cjs

@@ -0,0 +1,248 @@
+/**
+ * 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.cjs');
+ *   const result = await applyMigrations(planningDir, { dryRun: false });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWrite } = require('./core.cjs');
+
+/** The current schema version supported by this version of PBR. */
+const CURRENT_SCHEMA_VERSION = 2;
+
+/**
+ * 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;
+    }
+  }
+];
+
+/**
+ * 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/plan-build-run/bin/lib/milestone.cjs

@@ -0,0 +1,245 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { writeStateMd } = require('./state.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 = 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');
+  }
+
+  // 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`
+    );
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // 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,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+// Delegate milestoneStats to phase.cjs where it was consolidated
+const milestoneStats = (...args) => require('./phase.cjs').milestoneStats(...args);
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+  milestoneStats,
+};