@nforma.ai/nforma 0.2.1

package/bin/migrate-formal-dir.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * migrate-formal-dir.cjs
+ *
+ * Migrates a legacy .formal/ directory at the project root into the canonical
+ * .planning/formal/ location. Projects that adopted formal verification before
+ * the layout consolidation may still have root-level .formal/ — this script
+ * detects, merges, and optionally removes it.
+ *
+ * Conflict resolution: .planning/formal/ (canonical) always wins. If a file
+ * exists in both locations, the legacy version is skipped.
+ *
+ * Usage:
+ *   node bin/migrate-formal-dir.cjs [--project-root=PATH] [--json] [--remove-legacy]
+ *
+ * Exit codes:
+ *   0 = success (or nothing to migrate)
+ *   1 = could not start (invalid ROOT)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── CLI args ────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+function getFlag(name) {
+  return args.some(a => a === `--${name}`);
+}
+
+function getOption(name) {
+  const prefix = `--${name}=`;
+  const arg = args.find(a => a.startsWith(prefix));
+  return arg ? arg.slice(prefix.length) : null;
+}
+
+const jsonMode     = getFlag('json');
+const removeLegacy = getFlag('remove-legacy');
+const ROOT         = getOption('project-root') || process.cwd();
+
+const TAG = '[migrate-formal]';
+
+// ─── Logging ─────────────────────────────────────────────────────────────────
+
+const logs = [];
+
+function log(msg) {
+  if (!jsonMode) {
+    console.log(`${TAG} ${msg}`);
+  }
+  logs.push(msg);
+}
+
+// ─── Validate ROOT ──────────────────────────────────────────────────────────
+
+if (!fs.existsSync(ROOT) || !fs.statSync(ROOT).isDirectory()) {
+  if (jsonMode) {
+    console.log(JSON.stringify({ error: `Invalid project root: ${ROOT}` }));
+  } else {
+    console.error(`${TAG} ERROR: Invalid project root: ${ROOT}`);
+  }
+  process.exit(1);
+}
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+const legacyDir  = path.join(ROOT, '.formal');
+const canonDir   = path.join(ROOT, '.planning', 'formal');
+
+// ─── Detect ──────────────────────────────────────────────────────────────────
+
+if (!fs.existsSync(legacyDir) || !fs.statSync(legacyDir).isDirectory()) {
+  log('No legacy .formal/ found — nothing to migrate');
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      legacy_found: false,
+      copied: 0,
+      skipped: 0,
+      total: 0,
+      removed: false,
+      files_copied: [],
+      files_skipped: []
+    }));
+  }
+  process.exit(0);
+}
+
+// ─── Ensure target ──────────────────────────────────────────────────────────
+
+fs.mkdirSync(canonDir, { recursive: true });
+
+// ─── Walk helper ─────────────────────────────────────────────────────────────
+
+function walkDir(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// ─── Walk and merge ─────────────────────────────────────────────────────────
+
+const allFiles = walkDir(legacyDir);
+const filesCopied  = [];
+const filesSkipped = [];
+
+for (const srcFile of allFiles) {
+  const relPath  = path.relative(legacyDir, srcFile);
+  const destFile = path.join(canonDir, relPath);
+
+  try {
+    if (fs.existsSync(destFile)) {
+      log(`Skipped (already exists in .planning/formal/): ${relPath}`);
+      filesSkipped.push(relPath);
+    } else {
+      // Ensure intermediate directories
+      fs.mkdirSync(path.dirname(destFile), { recursive: true });
+      fs.copyFileSync(srcFile, destFile);
+      log(`Copied: ${relPath}`);
+      filesCopied.push(relPath);
+    }
+  } catch (err) {
+    log(`ERROR copying ${relPath}: ${err.message}`);
+    // Fail-open: continue with remaining files
+  }
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+const total = allFiles.length;
+log(`Migration complete: ${filesCopied.length} copied, ${filesSkipped.length} skipped (conflicts), ${total} total files in legacy .formal/`);
+
+// ─── Optional removal ────────────────────────────────────────────────────────
+
+let removed = false;
+
+if (removeLegacy && total > 0) {
+  try {
+    fs.rmSync(legacyDir, { recursive: true, force: true });
+    log('Removed legacy .formal/ directory');
+    removed = true;
+  } catch (err) {
+    log(`ERROR removing legacy .formal/: ${err.message}`);
+  }
+} else if (!removeLegacy && total > 0) {
+  log('Legacy .formal/ preserved — pass --remove-legacy to remove');
+}
+
+// ─── JSON output ─────────────────────────────────────────────────────────────
+
+if (jsonMode) {
+  console.log(JSON.stringify({
+    legacy_found: true,
+    copied: filesCopied.length,
+    skipped: filesSkipped.length,
+    total,
+    removed,
+    files_copied: filesCopied,
+    files_skipped: filesSkipped
+  }));
+}
+
+process.exit(0);

package/bin/migrate-planning.cjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * migrate-planning.cjs — Auto-migrate .planning/ from flat layout to v0.27+ hierarchy.
+ *
+ * Safe to run multiple times (idempotent). Moves files, never deletes.
+ * Writes a .planning/.migrated marker on completion.
+ *
+ * Usage:
+ *   node bin/migrate-planning.cjs [--dry-run] [--root <dir>]
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+function migrate(root, dryRun) {
+  const planDir = path.join(root, '.planning');
+  if (!fs.existsSync(planDir)) {
+    if (!dryRun) console.log('[migrate-planning] No .planning/ directory — nothing to do.');
+    return { moved: 0, skipped: 0 };
+  }
+
+  const stats = { moved: 0, skipped: 0, errors: [] };
+
+  function moveFile(src, dest) {
+    if (!fs.existsSync(src)) { stats.skipped++; return; }
+    if (fs.existsSync(dest)) { stats.skipped++; return; } // already migrated
+    if (dryRun) {
+      console.log(`  [dry-run] ${path.relative(root, src)} → ${path.relative(root, dest)}`);
+      stats.moved++;
+      return;
+    }
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.renameSync(src, dest);
+      stats.moved++;
+    } catch (err) {
+      stats.errors.push({ src, dest, error: err.message });
+    }
+  }
+
+  const entries = fs.readdirSync(planDir);
+
+  // ─── 1. Quorum round session logs → quorum/rounds/ ────────────────────────
+  for (const e of entries) {
+    if (e.startsWith('quorum-rounds-session-') || (e.startsWith('quorum-rounds-') && e.endsWith('.jsonl'))) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'quorum', 'rounds', e)
+      );
+    }
+  }
+
+  // ─── 2. Quorum slot correlation files → quorum/correlations/ ──────────────
+  for (const e of entries) {
+    if (e.startsWith('quorum-slot-corr-') && e.endsWith('.json')) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'quorum', 'correlations', e)
+      );
+    }
+  }
+
+  // ─── 3. Scoreboard + failures → quorum/ ──────────────────────────────────
+  moveFile(
+    path.join(planDir, 'quorum-scoreboard.json'),
+    path.join(planDir, 'quorum', 'scoreboard.json')
+  );
+  moveFile(
+    path.join(planDir, 'quorum-failures.json'),
+    path.join(planDir, 'quorum', 'failures.json')
+  );
+
+  // ─── 3b. debates/ → quorum/debates/ ────────────────────────────────────
+  const debatesDir = path.join(planDir, 'debates');
+  if (fs.existsSync(debatesDir) && fs.statSync(debatesDir).isDirectory()) {
+    const debateFiles = fs.readdirSync(debatesDir);
+    for (const f of debateFiles) {
+      moveFile(
+        path.join(debatesDir, f),
+        path.join(planDir, 'quorum', 'debates', f)
+      );
+    }
+    // Remove empty debates/ directory
+    if (!dryRun) {
+      try {
+        const remaining = fs.readdirSync(debatesDir);
+        if (remaining.length === 0) fs.rmdirSync(debatesDir);
+      } catch (_) {}
+    }
+  }
+
+  // ─── 4. Telemetry files → telemetry/ ──────────────────────────────────────
+  moveFile(
+    path.join(planDir, 'conformance-events.jsonl'),
+    path.join(planDir, 'telemetry', 'conformance-events.jsonl')
+  );
+  moveFile(
+    path.join(planDir, 'token-usage.jsonl'),
+    path.join(planDir, 'telemetry', 'token-usage.jsonl')
+  );
+
+  // ─── 4. Milestone audit/integration files → milestones/ ───────────────────
+  for (const e of entries) {
+    // v0.X-MILESTONE-AUDIT.md
+    const auditMatch = e.match(/^(v[\d.]+)-MILESTONE-AUDIT\.md$/);
+    if (auditMatch) {
+      // Only move if not already in milestones/
+      const dest = path.join(planDir, 'milestones', e);
+      moveFile(path.join(planDir, e), dest);
+      continue;
+    }
+
+    // v0.X-INTEGRATION-{CHECK,SUMMARY,KEY-FILES,REPORT}.{md,txt}
+    const intMatch = e.match(/^(v[\d.]+)-INTEGRATION-/);
+    if (intMatch) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'milestones', e)
+      );
+      continue;
+    }
+  }
+
+  // ─── 5. State backups → archive/state-backups/ ────────────────────────────
+  for (const e of entries) {
+    if (e.startsWith('STATE.md.bak-')) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'archive', 'state-backups', e)
+      );
+    }
+  }
+
+  // ─── 6. Dated design docs → archive/designs/ ─────────────────────────────
+  for (const e of entries) {
+    if (/^\d{4}-\d{2}-\d{2}-/.test(e)) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'archive', 'designs', e)
+      );
+    }
+  }
+
+  // ─── 7. Old roadmap versions → archive/designs/ ──────────────────────────
+  for (const e of entries) {
+    if (/^ROADMAP-v[\d.]+\.md$/.test(e)) {
+      moveFile(
+        path.join(planDir, e),
+        path.join(planDir, 'archive', 'designs', e)
+      );
+    }
+  }
+
+  // ─── 8. Write .planning/.gitignore ─────────────────────────────────────────
+  if (!dryRun) {
+    const gitignorePath = path.join(planDir, '.gitignore');
+    const gitignoreContent = [
+      '# Auto-generated by migrate-planning.cjs',
+      '# Ephemeral quorum runtime data',
+      'quorum/rounds/',
+      'quorum/correlations/',
+      'quorum/scoreboard.json',
+      'quorum/failures.json',
+      '',
+      '# Telemetry (append-only logs)',
+      'telemetry/conformance-events.jsonl',
+      'telemetry/token-usage.jsonl',
+      '',
+      '# State backups',
+      'archive/state-backups/',
+      '',
+    ].join('\n');
+    fs.writeFileSync(gitignorePath, gitignoreContent, 'utf8');
+  }
+
+  // ─── 9. Write migration marker ────────────────────────────────────────────
+  if (!dryRun && stats.moved > 0) {
+    const markerPath = path.join(planDir, '.migrated');
+    fs.writeFileSync(markerPath, JSON.stringify({
+      version: '0.27',
+      migratedAt: new Date().toISOString(),
+      filesMoved: stats.moved,
+    }, null, 2), 'utf8');
+  }
+
+  return stats;
+}
+
+// ─── CLI entry ───────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const rootIdx = args.indexOf('--root');
+  const root = rootIdx >= 0 ? args[rootIdx + 1] : process.cwd();
+
+  console.log(`[migrate-planning] ${dryRun ? 'DRY RUN — ' : ''}Migrating ${root}/.planning/`);
+  const stats = migrate(root, dryRun);
+  console.log(`[migrate-planning] Done: ${stats.moved} moved, ${stats.skipped} skipped`);
+  if (stats.errors && stats.errors.length) {
+    console.error(`[migrate-planning] Errors:`, stats.errors);
+  }
+}
+
+module.exports = { migrate };

