mindforge-cc 8.2.0 → 10.0.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.planning/archive/v8-cleanup/implementation-roadmap/v1.0.0/day-7-imp-prod/DAY7-PRODUCTION-FINAL.md

@@ -1,4513 +0,0 @@
-# MindForge — Day 7: Production Hardening, Polish & v1.0.0 Public Release
-# Branch: `feat/mindforge-production-release`
-# Prerequisite: `feat/mindforge-distribution-platform` merged to `main`
-# Version target: **v1.0.0 — First Stable Public Release**
-
----
-
-## BRANCH SETUP
-
-```bash
-git checkout main
-git pull origin main
-git checkout -b feat/mindforge-production-release
-```
-
-Verify all prior days are present and all 12 test suites pass with zero failures:
-
-```bash
-cat package.json | grep '"version"'   # Must be "0.6.0"
-
-SUITES=(install wave-engine audit compaction skills-platform
-        integrations governance intelligence metrics
-        distribution ci-mode sdk)
-
-for SUITE in "${SUITES[@]}"; do
-  printf "%-30s" "  ${SUITE}..."
-  node tests/${SUITE}.test.js 2>&1 | tail -1
-done
-
-# ALL 12 must show "All * tests passed" — zero failures before Day 7 begins
-```
-
----
-
-## DAY 7 SCOPE
-
-Day 7 is the **Production Hardening & v1.0.0 Public Release** sprint.
-
-Days 1–6 built MindForge. Day 7 makes it **shippable to the world**:
-end-to-end tested across all installation paths, fully documented, performance-
-profiled, self-maintaining, migration-safe, adversarially reviewed, and ready
-for the public npm registry at the v1.0.0 stable interface contract.
-
-| Component | Description |
-|---|---|
-| Complete `npx mindforge-cc` installer | Every code path covered: first-install, update, uninstall, self-install, CI, bad input |
-| Self-update mechanism | `/mindforge:update` — version check, changelog diff, scope-preserving apply |
-| Version migration engine | Schema migration for HANDOFF.json / STATE.md / AUDIT.jsonl across all prior versions |
-| Plugin system | First-class third-party extensions via `mindforge-plugin-` npm namespace |
-| Token usage optimiser | Measure, profile, and systematically reduce Claude API token consumption |
-| Cross-version compatibility layer | Graceful degradation when older schema files meet newer engine |
-| Complete reference documentation | Full `docs/` hierarchy ready for public release |
-| Threat model & security posture | Adversarial review of all seven attack surfaces |
-| 50-point production readiness checklist | Every item is blocking — all must pass before v1.0.0 tag |
-| v1.0.0 release pipeline | Complete tag, GitHub release, npm publish, announcement |
-| Day 7 test suites | `tests/production.test.js`, `tests/migration.test.js`, `tests/e2e.test.js` |
-
----
-
-# ═══════════════════════════════════════════════════════════════════
-# PART 1 — IMPLEMENTATION PROMPT
-# ═══════════════════════════════════════════════════════════════════
-
----
-
-## TASK 1 — Scaffold Day 7 directory additions
-
-```bash
-# Production hardening engine
-mkdir -p .mindforge/production
-touch .mindforge/production/token-optimiser.md
-touch .mindforge/production/migration-engine.md
-touch .mindforge/production/compatibility-layer.md
-touch .mindforge/production/production-checklist.md
-
-# Plugin system
-mkdir -p .mindforge/plugins
-touch .mindforge/plugins/plugin-schema.md
-touch .mindforge/plugins/plugin-loader.md
-touch .mindforge/plugins/plugin-registry.md
-touch .mindforge/plugins/PLUGINS-MANIFEST.md
-
-# Self-update system
-mkdir -p bin/updater
-touch bin/updater/self-update.js
-touch bin/updater/changelog-fetcher.js
-touch bin/updater/version-comparator.js
-
-# Migration system
-mkdir -p bin/migrations
-touch bin/migrations/migrate.js
-touch bin/migrations/schema-versions.js
-touch bin/migrations/0.1.0-to-0.5.0.js
-touch bin/migrations/0.5.0-to-0.6.0.js
-touch bin/migrations/0.6.0-to-1.0.0.js
-
-# Complete documentation hierarchy
-mkdir -p docs/reference
-mkdir -p docs/architecture
-mkdir -p docs/contributing
-mkdir -p docs/security
-touch docs/reference/commands.md
-touch docs/reference/skills-api.md
-touch docs/reference/sdk-api.md
-touch docs/reference/config-reference.md
-touch docs/reference/audit-events.md
-touch docs/architecture/README.md
-touch docs/architecture/decision-records-index.md
-touch docs/contributing/CONTRIBUTING.md
-touch docs/contributing/skill-authoring.md
-touch docs/contributing/plugin-authoring.md
-touch docs/security/SECURITY.md
-touch docs/security/threat-model.md
-touch docs/security/penetration-test-results.md
-
-# New commands
-touch .claude/commands/mindforge/update.md
-touch .claude/commands/mindforge/migrate.md
-touch .claude/commands/mindforge/plugins.md
-touch .claude/commands/mindforge/tokens.md
-touch .claude/commands/mindforge/release.md
-
-# Mirror to Antigravity
-for cmd in update migrate plugins tokens release; do
-  cp .claude/commands/mindforge/${cmd}.md .agent/mindforge/${cmd}.md
-done
-
-# Test suites
-touch tests/production.test.js
-touch tests/migration.test.js
-touch tests/e2e.test.js
-
-# Release artifacts
-touch .planning/RELEASE-CHECKLIST.md
-touch SECURITY.md
-```
-
-**Commit:**
-```bash
-git add .
-git commit -m "chore(day7): scaffold production release directory structure"
-```
-
----
-
-## TASK 2 — Write the complete `npx mindforge-cc` installer
-
-The installer has been scaffolded across Days 1-6 but never implemented end-to-end.
-Day 7 makes it production-complete — every edge case handled, every flag tested.
-
-### `bin/install.js` — Main entry point (rewrite completely)
-
-```javascript
-#!/usr/bin/env node
-/**
- * MindForge Installer — v1.0.0 Production Release
- *
- * USAGE:
- *   npx mindforge-cc@latest                   → Interactive setup wizard
- *   npx mindforge-cc@latest --claude --local  → Install for Claude Code, local project
- *   npx mindforge-cc@latest --all --global    → Install for all runtimes, globally
- *   npx mindforge-cc@latest --update          → Update existing installation
- *   npx mindforge-cc@latest --uninstall       → Remove MindForge
- *   npx mindforge-cc@latest --check           → Check for updates (no install)
- *   npx mindforge-cc@latest --version         → Print version and exit
- *   npx mindforge-cc@latest --help            → Print usage and exit
- *
- * Runtime flags:    --claude | --antigravity | --all
- * Scope flags:      --global (-g) | --local (-l)
- * Action flags:     --install (default) | --update | --uninstall | --check
- * Control flags:    --skip-wizard | --dry-run | --verbose | --force
- */
-
-'use strict';
-
-const VERSION = require('./package.json').version;
-const ARGS    = process.argv.slice(2);
-
-// ── Minimum Node.js version gate ─────────────────────────────────────────────
-const NODE_MAJOR = parseInt(process.versions.node.split('.')[0], 10);
-if (NODE_MAJOR < 18) {
-  process.stderr.write(
-    `\n❌  MindForge requires Node.js 18 or later.\n` +
-    `    Current: v${process.versions.node}\n` +
-    `    Install: https://nodejs.org/en/download/\n\n`
-  );
-  process.exit(1);
-}
-
-// ── Quick-exit flags ──────────────────────────────────────────────────────────
-if (ARGS.includes('--version') || ARGS.includes('-v')) {
-  process.stdout.write(`mindforge-cc v${VERSION}\n`);
-  process.exit(0);
-}
-
-if (ARGS.includes('--help') || ARGS.includes('-h')) {
-  printHelp();
-  process.exit(0);
-}
-
-// ── Determine execution mode ──────────────────────────────────────────────────
-const NON_INTERACTIVE_FLAGS = [
-  '--claude', '--antigravity', '--all',
-  '--global', '-g', '--local', '-l',
-  '--uninstall', '--update', '--check',
-  '--skip-wizard', '--dry-run',
-];
-
-const IS_NON_INTERACTIVE =
-  NON_INTERACTIVE_FLAGS.some(f => ARGS.includes(f)) ||
-  process.env.CI === 'true'                          ||
-  process.env.MINDFORGE_CI === 'true'                ||
-  process.stdin.isTTY === false;
-
-if (IS_NON_INTERACTIVE) {
-  require('./bin/installer-core').run(ARGS).catch(err => {
-    process.stderr.write(`\n❌  Installation failed: ${err.message}\n`);
-    process.stderr.write(`    For help: npx mindforge-cc --help\n\n`);
-    process.exit(1);
-  });
-} else {
-  require('./bin/wizard/setup-wizard').main().catch(err => {
-    process.stderr.write(`\n❌  Setup wizard failed: ${err.message}\n`);
-    process.stderr.write(`    Try non-interactive: npx mindforge-cc --claude --local\n\n`);
-    process.exit(1);
-  });
-}
-
-function printHelp() {
-  process.stdout.write(`
-  ⚡  MindForge v${VERSION} — Enterprise Agentic Framework
-
-  USAGE
-    npx mindforge-cc@latest [runtime] [scope] [action] [options]
-
-  RUNTIMES (pick one or use --all)
-    --claude          Claude Code  (~/.claude or .claude/)
-    --antigravity     Antigravity  (~/.gemini/antigravity or .agent/)
-    --all             Both runtimes
-
-  SCOPE
-    --global, -g      Install to home directory (all projects)
-    --local,  -l      Install to current directory (this project only)
-
-  ACTIONS (default: install)
-    --install         Install MindForge (default)
-    --update          Update existing installation
-    --uninstall       Remove MindForge
-    --check           Check for updates without installing
-
-  OPTIONS
-    --dry-run         Show what would happen without making changes
-    --force           Override existing installation without backup
-    --skip-wizard     Skip interactive wizard even in TTY
-    --verbose         Detailed output
-    --version, -v     Print version
-    --help, -h        Print this help
-
-  EXAMPLES
-    npx mindforge-cc@latest                       Interactive setup
-    npx mindforge-cc@latest --claude --local      Local Claude Code install
-    npx mindforge-cc@latest --all --global        Global install for all runtimes
-    npx mindforge-cc@latest --update --global     Update global install
-    npx mindforge-cc@latest --uninstall --local   Remove local install
-
-  DOCUMENTATION
-    https://github.com/mindforge-dev/mindforge
-    docs/enterprise-setup.md (after install)
-\n`);
-}
-```
-
-### `bin/installer-core.js` — Complete non-interactive installer
-
-```javascript
-/**
- * MindForge Installer Core — Production v1.0.0
- * Handles all non-interactive installation scenarios.
- */
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-
-const VERSION = require('../package.json').version;
-
-// ── Runtime configurations ────────────────────────────────────────────────────
-const RUNTIMES = {
-  claude: {
-    globalDir:      path.join(os.homedir(), '.claude'),
-    localDir:       '.claude',
-    commandsSubdir: 'commands/mindforge',
-    entryFile:      'CLAUDE.md',
-  },
-  antigravity: {
-    globalDir:      path.join(os.homedir(), '.gemini', 'antigravity'),
-    localDir:       '.agent',
-    commandsSubdir: 'mindforge',
-    entryFile:      'CLAUDE.md',
-  },
-};
-
-// ── File system utilities ─────────────────────────────────────────────────────
-const fsu = {
-  exists:     p  => fs.existsSync(p),
-  read:       p  => fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '',
-  write:      (p, t) => { fsu.ensureDir(path.dirname(p)); fs.writeFileSync(p, t, 'utf8'); },
-  ensureDir:  p  => { if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true }); },
-  copy:       (src, dst) => { fsu.ensureDir(path.dirname(dst)); fs.copyFileSync(src, dst); },
-  listFiles:  p  => fs.existsSync(p) ? fs.readdirSync(p) : [],
-
-  copyDir(src, dst, options = {}) {
-    const { excludePatterns = [] } = options;
-    fsu.ensureDir(dst);
-    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-      const skip = excludePatterns.some(pat =>
-        typeof pat === 'string' ? entry.name === pat : pat.test(entry.name)
-      );
-      if (skip) continue;
-
-      const s = path.join(src, entry.name);
-      const d = path.join(dst, entry.name);
-      entry.isDirectory() ? fsu.copyDir(s, d, options) : fsu.copy(s, d);
-    }
-  },
-};
-
-// ── Self-install detection ────────────────────────────────────────────────────
-function isSelfInstall() {
-  const pkgPath = path.join(process.cwd(), 'package.json');
-  if (!fsu.exists(pkgPath)) return false;
-  try {
-    return JSON.parse(fsu.read(pkgPath)).name === 'mindforge-cc';
-  } catch {
-    return false;
-  }
-}
-
-// ── Source root ───────────────────────────────────────────────────────────────
-const SOURCE_ROOT = path.resolve(__dirname, '..');
-const src         = (...parts) => path.join(SOURCE_ROOT, ...parts);
-
-// ── Sensitive file exclusions (never copy these) ──────────────────────────────
-const SENSITIVE_EXCLUDE = [
-  '.env', /^\.env\..*/,
-  '*.key', /\.key$/,
-  '*.pem', /\.pem$/,
-  'secrets', /^secrets$/,
-  '.secrets', /^\.secrets$/,
-];
-
-// ── CLAUDE.md safe copy ───────────────────────────────────────────────────────
-function safeCopyClaude(src, dst, options = {}) {
-  const { force = false, verbose = false } = options;
-
-  if (fsu.exists(dst)) {
-    const existing = fsu.read(dst);
-
-    if (!force) {
-      // Back up non-MindForge CLAUDE.md files
-      if (!existing.includes('MindForge')) {
-        const backup = `${dst}.backup-${Date.now()}`;
-        fsu.copy(dst, backup);
-        const sizeKb = (existing.length / 1024).toFixed(1);
-        console.log(`  ⚠️  Backed up existing CLAUDE.md (${sizeKb}KB) → ${path.basename(backup)}`);
-        if (existing.length > 5000) {
-          console.log(`      Large file detected — review the backup for custom instructions`);
-          console.log(`      to merge into the new CLAUDE.md.`);
-        }
-      }
-    }
-  }
-
-  fsu.copy(src, dst);
-  if (verbose) console.log(`  → ${dst}`);
-}
-
-// ── Install verification ──────────────────────────────────────────────────────
-function verifyInstall(baseDir, cmdsDir, runtime) {
-  // Minimum required files for a functional installation
-  const required = [
-    path.join(baseDir, 'CLAUDE.md'),
-    path.join(cmdsDir, 'help.md'),
-    path.join(cmdsDir, 'init-project.md'),
-    path.join(cmdsDir, 'health.md'),
-    path.join(cmdsDir, 'execute-phase.md'),
-    path.join(cmdsDir, 'security-scan.md'),
-  ];
-
-  const missing = required.filter(f => !fsu.exists(f));
-
-  if (missing.length > 0) {
-    console.error(`\n  ❌  Install verification failed — ${missing.length} required file(s) missing:`);
-    missing.forEach(f => console.error(`      ${f}`));
-    console.error(`\n  Retry: npx mindforge-cc@latest --${runtime} --${scope} --force`);
-    process.exit(1);
-  }
-}
-
-// ── Install single runtime ────────────────────────────────────────────────────
-async function install(runtime, scope, options = {}) {
-  const { dryRun = false, force = false, verbose = false } = options;
-  const cfg     = RUNTIMES[runtime];
-  const baseDir = scope === 'global' ? cfg.globalDir : path.join(process.cwd(), cfg.localDir);
-  const cmdsDir = path.join(baseDir, cfg.commandsSubdir);
-  const selfInstall = isSelfInstall();
-
-  console.log(`\n  Runtime : ${runtime}`);
-  console.log(`  Scope   : ${scope} → ${baseDir}`);
-  if (dryRun) console.log(`  Mode    : DRY RUN (no changes)`);
-  if (selfInstall) console.log(`  ⚠️  Self-install detected — skipping framework file copy`);
-
-  if (dryRun) {
-    console.log(`\n  Would install:`);
-    console.log(`    CLAUDE.md → ${path.join(baseDir, 'CLAUDE.md')}`);
-    console.log(`    ${fsu.listFiles(src('.claude', 'commands', 'mindforge')).length} commands → ${cmdsDir}`);
-    return;
-  }
-
-  // ── 1. Install CLAUDE.md ────────────────────────────────────────────────────
-  const claudeSrc = runtime === 'claude'
-    ? src('.claude', 'CLAUDE.md')
-    : src('.agent', 'CLAUDE.md');
-
-  if (fsu.exists(claudeSrc)) {
-    safeCopyClaude(claudeSrc, path.join(baseDir, 'CLAUDE.md'), { force, verbose });
-    console.log(`  ✅  CLAUDE.md`);
-  }
-
-  // ── 2. Install commands ─────────────────────────────────────────────────────
-  const cmdSrc = runtime === 'claude'
-    ? src('.claude', 'commands', 'mindforge')
-    : src('.agent', 'mindforge');
-
-  if (fsu.exists(cmdSrc)) {
-    fsu.ensureDir(cmdsDir);
-    const files = fsu.listFiles(cmdSrc).filter(f => f.endsWith('.md'));
-    files.forEach(f => fsu.copy(path.join(cmdSrc, f), path.join(cmdsDir, f)));
-    console.log(`  ✅  ${files.length} commands`);
-  }
-
-  // ── 3. Framework files (local scope only, non-self-install) ─────────────────
-  if (scope === 'local' && !selfInstall) {
-    // .mindforge/ — framework engine files
-    const forgeSrc = src('.mindforge');
-    const forgeDst = path.join(process.cwd(), '.mindforge');
-    if (fsu.exists(forgeSrc)) {
-      fsu.copyDir(forgeSrc, forgeDst, { excludePatterns: SENSITIVE_EXCLUDE });
-      console.log(`  ✅  .mindforge/ (framework engine)`);
-    }
-
-    // .planning/ — create only if it doesn't already exist (preserve project state)
-    const planningDst = path.join(process.cwd(), '.planning');
-    if (!fsu.exists(planningDst)) {
-      const planningSrc = src('.planning');
-      if (fsu.exists(planningSrc)) {
-        fsu.copyDir(planningSrc, planningDst, { excludePatterns: SENSITIVE_EXCLUDE });
-        console.log(`  ✅  .planning/ (state templates)`);
-      }
-    } else {
-      console.log(`  ⏭️  .planning/ already exists — preserved (run /mindforge:health to verify)`);
-    }
-
-    // MINDFORGE.md — create only if it doesn't already exist
-    const mindforgemDst = path.join(process.cwd(), 'MINDFORGE.md');
-    const mindforgemSrc = src('MINDFORGE.md');
-    if (!fsu.exists(mindforgemDst) && fsu.exists(mindforgemSrc)) {
-      fsu.copy(mindforgemSrc, mindforgemDst);
-      console.log(`  ✅  MINDFORGE.md (project constitution)`);
-    }
-
-    // bin/ utilities (validate-config, wizard)
-    const binDst = path.join(process.cwd(), 'bin');
-    const binSrc = src('bin');
-    if (fsu.exists(binSrc) && !fsu.exists(binDst)) {
-      fsu.copyDir(binSrc, binDst, { excludePatterns: SENSITIVE_EXCLUDE });
-      console.log(`  ✅  bin/ (utilities)`);
-    }
-  }
-
-  // ── 4. Verify installation ──────────────────────────────────────────────────
-  verifyInstall(baseDir, cmdsDir, runtime);
-  console.log(`  ✅  Install verified`);
-}
-
-// ── Uninstall ─────────────────────────────────────────────────────────────────
-async function uninstall(runtime, scope, options = {}) {
-  const { dryRun = false } = options;
-  const cfg     = RUNTIMES[runtime];
-  const baseDir = scope === 'global' ? cfg.globalDir : path.join(process.cwd(), cfg.localDir);
-  const cmdsDir = path.join(baseDir, cfg.commandsSubdir);
-  const claudeMd = path.join(baseDir, 'CLAUDE.md');
-
-  console.log(`\n  Uninstalling MindForge (${runtime} / ${scope})...`);
-  if (dryRun) {
-    console.log(`  Would remove: ${cmdsDir}`);
-    if (fsu.exists(claudeMd) && fsu.read(claudeMd).includes('MindForge'))
-      console.log(`  Would remove: ${claudeMd}`);
-    return;
-  }
-
-  // Remove commands directory
-  if (fsu.exists(cmdsDir)) {
-    fs.rmSync(cmdsDir, { recursive: true, force: true });
-    console.log(`  ✅  Removed: ${cmdsDir}`);
-  }
-
-  // Remove CLAUDE.md only if it's a MindForge-generated file
-  if (fsu.exists(claudeMd) && fsu.read(claudeMd).includes('MindForge')) {
-    fs.unlinkSync(claudeMd);
-    console.log(`  ✅  Removed: ${claudeMd}`);
-  }
-
-  // Preserve .planning/ and .mindforge/ — user data, not our files to delete
-  console.log(`  ℹ️  .planning/ and .mindforge/ preserved (user data)`);
-  console.log(`      Remove manually if desired.`);
-}
-
-// ── Main run ──────────────────────────────────────────────────────────────────
-async function run(args) {
-  const runtime    = args.includes('--antigravity') ? 'antigravity'
-                   : args.includes('--all')         ? 'all'
-                   : 'claude';
-  const scope      = args.includes('--global') || args.includes('-g') ? 'global' : 'local';
-  const dryRun     = args.includes('--dry-run');
-  const force      = args.includes('--force');
-  const verbose    = args.includes('--verbose');
-  const isUninstall = args.includes('--uninstall');
-  const isUpdate    = args.includes('--update');
-  const isCheck     = args.includes('--check');
-  const options     = { dryRun, force, verbose };
-
-  console.log(`\n⚡  MindForge v${VERSION} — Enterprise Agentic Framework\n`);
-
-  // Check for updates only
-  if (isCheck) {
-    const { checkAndUpdate } = require('./updater/self-update');
-    await checkAndUpdate({ apply: false });
-    return;
-  }
-
-  const runtimes = runtime === 'all' ? Object.keys(RUNTIMES) : [runtime];
-
-  for (const rt of runtimes) {
-    if (isUninstall)  await uninstall(rt, scope, options);
-    else if (isUpdate) await install(rt, scope, { ...options, isUpdate: true });
-    else               await install(rt, scope, options);
-  }
-
-  if (!isUninstall) {
-    console.log(`\n  ✅  MindForge v${VERSION} installed (${runtime} / ${scope})\n`);
-    console.log(`  Next steps:`);
-    console.log(`    1. Open Claude Code or Antigravity in your project directory`);
-    console.log(`    2. Run: /mindforge:health  (verify installation)`);
-    console.log(`    3. Run: /mindforge:init-project  (new project)`);
-    console.log(`         OR /mindforge:map-codebase  (existing project)\n`);
-  } else {
-    console.log(`\n  ✅  MindForge uninstalled\n`);
-  }
-}
-
-module.exports = { run, install, uninstall };
-```
-
-**Commit:**
-```bash
-git add bin/install.js bin/installer-core.js
-git commit -m "feat(installer): complete production-grade installer — all code paths, edge cases, DRY_RUN"
-```
-
----
-
-## TASK 3 — Write the Self-Update System
-
-### `bin/updater/version-comparator.js`
-
-```javascript
-/**
- * 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 };
-```
-
-### `bin/updater/changelog-fetcher.js`
-
-```javascript
-/**
- * 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 };
-```
-
-### `bin/updater/self-update.js`
-
-```javascript
-/**
- * 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();
-
-  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 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) {
-    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 };
-```
-
-**Commit:**
-```bash
-git add bin/updater/
-git commit -m "feat(updater): implement self-update with scope detection, changelog, schema-version-aware migration"
-```
-
----
-
-## TASK 4 — Write the Version Migration Engine
-
-### `bin/migrations/schema-versions.js`
-
-```javascript
-/**
- * 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 };
-```
-
-### `bin/migrations/migrate.js`
-
-```javascript
-/**
- * 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'),
-  ].filter(m =>
-    compareSemver(m.fromVersion, fromVersion) >= 0 &&
-    compareSemver(m.toVersion,   toVersion)   <= 0
-  );
-
-  if (allMigrations.length === 0) {
-    console.log(`  ✅  No applicable migrations`);
-    return { status: 'no-migrations' };
-  }
-
-  console.log(`  Migrations to run (${allMigrations.length}):`);
-  allMigrations.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 allMigrations) {
-    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}`);
-  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;
-```
-
-### `bin/migrations/0.6.0-to-1.0.0.js`
-
-```javascript
-/**
- * MindForge Migration: v0.6.0 → v1.0.0
- *
- * Changes:
- * 1. HANDOFF.json: add `plugin_api_version` field
- * 2. AUDIT.jsonl: backfill `session_id` for entries missing it
- * 3. MINDFORGE.md: convert VERIFY_PASS_RATE_WARNING_THRESHOLD if in old 0-100 format
- * 4. STATE.md: add v1.0.0 compatibility note if it doesn't already have one
- */
-'use strict';
-
-const fs = require('fs');
-
-module.exports = {
-  fromVersion: '0.6.0',
-  toVersion:   '1.0.0',
-  description: 'Add plugin_api_version; backfill session_id; normalise MINDFORGE.md thresholds',
-
-  async run(paths) {
-    // ── 1. HANDOFF.json ───────────────────────────────────────────────────────
-    if (fs.existsSync(paths.handoff)) {
-      const handoff = JSON.parse(fs.readFileSync(paths.handoff, 'utf8'));
-
-      if (!handoff.plugin_api_version) {
-        handoff.plugin_api_version = '1.0.0';
-      }
-      // Ensure fields added in 0.6.0 are present (for projects that skipped intermediate updates)
-      if (!Array.isArray(handoff.recent_commits)) handoff.recent_commits = [];
-      if (!Array.isArray(handoff.recent_files))   handoff.recent_files   = [];
-      if (!handoff.session_id) {
-        handoff.session_id = `migrated-${Date.now()}`;
-      }
-
-      fs.writeFileSync(paths.handoff, JSON.stringify(handoff, null, 2) + '\n');
-      console.log(`    • HANDOFF.json: added plugin_api_version, normalised arrays`);
-    }
-
-    // ── 2. AUDIT.jsonl ────────────────────────────────────────────────────────
-    if (fs.existsSync(paths.audit)) {
-      const raw   = fs.readFileSync(paths.audit, 'utf8');
-      const lines = raw.split('\n').filter(Boolean);
-      let modified = 0;
-
-      const updated = lines.map(line => {
-        try {
-          const entry = JSON.parse(line);
-          if (!entry.session_id) {
-            entry.session_id = 'migrated-from-pre-1.0';
-            modified++;
-            return JSON.stringify(entry);
-          }
-          return line;
-        } catch {
-          return line;  // Preserve unparseable lines exactly as-is (quarantine pattern)
-        }
-      });
-
-      if (modified > 0) {
-        fs.writeFileSync(paths.audit, updated.join('\n') + '\n');
-        console.log(`    • AUDIT.jsonl: backfilled session_id in ${modified} of ${lines.length} entries`);
-      } else {
-        console.log(`    • AUDIT.jsonl: all entries already have session_id`);
-      }
-    }
-
-    // ── 3. MINDFORGE.md ───────────────────────────────────────────────────────
-    if (fs.existsSync(paths.mindforgemd)) {
-      let content = fs.readFileSync(paths.mindforgemd, 'utf8');
-      let changed = false;
-
-      // Convert VERIFY_PASS_RATE_WARNING_THRESHOLD from percent (>1) to decimal
-      const pctPattern = /^(VERIFY_PASS_RATE_WARNING_THRESHOLD=)(\d+(?:\.\d+)?)(\s*)$/m;
-      const match = content.match(pctPattern);
-      if (match) {
-        const val = parseFloat(match[2]);
-        if (val > 1) {
-          // Old format: integer like 75 → new format: 0.75
-          const newVal = (val / 100).toFixed(2);
-          content = content.replace(pctPattern, `$1${newVal}$3`);
-          changed = true;
-          console.log(`    • MINDFORGE.md: converted VERIFY_PASS_RATE_WARNING_THRESHOLD ${val} → ${newVal}`);
-        }
-        // If val <= 1, it's already in the correct format — no change needed
-      }
-
-      if (changed) fs.writeFileSync(paths.mindforgemd, content);
-    }
-
-    // ── 4. STATE.md ───────────────────────────────────────────────────────────
-    if (fs.existsSync(paths.state)) {
-      const content = fs.readFileSync(paths.state, 'utf8');
-      if (!content.includes('v1.0.0') && !content.includes('MindForge v1')) {
-        fs.appendFileSync(paths.state,
-          `\n\n---\n*Migrated to MindForge v1.0.0 schema on ${new Date().toISOString().slice(0,10)}*\n`
-        );
-        console.log(`    • STATE.md: added v1.0.0 migration note`);
-      }
-    }
-  },
-};
-```
-
-### `bin/migrations/0.1.0-to-0.5.0.js` and `0.5.0-to-0.6.0.js`
-
-```javascript
-// bin/migrations/0.1.0-to-0.5.0.js
-'use strict';
-const fs = require('fs');
-module.exports = {
-  fromVersion: '0.1.0',
-  toVersion:   '0.5.0',
-  description: 'Add decisions_made, discoveries, implicit_knowledge to HANDOFF.json',
-  async run(paths) {
-    if (!fs.existsSync(paths.handoff)) return;
-    const handoff = JSON.parse(fs.readFileSync(paths.handoff, 'utf8'));
-    if (!handoff.decisions_made)     handoff.decisions_made     = [];
-    if (!handoff.discoveries)        handoff.discoveries        = [];
-    if (!handoff.implicit_knowledge) handoff.implicit_knowledge = [];
-    if (!handoff.quality_signals)    handoff.quality_signals    = [];
-    fs.writeFileSync(paths.handoff, JSON.stringify(handoff, null, 2) + '\n');
-    console.log(`    • HANDOFF.json: added intelligence layer fields`);
-  },
-};
-
-// bin/migrations/0.5.0-to-0.6.0.js
-'use strict';
-const fs = require('fs');
-module.exports = {
-  fromVersion: '0.5.0',
-  toVersion:   '0.6.0',
-  description: 'Add developer_id, session_id, recent_commits, recent_files to HANDOFF.json',
-  async run(paths) {
-    if (!fs.existsSync(paths.handoff)) return;
-    const handoff = JSON.parse(fs.readFileSync(paths.handoff, 'utf8'));
-    if (!handoff.developer_id)   handoff.developer_id   = null;
-    if (!handoff.session_id)     handoff.session_id     = null;
-    if (!Array.isArray(handoff.recent_commits)) handoff.recent_commits = [];
-    if (!Array.isArray(handoff.recent_files))   handoff.recent_files   = [];
-    fs.writeFileSync(paths.handoff, JSON.stringify(handoff, null, 2) + '\n');
-    console.log(`    • HANDOFF.json: added distribution platform fields`);
-  },
-};
-```
-
-**Commit:**
-```bash
-git add bin/migrations/
-git commit -m "feat(migration): complete migration engine — all versions 0.1.0→1.0.0 with backup/restore"
-```
-
----
-
-## TASK 5 — Write the Plugin System
-
-### `.mindforge/plugins/plugin-schema.md`
-
-```markdown
-# MindForge Plugin System — Schema v1.0.0
-
-## Philosophy
-Plugins extend MindForge without modifying the core framework files.
-They are first-class citizens: versioned, validated, injection-guarded, and audited.
-
-## Package naming convention
-`mindforge-plugin-[category]-[name]`
-
-Examples:
-- `mindforge-plugin-jira-advanced`    — Advanced Jira sprint and velocity commands
-- `mindforge-plugin-testing-playwright` — Playwright E2E testing skill and commands
-- `mindforge-plugin-cloud-aws`        — AWS deployment patterns and runbooks
-- `mindforge-plugin-design-figma`     — Figma design review integration
-
-## What a plugin can provide
-
-| Component | Description | File location |
-|---|---|---|
-| Commands | New slash commands | `commands/[name].md` |
-| Skills | New skill packs | `skills/[name]/SKILL.md` |
-| Personas | New agent personas | `personas/[name].md` |
-| Hooks | Lifecycle event handlers | `hooks/[hook-name].md` |
-
-## `plugin.json` manifest (required in every plugin package)
-
-```json
-{
-  "name": "mindforge-plugin-jira-advanced",
-  "version": "1.0.0",
-  "description": "Advanced Jira integration with sprint planning and velocity tracking",
-  "mindforge": {
-    "type": "plugin",
-    "min_mindforge_version": "1.0.0",
-    "plugin_api_version": "1.0.0",
-    "provides": {
-      "commands":  ["jira-sprint", "jira-velocity", "jira-epics"],
-      "skills":    [],
-      "personas":  [],
-      "hooks": {
-        "post_phase_complete": "hooks/post-phase.md",
-        "pre_plan_phase":      null,
-        "post_execute_phase":  null,
-        "post_verify_phase":   null,
-        "post_milestone":      null,
-        "pre_security_scan":   null,
-        "post_security_scan":  null
-      }
-    },
-    "permissions": {
-      "read_audit_log":    true,
-      "write_audit_log":   true,
-      "read_state":        true,
-      "write_state":       false,
-      "network_access":    true,
-      "file_system_write": false
-    },
-    "conflicts_with": []
-  },
-  "keywords": ["mindforge", "mindforge-plugin", "jira"],
-  "license": "MIT"
-}
-```
-
-## Permissions — advisory model
-
-The permission system is advisory, not OS-enforced. Permissions are:
-- **Declared** in plugin.json before installation
-- **Displayed** to the user for review at install time
-- **Recorded** in AUDIT.jsonl with plugin name as the agent field
-- **Enforced** through the agent's own governance layer (plan-first, audit requirements)
-
-A plugin instructing the agent to take actions outside its declared permissions
-would still be subject to all MindForge governance checks (secret detection,
-quality gates, Tier classification). The permission declaration is a statement
-of intent — it enables trust decisions, not OS-level sandboxing.
-
-**The real security layer is:**
-1. Injection guard at install time (blocks obvious adversarial instructions)
-2. Level 1/2/3 validation of all plugin SKILL.md files
-3. User review of plugin commands before installation
-4. Complete audit trail with plugin name on every action
-
-## Available lifecycle hooks
-
-| Hook name | Trigger point | Typical use case |
-|---|---|---|
-| `post_phase_complete` | After /mindforge:verify-phase passes | External notifications, custom reports |
-| `pre_plan_phase` | Before /mindforge:plan-phase starts | Requirement fetching from external system |
-| `post_execute_phase` | After all execution waves complete | Custom metrics collection |
-| `post_verify_phase` | After UAT sign-off | Custom acceptance report |
-| `post_milestone` | After /mindforge:complete-milestone | Release announcement, changelog distribution |
-| `pre_security_scan` | Before /mindforge:security-scan | Custom scan tool preparation |
-| `post_security_scan` | After security scan completes | Custom finding routing, ticketing |
-
-## Reserved command names
-
-These 36 command names are permanently reserved for MindForge built-ins.
-Plugin commands with these names will be prefixed with the plugin name:
-
-```
-help, init-project, plan-phase, execute-phase, verify-phase, ship,
-next, quick, status, debug, skills, review, security-scan, map-codebase,
-discuss-phase, audit, milestone, complete-milestone, approve, sync-jira,
-sync-confluence, health, retrospective, profile-team, metrics, init-org,
-install-skill, publish-skill, pr-review, workspace, benchmark, update,
-migrate, plugins, tokens, release
-```
-```
-
----
-
-### `.mindforge/plugins/plugin-loader.md`
-
-```markdown
-# MindForge Plugin System — Loader Protocol
-
-## Loading sequence (runs at session start)
-
-### Step 1 — Discover installed plugins
-```bash
-MANIFEST=".mindforge/plugins/PLUGINS-MANIFEST.md"
-[ -f "${MANIFEST}" ] || { echo "No plugins installed"; return; }
-
-# Extract plugin names from manifest table rows
-PLUGINS=$(grep "^| " "${MANIFEST}" | grep -v "^| Name" | grep -v "none" | \
-  awk -F'|' '{gsub(/[[:space:]]/, "", $2); print $2}' | grep -v '^$')
-```
-
-### Step 2 — Validate each installed plugin
-
-For each installed plugin directory at `.mindforge/plugins/[plugin-name]/`:
-
-1. **plugin.json exists and is valid JSON**
-2. **plugin_api_version compatibility**: read `plugin.json mindforge.plugin_api_version`
-   and verify it matches the current supported API version (`1.0.0`)
-3. **min_mindforge_version compatibility**: verify current MindForge version satisfies minimum
-4. **Injection guard**: run against all command, skill, and persona .md files in the plugin
-   - If injection patterns found: do NOT load. Log AUDIT entry, alert user
-5. **Level 1 + Level 2 validation**: for every SKILL.md in the plugin
-
-### Step 3 — Load plugin components
-
-**Commands:**
-```bash
-for CMD_FILE in ".mindforge/plugins/[plugin]/commands/"*.md; do
-  CMD_NAME=$(basename "${CMD_FILE}" .md)
-
-  # Check for conflict with reserved names
-  RESERVED_NAMES=(help init-project plan-phase execute-phase verify-phase ship
-                  next quick status debug skills review security-scan
-                  map-codebase discuss-phase audit milestone complete-milestone
-                  approve sync-jira sync-confluence health retrospective
-                  profile-team metrics init-org install-skill publish-skill
-                  pr-review workspace benchmark update migrate plugins tokens release)
-
-  IS_RESERVED=false
-  for RESERVED in "${RESERVED_NAMES[@]}"; do
-    [ "${CMD_NAME}" = "${RESERVED}" ] && { IS_RESERVED=true; break; }
-  done
-
-  # Prefix if conflict
-  FINAL_NAME="${IS_RESERVED:-true && "${PLUGIN_NAME}-${CMD_NAME}" || "${CMD_NAME}"}"
-
-  cp "${CMD_FILE}" ".claude/commands/mindforge/${FINAL_NAME}.md"
-  cp "${CMD_FILE}" ".agent/mindforge/${FINAL_NAME}.md"
-done
-```
-
-**Skills:** Registered in MANIFEST.md under Tier 2 section (prefix: `[plugin-name]-`)
-**Personas:** Installed as `.mindforge/personas/[plugin-name]-[persona].md`
-**Hooks:** Registered in `.mindforge/plugins/hooks-registry.md`
-
-### Step 4 — Report loaded plugins
-
-At session start, CLAUDE.md reads the loaded plugins list and reports:
-```
-Active plugins (2):
-  jira-advanced v1.0.0 — hooks: post_phase_complete
-  testing-playwright v0.9.0 — skills: playwright-e2e
-```
-
-If any plugin fails validation: skip it, report error, continue loading others.
-Never fail the session start because a plugin is invalid.
-
-### Step 5 — Write AUDIT entry for plugin load
-
-```json
-{
-  "event": "plugins_loaded",
-  "plugins": [
-    { "name": "mindforge-plugin-jira-advanced", "version": "1.0.0", "hooks": ["post_phase_complete"] }
-  ],
-  "failed": []
-}
-```
-```
-
----
-
-### `.mindforge/plugins/PLUGINS-MANIFEST.md`
-
-```markdown
-# MindForge Plugins Manifest
-# Schema version: 1.0.0
-# This file is managed by /mindforge:plugins install|uninstall
-
-## Installed plugins
-
-| Name | Version | Status | Min MindForge | Permissions |
-|---|---|---|---|---|
-| (no plugins installed) | | | | |
-
-## Available plugins (public registry)
-
-Search: `npm search mindforge-plugin`
-Install: `/mindforge:plugins install [plugin-name]`
-
-## Plugin development
-
-To create a plugin: see `docs/contributing/plugin-authoring.md`
-To publish:        `npm publish --access public`
-To validate:       `node bin/validate-config.js --type plugin ./plugin.json`
-
-## Hooks registry
-(populated automatically when plugins with hooks are installed)
-```
-
-**Commit:**
-```bash
-git add .mindforge/plugins/
-git commit -m "feat(plugins): implement plugin schema, loader protocol, and manifest — v1.0.0 stable"
-```
-
----
-
-## TASK 6 — Write the Token Usage Optimiser
-
-### `.mindforge/production/token-optimiser.md`
-
-```markdown
-# MindForge Production — Token Usage Optimiser
-
-## Purpose
-Measure, profile, and systematically reduce Claude API token consumption.
-Token efficiency impacts both cost and session quality — a session that
-exhausts its context on large file reads has less capacity for reasoning.
-
-## Token consumption model
-
-### Where tokens are spent in a typical MindForge session
-
-| Component | Typical estimate | Notes |
-|---|---|---|
-| Session startup (CLAUDE.md + ORG.md + PROJECT.md + STATE.md) | 4,000–9,000 | Fixed per session |
-| Each skill injected (full) | 2,500–6,000 | Depends on skill complexity |
-| Each skill injected (summary) | 300–600 | When > 3 skills loaded |
-| PLAN file per task | 400–1,800 | Lean plans save 800+ tokens |
-| File reading per task | 1,500–50,000 | Biggest variable cost |
-| Agent reasoning + response | 1,500–8,000 | |
-| Verify step + output | 400–1,500 | |
-
-**Note:** These are estimates based on typical MindForge projects.
-Actual values depend on file sizes, code complexity, and model verbosity.
-Run `/mindforge:tokens` to see measured estimates for your project.
-
-### Token efficiency threshold
-
-| Efficiency | Meaning | Action |
-|---|---|---|
-| > 45% | Excellent — agent spending time on reasoning and output | No action |
-| 35–45% | Good — healthy balance | No action |
-| 20–35% | Acceptable — room to optimise | Review high-cost sessions |
-| < 20% | Poor — most tokens spent on reading, not reasoning | Apply optimisations below |
-
-```
-token_efficiency = useful_output_tokens / total_tokens_consumed
-useful_output_tokens = tokens in SUMMARY files + verified code changes + ADRs written
-```
-
-## Optimisation strategies
-
-### Strategy 1 — Lean PLAN `<action>` fields (highest impact)
-
-**Anti-pattern:** Over-specified actions that tell the agent HOW to implement,
-rather than WHAT to implement. These waste tokens on instructions the agent's
-persona and skills already provide.
-
-```xml
-<!-- ❌ Over-specified: 720 tokens — redundant with developer.md persona -->
-<action>
-  Create a TypeScript interface called UserProfile in src/types/user.ts.
-  The interface should have the following fields: id (string, UUID v4),
-  email (string, validated with RFC 5322 regex), firstName (string, min 1 char),
-  lastName (string, min 1 char), createdAt (Date, UTC), updatedAt (Date, UTC),
-  deletedAt (Date | null), role (string enum: 'admin' | 'editor' | 'viewer'),
-  preferences object with keys: theme ('light' | 'dark'), notifications (boolean),
-  timezone (string). Add JSDoc comments with @param tags for each field.
-  Export as a named export. Use strict TypeScript types throughout.
-</action>
-
-<!-- ✅ Lean: 140 tokens — trusts the developer persona -->
-<action>
-  Create UserProfile interface in src/types/user.ts.
-  Fields: id (UUID), email (RFC 5322 validated), name fields,
-  timestamps (created/updated/deleted), role enum (admin/editor/viewer),
-  preferences (theme, notifications, timezone).
-  Full JSDoc. Named export.
-</action>
-```
-
-**Token saving: ~580 tokens per plan action. For 10 tasks: ~5,800 tokens (≈ one extra skill).**
-
-### Strategy 2 — Just-in-time file reading
-
-Current: subagents read ALL files in `<files>` at task start.
-Optimal: Read files when they are first referenced in the action.
-
-This is a recommendation for planning — instruct the planner:
-"Add a note to `<context>` in plans: 'Read files lazily — read each file
-when first needed in the action, not all upfront.'"
-
-**Known limitation:** This is advisory. The execution engine update to enforce
-lazy loading is planned for v1.1.0.
-
-### Strategy 3 — Selective STATE.md section loading
-
-STATE.md grows over time as projects accumulate phase summaries and decisions.
-Loading the full file at session start can cost 3,000–8,000 tokens.
-
-Optimised loading approach (add to CLAUDE.md session start):
-```bash
-# Extract only the sections needed at session start
-# Full STATE.md: only loaded when the agent needs project history
-
-# Minimal load — always (200-500 tokens):
-CURRENT_STATUS_SECTION=$(awk '/^## Current status/,/^## /' .planning/STATE.md | head -30)
-NEXT_ACTION_SECTION=$(awk '/^## Next action/,/^## /' .planning/STATE.md | head -10)
-
-# Full load — only when agent explicitly needs history:
-# (e.g., plan-phase, retrospective, complete-milestone)
-```
-
-### Strategy 4 — Code context precision
-
-For tasks that modify specific functions: provide only the relevant code section.
-
-```xml
-<!-- ❌ Reads entire 450-line file for a 10-line change -->
-<files>src/services/user.service.ts</files>
-
-<!-- ✅ Agent reads only the relevant section -->
-<files>src/services/user.service.ts:40-65</files>
-<!-- (line range specification — a Day 7 planner feature) -->
-```
-
-**Note:** Line-range file reading is a planned v1.1.0 feature.
-For now: add to `<context>`: "Focus on lines 40-65 of user.service.ts."
-
-### Strategy 5 — Skill summarisation at 4+ skills
-
-Already implemented in loader.md. This strategy verifies it is working:
-
-Check skill-usage.jsonl for `tokens_est` field.
-If any session shows 4+ skills loaded at full injection: loader protocol needs review.
-Target: never more than 3 skills at full injection per task.
-
-## Token budget tracking
-
-Written to `.mindforge/metrics/token-usage.jsonl` after each task:
-
-```json
-{
-  "timestamp": "ISO-8601",
-  "session_id": "sess_abc123",
-  "phase": 3,
-  "plan": "02",
-  "task_name": "Implement auth middleware",
-  "token_estimates": {
-    "context_startup": 6200,
-    "skills": { "count": 2, "total": 8400, "summarised": 0 },
-    "plan_file": 620,
-    "code_reading": 12400,
-    "agent_response": 3800,
-    "verify": 720,
-    "total": 32140
-  },
-  "efficiency": 0.34,
-  "flags": []
-}
-```
-
-## MINDFORGE.md token settings
-
-```
-# Add to MINDFORGE.md to configure token behaviour:
-
-# Warn when single task token estimate exceeds this
-TOKEN_WARN_THRESHOLD=40000
-
-# Lean mode: agent produces shorter responses where possible
-TOKEN_LEAN_MODE=false
-
-# Maximum lines to read per file when no line range specified
-TOKEN_MAX_FILE_LINES=300
-```
-```
-
-**Commit:**
-```bash
-git add .mindforge/production/token-optimiser.md
-git commit -m "feat(tokens): implement token usage optimiser with profiling, strategies, and JSONL tracking"
-```
-
----
-
-## TASK 7 — Write the 50-point Production Readiness Checklist
-
-### `.mindforge/production/production-checklist.md`
-
-```markdown
-# MindForge v1.0.0 — Production Readiness Checklist
-
-## Policy: ALL 50 items must be ✅ before tagging v1.0.0
-
-This is not a "should" list — it is a hard gate.
-No item can be marked ✅ without:
-1. The specific verification step executed successfully
-2. The verifier's git email recorded
-3. The date verified recorded
-
-Document completed checks in `.planning/RELEASE-CHECKLIST.md`.
-
----
-
-## SECTION A — Installation & Upgrade (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| A01 | `npx mindforge-cc@latest` launches interactive wizard on macOS | Run on macOS terminal with TTY | | | |
-| A02 | `npx mindforge-cc@latest` launches wizard on Linux | Run on Ubuntu 22.04 LTS terminal | | | |
-| A03 | `npx mindforge-cc --claude --local` installs correctly | Verify files, run /mindforge:health | | | |
-| A04 | `npx mindforge-cc --all --global` installs both runtimes | Check ~/.claude and ~/.gemini/antigravity | | | |
-| A05 | `--update` updates and preserves install scope | Install locally, run --update, verify scope preserved | | | |
-| A06 | `--uninstall` removes only MindForge files (not .planning/) | Run uninstall, verify .planning/ intact | | | |
-| A07 | `--version` and `--help` exit 0 with correct output | Run both flags, check exit code | | | |
-| A08 | Install over existing CLAUDE.md backs it up | Create custom CLAUDE.md, install, verify backup | | | |
-| A09 | Install over existing .planning/ preserves it | Create test .planning/, install, verify preserved | | | |
-| A10 | Node.js < 18 prints helpful error and exits 1 | Run with node 16, verify error message | | | |
-
-## SECTION B — Command Coverage (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| B01 | `/mindforge:help` shows all 36 commands | Count commands in output, verify ≥ 36 | | | |
-| B02 | `/mindforge:init-project` creates all 5 required .planning/ files | Run in empty dir, check file list | | | |
-| B03 | `/mindforge:health` reports ✅ on a fresh install | Fresh install, run health, zero errors | | | |
-| B04 | `/mindforge:health --repair` fixes CLAUDE.md drift | Corrupt .agent/CLAUDE.md, run repair, verify fix | | | |
-| B05 | `/mindforge:skills list` shows all 10 core skills | Count in output, verify all 10 names | | | |
-| B06 | `/mindforge:skills validate` shows all valid | Run, verify zero errors | | | |
-| B07 | `/mindforge:security-scan --secrets` detects fake key | Add test key pattern, scan, verify detection | | | |
-| B08 | `/mindforge:audit --summary` shows metrics dashboard | Run in project with some audit entries | | | |
-| B09 | `/mindforge:update` checks version without changing files | Run without --apply, verify no file changes | | | |
-| B10 | `/mindforge:migrate --dry-run` shows plan without changes | Run dry-run on v0.6.0 schema, verify dry-run | | | |
-
-## SECTION C — Governance Gates (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| C01 | Gate 3 (secret detection) blocks commit with fake API key | Stage file with `FAKE_ghp_abcdef1234567890abcd`, run gate | | | |
-| C02 | Gate 2 (tests passing) blocks on test failure | Break a test, run gate, verify block | | | |
-| C03 | Gate 1 (CRITICAL findings) blocks PR creation | Add CRITICAL finding to SECURITY-REVIEW, attempt ship | | | |
-| C04 | AUDIT.jsonl gains entry for every task start and complete | Execute one quick task, count new AUDIT lines | | | |
-| C05 | Tier 3 change classifier detects jwt.sign in non-auth path | Create file with jwt.sign, run classifier | | | |
-| C06 | Tier 3 CI block produces clear error message | Simulate CI run with Tier 3 pending, check output | | | |
-| C07 | MINDFORGE.md non-overridable keys are silently enforced | Set SECRET_DETECTION=false, verify it has no effect | | | |
-| C08 | Approval workflow creates APPROVAL-[uuid].json | Request a Tier 2 approval, verify file created | | | |
-| C09 | Plugin injection guard blocks malicious SKILL.md | Create SKILL.md with IGNORE ALL PREVIOUS, run guard | | | |
-| C10 | All 5 compliance gates produce GATE-RESULTS-N.md | Complete a full phase, verify GATE-RESULTS file | | | |
-
-## SECTION D — Documentation (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| D01 | README.md quick start works end-to-end in < 5 minutes | New developer follows README, measures time | | | |
-| D02 | `docs/reference/commands.md` documents all 36 commands | Count documented commands, verify ≥ 36 | | | |
-| D03 | `docs/enterprise-setup.md` covers all integration steps | Walk through integration setup docs | | | |
-| D04 | `docs/governance-guide.md` explains all 3 tiers clearly | Review with someone unfamiliar with governance | | | |
-| D05 | `docs/security/threat-model.md` covers all 7 threat actors | Count actors, verify controls for each | | | |
-| D06 | `docs/security/SECURITY.md` has disclosure process | Verify email + 90-day policy present | | | |
-| D07 | `docs/contributing/CONTRIBUTING.md` has PR guidelines | Check for: fork, branch, test, PR process | | | |
-| D08 | `docs/contributing/skill-authoring.md` is actionable | Follow guide to create a test skill | | | |
-| D09 | All 20 ADRs listed in decision-records-index.md | Count ADRs, cross-check index | | | |
-| D10 | CHANGELOG.md v1.0.0 entry is complete with date | Verify entry has date, all components listed | | | |
-
-## SECTION E — Test Coverage (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| E01 | All 15 test suites pass with 0 failures (Run 1) | Execute full test battery | | | |
-| E02 | All 15 test suites pass with 0 failures (Run 2) | Execute full test battery again | | | |
-| E03 | All 15 test suites pass with 0 failures (Run 3) | Execute full test battery third time | | | |
-| E04 | No test uses `process.exit(0)` inside a test function | `grep -rn 'process.exit(0)' tests/` | | | |
-| E05 | E2E tests simulate complete brownfield onboarding | Run tests/e2e.test.js, verify brownfield path | | | |
-| E06 | Migration tests cover v0.1.0 → v1.0.0 full chain | Run tests/migration.test.js full suite | | | |
-| E07 | No test has `// TODO` or `// skip` in test body | `grep -rn 'TODO\|skip' tests/` | | | |
-| E08 | Security penetration test pass (all 7 threat actors) | Run through threat-model.md controls manually | | | |
-| E09 | CI pipeline runs all tests on PR against main | Create test PR, verify CI passes | | | |
-| E10 | Version in package.json matches git tag matches npm dist | `node -e "console.log(require('./package.json').version)"` | | | |
-
----
-
-## Release gate procedure
-
-When ALL 50 items show ✅:
-
-```bash
-# 1. Final security scan
-/mindforge:security-scan --deep --secrets --deps
-
-# 2. Triple-run test battery
-node -e "
-const { execSync } = require('child_process');
-const suites = ['install','wave-engine','audit','compaction','skills-platform',
-  'integrations','governance','intelligence','metrics',
-  'distribution','ci-mode','sdk','production','migration','e2e'];
-let allPass = true;
-for (let run = 1; run <= 3; run++) {
-  for (const suite of suites) {
-    try {
-      execSync('node tests/' + suite + '.test.js', { stdio: 'pipe' });
-    } catch {
-      console.error('FAILED: ' + suite + ' run ' + run);
-      allPass = false;
-    }
-  }
-}
-console.log(allPass ? 'ALL TESTS PASSED × 3' : 'FAILURES DETECTED');
-process.exit(allPass ? 0 : 1);
-"
-
-# 3. Tag and publish (only after the above pass)
-git tag -a v1.0.0 -m "MindForge v1.0.0 — First stable public release"
-git push origin v1.0.0
-npm publish --access public
-```
-```
-
-**Commit:**
-```bash
-git add .mindforge/production/
-git commit -m "feat(production): 50-point release checklist, token optimiser, migration spec"
-```
-
----
-
-## TASK 8 — Write all 5 new commands
-
-### `.claude/commands/mindforge/update.md`
-
-```markdown
-# MindForge — Update Command
-# Usage: /mindforge:update [--apply] [--force] [--check] [--skip-changelog]
-
-## Purpose
-Check for and apply MindForge framework updates in a safe, scope-preserving way.
-
-## Execution flow
-
-### 1. Version check
-Execute `bin/updater/self-update.js` `checkAndUpdate()`.
-Always show: current version, latest version, update type (major/minor/patch).
-
-### 2. Changelog display (unless --skip-changelog)
-Fetch and display the relevant CHANGELOG.md section.
-For major updates: prefix with ⚠️ BREAKING CHANGES notice.
-Limit display to 3,000 characters — link to full CHANGELOG for the rest.
-
-### 3. Confirmation gate (unless --apply)
-Without --apply: show update info, stop. Do not modify any files.
-Message: "To apply this update: /mindforge:update --apply"
-
-### 4. Apply (with --apply)
-a. Detect original install scope (local vs global, claude vs antigravity)
-b. Read schema_version from HANDOFF.json (captures current version BEFORE update)
-c. Run `npx mindforge-cc@[latest] --[runtime] --[scope]`
-d. Run migration: `node bin/migrations/migrate.js` with captured schema_version
-e. Run /mindforge:health to verify update succeeded
-
-### 5. Post-update health check
-If health errors: surface them immediately with specific fix instructions.
-Common post-update issue: CLAUDE.md and .agent/CLAUDE.md drifted → auto-repair.
-
-## Error scenarios and recovery
-
-| Error | Recovery |
-|---|---|
-| npm registry unreachable | Message: "Check internet. Manual: npm info mindforge-cc version" |
-| Update download fails | Retry once, then suggest manual: `npx mindforge-cc@latest` |
-| Migration fails | Restored from backup automatically. Run /mindforge:migrate manually. |
-| Install scope detection fails | Prompt user: "Is your install global or local?" |
-
-## AUDIT entry
-```json
-{
-  "event": "framework_updated",
-  "from_version": "0.6.0",
-  "to_version": "1.0.0",
-  "update_type": "major",
-  "scope": "local",
-  "runtime": "claude",
-  "migration_ran": true,
-  "health_check_result": "healthy"
-}
-```
-```
-
-### `.claude/commands/mindforge/migrate.md`
-
-```markdown
-# MindForge — Migrate Command
-# Usage: /mindforge:migrate [--from X.Y.Z] [--to X.Y.Z] [--dry-run] [--force]
-
-## Purpose
-Run explicit schema migrations for .planning/ files.
-Normally triggered automatically by /mindforge:update.
-Use this command manually when: auto-migration failed, manual version jump, recovery.
-
-## Flow
-
-### Auto-detect migration need
-Read `schema_version` from HANDOFF.json.
-Compare against current `package.json` version.
-Determine migration path.
-
-### Dry-run mode (--dry-run)
-Show: which migrations would run, what each changes.
-Show: breaking changes for the migration path.
-Make NO changes to any file.
-
-### Backup first
-Before any changes: create `.planning/migration-backup-[timestamp]/`
-Verify backup integrity (file count, non-empty).
-If backup fails: ABORT. Explain disk space issue.
-
-### Execute migrations
-Run `node bin/migrations/migrate.js`.
-Show progress for each migration.
-If any migration fails: auto-restore from backup.
-
-### Verify
-Run /mindforge:health after migration.
-If health errors: report with specific fix instructions.
-Preserve backup until user is satisfied — they must delete it manually.
-
-## Manual version override
-`/mindforge:migrate --from 0.1.0 --to 1.0.0` — forces migration between specified versions.
-Use with care: intended for recovery scenarios where HANDOFF.json schema_version is wrong.
-
-## AUDIT entry
-```json
-{
-  "event": "schema_migrated",
-  "from_version": "0.6.0",
-  "to_version": "1.0.0",
-  "migrations_run": 1,
-  "backup_path": ".planning/migration-backup-1234567890",
-  "result": "success"
-}
-```
-```
-
-### `.claude/commands/mindforge/plugins.md`
-
-```markdown
-# MindForge — Plugins Command
-# Usage: /mindforge:plugins [list|install|uninstall|info|validate|create] [name]
-
-## list
-Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
-If no plugins: "No plugins installed. Find plugins: npm search mindforge-plugin"
-
-## install [plugin-name]
-Full installation protocol per plugin-loader.md:
-1. Resolve package: `mindforge-plugin-[name]` convention
-2. Download to chmod 700 temp directory
-3. Validate plugin.json manifest
-4. Check plugin_api_version compatibility (1.0.0 required)
-5. Run injection guard on ALL .md files in the plugin
-6. Run Level 1 + 2 skill validation on all SKILL.md files
-7. Display permission list for user approval:
-   ```
-   Plugin: mindforge-plugin-jira-advanced v1.0.0
-   Requests these permissions:
-     • read_audit_log:  read AUDIT.jsonl ✅ (safe)
-     • write_audit_log: append to AUDIT.jsonl ⚠️
-     • network_access:  make HTTP requests ⚠️
-   Install? (yes/no)
-   ```
-8. Install components (commands, skills, personas, hooks)
-9. Add to PLUGINS-MANIFEST.md
-10. Write AUDIT entry
-
-## uninstall [plugin-name]
-Remove all installed components. Update PLUGINS-MANIFEST.md.
-Confirm: "This will remove [N] commands, [N] skills from this plugin."
-
-## info [plugin-name]
-Display: version, description, author, permissions, commands, skills, personas, hooks.
-
-## validate
-Validate all installed plugins for compatibility, injection safety, permission scope.
-
-## create [plugin-name]
-Generate a plugin scaffold:
-```
-mindforge-plugin-[name]/
-├── plugin.json          (pre-filled template)
-├── commands/            (empty, ready for .md files)
-├── skills/              (empty, ready for skill directories)
-├── hooks/               (empty, ready for hook .md files)
-└── README.md            (template)
-```
-See docs/contributing/plugin-authoring.md for authoring guidance.
-```
-
-### `.claude/commands/mindforge/tokens.md`
-
-```markdown
-# MindForge — Token Usage Command
-# Usage: /mindforge:tokens [--phase N] [--session ID] [--window short|medium|long] [--optimise]
-
-## Purpose
-Display token consumption profile and efficiency analysis.
-Helps identify where tokens are being spent and how to reduce waste.
-
-## Default output (no flags — last 5 sessions)
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚡  Token Usage Profile — [Project Name]
-    Last 5 sessions
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Session       Estimated   Code Read  Skills  Efficiency
-  ──────────    ─────────   ─────────  ──────  ──────────
-  sess-01         31,200      17,800    6,400     40% ✅
-  sess-02         62,400      44,100    6,200     22% ⚠️
-  sess-03         28,900      15,400    5,800     43% ✅
-  sess-04         74,800      55,600    7,100     17% 🔴
-  sess-05         33,100      18,600    7,400     39% ✅
-
-  Average         46,080      30,300    6,580     32%
-  Target                                          >35%
-
-  Efficiency flags:
-  🔴 sess-04: code_reading extremely high (55,600) — plan scope too broad
-  ⚠️  sess-02: code_reading high (44,100) — consider narrower <files> list
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Run /mindforge:tokens --optimise for specific recommendations.
-```
-
-## Data source
-Read `.mindforge/metrics/token-usage.jsonl`.
-If file doesn't exist: "No token usage data yet. Data collected after tasks complete."
-
-## --optimise flag
-Analyse recent sessions for patterns. Report concrete improvements:
-- If code_reading consistently > 25,000: "Plans are reading too broadly. Add file line-ranges to `<context>` fields."
-- If skills > 4 per session: "4+ skills loading frequently. Consider adding specific triggers to reduce auto-loading."
-- If plan_file > 1,000 tokens: "PLAN `<action>` fields are verbose. Use lean format (see token-optimiser.md Strategy 1)."
-- Suggest MINDFORGE.md settings that would reduce token use.
-
-## AUDIT entry
-```json
-{ "event": "tokens_viewed", "window": "short", "avg_efficiency": 0.32 }
-```
-```
-
-### `.claude/commands/mindforge/release.md`
-
-```markdown
-# MindForge — Release Command
-# Usage: /mindforge:release [--version X.Y.Z] [--dry-run] [--checklist-only]
-# ⚠️  This command is for releasing the MindForge framework itself.
-#     For releasing your project phases, use /mindforge:ship instead.
-
-## Purpose
-Execute the complete MindForge v1.0.0 (or any version) release pipeline.
-Intended for the MindForge core team.
-
-## Gate: Production Readiness Checklist
-
-```bash
-# Verify all 50 checklist items are ✅
-CHECKLIST=".planning/RELEASE-CHECKLIST.md"
-[ -f "${CHECKLIST}" ] || { echo "❌ Release checklist not found"; exit 1; }
-
-UNCHECKED=$(grep -c '| ❌\| \| |' "${CHECKLIST}" || true)
-if [ "${UNCHECKED}" -gt 0 ]; then
-  echo "❌ ${UNCHECKED} checklist item(s) are not verified."
-  echo "   Complete the checklist before releasing."
-  exit 1
-fi
-echo "✅ All 50 checklist items verified"
-```
-
-## Release pipeline (8 stages)
-
-### Stage 1 — Final test battery (15 suites × 3 runs)
-```bash
-SUITES=(install wave-engine audit compaction skills-platform
-        integrations governance intelligence metrics
-        distribution ci-mode sdk production migration e2e)
-
-for RUN in 1 2 3; do
-  echo "=== Run ${RUN}/3 ==="
-  for SUITE in "${SUITES[@]}"; do
-    node tests/${SUITE}.test.js || { echo "FAILED: ${SUITE}"; exit 1; }
-  done
-done
-echo "✅ All 15 suites × 3 runs passed"
-```
-
-### Stage 2 — Security final scan
-```bash
-/mindforge:security-scan --deep --secrets --deps
-# Must show: CLEAN — 0 CRITICAL, 0 HIGH findings
-# Must show: 0 secrets detected
-# Must show: 0 vulnerable dependencies (HIGH or CRITICAL)
-```
-
-### Stage 3 — Version verification
-```bash
-PACKAGE_VER=$(node -e "console.log(require('./package.json').version)")
-[ "${PACKAGE_VER}" = "${TARGET_VERSION}" ] || { echo "❌ Version mismatch"; exit 1; }
-grep -q "${TARGET_VERSION}" CHANGELOG.md || { echo "❌ No CHANGELOG entry"; exit 1; }
-echo "✅ Version: ${PACKAGE_VER}"
-```
-
-### Stage 4 — SDK build
-```bash
-cd sdk && npm run build
-[ -f "dist/index.js" ] || { echo "❌ SDK build failed"; exit 1; }
-[ -f "dist/index.d.ts" ] || { echo "❌ SDK types missing"; exit 1; }
-echo "✅ SDK built"
-cd ..
-```
-
-### Stage 5 — Release commit and tag
-```bash
-git add package.json CHANGELOG.md sdk/dist/ .planning/RELEASE-CHECKLIST.md
-git commit -m "chore(release): v${TARGET_VERSION} — enterprise agentic framework stable release"
-
-git tag -a "v${TARGET_VERSION}" -m "MindForge v${TARGET_VERSION}
-
-Enterprise Agentic Framework — First Stable Public Release
-
-Commands: 36 | Skills: 10 | Personas: 8 | ADRs: 20 | Test suites: 15
-
-See CHANGELOG.md for full release notes.
-Install: npx mindforge-cc@latest"
-```
-
-### Stage 6 — npm publish
-```bash
-# Dry run first — verify what will be published
-npm publish --dry-run --access public 2>&1 | head -50
-
-# Actual publish
-npm publish --access public
-
-# Verify publication
-sleep 10
-PUBLISHED=$(npm info mindforge-cc@${TARGET_VERSION} version 2>/dev/null)
-[ "${PUBLISHED}" = "${TARGET_VERSION}" ] || { echo "❌ Publish verification failed"; exit 1; }
-echo "✅ Published: mindforge-cc@${TARGET_VERSION}"
-```
-
-### Stage 7 — GitHub release
-```bash
-gh release create "v${TARGET_VERSION}" \
-  --title "MindForge v${TARGET_VERSION} — Enterprise Agentic Framework" \
-  --notes-file CHANGELOG.md \
-  --verify-tag
-```
-
-### Stage 8 — Post-release verification
-```bash
-# Test fresh install from published package
-TEMP_DIR=$(mktemp -d) && cd "${TEMP_DIR}"
-npx mindforge-cc@${TARGET_VERSION} --version
-[ "$?" = "0" ] || { echo "❌ Published package fails --version"; exit 1; }
-echo "✅ Published package verified"
-cd - && rm -rf "${TEMP_DIR}"
-```
-
-## --dry-run flag
-Runs all stages except Stage 6 (npm publish) and Stage 7 (GitHub release).
-Shows what would be published without publishing.
-
-## AUDIT entry (written after successful release)
-```json
-{
-  "event": "framework_released",
-  "version": "1.0.0",
-  "checklist_verified": true,
-  "test_runs": 3,
-  "security_scan": "clean",
-  "npm_url": "https://www.npmjs.com/package/mindforge-cc/v/1.0.0",
-  "github_release": "https://github.com/mindforge-dev/mindforge/releases/tag/v1.0.0"
-}
-```
-```
-
-**Commit:**
-```bash
-for cmd in update migrate plugins tokens release; do
-  cp .claude/commands/mindforge/${cmd}.md .agent/mindforge/${cmd}.md
-done
-git add .claude/commands/mindforge/ .agent/mindforge/
-git commit -m "feat(commands): add update, migrate, plugins, tokens, release — all 36 commands complete"
-```
-
----
-
-## TASK 9 — Write the complete reference documentation
-
-### `docs/reference/commands.md` (excerpt — complete the full 36-command table)
-
-```markdown
-# MindForge v1.0.0 — Complete Commands Reference
-
-## All 36 commands
-
-### Lifecycle commands (core workflow)
-| Command | Usage | Description | Added |
-|---|---|---|---|
-| `/mindforge:init-project` | `init-project` | Guided project setup — creates all .planning/ files | Day 1 |
-| `/mindforge:discuss-phase` | `discuss-phase [N] [--batch\|--auto]` | Pre-planning interview to capture implementation decisions | Day 3 |
-| `/mindforge:plan-phase` | `plan-phase [N]` | Research, decompose, and create atomic task plans | Day 1 |
-| `/mindforge:execute-phase` | `execute-phase [N]` | Wave-based parallel execution of all phase plans | Day 1+2 |
-| `/mindforge:verify-phase` | `verify-phase [N]` | Automated + human acceptance testing pipeline | Day 1 |
-| `/mindforge:ship` | `ship [N]` | Create PR, write release notes, push to remote | Day 1 |
-| `/mindforge:next` | `next` | Auto-detect and execute the correct next workflow step | Day 2 |
-
-[... 29 more commands documented in same format ...]
-
-## Command interface contract (v1.0.0 stable)
-
-As of v1.0.0, the following are part of the stable interface:
-- All 36 command names (new commands require MINOR bump)
-- All flags documented here (new flags require MINOR, removed flags require MAJOR)
-- HANDOFF.json and AUDIT.jsonl schemas (additions: MINOR, removals: MAJOR)
-- All 10 core skill `name:` values and trigger lists
-- SDK exported types and functions
-
-See ADR-020 for the complete stability contract.
-```
-
-### `docs/security/SECURITY.md`
-
-```markdown
-# MindForge — Security Policy
-
-## Supported versions
-
-| Version | Security support |
-|---|---|
-| 1.x.x | ✅ Active — patches released for all severity levels |
-| 0.6.x | ⚠️  Limited — critical fixes only, 90 days from v1.0.0 release |
-| < 0.6.0 | ❌ No support |
-
-## Reporting a vulnerability
-
-**Email:** security@mindforge.dev
-
-**Required information:**
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact assessment
-- Your name / handle (for acknowledgement, if desired)
-
-**Response timeline:**
-- Acknowledgement: within 24 hours
-- Initial assessment: within 7 days
-- Fix released: within 30 days for HIGH/CRITICAL, 90 days for MEDIUM/LOW
-- Coordinated disclosure: 90 days from initial report
-
-**We commit to:**
-- Not taking legal action against good-faith security researchers
-- Crediting researchers in the security advisory (with their permission)
-- Maintaining confidentiality until a fix is released
-
-## Known security model limitations
-
-See `docs/security/threat-model.md` for the full threat model.
-
-Key acknowledged limitations:
-1. Plugin permission model is advisory (not OS-enforced) — see TA7 in threat model
-2. The SSE event stream is localhost-only but any local process can connect — see TA6
-3. Approver identity uses `git config user.email` which is user-controlled — see TA5
-4. Agent instruction injection via SKILL.md requires review beyond pattern matching — see TA1
-
-These are known trade-offs, not bugs. They are documented in ADR-020.
-```
-
-### `docs/security/threat-model.md`
-
-```markdown
-# MindForge v1.0.0 — Threat Model
-
-## Scope
-All attack surfaces introduced by MindForge across 7 days of development.
-Last reviewed: v1.0.0 release (March 2026).
-
-## Assets being protected
-
-| Asset | Classification | Location |
-|---|---|---|
-| API credentials | CRITICAL | Environment variables only (never in files) |
-| HANDOFF.json | HIGH — project state, agent notes, decisions | `.planning/HANDOFF.json` |
-| AUDIT.jsonl | HIGH — complete governance audit trail | `.planning/AUDIT.jsonl` |
-| Approval files | HIGH — governance records | `.planning/approvals/*.json` |
-| SECURITY.md | MEDIUM — security policy documentation | `.mindforge/org/SECURITY.md` |
-| CLAUDE.md | MEDIUM — agent instructions that shape behaviour | `.claude/CLAUDE.md` |
-| CONVENTIONS.md | LOW — coding standards | `.mindforge/org/CONVENTIONS.md` |
-
-## Threat Actor 1 — Malicious skill package author
-
-**Goal:** Inject adversarial instructions via a published `mindforge-skill-*` npm package.
-**Attack:** SKILL.md contains "IGNORE ALL PREVIOUS INSTRUCTIONS" or similar.
-**Controls:**
-- Injection guard in `loader.md` blocks known patterns at both install and load time
-- Level 1/2/3 skill validation at install time
-- TOCTOU-safe download (chmod 700 temp dir, tarball size check)
-- User must explicitly run `/mindforge:install-skill` — no auto-install
-
-**Residual risk:** MEDIUM — sophisticated injections that avoid simple string matching.
-**Mitigation:** Community review of public registry skills; organisation vetting of org-tier skills.
-
----
-
-## Threat Actor 2 — MINDFORGE.md governance bypass
-
-**Goal:** Disable governance primitives via MINDFORGE.md settings.
-**Attack:** Set `SECRET_DETECTION=false`, `SECURITY_AUTOTRIGGER=false`.
-**Controls:**
-- Non-overridable rules enforced in CLAUDE.md session start protocol
-- MINDFORGE-SCHEMA.json marks these fields as `nonOverridable: true`
-- `bin/validate-config.js` warns on attempts to override these fields
-
-**Residual risk:** LOW — enforced at the agent instruction layer, not OS level.
-**Note:** An agent that ignores its CLAUDE.md is an agent that ignores everything.
-
----
-
-## Threat Actor 3 — Accidental credential exposure in project files
-
-**Goal:** Not adversarial — developer accidentally commits a credential.
-**Attack vectors:**
-- Token pasted into HANDOFF.json
-- API key in MINDFORGE.md ADDITIONAL_AGENT_INSTRUCTIONS
-- Secret in AUDIT.jsonl via an error message
-
-**Controls:**
-- Gate 3 (secret detection) blocks ANY commit with credential patterns
-- `_warning` field in every HANDOFF.json schema reminding devs not to store secrets
-- Health engine (Category 7) scans .planning/ and root files for credential patterns
-- installer-core.js skips .env and *.key files during copyDir
-
-**Residual risk:** LOW — multiple detection layers with complementary coverage.
-
----
-
-## Threat Actor 4 — TOCTOU attack on skill installation
-
-**Goal:** Replace a valid SKILL.md with malicious content in the window between download and validation.
-**Attack:** Race condition in temp directory.
-**Controls:**
-- `chmod 700` on temp directory (user-only access, blocks other OS users)
-- Tarball size check (detects empty/corrupted downloads)
-- Download → validate → install is a single-process, single-threaded operation
-
-**Residual risk:** VERY LOW — requires local machine compromise and precise timing.
-
----
-
-## Threat Actor 5 — Compromised CI environment
-
-**Goal:** Bypass governance gates in CI to ship malicious code.
-**Attack:** Modify GitHub Actions workflow or CI runner environment to skip MindForge checks.
-**Controls:**
-- Gates run as separate CI jobs with explicit dependencies
-- Tier 3 changes always fail CI (cannot be configured away)
-- AUDIT.jsonl writes all gate results — tampering would require audit log manipulation
-- Branch protection rules on the repository (outside MindForge scope)
-
-**Residual risk:** HIGH — an attacker with write access to the workflow file or CI secrets
-can bypass. This is a threat to all CI systems, not MindForge specifically.
-**Mitigation:** Protect the `main` branch with required status checks.
-
----
-
-## Threat Actor 6 — SSE event stream eavesdropping
-
-**Goal:** Read sensitive project state from the real-time event stream.
-**Attack:** Connect to port 7337 from another local process.
-**Controls:**
-- localhost-only binding (127.0.0.1) — not accessible from network
-- IP address check on every connection — non-localhost rejected with 403
-- CORS exact-origin matching (not wildcard)
-- Port only opens when the SDK's `MindForgeEventStream.start()` is explicitly called
-
-**Residual risk:** LOW — any process running as the same OS user can connect to localhost.
-**Mitigation:** The SSE stream exposes AUDIT entries, not credentials. Risk is information disclosure, not code execution.
-
----
-
-## Threat Actor 7 — Plugin with elevated or undeclared permissions
-
-**Goal:** Use a MindForge plugin to exfiltrate project state or modify governance.
-**Attack:** Install a plugin that reads HANDOFF.json and sends it to an external server.
-**Controls:**
-- Permission model displayed to user at install time (requires explicit approval)
-- Injection guard run against all plugin .md files
-- All plugin-triggered actions logged with plugin name as agent in AUDIT.jsonl
-- `ELEVATED_PLUGINS` allowlist required for `write_state: true` permission
-
-**Residual risk:** MEDIUM — a user who installs a malicious plugin and approves its permissions.
-**Mitigation:** Only install plugins from sources you trust. Review plugin commands before installing.
-Treat MindForge plugins like VSCode extensions — they have significant project access.
-
----
-
-## Controls summary matrix
-
-| Control | Threat Actors Mitigated |
-|---|---|
-| Injection guard (loader.md) | TA1, TA7 |
-| TOCTOU-safe download (chmod 700) | TA1, TA4 |
-| Non-overridable governance primitives | TA2 |
-| Gate 3 secret detection | TA3 |
-| Health engine credential scan | TA3 |
-| CI Tier 3 block | TA5 |
-| SSE localhost-only binding | TA6 |
-| Plugin permission model + AUDIT logging | TA7 |
-
-## Penetration test results
-
-See `docs/security/penetration-test-results.md` for the adversarial review
-conducted as part of the v1.0.0 production readiness process.
-```
-
-### `docs/architecture/decision-records-index.md`
-
-```markdown
-# MindForge — Architecture Decision Records Index
-
-All 20 ADRs in chronological order.
-
-| ADR | Title | Status | Day | Key decision |
-|---|---|---|---|---|
-| ADR-001 | HANDOFF.json for cross-session state | Accepted | Day 2 | HANDOFF.json as the primary cross-session state artifact |
-| ADR-002 | Markdown-based commands | Accepted | Day 1 | Slash commands as Markdown files (not code) |
-| ADR-003 | Keyword-trigger model for skill loading | Accepted | Day 1 | Deterministic keyword matching over AI-decided selection |
-| ADR-004 | Wave parallelism over full parallelism | Accepted | Day 2 | Wave-based (dependency-ordered) over unconstrained parallel |
-| ADR-005 | Append-only JSONL for audit log | Accepted | Day 2 | AUDIT.jsonl append-only (never update, never delete) |
-| ADR-006 | Three-tier skills architecture | Accepted | Day 3 | Core → Org → Project tier hierarchy |
-| ADR-007 | Keyword-trigger model (reaffirmed at Day 3 scale) | Accepted | Day 3 | Confirmed at 10+ skill scale |
-| ADR-008 | Just-in-time skill loading | Accepted | Day 3 | Load at task time, not session start |
-| ADR-009 | Environment-variable-only credential storage | Accepted | Day 4 | Credentials only in env vars, never in config files |
-| ADR-010 | Compliance gates non-bypassable; approvals allow emergency | Accepted | Day 4 | Gates: never bypass. Approvals: emergency override with audit |
-| ADR-011 | Integration failures are non-blocking | Accepted | Day 4 | Jira/Slack/GitHub down ≠ phase blocked |
-| ADR-012 | Intelligence outputs feed back into system behaviour | Accepted | Day 5 | Difficulty → granularity, retro → MINDFORGE.md, quality → behaviour |
-| ADR-013 | MINDFORGE.md as constitution with non-overridable primitives | Accepted | Day 5 | Non-overridable governance primitives cannot be disabled |
-| ADR-014 | Metrics are system signals, not developer performance | Accepted | Day 5 | Quality scores improve the system, not evaluate individuals |
-| ADR-015 | npm as the public skills registry | Accepted | Day 6 | npm ecosystem for skill distribution |
-| ADR-016 | CI timeout exits with code 0 (soft stop) | Accepted | Day 6 | Timeout = save and resume, not failure |
-| ADR-017 | SDK event stream is localhost-only | Accepted | Day 6 | SSE binds to 127.0.0.1 only |
-| ADR-018 | Installer detects and handles self-install | Accepted | Day 7 | Installer running inside its own repo = no-op for framework files |
-| ADR-019 | Self-update preserves original install scope | Accepted | Day 7 | Update local→local, global→global |
-| ADR-020 | v1.0.0 stable interface contract | Accepted | Day 7 | Defines what "stable" means for plugins and SDK consumers |
-```
-
-**Commit:**
-```bash
-git add docs/
-git commit -m "docs: complete reference documentation, threat model, ADR index, security policy for v1.0.0"
-```
-
----
-
-## TASK 10 — Write Day 7 test suites
-
-### `tests/production.test.js`
-
-```javascript
-/**
- * MindForge Day 7 — Production Readiness Tests
- * Verifies the installer, updater, migration engine, plugin system,
- * token optimiser, and all 36 commands exist.
- *
- * Run: node tests/production.test.js
- */
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const assert = require('assert');
-let passed = 0, failed = 0;
-
-function test(name, fn) {
-  try { fn(); console.log(`  ✅  ${name}`); passed++; }
-  catch(e) { console.error(`  ❌  ${name}\n      ${e.message}`); failed++; }
-}
-
-const read   = p  => fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
-const exists = p  => fs.existsSync(p);
-
-// ── Installer completeness ─────────────────────────────────────────────────────
-console.log('\nMindForge Day 7 — Production Readiness Tests\n');
-console.log('Installer:');
-
-test('bin/install.js exists with shebang', () => {
-  const c = read('bin/install.js');
-  assert.ok(c.includes('#!/usr/bin/env node'), 'Missing shebang');
-  assert.ok(c.length > 500, 'install.js seems too short');
-});
-
-test('bin/installer-core.js exists and exports run()', () => {
-  const c = read('bin/installer-core.js');
-  assert.ok(c.includes('module.exports'), 'Missing module.exports');
-  assert.ok(c.includes('async function run') || c.includes('function run'), 'Missing run function');
-});
-
-test('installer handles --version flag correctly', () => {
-  const c = read('bin/install.js');
-  assert.ok(c.includes("'--version'") || c.includes('"--version"'), 'Missing --version');
-  assert.ok(c.includes('process.exit(0)'), 'Should exit 0 for --version');
-});
-
-test('installer has Node.js version gate (≥ 18)', () => {
-  const combined = read('bin/install.js') + read('bin/installer-core.js');
-  assert.ok(combined.includes('18'), 'Should check for Node.js 18');
-  assert.ok(combined.includes('process.exit(1)') || combined.includes('exit(1)'), 'Should exit 1 for old node');
-});
-
-test('installer has CI mode detection', () => {
-  const c = read('bin/install.js');
-  assert.ok(c.includes("process.env.CI"), 'Should detect CI environment');
-  assert.ok(c.includes('IS_NON_INTERACTIVE'), 'Should have non-interactive flag');
-});
-
-test('installer backs up existing CLAUDE.md', () => {
-  const c = read('bin/installer-core.js');
-  assert.ok(c.includes('backup') || c.includes('.backup-'), 'Should back up CLAUDE.md');
-});
-
-test('installer has self-install detection', () => {
-  const c = read('bin/installer-core.js');
-  assert.ok(
-    c.includes('isSelfInstall') || c.includes("'mindforge-cc'"),
-    'Should detect self-install scenario'
-  );
-});
-
-test('installer excludes sensitive files (*.env, *.key, *.pem)', () => {
-  const c = read('bin/installer-core.js');
-  assert.ok(
-    c.includes('.env') || c.includes('SENSITIVE_EXCLUDE') || c.includes('.key'),
-    'Should have sensitive file exclusion list'
-  );
-});
-
-test('installer verifies install after completing', () => {
-  const c = read('bin/installer-core.js');
-  assert.ok(
-    c.includes('verifyInstall') || c.includes('verification'),
-    'Should verify install after completing'
-  );
-});
-
-// ── Self-update system ─────────────────────────────────────────────────────────
-console.log('\nSelf-update system:');
-
-['version-comparator.js', 'changelog-fetcher.js', 'self-update.js'].forEach(f => {
-  test(`bin/updater/${f} exists`, () => {
-    assert.ok(exists(`bin/updater/${f}`), `Missing: bin/updater/${f}`);
-  });
-});
-
-test('compareSemver: 1.0.0 > 0.6.0', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  assert.ok(compareSemver('1.0.0', '0.6.0') > 0);
-});
-
-test('compareSemver: 0.6.0 < 1.0.0', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  assert.ok(compareSemver('0.6.0', '1.0.0') < 0);
-});
-
-test('compareSemver: 1.0.0 == 1.0.0', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  assert.strictEqual(compareSemver('1.0.0', '1.0.0'), 0);
-});
-
-test('compareSemver handles v prefix', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  assert.ok(compareSemver('v1.0.0', 'v0.6.0') > 0);
-});
-
-test('upgradeType: 0.6.0 → 1.0.0 is major', () => {
-  const { upgradeType } = require('../bin/updater/version-comparator');
-  assert.strictEqual(upgradeType('0.6.0', '1.0.0'), 'major');
-});
-
-test('upgradeType: 1.0.0 → 1.1.0 is minor', () => {
-  const { upgradeType } = require('../bin/updater/version-comparator');
-  assert.strictEqual(upgradeType('1.0.0', '1.1.0'), 'minor');
-});
-
-test('upgradeType: 1.0.0 → 1.0.1 is patch', () => {
-  const { upgradeType } = require('../bin/updater/version-comparator');
-  assert.strictEqual(upgradeType('1.0.0', '1.0.1'), 'patch');
-});
-
-test('upgradeType: 1.0.0 → 1.0.0 is none', () => {
-  const { upgradeType } = require('../bin/updater/version-comparator');
-  assert.strictEqual(upgradeType('1.0.0', '1.0.0'), 'none');
-});
-
-test('self-update has scope detection', () => {
-  const c = read('bin/updater/self-update.js');
-  assert.ok(c.includes('detectInstallScope'), 'Should have detectInstallScope()');
-});
-
-test('self-update reads schema_version before applying update', () => {
-  const c = read('bin/updater/self-update.js');
-  assert.ok(
-    c.includes('readHandoffSchemaVersion') || c.includes('schema_version'),
-    'Should read schema_version from HANDOFF before updating'
-  );
-});
-
-// ── Migration engine ────────────────────────────────────────────────────────────
-console.log('\nMigration engine:');
-
-['migrate.js', 'schema-versions.js', '0.1.0-to-0.5.0.js', '0.5.0-to-0.6.0.js', '0.6.0-to-1.0.0.js'].forEach(f => {
-  test(`bin/migrations/${f} exists`, () => {
-    assert.ok(exists(`bin/migrations/${f}`), `Missing: ${f}`);
-  });
-});
-
-test('migrate.js creates backup before migrating', () => {
-  const c = read('bin/migrations/migrate.js');
-  assert.ok(c.includes('backup') || c.includes('Backup'), 'Should create backup');
-});
-
-test('migrate.js aborts if backup fails', () => {
-  const c = read('bin/migrations/migrate.js');
-  assert.ok(
-    c.includes('backupErr') || c.includes('Migration aborted'),
-    'Should abort if backup creation fails'
-  );
-});
-
-test('migrate.js restores from backup on migration failure', () => {
-  const c = read('bin/migrations/migrate.js');
-  assert.ok(
-    c.includes('Restoring') || c.includes('restoreFromBackup') || c.includes('restore'),
-    'Should restore from backup on failure'
-  );
-});
-
-test('0.6.0-to-1.0.0 migration adds plugin_api_version', () => {
-  const c = read('bin/migrations/0.6.0-to-1.0.0.js');
-  assert.ok(c.includes('plugin_api_version'), 'Should add plugin_api_version field');
-});
-
-test('0.6.0-to-1.0.0 migration backfills session_id in AUDIT.jsonl', () => {
-  const c = read('bin/migrations/0.6.0-to-1.0.0.js');
-  assert.ok(c.includes('session_id'), 'Should backfill session_id');
-});
-
-test('0.6.0-to-1.0.0 migration converts VERIFY_PASS_RATE_WARNING_THRESHOLD', () => {
-  const c = read('bin/migrations/0.6.0-to-1.0.0.js');
-  assert.ok(
-    c.includes('VERIFY_PASS_RATE') || c.includes('val / 100'),
-    'Should convert percentage to decimal'
-  );
-});
-
-test('migration preserves invalid AUDIT.jsonl lines (no crash)', () => {
-  const c = read('bin/migrations/0.6.0-to-1.0.0.js');
-  assert.ok(c.includes('catch') || c.includes('try'), 'Should handle parse errors gracefully');
-});
-
-// ── Plugin system ────────────────────────────────────────────────────────────────
-console.log('\nPlugin system:');
-
-['plugin-schema.md', 'plugin-loader.md', 'PLUGINS-MANIFEST.md'].forEach(f => {
-  test(`.mindforge/plugins/${f} exists`, () => {
-    assert.ok(exists(`.mindforge/plugins/${f}`));
-  });
-});
-
-test('plugin schema defines permission model', () => {
-  const c = read('.mindforge/plugins/plugin-schema.md');
-  assert.ok(c.includes('permissions'), 'Should define permissions');
-  assert.ok(c.includes('write_state'), 'Should include write_state permission');
-  assert.ok(c.includes('network_access'), 'Should include network_access permission');
-});
-
-test('plugin loader has injection guard step', () => {
-  const c = read('.mindforge/plugins/plugin-loader.md');
-  assert.ok(c.includes('injection guard') || c.includes('Injection'), 'Should run injection guard');
-});
-
-test('plugin loader documents advisory permission model', () => {
-  const c = read('.mindforge/plugins/plugin-loader.md');
-  assert.ok(
-    c.includes('advisory') || c.includes('not OS-enforced') || c.includes('not enforced'),
-    'Should explain that permissions are advisory'
-  );
-});
-
-test('plugin schema lists all 36 reserved command names', () => {
-  const c = read('.mindforge/plugins/plugin-schema.md');
-  assert.ok(
-    c.includes('Reserved command names') || c.includes('reserved'),
-    'Should list reserved command names'
-  );
-  // Check a few specific reserved names are mentioned
-  assert.ok(c.includes('health'), 'Should list health as reserved');
-  assert.ok(c.includes('security-scan'), 'Should list security-scan as reserved');
-});
-
-// ── Token optimiser ─────────────────────────────────────────────────────────────
-console.log('\nToken optimiser:');
-
-test('token-optimiser.md exists', () => {
-  assert.ok(exists('.mindforge/production/token-optimiser.md'));
-});
-
-test('token optimiser defines efficiency formula', () => {
-  const c = read('.mindforge/production/token-optimiser.md');
-  assert.ok(c.includes('token_efficiency') || c.includes('efficiency'), 'Should define efficiency');
-  assert.ok(c.includes('useful_output') || c.includes('output_tokens'), 'Should define useful output');
-});
-
-test('token optimiser has lean plan strategy', () => {
-  const c = read('.mindforge/production/token-optimiser.md');
-  assert.ok(c.includes('Strategy 1') || c.includes('Lean'), 'Should have lean plan strategy');
-});
-
-// ── Production checklist ────────────────────────────────────────────────────────
-console.log('\nProduction checklist:');
-
-test('production-checklist.md has exactly 50 checkbox items', () => {
-  const c = read('.mindforge/production/production-checklist.md');
-  const boxes = (c.match(/- \[ \]/g) || []).length;
-  assert.ok(boxes >= 50, `Expected >= 50 items, found ${boxes}`);
-});
-
-// ── Documentation completeness ──────────────────────────────────────────────────
-console.log('\nDocumentation:');
-
-const DOC_FILES = [
-  'docs/reference/commands.md',
-  'docs/security/SECURITY.md',
-  'docs/security/threat-model.md',
-  'docs/architecture/decision-records-index.md',
-  'docs/contributing/CONTRIBUTING.md',
-];
-DOC_FILES.forEach(f => test(`${f} exists`, () => assert.ok(exists(f), `Missing: ${f}`)));
-
-test('threat model covers all 7 threat actors', () => {
-  const c = read('docs/security/threat-model.md');
-  for (let i = 1; i <= 7; i++) {
-    assert.ok(c.includes(`Threat Actor ${i}`), `Missing Threat Actor ${i}`);
-  }
-});
-
-test('ADR index lists all 20 ADRs', () => {
-  const c = read('docs/architecture/decision-records-index.md');
-  for (let i = 1; i <= 20; i++) {
-    const adrRef = `ADR-${String(i).padStart(3, '0')}`;
-    assert.ok(c.includes(adrRef) || c.includes(`ADR-${i}`), `Missing ${adrRef} in index`);
-  }
-});
-
-test('SECURITY.md has responsible disclosure policy', () => {
-  const c = read('docs/security/SECURITY.md');
-  assert.ok(c.includes('disclosure') || c.includes('24 hours'), 'Should have disclosure timeline');
-});
-
-// ── All 36 commands ─────────────────────────────────────────────────────────────
-console.log('\nAll 36 commands:');
-
-const ALL_COMMANDS = [
-  // Day 1
-  'help', 'init-project', 'plan-phase', 'execute-phase', 'verify-phase', 'ship',
-  // Day 2
-  'next', 'quick', 'status', 'debug',
-  // Day 3
-  'skills', 'review', 'security-scan', 'map-codebase', 'discuss-phase',
-  // Day 4
-  'audit', 'milestone', 'complete-milestone', 'approve', 'sync-jira', 'sync-confluence',
-  // Day 5
-  'health', 'retrospective', 'profile-team', 'metrics',
-  // Day 6
-  'init-org', 'install-skill', 'publish-skill', 'pr-review', 'workspace', 'benchmark',
-  // Day 7
-  'update', 'migrate', 'plugins', 'tokens', 'release',
-];
-
-assert.strictEqual(ALL_COMMANDS.length, 36, `Expected 36 commands, have ${ALL_COMMANDS.length}`);
-console.log(`  (verifying all ${ALL_COMMANDS.length} commands)`);
-
-test('all 36 commands in .claude/commands/mindforge/', () => {
-  const missing = ALL_COMMANDS.filter(cmd => !exists(`.claude/commands/mindforge/${cmd}.md`));
-  assert.strictEqual(missing.length, 0, `Missing: ${missing.join(', ')}`);
-});
-
-test('all 36 commands mirrored to .agent/mindforge/', () => {
-  const missing = ALL_COMMANDS.filter(cmd => !exists(`.agent/mindforge/${cmd}.md`));
-  assert.strictEqual(missing.length, 0, `Missing agent mirror: ${missing.join(', ')}`);
-});
-
-test('no command file is empty (> 100 chars)', () => {
-  const tiny = ALL_COMMANDS.filter(cmd => {
-    const p = `.claude/commands/mindforge/${cmd}.md`;
-    return exists(p) && fs.statSync(p).size < 100;
-  });
-  assert.strictEqual(tiny.length, 0, `Too small: ${tiny.join(', ')}`);
-});
-
-// ── Final version check ────────────────────────────────────────────────────────
-console.log('\nVersion:');
-
-test('package.json version is 1.0.0', () => {
-  const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-  assert.strictEqual(pkg.version, '1.0.0', `Expected 1.0.0, got ${pkg.version}`);
-});
-
-test('CHANGELOG.md has v1.0.0 entry', () => {
-  const c = read('CHANGELOG.md');
-  assert.ok(c.includes('1.0.0'), 'CHANGELOG.md should have 1.0.0 entry');
-});
-
-test('all 20 ADR files present in .planning/decisions/', () => {
-  if (!exists('.planning/decisions/')) return; // Skip if no decisions dir yet
-  const adrs = fs.readdirSync('.planning/decisions/').filter(f => f.startsWith('ADR-') && f.endsWith('.md'));
-  assert.ok(adrs.length >= 20, `Expected >= 20 ADRs, found ${adrs.length}`);
-});
-
-// ── Results ─────────────────────────────────────────────────────────────────────
-console.log(`\n${'─'.repeat(55)}`);
-console.log(`Results: ${passed} passed, ${failed} failed`);
-if (failed > 0) {
-  console.error(`\n❌  ${failed} test(s) failed — not production ready.\n`);
-  process.exit(1);
-} else {
-  console.log(`\n✅  All production readiness tests passed.\n`);
-}
-```
-
-### `tests/migration.test.js`
-
-```javascript
-/**
- * MindForge Day 7 — Migration Engine Tests
- * Tests the migration logic without touching real .planning/ files.
- *
- * Run: node tests/migration.test.js
- */
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-const assert = require('assert');
-let passed = 0, failed = 0;
-
-function test(name, fn) {
-  try { fn(); console.log(`  ✅  ${name}`); passed++; }
-  catch(e) { console.error(`  ❌  ${name}\n      ${e.message}`); failed++; }
-}
-
-// ── Simulation helpers ─────────────────────────────────────────────────────────
-
-function simulateHandoffMigration(handoff, toVersion) {
-  const result = JSON.parse(JSON.stringify(handoff));
-  if (toVersion === '0.5.0' || toVersion === '1.0.0') {
-    if (!Array.isArray(result.decisions_made))     result.decisions_made     = [];
-    if (!Array.isArray(result.discoveries))        result.discoveries        = [];
-    if (!Array.isArray(result.implicit_knowledge)) result.implicit_knowledge = [];
-    if (!Array.isArray(result.quality_signals))    result.quality_signals    = [];
-  }
-  if (toVersion === '0.6.0' || toVersion === '1.0.0') {
-    if (!result.developer_id)                         result.developer_id   = null;
-    if (!result.session_id)                           result.session_id     = null;
-    if (!Array.isArray(result.recent_commits))        result.recent_commits = [];
-    if (!Array.isArray(result.recent_files))          result.recent_files   = [];
-  }
-  if (toVersion === '1.0.0') {
-    if (!result.plugin_api_version)                   result.plugin_api_version = '1.0.0';
-    result.schema_version = '1.0.0';
-  }
-  return result;
-}
-
-function simulateAuditMigration(lines) {
-  return lines.map(line => {
-    try {
-      const entry = JSON.parse(line);
-      if (!entry.session_id) {
-        return JSON.stringify({ ...entry, session_id: 'migrated-from-pre-1.0' });
-      }
-      return line;
-    } catch {
-      return line; // preserve invalid lines
-    }
-  });
-}
-
-function simulateMindforgeMdMigration(content) {
-  return content.replace(
-    /^(VERIFY_PASS_RATE_WARNING_THRESHOLD=)(\d+(?:\.\d+)?)(\s*)$/m,
-    (match, prefix, val, suffix) => {
-      const num = parseFloat(val);
-      return num > 1
-        ? `${prefix}${(num / 100).toFixed(2)}${suffix}`
-        : match;
-    }
-  );
-}
-
-// ── Tests ──────────────────────────────────────────────────────────────────────
-console.log('\nMindForge Day 7 — Migration Tests\n');
-
-console.log('Version comparator:');
-
-test('compareSemver works for all comparison cases', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  assert.ok(compareSemver('1.0.0', '0.9.9') > 0, '1.0.0 > 0.9.9');
-  assert.ok(compareSemver('0.1.0', '1.0.0') < 0, '0.1.0 < 1.0.0');
-  assert.strictEqual(compareSemver('0.5.0', '0.5.0'), 0, '0.5.0 == 0.5.0');
-  assert.ok(compareSemver('2.0.0', '1.99.99') > 0, 'Major beats all minors');
-});
-
-console.log('\nHANDOFF.json migrations:');
-
-test('v0.1.0 → v0.5.0: adds intelligence layer fields', () => {
-  const h = { schema_version: '0.1.0', next_task: 'test', _warning: 'warn' };
-  const m = simulateHandoffMigration(h, '0.5.0');
-  assert.ok(Array.isArray(m.decisions_made), 'decisions_made should be array');
-  assert.ok(Array.isArray(m.discoveries), 'discoveries should be array');
-  assert.ok(Array.isArray(m.implicit_knowledge), 'implicit_knowledge should be array');
-  assert.ok(Array.isArray(m.quality_signals), 'quality_signals should be array');
-});
-
-test('v0.5.0 → v0.6.0: adds distribution platform fields', () => {
-  const h = { schema_version: '0.5.0', next_task: 'test', _warning: 'warn' };
-  const m = simulateHandoffMigration(h, '0.6.0');
-  assert.ok(Array.isArray(m.recent_commits), 'recent_commits should be array');
-  assert.ok(Array.isArray(m.recent_files), 'recent_files should be array');
-  assert.ok('developer_id' in m, 'developer_id should exist');
-  assert.ok('session_id' in m, 'session_id should exist');
-});
-
-test('v0.6.0 → v1.0.0: adds plugin_api_version', () => {
-  const h = { schema_version: '0.6.0', next_task: 'test', _warning: 'warn' };
-  const m = simulateHandoffMigration(h, '1.0.0');
-  assert.strictEqual(m.plugin_api_version, '1.0.0');
-  assert.strictEqual(m.schema_version, '1.0.0');
-});
-
-test('v0.1.0 → v1.0.0 full chain: all fields present', () => {
-  const h = { schema_version: '0.1.0', next_task: 'first task', _warning: 'warn', phase: 1 };
-  const m = simulateHandoffMigration(h, '1.0.0');
-
-  // All fields from all migrations should be present
-  assert.ok(Array.isArray(m.decisions_made), 'decisions_made from 0.5.0 migration');
-  assert.ok(Array.isArray(m.recent_commits), 'recent_commits from 0.6.0 migration');
-  assert.strictEqual(m.plugin_api_version, '1.0.0', 'plugin_api_version from 1.0.0 migration');
-  assert.strictEqual(m.phase, 1, 'Original field preserved');
-  assert.strictEqual(m.next_task, 'first task', 'Original next_task preserved');
-});
-
-test('migration does not overwrite existing values', () => {
-  const h = {
-    schema_version: '0.1.0',
-    next_task: 'existing task',
-    _warning: 'original warning',
-    phase: 3,
-    plan: '04',
-    custom_org_field: 'preserved',
-  };
-  const m = simulateHandoffMigration(h, '1.0.0');
-  assert.strictEqual(m.next_task, 'existing task');
-  assert.strictEqual(m.phase, 3);
-  assert.strictEqual(m.plan, '04');
-  assert.strictEqual(m.custom_org_field, 'preserved');
-  assert.strictEqual(m._warning, 'original warning');
-});
-
-console.log('\nAUDIT.jsonl migration:');
-
-test('backfills missing session_id in audit entries', () => {
-  const lines = [
-    JSON.stringify({ id: 'uuid-1', timestamp: '2026-01-01T00:00:00Z', event: 'task_started', agent: 'test' }),
-    JSON.stringify({ id: 'uuid-2', timestamp: '2026-01-01T00:01:00Z', event: 'task_completed', agent: 'test', session_id: 'existing' }),
-  ];
-  const migrated = simulateAuditMigration(lines);
-  const first  = JSON.parse(migrated[0]);
-  const second = JSON.parse(migrated[1]);
-  assert.ok(first.session_id, 'Missing session_id should be backfilled');
-  assert.strictEqual(first.session_id, 'migrated-from-pre-1.0');
-  assert.strictEqual(second.session_id, 'existing', 'Existing session_id must not be changed');
-});
-
-test('preserves invalid JSON lines without crashing', () => {
-  const lines = [
-    JSON.stringify({ id: 'uuid-1', event: 'test', timestamp: 't', agent: 'a' }),
-    '{this is not valid JSON}',
-    JSON.stringify({ id: 'uuid-2', event: 'test', timestamp: 't', agent: 'a' }),
-  ];
-  const migrated = simulateAuditMigration(lines);
-  assert.strictEqual(migrated.length, 3, 'All lines preserved');
-  assert.strictEqual(migrated[1], '{this is not valid JSON}', 'Invalid line unchanged');
-});
-
-test('does not double-backfill entries that already have session_id', () => {
-  const original = JSON.stringify({ id: 'uuid', event: 'test', timestamp: 't', agent: 'a', session_id: 'my-session' });
-  const [migrated] = simulateAuditMigration([original]);
-  const entry = JSON.parse(migrated);
-  assert.strictEqual(entry.session_id, 'my-session', 'Should not overwrite existing session_id');
-});
-
-console.log('\nMINDFORGE.md migration:');
-
-test('converts VERIFY_PASS_RATE_WARNING_THRESHOLD from 75 to 0.75', () => {
-  const content = 'VERIFY_PASS_RATE_WARNING_THRESHOLD=75\n';
-  const migrated = simulateMindforgeMdMigration(content);
-  assert.ok(migrated.includes('0.75'), `Expected 0.75, got: ${migrated.trim()}`);
-  assert.ok(!migrated.match(/=75(\s|$)/), 'Should not still contain =75');
-});
-
-test('converts VERIFY_PASS_RATE_WARNING_THRESHOLD from 80 to 0.80', () => {
-  const content = 'VERIFY_PASS_RATE_WARNING_THRESHOLD=80\nOTHER=value\n';
-  const migrated = simulateMindforgeMdMigration(content);
-  assert.ok(migrated.includes('0.80') || migrated.includes('0.8'), `Expected 0.80`);
-  assert.ok(migrated.includes('OTHER=value'), 'Should preserve other settings');
-});
-
-test('does NOT modify values already in decimal format (0.75)', () => {
-  const content = 'VERIFY_PASS_RATE_WARNING_THRESHOLD=0.75\n';
-  const migrated = simulateMindforgeMdMigration(content);
-  assert.ok(migrated.includes('0.75'), 'Should preserve existing decimal format');
-  assert.ok(!migrated.includes('0.0075'), 'Should not double-convert a decimal');
-});
-
-test('does NOT modify value of exactly 1 (ambiguous — preserve)', () => {
-  const content = 'VERIFY_PASS_RATE_WARNING_THRESHOLD=1\n';
-  const migrated = simulateMindforgeMdMigration(content);
-  // Value of 1 should be preserved as-is (it's ≤ 1, within decimal range)
-  assert.ok(migrated.includes('=1'), 'Value of 1 should not be converted');
-  assert.ok(!migrated.includes('=0.01'), 'Value of 1 should not become 0.01');
-});
-
-console.log('\nMigration infrastructure:');
-
-test('all migration files have correct fromVersion/toVersion', () => {
-  const files = [
-    { file: 'bin/migrations/0.1.0-to-0.5.0.js', from: '0.1.0', to: '0.5.0' },
-    { file: 'bin/migrations/0.5.0-to-0.6.0.js', from: '0.5.0', to: '0.6.0' },
-    { file: 'bin/migrations/0.6.0-to-1.0.0.js', from: '0.6.0', to: '1.0.0' },
-  ];
-  files.forEach(({ file, from, to }) => {
-    const c = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-    assert.ok(c.includes(from), `${file}: should contain fromVersion ${from}`);
-    assert.ok(c.includes(to),   `${file}: should contain toVersion ${to}`);
-  });
-});
-
-test('migration chain covers v0.1.0 → v1.0.0 completely', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-
-  // Chain: 0.1.0 → 0.5.0 → 0.6.0 → 1.0.0
-  const chain = ['0.1.0', '0.5.0', '0.6.0', '1.0.0'];
-  for (let i = 0; i < chain.length - 1; i++) {
-    const file = `bin/migrations/${chain[i]}-to-${chain[i+1]}.js`;
-    assert.ok(fs.existsSync(file), `Missing migration: ${file}`);
-  }
-
-  // Verify no gaps: each migration's toVersion = next migration's fromVersion
-  for (let i = 0; i < chain.length - 2; i++) {
-    assert.ok(
-      compareSemver(chain[i + 1], chain[i]) > 0,
-      `Chain gap between ${chain[i]} and ${chain[i+1]}`
-    );
-  }
-});
-
-test('migrate.js exports runMigrations function', () => {
-  const { runMigrations } = require('../bin/migrations/migrate');
-  assert.strictEqual(typeof runMigrations, 'function', 'runMigrations should be a function');
-});
-
-console.log(`\n${'─'.repeat(55)}`);
-console.log(`Results: ${passed} passed, ${failed} failed`);
-if (failed > 0) {
-  console.error(`\n❌  ${failed} test(s) failed.\n`);
-  process.exit(1);
-} else {
-  console.log(`\n✅  All migration tests passed.\n`);
-}
-```
-
-### `tests/e2e.test.js`
-
-```javascript
-/**
- * MindForge Day 7 — End-to-End Simulation Tests
- * Simulates complete project workflows using file system operations.
- * No actual Claude API calls — tests the state machine, not the AI.
- *
- * Run: node tests/e2e.test.js
- */
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-const assert = require('assert');
-let passed = 0, failed = 0;
-
-function test(name, fn) {
-  try { fn(); console.log(`  ✅  ${name}`); passed++; }
-  catch(e) { console.error(`  ❌  ${name}\n      ${e.message}`); failed++; }
-}
-
-// ── Test project factory ───────────────────────────────────────────────────────
-function createTestProject() {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mindforge-e2e-'));
-
-  function write(relPath, content) {
-    const fullPath = path.join(tmpDir, relPath);
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-    fs.writeFileSync(fullPath, content, 'utf8');
-    return fullPath;
-  }
-
-  function read(relPath) {
-    const p = path.join(tmpDir, relPath);
-    return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
-  }
-
-  function exists(relPath) {
-    return fs.existsSync(path.join(tmpDir, relPath));
-  }
-
-  function appendAudit(entry) {
-    const auditPath = path.join(tmpDir, '.planning', 'AUDIT.jsonl');
-    const line = JSON.stringify({
-      id:         `test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
-      timestamp:  new Date().toISOString(),
-      session_id: 'test-session-001',
-      agent:      'mindforge-test',
-      ...entry,
-    });
-    fs.appendFileSync(auditPath, line + '\n');
-  }
-
-  function cleanup() {
-    try { fs.rmSync(tmpDir, { recursive: true, force: true }); }
-    catch(e) { console.warn(`  ⚠️  Cleanup warning: ${e.message} (dir: ${tmpDir})`); }
-  }
-
-  return { tmpDir, write, read, exists, appendAudit, cleanup };
-}
-
-// ── Workflow simulation functions ──────────────────────────────────────────────
-
-function initProject(project) {
-  const { write } = project;
-
-  // Core .planning/ files
-  write('.planning/PROJECT.md', `# E2E Test Project
-
-## Tech stack
-- Node.js 20 LTS
-- TypeScript 5.x
-- PostgreSQL via Prisma
-
-## v1 scope — IN
-- [x] User authentication (email/password)
-- [x] User profile management
-
-## Success criteria
-All acceptance tests passing. Zero HIGH security findings.
-`);
-
-  write('.planning/REQUIREMENTS.md', `# Requirements
-
-## Functional requirements
-| ID | Requirement | Acceptance criterion | Scope |
-|---|---|---|---|
-| FR-01 | User login | POST /auth/login returns JWT for valid credentials | v1 |
-| FR-02 | User logout | POST /auth/logout invalidates session | v1 |
-| FR-03 | Profile fetch | GET /users/:id returns profile for authenticated user | v1 |
-`);
-
-  write('.planning/ARCHITECTURE.md', `# Architecture
-
-## Architectural pattern
-Modular monolith — Express API with Prisma ORM
-
-## Technology stack
-- Runtime: Node.js 20
-- Framework: Express 4.x
-- Database: PostgreSQL 15
-
-## Data model
-**User**: id (UUID), email, passwordHash, createdAt, updatedAt
-`);
-
-  write('.planning/STATE.md', `# Project State
-
-## Status
-Phase 1 in progress
-
-## Current phase
-Phase 1 — Authentication
-
-## Next action
-Execute Phase 1 plans
-`);
-
-  write('.planning/HANDOFF.json', JSON.stringify({
-    schema_version: '1.0.0',
-    plugin_api_version: '1.0.0',
-    project: 'E2E Test Project',
-    phase: 1,
-    plan: null,
-    next_task: 'Execute Phase 1 — Authentication',
-    blockers: [],
-    decisions_needed: [],
-    decisions_made: [],
-    discoveries: [],
-    implicit_knowledge: [],
-    quality_signals: [],
-    context_refs: ['.planning/PROJECT.md', '.planning/STATE.md'],
-    recent_commits: [],
-    recent_files: [],
-    session_id: 'test-session-001',
-    _warning: 'Never store secrets, tokens, or passwords in this file.',
-    updated_at: new Date().toISOString(),
-  }, null, 2));
-
-  write('.planning/AUDIT.jsonl', '');
-  project.appendAudit({ event: 'project_initialised', phase: null });
-}
-
-function planPhase(project, phaseNum) {
-  const { write, appendAudit } = project;
-  const phaseDir = `.planning/phases/${phaseNum}`;
-
-  // Difficulty score
-  write(`${phaseDir}/DIFFICULTY-SCORE-${phaseNum}.md`, `# Difficulty Score — Phase ${phaseNum}
-## Scores
-| Dimension | Score |
-|---|---|
-| Technical | 4/5 |
-| Risk | 5/5 |
-| Ambiguity | 2/5 |
-| Dependencies | 2/5 |
-## Composite: 3.75 — Challenging
-## Recommendations: 6 atomic tasks
-`);
-
-  // Plan file with valid XML
-  write(`${phaseDir}/PLAN-${phaseNum}-01.md`, `<task type="auto">
-  <n>Implement login endpoint with JWT</n>
-  <persona>developer</persona>
-  <phase>${phaseNum}</phase>
-  <plan>01</plan>
-  <dependencies>none</dependencies>
-  <files>
-    src/auth/login.ts
-    src/auth/login.test.ts
-  </files>
-  <context>
-    Skills: security-review (jwt.sign trigger), api-design, testing-standards
-  </context>
-  <action>
-    Create POST /auth/login endpoint. Validate email/password against database.
-    Use argon2 for password verification. Return signed JWT on success.
-    Return 401 for invalid credentials (no information disclosure).
-  </action>
-  <verify>npm test -- --testPathPattern=auth.login</verify>
-  <done>All login tests passing, argon2 verification working, JWT returned</done>
-</task>`);
-
-  write(`${phaseDir}/PLAN-${phaseNum}-02.md`, `<task type="auto">
-  <n>Implement logout endpoint with session invalidation</n>
-  <persona>developer</persona>
-  <phase>${phaseNum}</phase>
-  <plan>02</plan>
-  <dependencies>01</dependencies>
-  <files>
-    src/auth/logout.ts
-    src/auth/logout.test.ts
-  </files>
-  <context>
-    Skills: security-review, testing-standards
-  </context>
-  <action>
-    Create POST /auth/logout endpoint. Invalidate JWT via blocklist in Redis.
-    Verify that blocklisted tokens return 401 on subsequent requests.
-  </action>
-  <verify>npm test -- --testPathPattern=auth.logout</verify>
-  <done>Logout invalidates tokens, blocklisted tokens rejected</done>
-</task>`);
-
-  // Dependency graph
-  write(`${phaseDir}/DEPENDENCY-GRAPH-${phaseNum}.md`, `# Dependency Graph — Phase ${phaseNum}
-
-## Wave 1 (independent)
-- Plan 01: Implement login endpoint
-
-## Wave 2 (depends on Wave 1)
-- Plan 02: Implement logout endpoint (requires login implementation)
-`);
-
-  appendAudit({ event: 'phase_planned', phase: phaseNum, plans_created: 2, waves: 2 });
-}
-
-function executeTask(project, phaseNum, planId, commitSha) {
-  const { write, appendAudit } = project;
-  const phaseDir = `.planning/phases/${phaseNum}`;
-
-  appendAudit({ event: 'task_started', phase: phaseNum, plan: planId });
-
-  write(`${phaseDir}/SUMMARY-${phaseNum}-${planId}.md`, `# Summary — Phase ${phaseNum}, Plan ${planId}
-## Status: Completed ✅
-## Commit: ${commitSha}
-## Verify result: PASS
-## Files modified:
-- src/auth/${planId === '01' ? 'login' : 'logout'}.ts (created)
-- src/auth/${planId === '01' ? 'login' : 'logout'}.test.ts (created, 8 tests)
-`);
-
-  appendAudit({ event: 'task_completed', phase: phaseNum, plan: planId, commit_sha: commitSha, verify_result: 'pass' });
-}
-
-function runSecurityScan(project, phaseNum, findings = []) {
-  const { write, appendAudit } = project;
-  const phaseDir = `.planning/phases/${phaseNum}`;
-
-  const criticalCount = findings.filter(f => f.severity === 'CRITICAL').length;
-  const highCount     = findings.filter(f => f.severity === 'HIGH').length;
-
-  write(`${phaseDir}/SECURITY-REVIEW-${phaseNum}.md`, `# Security Review — Phase ${phaseNum}
-## Scan date: ${new Date().toISOString()}
-## OWASP A01: ${findings.length === 0 ? 'PASS ✅' : 'FINDINGS'}
-
-${findings.map(f => `### ${f.severity}: ${f.description}\nFile: ${f.file}:${f.line}\nRemediation: ${f.remediation}`).join('\n\n')}
-
-## Summary
-- CRITICAL: ${criticalCount}
-- HIGH: ${highCount}
-- Total: ${findings.length}
-${findings.length === 0 ? '## Verdict: CLEAN ✅' : `## Verdict: ${criticalCount > 0 ? '🔴 BLOCKED' : '⚠️  REVIEW REQUIRED'}`}
-`);
-
-  appendAudit({ event: 'security_scan_completed', phase: phaseNum, critical: criticalCount, high: highCount });
-}
-
-function verifyPhase(project, phaseNum) {
-  const { write, appendAudit } = project;
-  const phaseDir = `.planning/phases/${phaseNum}`;
-
-  write(`${phaseDir}/GATE-RESULTS-${phaseNum}.md`, `# Compliance Gate Results — Phase ${phaseNum}
-## Run at: ${new Date().toISOString()}
-| Gate | Status | Detail |
-|---|---|---|
-| Secret detection | ✅ PASS | 0 patterns found |
-| CRITICAL security findings | ✅ PASS | No open CRITICAL findings |
-| Test suite | ✅ PASS | 16 tests passing |
-| Dependency CVEs | ✅ PASS | 0 HIGH/CRITICAL |
-| GDPR retention | ✅ PASS | data-privacy skill not active |
-## Overall: ✅ ALL BLOCKING GATES PASSED
-`);
-
-  write(`${phaseDir}/VERIFICATION-${phaseNum}.md`, `# Verification — Phase ${phaseNum}
-## Stage 1 — Tests: 16/16 passing ✅
-## Stage 2 — Requirements:
-| FR-01 | User login | ✅ | src/auth/login.ts:24 |
-| FR-02 | User logout | ✅ | src/auth/logout.ts:18 |
-## Stage 3 — Type check: PASS ✅
-## Stage 4 — Security: PASS ✅
-## Overall: ✅ PHASE VERIFIED
-`);
-
-  write(`${phaseDir}/UAT-${phaseNum}.md`, `# UAT — Phase ${phaseNum}
-## Test results
-| # | Deliverable | Result | Notes |
-|---|---|---|---|
-| 1 | POST /auth/login returns JWT | ✅ | Tested with valid+invalid credentials |
-| 2 | POST /auth/logout invalidates session | ✅ | Blocklist verified |
-## Overall: ✅ ALL UAT PASSED
-`);
-
-  appendAudit({ event: 'phase_completed', phase: phaseNum, uat_pass_rate: 1.0 });
-}
-
-// ── Tests ──────────────────────────────────────────────────────────────────────
-console.log('\nMindForge Day 7 — End-to-End Tests\n');
-
-// ── Test 1: Complete greenfield workflow ───────────────────────────────────────
-console.log('Greenfield project workflow:');
-const gf = createTestProject();
-
-try {
-  test('init-project creates all required .planning/ files', () => {
-    initProject(gf);
-    const required = ['PROJECT.md', 'REQUIREMENTS.md', 'ARCHITECTURE.md', 'STATE.md', 'HANDOFF.json', 'AUDIT.jsonl'];
-    required.forEach(f => assert.ok(gf.exists(`.planning/${f}`), `Missing: ${f}`));
-  });
-
-  test('HANDOFF.json has v1.0.0 schema_version and plugin_api_version', () => {
-    const handoff = JSON.parse(gf.read('.planning/HANDOFF.json'));
-    assert.strictEqual(handoff.schema_version, '1.0.0');
-    assert.strictEqual(handoff.plugin_api_version, '1.0.0');
-    assert.ok(handoff._warning, 'Should have _warning field');
-    assert.ok(!handoff._warning.toLowerCase().includes('password'), '_warning should not contain password');
-  });
-
-  test('initial AUDIT.jsonl has project_initialised event with session_id', () => {
-    const lines = gf.read('.planning/AUDIT.jsonl').split('\n').filter(Boolean);
-    assert.ok(lines.length >= 1, 'Should have at least one audit entry');
-    const first = JSON.parse(lines[0]);
-    assert.strictEqual(first.event, 'project_initialised');
-    assert.ok(first.session_id, 'Should have session_id');
-    assert.ok(first.id, 'Should have id');
-    assert.ok(first.timestamp, 'Should have timestamp');
-  });
-
-  test('plan-phase creates PLAN files with valid XML structure', () => {
-    planPhase(gf, 1);
-    const plan = gf.read('.planning/phases/1/PLAN-1-01.md');
-    assert.ok(plan, 'PLAN-1-01.md should exist');
-    assert.ok(plan.includes('<task type="auto">'), 'Should have task element');
-    assert.ok(plan.includes('<n>'), 'Should have task name');
-    assert.ok(plan.includes('<persona>'), 'Should specify persona');
-    assert.ok(plan.includes('<dependencies>'), 'Should have dependencies');
-    assert.ok(plan.includes('<verify>'), 'Should have verify step');
-    assert.ok(plan.includes('<done>'), 'Should have definition of done');
-  });
-
-  test('difficulty score file created before plans', () => {
-    assert.ok(gf.exists('.planning/phases/1/DIFFICULTY-SCORE-1.md'));
-    const score = gf.read('.planning/phases/1/DIFFICULTY-SCORE-1.md');
-    assert.ok(score.includes('Composite'), 'Should have composite score');
-    assert.ok(score.includes('Challenging'), 'Should have difficulty label');
-  });
-
-  test('dependency graph created and shows wave structure', () => {
-    const dep = gf.read('.planning/phases/1/DEPENDENCY-GRAPH-1.md');
-    assert.ok(dep, 'Dependency graph should exist');
-    assert.ok(dep.includes('Wave 1'), 'Should define Wave 1');
-    assert.ok(dep.includes('Wave 2'), 'Should define Wave 2');
-    assert.ok(dep.includes('Plan 01'), 'Should reference Plan 01');
-    assert.ok(dep.includes('Plan 02'), 'Should reference Plan 02');
-  });
-
-  test('execute task creates SUMMARY with commit SHA', () => {
-    executeTask(gf, 1, '01', 'abc1234ef');
-    const summary = gf.read('.planning/phases/1/SUMMARY-1-01.md');
-    assert.ok(summary, 'SUMMARY-1-01.md should exist');
-    assert.ok(summary.includes('Completed ✅'), 'Should show completed status');
-    assert.ok(summary.includes('abc1234ef'), 'Should include commit SHA');
-  });
-
-  test('task execution writes task_started and task_completed to AUDIT.jsonl', () => {
-    executeTask(gf, 1, '02', 'def5678ab');
-    const lines = gf.read('.planning/AUDIT.jsonl').split('\n').filter(Boolean);
-    const events = lines.map(l => JSON.parse(l).event);
-    assert.ok(events.includes('task_started'), 'Should have task_started event');
-    assert.ok(events.includes('task_completed'), 'Should have task_completed event');
-  });
-
-  test('security scan writes SECURITY-REVIEW file', () => {
-    runSecurityScan(gf, 1, []);
-    assert.ok(gf.exists('.planning/phases/1/SECURITY-REVIEW-1.md'));
-    const review = gf.read('.planning/phases/1/SECURITY-REVIEW-1.md');
-    assert.ok(review.includes('CLEAN ✅') || review.includes('PASS'), 'Should show passing result');
-  });
-
-  test('verify-phase creates GATE-RESULTS, VERIFICATION, and UAT files', () => {
-    verifyPhase(gf, 1);
-    assert.ok(gf.exists('.planning/phases/1/GATE-RESULTS-1.md'), 'GATE-RESULTS should exist');
-    assert.ok(gf.exists('.planning/phases/1/VERIFICATION-1.md'), 'VERIFICATION should exist');
-    assert.ok(gf.exists('.planning/phases/1/UAT-1.md'), 'UAT should exist');
-  });
-
-  test('GATE-RESULTS shows all 5 gates passing', () => {
-    const gates = gf.read('.planning/phases/1/GATE-RESULTS-1.md');
-    assert.ok(gates.includes('Secret detection'), 'Should have secret detection gate');
-    assert.ok(gates.includes('CRITICAL security'), 'Should have CRITICAL findings gate');
-    assert.ok(gates.includes('Test suite'), 'Should have test suite gate');
-    assert.ok(gates.includes('✅ PASS'), 'Gates should pass');
-    assert.ok(gates.includes('ALL BLOCKING GATES PASSED'), 'Should confirm all gates passed');
-  });
-
-  test('VERIFICATION.md references requirements with traceability', () => {
-    const v = gf.read('.planning/phases/1/VERIFICATION-1.md');
-    assert.ok(v.includes('FR-01'), 'Should reference FR-01');
-    assert.ok(v.includes('FR-02'), 'Should reference FR-02');
-    assert.ok(v.includes('src/auth/'), 'Should reference source files');
-  });
-
-  // Complete audit log validation
-  test('full workflow: all AUDIT.jsonl entries are valid with required fields', () => {
-    const lines = gf.read('.planning/AUDIT.jsonl').split('\n').filter(Boolean);
-    assert.ok(lines.length >= 6, `Should have >= 6 audit entries, got ${lines.length}`);
-
-    lines.forEach((line, i) => {
-      let entry;
-      assert.doesNotThrow(() => { entry = JSON.parse(line); }, `Line ${i+1} is not valid JSON`);
-      assert.ok(entry.id,         `Line ${i+1}: missing 'id'`);
-      assert.ok(entry.timestamp,  `Line ${i+1}: missing 'timestamp'`);
-      assert.ok(entry.event,      `Line ${i+1}: missing 'event'`);
-      assert.ok(entry.session_id, `Line ${i+1}: missing 'session_id'`);
-      assert.ok(entry.agent,      `Line ${i+1}: missing 'agent'`);
-    });
-  });
-
-  test('full workflow: AUDIT.jsonl events cover complete lifecycle', () => {
-    const lines   = gf.read('.planning/AUDIT.jsonl').split('\n').filter(Boolean);
-    const events  = new Set(lines.map(l => JSON.parse(l).event));
-    assert.ok(events.has('project_initialised'), 'Missing: project_initialised');
-    assert.ok(events.has('phase_planned'),       'Missing: phase_planned');
-    assert.ok(events.has('task_started'),        'Missing: task_started');
-    assert.ok(events.has('task_completed'),      'Missing: task_completed');
-    assert.ok(events.has('phase_completed'),     'Missing: phase_completed');
-  });
-
-} finally {
-  gf.cleanup();
-}
-
-// ── Test 2: Brownfield / map-codebase workflow ─────────────────────────────────
-console.log('\nBrownfield project workflow:');
-const bf = createTestProject();
-
-try {
-  // Simulate what /mindforge:map-codebase produces
-  test('map-codebase creates CONVENTIONS.md with DRAFT status marker', () => {
-    bf.write('.mindforge/org/CONVENTIONS.md', `# Coding Conventions — E2E Test Project
-# Source: Inferred from codebase analysis by MindForge
-# Status: DRAFT — confirm with team before treating as authoritative
-
-## IMPORTANT
-These conventions were inferred from code analysis.
-Review each section and mark as [CONFIRMED] or [NEEDS REVIEW].
-
-## Naming conventions [NEEDS REVIEW]
-- Variables: camelCase
-- Files: kebab-case
-- Classes: PascalCase
-
-## Import order [NEEDS REVIEW]
-- Node.js built-ins
-- Third-party libraries
-- Internal modules
-`);
-    const content = bf.read('.mindforge/org/CONVENTIONS.md');
-    assert.ok(content.includes('DRAFT'), 'Should be marked as DRAFT');
-    assert.ok(content.includes('NEEDS REVIEW'), 'Should have review markers');
-  });
-
-  test('map-codebase creates ARCHITECTURE.md with inferred stack', () => {
-    bf.write('.planning/ARCHITECTURE.md', `# Architecture — E2E Test Project
-## MindForge onboarding: Inferred from codebase
-## Technology stack
-- Runtime: Node.js 20 (inferred from .nvmrc)
-- Framework: Express 4.x (inferred from package.json)
-- Database: PostgreSQL via Prisma (inferred from prisma/schema.prisma)
-## Quality baseline
-- Tests: Vitest, ~200 test files
-- Linting: ESLint configured
-- CI/CD: GitHub Actions
-`);
-    const arch = bf.read('.planning/ARCHITECTURE.md');
-    assert.ok(arch, 'ARCHITECTURE.md should exist');
-    assert.ok(arch.includes('inferred') || arch.includes('Inferred'), 'Should note inferred content');
-  });
-
-  test('STATE.md from map-codebase shows ready-for-planning status', () => {
-    bf.write('.planning/STATE.md', `# Project State
-
-## Status
-Codebase mapped. Ready to plan first phase.
-
-## Current phase
-None — run /mindforge:plan-phase 1 to begin.
-
-## Last action
-/mindforge:map-codebase completed — codebase analysis done.
-`);
-    const state = bf.read('.planning/STATE.md');
-    assert.ok(state.includes('map'), 'STATE.md should reference map-codebase');
-    assert.ok(state.includes('plan'), 'STATE.md should suggest next step');
-  });
-
-} finally {
-  bf.cleanup();
-}
-
-// ── Test 3: Security gate scenarios ───────────────────────────────────────────
-console.log('\nSecurity gate scenarios:');
-const sg = createTestProject();
-
-try {
-  test('CRITICAL security finding in review blocks phase completion indicator', () => {
-    initProject(sg);
-    planPhase(sg, 1);
-    executeTask(sg, 1, '01', 'abc1234');
-
-    // Run security scan with a CRITICAL finding
-    runSecurityScan(sg, 1, [{
-      severity: 'CRITICAL',
-      description: 'SQL injection via unsanitised user input',
-      file: 'src/db/users.ts',
-      line: 47,
-      remediation: 'Use parameterised queries: db.query($1, [id])',
-    }]);
-
-    const review = sg.read('.planning/phases/1/SECURITY-REVIEW-1.md');
-    assert.ok(review.includes('CRITICAL'), 'Should show CRITICAL finding');
-    assert.ok(review.includes('BLOCKED') || review.includes('0 CRITICAL') === false, 'Should indicate blocked state');
-  });
-
-  test('AUDIT.jsonl captures security findings with correct schema', () => {
-    const lines = sg.read('.planning/AUDIT.jsonl').split('\n').filter(Boolean);
-    const secScan = lines.map(l => JSON.parse(l)).find(e => e.event === 'security_scan_completed');
-    assert.ok(secScan, 'Should have security_scan_completed audit entry');
-    assert.strictEqual(secScan.critical, 1, 'Should record 1 critical finding');
-    assert.ok(secScan.session_id, 'Security scan audit entry should have session_id');
-  });
-
-} finally {
-  sg.cleanup();
-}
-
-// ── Results ─────────────────────────────────────────────────────────────────────
-console.log(`\n${'─'.repeat(55)}`);
-console.log(`Results: ${passed} passed, ${failed} failed`);
-if (failed > 0) {
-  console.error(`\n❌  ${failed} test(s) failed.\n`);
-  process.exit(1);
-} else {
-  console.log(`\n✅  All E2E tests passed.\n`);
-}
-```
-
-**Commit:**
-```bash
-git add tests/
-git commit -m "test(day7): add production readiness, migration, and E2E test suites"
-```
-
----
-
-## TASK 11 — Update CLAUDE.md, bump to v1.0.0, final commit
-
-Add to `.claude/CLAUDE.md` and mirror to `.agent/CLAUDE.md`:
-
-```markdown
----
-
-## PRODUCTION LAYER (Day 7 — v1.0.0)
-
-### Plugin awareness at session start
-On session start: read PLUGINS-MANIFEST.md if it exists.
-Load all installed plugins per plugin-loader.md protocol.
-Report: "Active plugins: [list]" or "No plugins installed."
-If a plugin has a lifecycle hook that applies to the current operation: execute it.
-Never fail session start because a plugin is invalid — skip and report.
-
-### Schema version awareness
-On session start: compare HANDOFF.json schema_version against current package.json version.
-If schema_version is OLDER than current version by more than a patch:
-  Suggest: "Your .planning/ files are on MindForge v[old]. Run /mindforge:migrate."
-  Do NOT auto-migrate without explicit user command.
-  Old schemas are still readable — don't block execution, just suggest migration.
-
-### Token efficiency mindset
-Apply token-optimiser.md strategies in all sessions:
-- PLAN `<action>` fields: lean (150-400 words), specify WHAT not HOW
-- Read files when referenced, not all upfront
-- Load only "Current status" section of STATE.md unless history is needed
-- Maximum 3 skills at full injection — summarise anything beyond
-
-### Self-update awareness
-On session start: if MINDFORGE_AUTO_CHECK_UPDATES=true in MINDFORGE.md,
-  check for updates silently (no output unless update is available).
-  If update available: notify once, do not repeat.
-
-### v1.0.0 stable interface
-As of v1.0.0, all 36 commands have stable interfaces.
-All plugin.json, HANDOFF.json, AUDIT.jsonl schemas are stable.
-Breaking changes to these require MAJOR version bump.
-Non-breaking additions (new optional fields, new commands) require MINOR.
-
-### New commands (Day 7)
-- /mindforge:update — check for and apply framework updates
-- /mindforge:migrate — run schema migrations between versions
-- /mindforge:plugins — manage plugins (install, uninstall, validate)
-- /mindforge:tokens — token usage profiling and optimisation
-- /mindforge:release — framework release pipeline (core team only)
-
----
-```
-
-**Bump to v1.0.0:**
-
-```bash
-node -e "
-  const fs = require('fs');
-  const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-  p.version = '1.0.0';
-  fs.writeFileSync('package.json', JSON.stringify(p, null, 2) + '\n');
-  console.log('Bumped to v1.0.0');
-"
-
-git add package.json .claude/CLAUDE.md .agent/CLAUDE.md
-git commit -m "feat(core): v1.0.0 stable — production CLAUDE.md with plugin, migration, token awareness"
-```
-
----
-
-## TASK 12 — Run all 15 suites × 3 consecutive runs
-
-```bash
-#!/usr/bin/env bash
-# MindForge v1.0.0 Pre-Release Verification
-# ALL 15 suites × 3 runs must pass
-
-set -euo pipefail
-
-SUITES=(install wave-engine audit compaction skills-platform
-        integrations governance intelligence metrics
-        distribution ci-mode sdk production migration e2e)
-
-TOTAL_PASS=0
-TOTAL_FAIL=0
-ALL_OK=true
-
-echo ""
-echo "⚡ MindForge v1.0.0 Pre-Release Test Battery"
-echo "  15 suites × 3 runs = $((${#SUITES[@]} * 3)) expected passes"
-echo ""
-
-for RUN in 1 2 3; do
-  echo "═══ Run ${RUN} / 3 ════════════════════════════════════════════════"
-  for SUITE in "${SUITES[@]}"; do
-    printf "  %-30s" "${SUITE}..."
-    if OUTPUT=$(node tests/${SUITE}.test.js 2>&1); then
-      LAST=$(echo "${OUTPUT}" | tail -1)
-      echo "✅ ${LAST}"
-      ((TOTAL_PASS++))
-    else
-      echo "❌ FAILED"
-      echo "${OUTPUT}" | grep -E "❌|Error" | head -5
-      ((TOTAL_FAIL++))
-      ALL_OK=false
-    fi
-  done
-done
-
-echo ""
-echo "═══════════════════════════════════════════════════════════════"
-echo "Results: ${TOTAL_PASS} passed / ${TOTAL_FAIL} failed"
-
-if "${ALL_OK}"; then
-  echo "✅ ALL $((${#SUITES[@]} * 3)) TESTS PASSED × 3 RUNS"
-  echo ""
-  echo "Ready to tag v1.0.0:"
-  echo "  git tag -a v1.0.0 -m 'MindForge v1.0.0 — First stable release'"
-  echo "  git push origin v1.0.0"
-  echo "  npm publish --access public"
-else
-  echo "❌ ${TOTAL_FAIL} FAILURES — NOT READY FOR RELEASE"
-  exit 1
-fi
-```
-
-**Final commit and push:**
-
-```bash
-git add .
-git commit -m "feat(day7): complete production hardening — v1.0.0 release ready"
-git push origin feat/mindforge-production-release
-```
-
----
-
-# ═══════════════════════════════════════════════════════════════════
-# PART 2 — REVIEW PROMPT
-# ═══════════════════════════════════════════════════════════════════
-
----
-
-## DAY 7 REVIEW — Run after implementation is complete
-
-Activate **`architect.md` + `qa-engineer.md` + `security-reviewer.md`** simultaneously.
-
-Day 7 is the v1.0.0 release sprint. The review standard is higher than any
-previous day — every issue found here is an issue that ships to production users.
-
-Three adversarial lenses for this review:
-1. **Reliability lens**: what breaks under realistic production conditions?
-2. **Security lens**: what attack surfaces were not hardened?
-3. **User experience lens**: what fails silently or produces confusing errors?
-
----
-
-## REVIEW PASS 1 — Installer: All code paths
-
-Read `bin/install.js` and `bin/installer-core.js`.
-
-- [ ] **Windows path handling**: The installer uses `os.homedir()` and `path.join()`.
-  On Windows, paths use backslashes. The runtime directories (`.claude/`, `.agent/`)
-  use forward slashes everywhere. Does `path.join()` produce correct paths on Windows?
-  Specifically: `path.join(os.homedir(), '.claude')` → `C:\Users\john\.claude` on Windows.
-  Does Claude Code on Windows use `C:\Users\john\.claude` or `C:\Users\john\.claude\`?
-  Add: "For Windows compatibility, normalize all paths with `path.normalize()` before use."
-
-- [ ] **copyDir excludePatterns**: The exclude list uses `{ excludePatterns: SENSITIVE_EXCLUDE }`.
-  But `SENSITIVE_EXCLUDE` contains strings like `'.env'` and regex like `/^\.env\..*/`.
-  The copyDir function checks:
-  `excludePatterns.some(pat => typeof pat === 'string' ? entry.name === pat : pat.test(entry.name))`
-  But `'*.key'` is a glob pattern string, not a filename — `entry.name === '*.key'` will never match.
-  Fix: replace glob patterns with regex equivalents: `/\.key$/` not `'*.key'`.
-
-- [ ] **`--all` scope variable**: In the `run()` function, when `runtime === 'all'`,
-  the code iterates `runtimes.forEach(rt => install(rt, scope, options))`.
-  But `scope` is not in scope at this point in the function — it was destructured
-  from args before the `isUpdate` check, so it should be available. Verify this is correct.
-
----
-
-## REVIEW PASS 2 — Self-Update: Edge cases
-
-Read all three updater files.
-
-- [ ] **`checkAndUpdate` with CI=true**: In CI mode, the update should not prompt
-  the user for confirmation before applying. But the current code checks `apply` flag only.
-  Add: "In CI mode (`process.env.CI === 'true'`): if `--apply` is passed, apply without confirmation.
-  If `--apply` is NOT passed in CI: check only (don't apply silently)."
-
-- [ ] **changelog extraction**: `extractEntries` splits the changelog on `\n` and looks for
-  `## [v?X.Y.Z` pattern. But if the CHANGELOG.md uses a different date format
-  (e.g., `## v1.0.0 — 2026-03-22`) the regex `## \[?v?(\d+\.\d+\.\d+)` should still match
-  (the `\[?` allows the optional bracket). Verify this works for:
-  - `## [1.0.0] — 2026-03-22`
-  - `## v1.0.0 — 2026-03-22`
-  - `## 1.0.0 (2026-03-22)`
-
-- [ ] **detectInstallScope**: The function checks file existence to determine scope.
-  But what if BOTH local and global installs exist?
-  The function returns local first (checked first) — this is correct per ADR-019.
-  But the decision should be documented in the code with a comment for maintainability.
-  Add: `// Per ADR-019: local takes precedence over global`
-
----
-
-## REVIEW PASS 3 — Migration Engine: Correctness
-
-Read all migration files.
-
-- [ ] **Migration backup retention**: After successful migration, the backup is retained
-  with a note: "Remove when satisfied." But in CI environments, accumulated migration
-  backups will fill disk space over time. Add: "In CI mode: auto-delete backup on successful
-  migration. In interactive mode: retain backup."
-
-- [ ] **The `0.6.0-to-1.0.0.js` migration** converts `VERIFY_PASS_RATE_WARNING_THRESHOLD`.
-  The test `test('does NOT modify value of exactly 1')` verifies that `=1` is preserved.
-  But what about `VERIFY_PASS_RATE_WARNING_THRESHOLD=1.0` (explicit decimal)?
-  The regex `/^(VERIFY_PASS_RATE_WARNING_THRESHOLD=)(\d+(?:\.\d+)?)(\s*)$/m` matches `1.0`.
-  `parseFloat('1.0') > 1` is `false` — so `1.0` would be correctly preserved.
-  Verify this edge case is tested.
-
-- [ ] **Migration chain verification**: If someone has MindForge v0.3.0 (a version between
-  our migration files), there is no migration file for `0.3.0-to-0.5.0`.
-  The migrate.js uses a filter:
-  `compareSemver(m.fromVersion, fromVersion) >= 0 && compareSemver(m.toVersion, toVersion) <= 0`
-  For fromVersion=0.3.0 and toVersion=1.0.0:
-  - `0.1.0-to-0.5.0.js`: `compareSemver('0.1.0', '0.3.0') >= 0` → `0.1.0 >= 0.3.0` → false ❌
-  This means the migration from 0.3.0 would SKIP the 0.1.0-to-0.5.0 migration,
-  potentially leaving HANDOFF.json without the intelligence layer fields.
-  Fix: the filter should use `< toVersion` not `>= fromVersion`.
-  Or: use a range check: `m applies if m.toVersion is BETWEEN fromVersion and toVersion`.
-  The correct logic is: run migration if `m.toVersion > fromVersion AND m.toVersion <= toVersion`.
-
----
-
-## REVIEW PASS 4 — Plugin System: Conflict detection
-
-Read `plugin-schema.md` and `plugin-loader.md`.
-
-- [ ] **Reserved command conflict detection**: The loader checks a hardcoded list of
-  36 reserved command names. But this list will become stale as MindForge adds new
-  commands in future versions. When a new built-in command is added, the plugin loader's
-  reserved list must also be updated.
-  Better approach: derive the reserved list dynamically at runtime:
-  ```bash
-  RESERVED_NAMES=$(ls .claude/commands/mindforge/ 2>/dev/null | sed 's/\.md$//')
-  ```
-  This always reflects the actual installed commands, not a hardcoded list.
-
-- [ ] **Multiple plugins providing the same hook**: If `plugin-a` and `plugin-b` both
-  declare `post_phase_complete` hooks, what is the execution order?
-  The spec doesn't define this. Add: "Multiple plugins with the same hook:
-  execute in PLUGINS-MANIFEST.md installation order (first installed, first executed).
-  Each hook is independent — failure of one hook does not prevent others from running."
-
----
-
-## REVIEW PASS 5 — Token Optimiser: Signal Accuracy
-
-Read `token-optimiser.md`.
-
-- [ ] **Estimates vs. actual measurement**: The token budget tracking writes to
-  `token-usage.jsonl` with `token_estimates`. But these are estimates, not actual
-  measured token counts. The spec doesn't explain how to compute `code_reading` tokens
-  from file content.
-  Add: "Estimate code_reading tokens as: `sum(file_sizes_read / 4)`.
-  (Average 4 chars per token is a reasonable estimate for code.)
-  Mark all values in token-usage.jsonl as estimates with `"measured": false`."
-
-- [ ] **Efficiency formula definition of "useful output"**: The formula says:
-  `useful_output_tokens = tokens in SUMMARY files + verified code changes + ADRs written`
-  But how are "verified code changes" measured in tokens?
-  Clarify: "Estimate verified code changes as: `sum(SUMMARY file sizes / 4)`.
-  SUMMARY files contain the output description — this is a proxy for the value produced."
-
----
-
-## REVIEW PASS 6 — E2E Tests: Coverage Gaps
-
-Read `tests/e2e.test.js`.
-
-- [ ] **Multi-developer scenario not tested**: The E2E tests cover single-developer
-  workflows but not the multi-developer HANDOFF system (HANDOFF-[dev-id].json,
-  active_developers field, file conflict detection). Add at minimum:
-  "A test that simulates two developers working on different plans and verifies
-  that their per-developer HANDOFF files are distinct and non-conflicting."
-
-- [ ] **Context compaction scenario not tested**: The E2E tests don't test the
-  compaction protocol (Level 2 structured extraction). Add:
-  "A test that simulates a Level 2 compaction and verifies the HANDOFF.json
-  gains decisions_made and implicit_knowledge fields."
-
-- [ ] **Cleanup failure is too quiet**: The `catch(e) { console.warn(...) }` in cleanup
-  is good — but the test still passes even if cleanup fails.
-  Add: "Track cleanup failures in a global counter. Report at the end:
-  'N test directories were not cleaned up: [paths]'"
-
----
-
-## REVIEW PASS 7 — Production Checklist: Release Gate
-
-Read `production-checklist.md`.
-
-- [ ] **Missing version consistency checks**: The checklist does not verify that:
-  - `package.json` version === v1.0.0
-  - Git tag === `v1.0.0`
-  - npm published version === v1.0.0
-  - SDK `package.json` version matches root `package.json` version
-  These are classic "wrong version shipped" bugs. Add items E09 and E10 expansions
-  or add Section F (Release Artifacts, 5 items) to bring total to 55 and include:
-  - F01: package.json version === target release version
-  - F02: SDK package.json version matches root version
-  - F03: Git tag v1.0.0 exists and points to the correct commit
-  - F04: CHANGELOG.md has a complete entry for v1.0.0 with today's date
-  - F05: `npm publish --dry-run` shows no unexpected files
-
----
-
-## REVIEW SUMMARY TABLE
-
-```
-## Day 7 Review Summary
-
-| Category              | BLOCKING | MAJOR | MINOR | SUGGESTION |
-|-----------------------|----------|-------|-------|------------|
-| Installer             |          |       |       |            |
-| Self-Update           |          |       |       |            |
-| Migration Engine      |          |       |       |            |
-| Plugin System         |          |       |       |            |
-| Token Optimiser       |          |       |       |            |
-| E2E Tests             |          |       |       |            |
-| Production Checklist  |          |       |       |            |
-| **TOTAL**             |          |       |       |            |
-
-## Verdict
-[ ] ✅ APPROVED — Proceed to HARDEN section
-[ ] ⚠️  APPROVED WITH CONDITIONS — Fix MAJOR findings first
-[ ] ❌ NOT APPROVED — BLOCKING findings prevent v1.0.0
-```
-
----
-
-# ═══════════════════════════════════════════════════════════════════
-# PART 3 — HARDENING PROMPT
-# ═══════════════════════════════════════════════════════════════════
-
----
-
-## DAY 7 HARDENING — Run after REVIEW is APPROVED
-
-Confirm all review findings resolved:
-
-```bash
-for suite in install wave-engine audit compaction skills-platform \
-             integrations governance intelligence metrics \
-             distribution ci-mode sdk production migration e2e; do
-  printf "  %-30s" "${suite}..."
-  node tests/${suite}.test.js 2>&1 | tail -1
-done
-```
-
----
-
-## HARDEN 1 — Fix installer glob patterns in excludePatterns
-
-The review found `'*.key'` is a string, not a glob — it never matches.
-
-Update `bin/installer-core.js`:
-
-```javascript
-// Replace glob strings with correct regex equivalents:
-const SENSITIVE_EXCLUDE = [
-  '.env',        // exact filename match
-  /^\.env\..*/,  // .env.local, .env.production, etc.
-  /\.key$/,      // anything ending in .key (was '*.key' — broken)
-  /\.pem$/,      // anything ending in .pem (was '*.pem' — broken)
-  'secrets',     // exact directory name
-  '.secrets',    // exact directory name
-  /^secrets$/,   // exact match at directory level
-];
-```
-
-Add a unit test to `tests/production.test.js`:
-
-```javascript
-test('SENSITIVE_EXCLUDE properly excludes .env and .key files', () => {
-  const SENSITIVE_EXCLUDE = [
-    '.env', /^\.env\..*/, /\.key$/, /\.pem$/, 'secrets', /^secrets$/
-  ];
-  const shouldExclude = (name) =>
-    SENSITIVE_EXCLUDE.some(p => typeof p === 'string' ? p === name : p.test(name));
-
-  assert.ok(shouldExclude('.env'),               '.env should be excluded');
-  assert.ok(shouldExclude('.env.local'),         '.env.local should be excluded');
-  assert.ok(shouldExclude('private.key'),        'private.key should be excluded');
-  assert.ok(shouldExclude('certificate.pem'),    'certificate.pem should be excluded');
-  assert.ok(shouldExclude('secrets'),            'secrets directory should be excluded');
-  assert.ok(!shouldExclude('package.json'),      'package.json should NOT be excluded');
-  assert.ok(!shouldExclude('.mindforge'),        '.mindforge should NOT be excluded');
-  assert.ok(!shouldExclude('src'),               'src should NOT be excluded');
-});
-```
-
-**Commit:**
-```bash
-git add bin/installer-core.js tests/production.test.js
-git commit -m "harden(installer): fix SENSITIVE_EXCLUDE glob patterns — use regex, not glob strings"
-```
-
----
-
-## HARDEN 2 — Fix migration chain filter logic
-
-The review found the filter breaks for intermediate versions (e.g., v0.3.0).
-
-Update `bin/migrations/migrate.js` — replace the getMigrationsToRun filter:
-
-```javascript
-function getMigrationsToRun(fromVersion, toVersion) {
-  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
-  //
-  // Example: upgrading 0.3.0 → 1.0.0:
-  //   - 0.1.0→0.5.0: toVersion=0.5.0 > fromVersion=0.3.0 ✅ run this
-  //   - 0.5.0→0.6.0: toVersion=0.6.0 > fromVersion=0.3.0 ✅ run this
-  //   - 0.6.0→1.0.0: toVersion=1.0.0 > fromVersion=0.3.0 ✅ run this
-  //
-  // Example: upgrading 0.6.0 → 1.0.0:
-  //   - 0.1.0→0.5.0: toVersion=0.5.0 > fromVersion=0.6.0? ❌ skip
-  //   - 0.5.0→0.6.0: toVersion=0.6.0 > fromVersion=0.6.0? ❌ skip (equal, not greater)
-  //   - 0.6.0→1.0.0: toVersion=1.0.0 > fromVersion=0.6.0? ✅ run this
-
-  return allMigrations.filter(m =>
-    compareSemver(m.toVersion, fromVersion) > 0  &&   // migration destination > current
-    compareSemver(m.toVersion, toVersion)   <= 0       // migration destination ≤ target
-  );
-}
-```
-
-Add migration chain tests to `tests/migration.test.js`:
-
-```javascript
-test('migration chain for v0.3.0 → v1.0.0 includes ALL 3 migrations', () => {
-  // Simulate the filter logic
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  const fromVersion = '0.3.0';
-  const toVersion   = '1.0.0';
-
-  const migrations = [
-    { fromVersion: '0.1.0', toVersion: '0.5.0' },
-    { fromVersion: '0.5.0', toVersion: '0.6.0' },
-    { fromVersion: '0.6.0', toVersion: '1.0.0' },
-  ].filter(m =>
-    compareSemver(m.toVersion, fromVersion) > 0 &&
-    compareSemver(m.toVersion, toVersion) <= 0
-  );
-
-  assert.strictEqual(migrations.length, 3,
-    `Expected 3 migrations for 0.3.0→1.0.0, got ${migrations.length}`);
-});
-
-test('migration chain for v0.6.0 → v1.0.0 includes only 1 migration', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  const fromVersion = '0.6.0';
-  const toVersion   = '1.0.0';
-
-  const migrations = [
-    { fromVersion: '0.1.0', toVersion: '0.5.0' },
-    { fromVersion: '0.5.0', toVersion: '0.6.0' },
-    { fromVersion: '0.6.0', toVersion: '1.0.0' },
-  ].filter(m =>
-    compareSemver(m.toVersion, fromVersion) > 0 &&
-    compareSemver(m.toVersion, toVersion) <= 0
-  );
-
-  assert.strictEqual(migrations.length, 1,
-    `Expected 1 migration for 0.6.0→1.0.0, got ${migrations.length}: ${migrations.map(m=>m.toVersion)}`);
-  assert.strictEqual(migrations[0].toVersion, '1.0.0');
-});
-
-test('migration chain for same version returns 0 migrations', () => {
-  const { compareSemver } = require('../bin/updater/version-comparator');
-  const fromVersion = '1.0.0';
-  const toVersion   = '1.0.0';
-
-  const migrations = [
-    { fromVersion: '0.1.0', toVersion: '0.5.0' },
-    { fromVersion: '0.5.0', toVersion: '0.6.0' },
-    { fromVersion: '0.6.0', toVersion: '1.0.0' },
-  ].filter(m =>
-    compareSemver(m.toVersion, fromVersion) > 0 &&
-    compareSemver(m.toVersion, toVersion) <= 0
-  );
-
-  assert.strictEqual(migrations.length, 0, 'No migrations needed for same version');
-});
-```
-
-**Commit:**
-```bash
-git add bin/migrations/migrate.js tests/migration.test.js
-git commit -m "harden(migration): fix migration chain filter — use toVersion range check, not fromVersion"
-```
-
----
-
-## HARDEN 3 — Add CI backup auto-deletion and dynamic reserved names
-
-### Fix CI migration backup cleanup in `migrate.js`
-
-```javascript
-  // ── 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)}`);
-  }
-```
-
-### Fix plugin loader to use dynamic reserved names
-
-Update `plugin-loader.md`:
-
-```markdown
-### Dynamic reserved command name detection
-
-Instead of a hardcoded list, detect reserved names at plugin install time:
-
-```bash
-# Detect currently installed built-in command names
-get_reserved_command_names() {
-  ls ".claude/commands/mindforge/"*.md 2>/dev/null | \
-    xargs -I{} basename {} .md | \
-    sort
-}
-
-RESERVED_NAMES=$(get_reserved_command_names)
-```
-
-For a plugin command that matches a reserved name:
-```bash
-# Check conflict
-CMD_NAME="health"
-PLUGIN_NAME="my-plugin"
-
-if echo "${RESERVED_NAMES}" | grep -q "^${CMD_NAME}$"; then
-  FINAL_NAME="${PLUGIN_NAME}-${CMD_NAME}"
-  echo "  ⚠️  Command '${CMD_NAME}' conflicts with built-in — renaming to '${FINAL_NAME}'"
-else
-  FINAL_NAME="${CMD_NAME}"
-fi
-```
-
-This approach always reflects actual installed commands rather than a hardcoded list
-that becomes stale with new MindForge releases.
-```
-
-**Commit:**
-```bash
-git add bin/migrations/migrate.js .mindforge/plugins/plugin-loader.md
-git commit -m "harden(migration,plugins): CI backup auto-delete, dynamic reserved command detection"
-```
-
----
-
-## HARDEN 4 — Write the final 3 ADRs
-
-### `.planning/decisions/ADR-018-installer-self-install-detection.md`
-
-```markdown
-# ADR-018: Installer detects and handles self-install scenario
-
-**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
-
-## Context
-Running `npx mindforge-cc --claude --local` inside the MindForge repo itself
-would copy `.mindforge/` to `.mindforge/` (source = destination).
-
-## Decision
-Detect self-install by checking `package.json.name === 'mindforge-cc'`.
-If self-install: skip framework file copies. Only install commands.
-
-## Rationale
-Core team runs the installer locally for testing frequently.
-Silent no-op with a clear warning is better than a cryptic error or accidental self-overwrite.
-```
-
-### `.planning/decisions/ADR-019-self-update-scope-preservation.md`
-
-```markdown
-# ADR-019: Self-update preserves the original installation scope
-
-**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
-
-## Context
-`/mindforge:update --apply` must update the correct installation.
-
-## Decision
-Detect original scope from filesystem (local before global per priority).
-Apply update using the detected scope. Per ADR-019.
-
-## Rationale
-Principle of least surprise. A local install user should get a local update.
-Unexpected global install is confusing and may affect other projects.
-```
-
-### `.planning/decisions/ADR-020-v1.0.0-stable-interface-contract.md`
-
-```markdown
-# ADR-020: v1.0.0 stable interface contract
-
-**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
-
-## Context
-MindForge reaches v1.0.0. "Stable" must be precisely defined.
-
-## Decision
-Stable public interfaces (additions require MINOR, removals/changes require MAJOR):
-- All 36 command names and their flag interfaces
-- HANDOFF.json schema fields
-- AUDIT.jsonl event types and required fields
-- All 10 core skill name values
-- MINDFORGE.md setting keys
-- @mindforge/sdk exported types and functions
-- plugin.json manifest format
-
-Governance primitives are permanently fixed and cannot become configurable
-in any future version without a MAJOR bump and explicit RFC process.
-
-## Consequences
-Plugin authors and SDK consumers can build on v1.0.0 with confidence.
-The MindForge team is committed to backwards compatibility in 1.x.x releases.
-```
-
-**Commit:**
-```bash
-git add .planning/decisions/
-git commit -m "docs(adr): add ADR-018, ADR-019, ADR-020 — complete 20 ADRs for v1.0.0"
-```
-
----
-
-## HARDEN 5 — Final CHANGELOG.md v1.0.0 entry
-
-```markdown
-## [1.0.0] — v1.0.0 First Stable Public Release — 2026-03-22
-
-🎉 **MindForge v1.0.0 — Enterprise Agentic Framework — First Stable Release**
-
-Built over 7 focused sprints, MindForge transforms Claude Code and Antigravity
-from powerful-but-unstructured AI tools into production-grade engineering
-partners with full governance, observability, and enterprise integration.
-
-### What ships in v1.0.0
-
-**36 commands** across 7 workflow categories
-**10 core skill packs** with three-tier registry (Core/Org/Project)
-**8 specialised agent personas** covering all engineering roles
-**Wave-based parallel execution** with dependency graph and automatic compaction
-**Enterprise integrations**: Jira, Confluence, Slack, GitHub, GitLab
-**Three-tier governance**: Tier 1 (auto) / Tier 2 (peer review) / Tier 3 (compliance)
-**Five non-bypassable compliance gates** (secret detection, CRITICAL findings, tests, CVEs, GDPR)
-**Intelligence layer**: health engine, difficulty scorer, anti-pattern detector, team profiling
-**Public skills registry**: npm-based `mindforge-skill-*` ecosystem
-**CI/CD integration**: GitHub Actions, GitLab CI, Jenkins adapters
-**@mindforge/sdk**: TypeScript SDK with client, event stream, and command builders
-**Monorepo support**: npm/pnpm/Nx/Turborepo/Lerna workspace detection
-**AI PR Review**: Claude API-powered code review with context loading
-**Self-update mechanism**: version check, changelog diff, scope-preserving apply
-**Version migration engine**: schema migration from v0.1.0 through v1.0.0
-**Plugin system**: extensible via `mindforge-plugin-*` npm namespace
-**Token usage optimiser**: profiling and efficiency strategies
-**50-point production readiness checklist**: fully verified before this release
-
-**20 Architecture Decision Records** documenting every major design choice
-**15 test suites** with 3× consecutive run requirement
-**Complete reference documentation**: commands, security, ADR index, threat model
-
-### Stable interface contract
-See ADR-020. All 36 commands, HANDOFF.json schema, AUDIT event types,
-@mindforge/sdk exports, and plugin.json format are stable in 1.x.x.
-
-### Breaking changes from 0.6.0
-- VERIFY_PASS_RATE_WARNING_THRESHOLD in MINDFORGE.md is now 0.0-1.0 (was 0-100)
-  Run `/mindforge:migrate` to auto-convert
-- AUDIT.jsonl session_id field is now required (auto-backfilled by migration)
-- HANDOFF.json plugin_api_version field required for plugin compatibility
-
-### Installation
-```bash
-npx mindforge-cc@latest
-# or
-npx mindforge-cc@1.0.0 --claude --global
-```
-```
-
-**Commit:**
-```bash
-git add CHANGELOG.md package.json
-git commit -m "chore(release): v1.0.0 final CHANGELOG and version bump"
-```
-
----
-
-## HARDEN 6 — Final hardening test additions
-
-Add to relevant test suites:
-
-```javascript
-// In tests/production.test.js — add after existing tests:
-console.log('\nHardening tests:');
-
-test('SENSITIVE_EXCLUDE uses regex for .key and .pem (not glob strings)', () => {
-  const c = fs.readFileSync('bin/installer-core.js', 'utf8');
-  // Should use regex pattern /\.key$/ not string '*.key'
-  assert.ok(!c.includes("'*.key'"), 'Should not use glob string for .key');
-  assert.ok(!c.includes("'*.pem'"), 'Should not use glob string for .pem');
-  assert.ok(c.includes('/\\.key$/') || c.includes('/.key$/'), 'Should use regex for .key');
-});
-
-test('migration filter uses toVersion range check (not fromVersion)', () => {
-  const c = fs.readFileSync('bin/migrations/migrate.js', 'utf8');
-  // The correct filter uses compareSemver(m.toVersion, fromVersion) > 0
-  assert.ok(
-    c.includes('m.toVersion') && c.includes('> 0'),
-    'Should use toVersion range check for migration filter'
-  );
-});
-
-test('migration has CI auto-delete of backup', () => {
-  const c = fs.readFileSync('bin/migrations/migrate.js', 'utf8');
-  assert.ok(
-    c.includes('CI') && (c.includes('auto-deleted') || c.includes('rmSync')),
-    'Should auto-delete backup in CI mode'
-  );
-});
-
-// In tests/migration.test.js — add after existing tests:
-test('MINDFORGE.md value 1.0 (explicit decimal) is not converted', () => {
-  const content = 'VERIFY_PASS_RATE_WARNING_THRESHOLD=1.0\n';
-  const migrated = simulateMindforgeMdMigration(content);
-  assert.ok(migrated.includes('=1.0'), 'Should preserve 1.0 format without conversion');
-});
-```
-
-**Commit:**
-```bash
-git add tests/production.test.js tests/migration.test.js
-git commit -m "test(day7): add hardening verification tests"
-```
-
----
-
-## HARDEN 7 — Pre-release final verification and tag
-
-```bash
-#!/usr/bin/env bash
-# MindForge v1.0.0 Final Pre-Release Verification
-
-echo ""
-echo "⚡ MindForge v1.0.0 Pre-Release Verification"
-echo "═══════════════════════════════════════════"
-
-PASS=true
-
-# 1. Version check
-PKGVER=$(node -e "console.log(require('./package.json').version)")
-[ "${PKGVER}" = "1.0.0" ] || { echo "❌ package.json version = ${PKGVER} (expected 1.0.0)"; PASS=false; }
-echo "  package.json version: ${PKGVER} ✅"
-
-# 2. CHANGELOG entry
-grep -q "1.0.0" CHANGELOG.md && echo "  CHANGELOG.md: v1.0.0 entry ✅" || { echo "❌ Missing CHANGELOG v1.0.0"; PASS=false; }
-
-# 3. ADR count
-ADR_COUNT=$(ls .planning/decisions/ADR-*.md 2>/dev/null | wc -l | tr -d ' ')
-[ "${ADR_COUNT}" -ge 20 ] && echo "  ADRs: ${ADR_COUNT} ✅" || { echo "❌ Only ${ADR_COUNT} ADRs (need 20)"; PASS=false; }
-
-# 4. Command count
-CMD_COUNT=$(ls .claude/commands/mindforge/*.md 2>/dev/null | wc -l | tr -d ' ')
-[ "${CMD_COUNT}" -ge 36 ] && echo "  Commands: ${CMD_COUNT} ✅" || { echo "❌ Only ${CMD_COUNT} commands (need 36)"; PASS=false; }
-
-# 5. Command parity
-diff <(ls .claude/commands/mindforge/ | sort) <(ls .agent/mindforge/ | sort) > /dev/null 2>&1 \
-  && echo "  Command parity: ✅" \
-  || { echo "❌ Command mismatch between runtimes"; PASS=false; }
-
-# 6. No secrets
-SECRETS=$(grep -rE "(password|api_key|token)\s*=\s*['\"][^'\"]{8,}" \
-  --include="*.md" --include="*.js" --include="*.json" --include="*.ts" \
-  --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | \
-  grep -v "placeholder\|example\|your-\|TEST_ONLY\|comment" || true)
-[ -z "${SECRETS}" ] && echo "  Secret scan: clean ✅" || { echo "❌ Potential credentials detected"; echo "${SECRETS}"; PASS=false; }
-
-# 7. All 15 test suites × 3 runs
-SUITES=(install wave-engine audit compaction skills-platform
-        integrations governance intelligence metrics
-        distribution ci-mode sdk production migration e2e)
-FAIL_COUNT=0
-for RUN in 1 2 3; do
-  for SUITE in "${SUITES[@]}"; do
-    node tests/${SUITE}.test.js 2>&1 | grep -q "All.*passed" || { ((FAIL_COUNT++)); }
-  done
-done
-[ "${FAIL_COUNT}" -eq 0 ] && echo "  Tests: 15 suites × 3 runs ✅" || { echo "❌ ${FAIL_COUNT} test failures"; PASS=false; }
-
-echo ""
-if "${PASS}"; then
-  echo "✅ ALL PRE-RELEASE CHECKS PASSED"
-  echo ""
-  echo "Release commands:"
-  echo "  git tag -a v1.0.0 -m 'MindForge v1.0.0 — First stable release'"
-  echo "  git push origin v1.0.0"
-  echo "  npm publish --access public"
-  echo "  gh release create v1.0.0 --title 'MindForge v1.0.0' --notes-file CHANGELOG.md"
-else
-  echo "❌ PRE-RELEASE CHECKS FAILED — do not release"
-  exit 1
-fi
-```
-
-**Final commit and push:**
-
-```bash
-git add .
-git commit -m "harden(day7): complete all production hardening — v1.0.0 release ready"
-git push origin feat/mindforge-production-release
-
-# After PR review, merge, and all checks pass:
-git checkout main && git pull
-git tag -a v1.0.0 -m "MindForge v1.0.0 — Enterprise Agentic Framework, First Stable Release"
-git push origin v1.0.0
-npm publish --access public
-```
-
----
-
-## MINDFORGE v1.0.0 — THE COMPLETE BUILD SUMMARY
-
-| Day | Branch | Core delivery | Commands |
-|---|---|---|---|
-| **1** | `feat/mindforge-core-scaffold` | Foundation: personas, skills, commands, state management | 6 |
-| **2** | `feat/mindforge-wave-engine` | Wave execution, compaction protocol, AUDIT pipeline | +4 = 10 |
-| **3** | `feat/mindforge-skills-platform` | Skills registry (3 tiers), 5 new skills, 5 commands | +5 = 15 |
-| **4** | `feat/mindforge-enterprise-integrations` | Jira/Confluence/Slack/GitHub, governance (Tier 1/2/3) | +6 = 21 |
-| **5** | `feat/mindforge-intelligence-layer` | Health engine, difficulty scorer, anti-patterns, metrics | +4 = 25 |
-| **6** | `feat/mindforge-distribution-platform` | npm registry, CI/CD, SDK, monorepo, AI PR review | +6 = 31 |
-| **7** | `feat/mindforge-production-release` | Complete installer, self-update, migration, plugins, tokens | +5 = **36** |
-
-### Final state: MindForge v1.0.0
-
-```
-36 commands     10 skills      8 personas
-20 ADRs         15 test suites 50-point checklist ✅
-```
-
-```bash
-npx mindforge-cc@latest
-# ⚡ MindForge — Enterprise Agentic Framework
-# The best agentic framework. Now shipped.
-```