mindforge-cc 1.0.0

package/bin/migrations/migrate.js

@@ -0,0 +1,151 @@
+/**
+ * MindForge — Migration Runner
+ * Safely upgrades .planning/ file schemas between MindForge versions.
+ * Philosophy: never lose data, always back up, always verify after.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// Re-export for use by self-update.js
+const { compareSemver } = require('../updater/version-comparator');
+module.exports.compareSemver = compareSemver;
+
+const PLANNING_DIR = path.join(process.cwd(), '.planning');
+
+const PATHS = {
+  handoff:    path.join(PLANNING_DIR, 'HANDOFF.json'),
+  state:      path.join(PLANNING_DIR, 'STATE.md'),
+  audit:      path.join(PLANNING_DIR, 'AUDIT.jsonl'),
+  mindforgemd: path.join(process.cwd(), 'MINDFORGE.md'),
+};
+
+/**
+ * Run all needed migrations from fromVersion to toVersion.
+ * Creates a backup first. Restores on failure.
+ * Returns { status, from, to, backupDir }
+ */
+async function runMigrations(fromVersion, toVersion) {
+  console.log(`\n  Migration: v${fromVersion} → v${toVersion}`);
+
+  if (!fs.existsSync(PLANNING_DIR)) {
+    console.log(`  ℹ️  No .planning/ directory found — skipping migration`);
+    return { status: 'no-planning-dir' };
+  }
+
+  if (compareSemver(fromVersion, toVersion) >= 0) {
+    console.log(`  ✅  No migration needed`);
+    return { status: 'no-migration-needed' };
+  }
+
+  // Determine which migrations to run
+  const allMigrations = [
+    require('./0.1.0-to-0.5.0'),
+    require('./0.5.0-to-0.6.0'),
+    require('./0.6.0-to-1.0.0'),
+  ];
+
+  // A migration should run if its DESTINATION VERSION falls within the range:
+  // (fromVersion, toVersion] — i.e., greater than fromVersion AND at most toVersion
+  const migrationsToRun = allMigrations.filter(m =>
+    compareSemver(m.toVersion, fromVersion) > 0 &&
+    compareSemver(m.toVersion, toVersion)   <= 0
+  );
+
+  if (migrationsToRun.length === 0) {
+    console.log(`  ✅  No applicable migrations`);
+    return { status: 'no-migrations' };
+  }
+
+  console.log(`  Migrations to run (${migrationsToRun.length}):`);
+  migrationsToRun.forEach(m => console.log(`    • v${m.fromVersion} → v${m.toVersion}: ${m.description}`));
+
+  // ── Create backup (abort if backup fails — never migrate without a backup) ──
+  const backupDir = path.join(PLANNING_DIR, `migration-backup-${Date.now()}`);
+  let backupCreated = false;
+  try {
+    fs.mkdirSync(backupDir, { recursive: true });
+    const filesToBackup = Object.values(PATHS).filter(p => fs.existsSync(p));
+
+    if (filesToBackup.length === 0) {
+      console.log(`  ℹ️  No files to migrate`);
+      fs.rmdirSync(backupDir);
+      return { status: 'no-files' };
+    }
+
+    for (const f of filesToBackup) {
+      fs.copyFileSync(f, path.join(backupDir, path.basename(f)));
+    }
+
+    // Verify backup: check every backed-up file exists and has content
+    const backed = fs.readdirSync(backupDir);
+    const allBacked = filesToBackup.every(f =>
+      backed.includes(path.basename(f)) &&
+      fs.statSync(path.join(backupDir, path.basename(f))).size > 0
+    );
+
+    if (!allBacked) throw new Error('Backup verification failed — some files missing or empty');
+
+    backupCreated = true;
+    console.log(`  📦 Backup: .planning/${path.basename(backupDir)} (${filesToBackup.length} files)`);
+
+  } catch (backupErr) {
+    // Abort cleanly — no migration is safer than a migration without backup
+    if (fs.existsSync(backupDir)) {
+      try { fs.rmSync(backupDir, { recursive: true, force: true }); } catch {}
+    }
+    throw new Error(
+      `Migration aborted: cannot create backup (${backupErr.message}). ` +
+      `Free disk space and retry.`
+    );
+  }
+
+  // ── Execute migrations in order ───────────────────────────────────────────
+  for (const migration of migrationsToRun) {
+    console.log(`\n  Running: v${migration.fromVersion} → v${migration.toVersion}...`);
+    try {
+      await migration.run(PATHS);
+      console.log(`  ✅  Complete`);
+    } catch (migErr) {
+      console.error(`  ❌  Failed: ${migErr.message}`);
+      console.log(`  Restoring from backup...`);
+
+      // Restore all files from backup
+      for (const f of fs.readdirSync(backupDir)) {
+        const dst = Object.values(PATHS).find(p => path.basename(p) === f) ||
+                    path.join(PLANNING_DIR, f);
+        fs.copyFileSync(path.join(backupDir, f), dst);
+      }
+      console.log(`  ✅  Restored from backup. No changes applied.`);
+      throw new Error(`Migration failed at v${migration.toVersion}: ${migErr.message}`);
+    }
+  }
+
+  // ── Update schema_version in HANDOFF.json ────────────────────────────────
+  if (fs.existsSync(PATHS.handoff)) {
+    const handoff = JSON.parse(fs.readFileSync(PATHS.handoff, 'utf8'));
+    handoff.schema_version = toVersion;
+    handoff._migration_completed = new Date().toISOString();
+    fs.writeFileSync(PATHS.handoff, JSON.stringify(handoff, null, 2) + '\n');
+  }
+
+  console.log(`\n  ✅  All migrations complete: v${fromVersion} → v${toVersion}`);
+
+  // ── Post-migration: clean up in CI, retain in interactive ─────────────────
+  if (process.env.CI === 'true') {
+    try {
+      fs.rmSync(backupDir, { recursive: true, force: true });
+      console.log(`  🗑️  CI mode: backup auto-deleted (disk space)`);
+    } catch {
+      // Silent failure on cleanup — migration succeeded, cleanup is optional
+    }
+  } else {
+    console.log(`  Backup retained: .planning/${path.basename(backupDir)}`);
+    console.log(`  Remove when satisfied: rm -rf .planning/${path.basename(backupDir)}\n`);
+  }
+
+  return { status: 'migrated', from: fromVersion, to: toVersion, backupDir };
+}
+
+module.exports.runMigrations = runMigrations;