package/bin/migrate-to-slots.cjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// SLOT_MIGRATION_MAP: old model-based names → new slot names
+const SLOT_MIGRATION_MAP = {
+  'codex-cli':         'codex-cli-1',
+  'gemini-cli':        'gemini-cli-1',
+  'opencode':          'opencode-1',
+  'copilot-cli':       'copilot-1',
+  'claude-deepseek':   'claude-1',
+  'claude-minimax':    'claude-2',
+  'claude-qwen-coder': 'claude-3',
+  'claude-kimi':       'claude-4',
+  'claude-llama4':     'claude-5',
+  'claude-glm':        'claude-6',
+};
+
+/**
+ * Migrate ~/.claude.json mcpServers keys from model-based names to slot names.
+ * @param {string} claudeJsonPath - Absolute path to ~/.claude.json
+ * @param {boolean} dryRun - If true, do not write changes
+ * @returns {{ changed: number, renamed: Array<{from: string, to: string}> }}
+ */
+function migrateClaudeJson(claudeJsonPath, dryRun = false) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      return { changed: 0, renamed: [] };
+    }
+    throw new Error(`Failed to read ${claudeJsonPath}: ${e.message}`);
+  }
+
+  const servers = raw.mcpServers || {};
+  let changed = 0;
+  const renamed = [];
+
+  for (const [oldName, newName] of Object.entries(SLOT_MIGRATION_MAP)) {
+    if (servers[oldName] !== undefined && servers[newName] === undefined) {
+      // Rename: assign to new key, delete old key
+      servers[newName] = servers[oldName];
+      delete servers[oldName];
+      changed++;
+      renamed.push({ from: oldName, to: newName });
+    }
+    // oldName absent + newName present → already migrated (skip, idempotent)
+    // both present → skip (safety — don't overwrite)
+  }
+
+  if (changed > 0) {
+    raw.mcpServers = servers;
+    if (!dryRun) {
+      fs.writeFileSync(claudeJsonPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    }
+  }
+
+  return { changed, renamed };
+}
+
+// tool_prefix migration map for qgsd.json
+const QGSD_PREFIX_MAP = {
+  'mcp__codex-cli__':   'mcp__codex-cli-1__',
+  'mcp__gemini-cli__':  'mcp__gemini-cli-1__',
+  'mcp__opencode__':    'mcp__opencode-1__',
+  'mcp__copilot-cli__': 'mcp__copilot-1__',
+};
+
+/**
+ * Migrate ~/.claude/qgsd.json required_models tool_prefix values to slot-based prefixes.
+ * @param {string} qgsdJsonPath - Absolute path to ~/.claude/qgsd.json
+ * @param {boolean} dryRun - If true, do not write changes
+ * @returns {{ changed: number, patched: Array<{key: string, from: string, to: string}> }}
+ */
+function migrateQgsdJson(qgsdJsonPath, dryRun = false) {
+  if (!fs.existsSync(qgsdJsonPath)) {
+    return { changed: 0, patched: [] };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to read ${qgsdJsonPath}: ${e.message}`);
+  }
+
+  const requiredModels = raw.required_models;
+  if (!requiredModels || typeof requiredModels !== 'object') {
+    return { changed: 0, patched: [] };
+  }
+
+  let changed = 0;
+  const patched = [];
+
+  for (const [modelKey, modelDef] of Object.entries(requiredModels)) {
+    if (modelDef && typeof modelDef.tool_prefix === 'string') {
+      const newPrefix = QGSD_PREFIX_MAP[modelDef.tool_prefix];
+      if (newPrefix) {
+        patched.push({ key: modelKey, from: modelDef.tool_prefix, to: newPrefix });
+        modelDef.tool_prefix = newPrefix;
+        changed++;
+      }
+    }
+  }
+
+  if (changed > 0 && !dryRun) {
+    fs.writeFileSync(qgsdJsonPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+  }
+
+  return { changed, patched };
+}
+
+/**
+ * Populate quorum_active in ~/.claude/qgsd.json from current mcpServers in ~/.claude.json.
+ * Idempotent: skips if quorum_active already present and non-empty.
+ * @param {string} qgsdJsonPath - Absolute path to ~/.claude/qgsd.json
+ * @param {string} claudeJsonPath - Absolute path to ~/.claude.json
+ * @param {boolean} dryRun - If true, do not write changes
+ * @returns {{ skipped: boolean, slots: string[] }}
+ */
+function populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun = false) {
+  // Read current slot names from ~/.claude.json
+  let slotNames = [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
+    slotNames = Object.keys(raw.mcpServers || {});
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw new Error(`Failed to read ${claudeJsonPath}: ${e.message}`);
+    // ~/.claude.json absent — nothing to populate
+    return { skipped: true, slots: [] };
+  }
+
+  // Read or create qgsd.json
+  let qgsdConfig = {};
+  try {
+    qgsdConfig = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw new Error(`Failed to read ${qgsdJsonPath}: ${e.message}`);
+    // qgsd.json absent — create minimal object
+  }
+
+  // Idempotent: skip if already set and non-empty
+  if (Array.isArray(qgsdConfig.quorum_active) && qgsdConfig.quorum_active.length > 0) {
+    return { skipped: true, slots: qgsdConfig.quorum_active };
+  }
+
+  // Populate and write
+  qgsdConfig.quorum_active = slotNames;
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(qgsdJsonPath), { recursive: true });
+    fs.writeFileSync(qgsdJsonPath, JSON.stringify(qgsdConfig, null, 2) + '\n', 'utf8');
+  }
+  return { skipped: false, slots: slotNames };
+}
+
+// CLI entrypoint
+if (require.main === module) {
+  const dryRun = process.argv.includes('--dry-run');
+  const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+  const qgsdJsonPath = path.join(os.homedir(), '.claude', 'qgsd.json');
+
+  let r1, r2;
+  try {
+    r1 = migrateClaudeJson(claudeJsonPath, dryRun);
+  } catch (e) {
+    console.error(`Error migrating ~/.claude.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  try {
+    r2 = migrateQgsdJson(qgsdJsonPath, dryRun);
+  } catch (e) {
+    console.error(`Error migrating ~/.claude/qgsd.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  let r3;
+  try {
+    r3 = populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun);
+    if (!r3.skipped) {
+      console.log(`[migrate-to-slots] quorum_active populated: ${r3.slots.join(', ')}`);
+    } else {
+      console.log(`[migrate-to-slots] quorum_active already set (${r3.slots.length} slots) — skipped`);
+    }
+  } catch (e) {
+    console.error(`Error populating quorum_active: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (r1.changed === 0 && r2.changed === 0) {
+    console.log('Already migrated — no changes needed');
+  } else if (dryRun) {
+    const totalRenames = r1.renamed.length + r2.patched.length;
+    console.log(`[DRY RUN] Would rename ${totalRenames} entries:`);
+    for (const { from, to } of r1.renamed) {
+      console.log(`  mcpServers: ${from} → ${to}`);
+    }
+    for (const { key, from, to } of r2.patched) {
+      console.log(`  qgsd.json required_models.${key}.tool_prefix: ${from} → ${to}`);
+    }
+  } else {
+    if (r1.changed > 0) {
+      console.log(`Migrated ${r1.changed} mcpServers entries:`);
+      for (const { from, to } of r1.renamed) {
+        console.log(`  ${from} → ${to}`);
+      }
+    }
+    if (r2.changed > 0) {
+      console.log(`Patched ${r2.changed} qgsd.json tool_prefix values`);
+      for (const { key, from, to } of r2.patched) {
+        console.log(`  required_models.${key}.tool_prefix: ${from} → ${to}`);
+      }
+    }
+  }
+
+  process.exit(0);
+}
+
+/**
+ * Append a single slot name to quorum_active in qgsd.json if not already present.
+ * Idempotent: no-op if slot is already in the array.
+ * @param {string} slotName - e.g. "copilot-2"
+ * @param {string} qgsdJsonPath - path to ~/.claude/qgsd.json
+ * @param {boolean} dryRun - if true, report but do not write
+ * @returns {{ added: boolean, slot: string, skipped: boolean }}
+ */
+function addSlotToQuorumActive(slotName, qgsdJsonPath, dryRun = false) {
+  let qgsdConfig = {};
+  try {
+    if (fs.existsSync(qgsdJsonPath)) {
+      qgsdConfig = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+    }
+  } catch (e) {
+    return { added: false, slot: slotName, skipped: true, error: e.message };
+  }
+
+  const active = Array.isArray(qgsdConfig.quorum_active) ? qgsdConfig.quorum_active : [];
+  if (active.includes(slotName)) {
+    return { added: false, slot: slotName, skipped: true, reason: 'already present' };
+  }
+
+  if (dryRun) {
+    return { added: true, slot: slotName, skipped: false, dryRun: true };
+  }
+
+  qgsdConfig.quorum_active = [...active, slotName];
+  fs.writeFileSync(qgsdJsonPath, JSON.stringify(qgsdConfig, null, 2) + '\n');
+  return { added: true, slot: slotName, skipped: false };
+}
+
+module.exports = { migrateClaudeJson, migrateQgsdJson, populateActiveSlots, addSlotToQuorumActive, SLOT_MIGRATION_MAP };