package/bin/migrations/schema-versions.js

@@ -0,0 +1,64 @@
+/**
+ * MindForge — Schema Version Registry
+ * Documents every breaking schema change across all released versions.
+ * Used by the migration engine to determine what migrations are needed.
+ */
+'use strict';
+
+const SCHEMA_HISTORY = [
+  {
+    version: '0.1.0',
+    date: '2026-01-01',
+    description: 'Initial release',
+    handoff_fields_added: [
+      'schema_version', 'project', 'phase', 'plan', 'next_task',
+      'blockers', 'decisions_needed', 'context_refs', '_warning', 'updated_at',
+    ],
+    handoff_fields_removed: [],
+    audit_fields_added: ['id', 'timestamp', 'event', 'agent', 'phase'],
+    breaking: [],
+  },
+  {
+    version: '0.5.0',
+    date: '2026-01-15',
+    description: 'Intelligence layer — smart compaction adds structured fields',
+    handoff_fields_added: [
+      'decisions_made', 'discoveries', 'implicit_knowledge',
+      'quality_signals', 'compaction_level', 'compaction_timestamp',
+    ],
+    handoff_fields_removed: [],
+    audit_fields_added: [],
+    breaking: [
+      'compaction_protocol.md now requires Level 1/2/3 classification',
+    ],
+  },
+  {
+    version: '0.6.0',
+    date: '2026-02-01',
+    description: 'Distribution platform — adds per-developer and CI fields',
+    handoff_fields_added: [
+      'developer_id', 'session_id', 'recent_commits', 'recent_files',
+    ],
+    handoff_fields_removed: [],
+    audit_fields_added: ['session_id'],
+    breaking: [
+      'AUDIT.jsonl entries should now include session_id',
+      'INTEGRATIONS-CONFIG.md gains EMERGENCY_APPROVERS field',
+    ],
+  },
+  {
+    version: '1.0.0',
+    date: '2026-03-22',
+    description: 'First stable release — plugin system and stable interface contract',
+    handoff_fields_added: ['plugin_api_version'],
+    handoff_fields_removed: [],
+    audit_fields_added: [],
+    breaking: [
+      'VERIFY_PASS_RATE_WARNING_THRESHOLD in MINDFORGE.md is now 0.0-1.0 (was 0-100)',
+      'AUDIT.jsonl session_id is now required (was optional)',
+      'HANDOFF.json plugin_api_version field is now required for plugin compatibility',
+    ],
+  },
+];
+
+module.exports = { SCHEMA_HISTORY };

package/bin/updater/changelog-fetcher.js

@@ -0,0 +1,62 @@
+/**
+ * MindForge — Changelog Fetcher
+ * Downloads and parses CHANGELOG.md entries between two versions.
+ * Used by /mindforge:update to show what changed.
+ */
+'use strict';
+
+const { compareSemver } = require('./version-comparator');
+
+const CHANGELOG_URL = 'https://raw.githubusercontent.com/mindforge-dev/mindforge/main/CHANGELOG.md';
+
+/**
+ * Fetch CHANGELOG.md and extract entries between fromVersion and toVersion.
+ * Returns formatted markdown string, or null if unavailable.
+ */
+async function fetchChangelog(fromVersion, toVersion) {
+  const raw = await fetchRaw();
+  if (!raw) return null;
+  return extractEntries(raw, fromVersion, toVersion);
+}
+
+async function fetchRaw() {
+  const https = require('https');
+  return new Promise(resolve => {
+    const req = https.get(CHANGELOG_URL, { timeout: 8000 }, res => {
+      if (res.statusCode !== 200) { resolve(null); return; }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => resolve(body));
+    });
+    req.on('error',   () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * Parse CHANGELOG.md and extract version sections in range (from, to].
+ */
+function extractEntries(changelog, fromVersion, toVersion) {
+  const sections = [];
+  let current = null;
+
+  for (const line of changelog.split('\n')) {
+    const vMatch = line.match(/^## \[?v?(\d+\.\d+\.\d+)/);
+    if (vMatch) {
+      if (current) sections.push(current);
+      const v = vMatch[1];
+      const inRange = compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0;
+      current = inRange ? { version: v, lines: [line] } : null;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) sections.push(current);
+
+  return sections.length
+    ? sections.map(s => s.lines.join('\n').trimEnd()).join('\n\n')
+    : null;
+}
+
+module.exports = { fetchChangelog };

package/bin/updater/self-update.js

@@ -0,0 +1,169 @@
+/**
+ * MindForge — Self-Update Engine
+ * Full update workflow: check → changelog → scope detection → apply → migrate → verify.
+ */
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const { execSync }         = require('child_process');
+const { compareSemver, upgradeType, fetchLatestVersion } = require('./version-comparator');
+const { fetchChangelog }   = require('./changelog-fetcher');
+
+const CURRENT_VERSION = require('../../package.json').version;
+
+/**
+ * Detect where MindForge was originally installed.
+ * Checks local before global (local installs take precedence).
+ * Returns { scope: 'local'|'global', runtime: 'claude'|'antigravity' }
+ */
+function detectInstallScope() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const cwd  = process.cwd();
+
+  // Per ADR-019: local installs take precedence over global
+  const locations = [
+    { scope: 'local',  runtime: 'claude',      file: path.join(cwd,  '.claude', 'CLAUDE.md') },
+    { scope: 'local',  runtime: 'antigravity', file: path.join(cwd,  '.agent',  'CLAUDE.md') },
+    { scope: 'global', runtime: 'claude',      file: path.join(home, '.claude', 'CLAUDE.md') },
+    { scope: 'global', runtime: 'antigravity', file: path.join(home, '.gemini', 'antigravity', 'CLAUDE.md') },
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc.file) && fs.readFileSync(loc.file, 'utf8').includes('MindForge')) {
+      return { scope: loc.scope, runtime: loc.runtime };
+    }
+  }
+
+  // Default: global claude (most common installation)
+  return { scope: 'global', runtime: 'claude' };
+}
+
+/**
+ * Read the schema_version from HANDOFF.json.
+ * This is the authoritative "what version are the .planning files" source.
+ * Must be read BEFORE the update runs (after update, installer version = new).
+ */
+function readHandoffSchemaVersion() {
+  const handoffPath = path.join(process.cwd(), '.planning', 'HANDOFF.json');
+  if (!fs.existsSync(handoffPath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+    return data.schema_version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Main update entry point.
+ * Called by /mindforge:update command.
+ *
+ * options:
+ *   apply          {boolean}  — actually apply the update (default: false = check only)
+ *   force          {boolean}  — skip major-version safety warning
+ *   skipChangelog  {boolean}  — skip changelog fetch
+ */
+async function checkAndUpdate(options = {}) {
+  const { apply = false, force = false, skipChangelog = false } = options;
+  const isCI = process.env.CI === 'true' || process.env.MINDFORGE_CI === 'true';
+
+  const TTY = process.stdout.isTTY;
+  const bold = s => TTY ? `\x1b[1m${s}\x1b[0m` : s;
+  const warn = s => TTY ? `\x1b[33m${s}\x1b[0m` : s;
+  const ok   = s => TTY ? `\x1b[32m${s}\x1b[0m` : s;
+  const err  = s => TTY ? `\x1b[31m${s}\x1b[0m` : s;
+
+  console.log(`\n${bold('⚡  MindForge Update Check')}\n`);
+  console.log(`  Current : v${CURRENT_VERSION}`);
+  process.stdout.write(`  Latest  : checking npm registry... `);
+
+  const latestVersion = await fetchLatestVersion();
+  if (!latestVersion) {
+    console.log(`${warn('unavailable')}`);
+    console.log(`\n  ${warn('⚠️')}  Cannot reach npm registry. Check your internet connection.`);
+    console.log(`  Manual check: npm info mindforge-cc version\n`);
+    return { status: 'check-failed' };
+  }
+
+  const type = upgradeType(CURRENT_VERSION, latestVersion);
+  if (type === 'none') {
+    console.log(`${ok('up to date')}`);
+    console.log(`\n  ${ok('✅')}  v${CURRENT_VERSION} is the latest version.\n`);
+    return { status: 'up-to-date', current: CURRENT_VERSION };
+  }
+
+  console.log(`${ok(`v${latestVersion} available`)}`);
+  console.log(`  Update  : ${CURRENT_VERSION} → ${latestVersion} ${warn(`(${type})`)}`);
+
+  // Major version safety gate
+  if (type === 'major' && !force) {
+    console.log(`\n  ${warn('⚠️  MAJOR UPDATE')} — may contain breaking changes.`);
+    console.log(`  Review the changelog before applying.`);
+    console.log(`  To apply anyway: /mindforge:update --apply --force\n`);
+  }
+
+  // Fetch and display changelog
+  if (!skipChangelog) {
+    process.stdout.write(`\n  Fetching changelog... `);
+    const changelog = await fetchChangelog(CURRENT_VERSION, latestVersion);
+    if (changelog) {
+      console.log(`done\n`);
+      console.log('─'.repeat(62));
+      console.log(changelog.slice(0, 3000));  // Max 3000 chars to avoid flooding terminal
+      if (changelog.length > 3000) console.log(`\n  [changelog truncated — see CHANGELOG.md for full details]`);
+      console.log('─'.repeat(62));
+    } else {
+      console.log(`unavailable\n`);
+    }
+  }
+
+  if (!apply) {
+    if (isCI) {
+      console.log(`\n  CI mode: check-only (no apply without --apply)`);
+    }
+    console.log(`\n  To apply: /mindforge:update --apply`);
+    console.log(`  Or directly: npx mindforge-cc@${latestVersion} --update\n`);
+    return { status: 'update-available', current: CURRENT_VERSION, latest: latestVersion, type };
+  }
+
+  // ── Apply the update ────────────────────────────────────────────────────────
+
+  // Capture schema version BEFORE updating (critical for correct migration path)
+  const fromSchemaVersion = readHandoffSchemaVersion() || CURRENT_VERSION;
+  console.log(`\n  Schema version: v${fromSchemaVersion}`);
+
+  // Detect original install scope to preserve it
+  const { scope, runtime } = detectInstallScope();
+  console.log(`  Install scope : ${runtime} / ${scope}`);
+  console.log(`\n  Applying update...`);
+
+  try {
+    execSync(
+      `npx mindforge-cc@${latestVersion} --${runtime} --${scope}`,
+      { stdio: 'inherit', timeout: 120_000 }
+    );
+  } catch (updateErr) {
+    console.error(`\n  ${err('❌')}  Update failed: ${updateErr.message}`);
+    console.error(`  Fallback: npx mindforge-cc@${latestVersion} --${runtime} --${scope}`);
+    return { status: 'update-failed', error: updateErr.message };
+  }
+
+  // Run schema migration with the pre-update schema version
+  try {
+    const { runMigrations } = require('../migrations/migrate');
+    const migResult = await runMigrations(fromSchemaVersion, latestVersion);
+    if (migResult.status === 'migrated') {
+      console.log(`  ✅  Schema migrated: v${fromSchemaVersion} → v${latestVersion}`);
+    }
+  } catch (migErr) {
+    console.warn(`  ${warn('⚠️')}  Schema migration had an issue: ${migErr.message}`);
+    console.warn(`      Run /mindforge:migrate manually if state files look wrong.`);
+  }
+
+  console.log(`\n  ${ok('✅')}  MindForge updated to v${latestVersion}\n`);
+  console.log(`  Run /mindforge:health to verify the update.\n`);
+  return { status: 'updated', from: CURRENT_VERSION, to: latestVersion };
+}
+
+module.exports = { checkAndUpdate, detectInstallScope, readHandoffSchemaVersion };

package/bin/updater/version-comparator.js

@@ -0,0 +1,68 @@
+/**
+ * MindForge — Version Comparator
+ * Pure functions for semver comparison.
+ * No external dependencies — must work offline.
+ */
+'use strict';
+
+/**
+ * Compare two semver strings (strips leading 'v').
+ * Returns: negative if a < b, 0 if a == b, positive if a > b
+ */
+function compareSemver(a, b) {
+  const pa = a.replace(/^v/, '').split('.').map(Number);
+  const pb = b.replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Determine the upgrade type between two versions.
+ * Returns 'major' | 'minor' | 'patch' | 'none'
+ */
+function upgradeType(current, latest) {
+  const c = current.replace(/^v/, '').split('.').map(Number);
+  const l = latest.replace(/^v/, '').split('.').map(Number);
+  if (l[0] > c[0]) return 'major';
+  if (l[1] > c[1]) return 'minor';
+  if (l[2] > c[2]) return 'patch';
+  return 'none';
+}
+
+/**
+ * Fetch the latest published version from the npm registry.
+ * Returns null on any error — callers must handle gracefully.
+ * Timeout: 5 seconds (respects enterprise proxies that may be slow).
+ */
+async function fetchLatestVersion(packageName = 'mindforge-cc') {
+  const https = require('https');
+  return new Promise(resolve => {
+    const options = {
+      hostname: 'registry.npmjs.org',
+      path:     `/${encodeURIComponent(packageName)}/latest`,
+      method:   'GET',
+      headers:  { 'Accept': 'application/json', 'User-Agent': `mindforge-cc/${require('../../package.json').version}` },
+      timeout:  5000,
+    };
+
+    const req = https.request(options, res => {
+      if (res.statusCode !== 200) { resolve(null); return; }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(body).version || null); }
+        catch { resolve(null); }
+      });
+    });
+
+    req.on('error',   () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+module.exports = { compareSemver, upgradeType, fetchLatestVersion };

package/bin/validate-config.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * MindForge configuration validator
+ * Validates MINDFORGE.md against the JSON schema
+ * Usage: node bin/validate-config.js [path-to-MINDFORGE.md]
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const CONFIG_PATH  = process.argv[2] || 'MINDFORGE.md';
+const SCHEMA_PATH  = '.mindforge/MINDFORGE-SCHEMA.json';
+
+if (!fs.existsSync(CONFIG_PATH)) {
+  console.log('ℹ️  MINDFORGE.md not found — using all defaults. Create one to customise.');
+  process.exit(0);
+}
+
+if (!fs.existsSync(SCHEMA_PATH)) {
+  console.log('ℹ️  MINDFORGE-SCHEMA.json not found — skipping schema validation.');
+  process.exit(0);
+}
+
+const content = fs.readFileSync(CONFIG_PATH, 'utf8');
+const schema  = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+
+const errors   = [];
+const warnings = [];
+
+// Parse key=value pairs from MINDFORGE.md
+const settings = {};
+const lines = content.split('\n');
+lines.forEach(line => {
+  const match = line.match(/^([A-Z_]+)=(.+)$/);
+  if (match) {
+    const [, key, value] = match;
+    settings[key] = value.trim();
+  }
+});
+
+// Validate against schema
+for (const [key, def] of Object.entries(schema.properties || {})) {
+  const value = settings[key];
+
+  if (def.required && !value) {
+    errors.push(`${key} is required but not set`);
+    continue;
+  }
+
+  if (!value) continue;
+
+  if (def.type === 'number') {
+    const num = parseFloat(value);
+    if (isNaN(num)) errors.push(`${key}: expected number, got "${value}"`);
+    if (def.minimum !== undefined && num < def.minimum)
+      errors.push(`${key}: ${num} is below minimum ${def.minimum}`);
+    if (def.maximum !== undefined && num > def.maximum)
+      errors.push(`${key}: ${num} exceeds maximum ${def.maximum}`);
+  }
+
+  if (def.type === 'enum' && !def.values.includes(value)) {
+    errors.push(`${key}: "${value}" is not valid. Options: ${def.values.join(', ')}`);
+  }
+
+  if (def.type === 'boolean' && !['true','false'].includes(value)) {
+    errors.push(`${key}: expected true or false, got "${value}"`);
+  }
+
+  if (def.nonOverridable) {
+    warnings.push(`${key}: this is a non-overridable governance primitive (value will be ignored)`);
+  }
+}
+
+// Report
+const total = errors.length + warnings.length;
+if (total === 0) {
+  console.log(`✅ MINDFORGE.md valid — ${Object.keys(settings).length} settings configured`);
+  process.exit(0);
+}
+
+if (errors.length) {
+  console.error(`❌ MINDFORGE.md has ${errors.length} error(s):`);
+  errors.forEach(e => console.error(`   • ${e}`));
+}
+if (warnings.length) {
+  console.warn(`⚠️  MINDFORGE.md has ${warnings.length} warning(s):`);
+  warnings.forEach(w => console.warn(`   • ${w}`));
+}
+
+process.exit(errors.length ? 1 : 0);