@nforma.ai/nforma 0.2.1

package/bin/polyrepo.cjs

@@ -0,0 +1,560 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const TAG = '[qgsd-polyrepo]';
+const POLYREPOS_DIR = path.join(os.homedir(), '.claude', 'polyrepos');
+const MARKER_FILE = 'polyrepo.json';
+
+/**
+ * Ensure ~/.claude/polyrepos/ directory exists
+ */
+function ensurePolyreposDir() {
+  try {
+    fs.mkdirSync(POLYREPOS_DIR, { recursive: true });
+  } catch (err) {
+    console.error(`${TAG} Failed to create polyrepos directory:`, err.message);
+    throw err;
+  }
+}
+
+/**
+ * Load a group config from ~/.claude/polyrepos/<name>.json
+ * Returns parsed object or null if not found.
+ * Fail-open: if malformed JSON, log warning and return null.
+ */
+function loadGroup(name) {
+  const filePath = path.join(POLYREPOS_DIR, `${name}.json`);
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      console.error(`${TAG} Warning: malformed JSON in ${filePath}, returning null`);
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save a group config to ~/.claude/polyrepos/<group.name>.json
+ */
+function saveGroup(group) {
+  ensurePolyreposDir();
+  const filePath = path.join(POLYREPOS_DIR, `${group.name}.json`);
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(group, null, 2), 'utf8');
+  } catch (err) {
+    console.error(`${TAG} Failed to save group:`, err.message);
+    throw err;
+  }
+}
+
+/**
+ * Write per-repo marker at <repoPath>/.planning/polyrepo.json
+ * Optional docs: { user?, developer?, examples? } — relative paths within the repo
+ */
+function writeMarker(repoPath, name, role, docs) {
+  try {
+    const markerDir = path.join(repoPath, '.planning');
+    fs.mkdirSync(markerDir, { recursive: true });
+    const markerPath = path.join(markerDir, MARKER_FILE);
+    const marker = { name, role };
+    if (docs && Object.keys(docs).length > 0) {
+      marker.docs = docs;
+    }
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2), 'utf8');
+  } catch (err) {
+    console.error(`${TAG} Failed to write marker:`, err.message);
+    throw err;
+  }
+}
+
+/**
+ * Read per-repo marker from <repoPath>/.planning/polyrepo.json
+ * Returns parsed object or null if not found/malformed.
+ */
+function readMarker(repoPath) {
+  try {
+    const markerPath = path.join(repoPath, '.planning', MARKER_FILE);
+    if (!fs.existsSync(markerPath)) return null;
+    return JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      console.error(`${TAG} Warning: malformed marker at ${repoPath}`);
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Set docs paths on an existing per-repo marker.
+ * docs: { user?, developer?, examples? } — relative paths within the repo.
+ * Merges with existing docs (pass null value to remove a key).
+ */
+function setDocs(repoPath, docs) {
+  const marker = readMarker(repoPath);
+  if (!marker) {
+    return { ok: false, error: `No polyrepo marker found at ${repoPath}/.planning/polyrepo.json` };
+  }
+  const merged = { ...(marker.docs || {}) };
+  for (const [key, val] of Object.entries(docs)) {
+    if (val === null) {
+      delete merged[key];
+    } else {
+      merged[key] = val;
+    }
+  }
+  marker.docs = Object.keys(merged).length > 0 ? merged : undefined;
+  try {
+    const markerPath = path.join(repoPath, '.planning', MARKER_FILE);
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2), 'utf8');
+    return { ok: true, docs: merged };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Remove per-repo marker at <repoPath>/.planning/polyrepo.json
+ * Fail-open: no error if file doesn't exist
+ */
+function removeMarker(repoPath) {
+  try {
+    const markerPath = path.join(repoPath, '.planning', MARKER_FILE);
+    if (fs.existsSync(markerPath)) {
+      fs.unlinkSync(markerPath);
+    }
+  } catch (err) {
+    console.error(`${TAG} Warning: failed to remove marker:`, err.message);
+    // Fail-open: don't throw
+  }
+}
+
+/**
+ * Validate group name: alphanumeric + hyphens, 1-50 chars, lowercase, start with alphanumeric
+ */
+function validateGroupName(name) {
+  const nameRegex = /^[a-z0-9][a-z0-9-]*$/;
+  if (!name || typeof name !== 'string') {
+    return { ok: false, error: 'Name must be a non-empty string' };
+  }
+  if (name.length > 50) {
+    return { ok: false, error: 'Name must be 1-50 characters' };
+  }
+  if (!nameRegex.test(name)) {
+    return { ok: false, error: 'Name must start with alphanumeric and contain only lowercase alphanumeric and hyphens' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Create a new polyrepo group with optional initial repos
+ * repos: array of { role, path, planning? }
+ * Empty repos array is valid (used by interactive create flow).
+ */
+function createGroup(name, repos = []) {
+  // Validate name
+  const nameVal = validateGroupName(name);
+  if (!nameVal.ok) {
+    return nameVal;
+  }
+
+  // Check if group already exists
+  if (loadGroup(name) !== null) {
+    return { ok: false, error: `Group '${name}' already exists` };
+  }
+
+  // Validate repos
+  if (!Array.isArray(repos)) {
+    return { ok: false, error: 'Repos must be an array' };
+  }
+
+  const seenPaths = new Set();
+  for (const repo of repos) {
+    if (typeof repo.role !== 'string' || repo.role.length === 0) {
+      return { ok: false, error: 'Each repo must have a non-empty role string' };
+    }
+    if (typeof repo.path !== 'string' || !path.isAbsolute(repo.path)) {
+      return { ok: false, error: `Repo path must be absolute: ${repo.path}` };
+    }
+    if (!fs.existsSync(repo.path)) {
+      return { ok: false, error: `Repo path does not exist: ${repo.path}` };
+    }
+    if (!fs.statSync(repo.path).isDirectory()) {
+      return { ok: false, error: `Repo path is not a directory: ${repo.path}` };
+    }
+    if (seenPaths.has(repo.path)) {
+      return { ok: false, error: `Duplicate path in group: ${repo.path}` };
+    }
+    seenPaths.add(repo.path);
+  }
+
+  // Create group
+  const group = {
+    name,
+    repos: repos.map(r => ({
+      role: r.role,
+      path: r.path,
+      planning: r.planning !== false ? true : false
+    }))
+  };
+
+  try {
+    saveGroup(group);
+    // Write markers for repos with planning: true
+    for (const repo of group.repos) {
+      if (repo.planning) {
+        writeMarker(repo.path, name, repo.role);
+      }
+    }
+    return { ok: true, group };
+  } catch (err) {
+    return { ok: false, error: `Failed to create group: ${err.message}` };
+  }
+}
+
+/**
+ * Add a repo to an existing group
+ */
+function addRepo(groupName, repoPath, role, planning = true) {
+  // Load group
+  const group = loadGroup(groupName);
+  if (!group) {
+    return { ok: false, error: `Group '${groupName}' does not exist` };
+  }
+
+  // Validate repo path
+  if (typeof repoPath !== 'string' || !path.isAbsolute(repoPath)) {
+    return { ok: false, error: `Repo path must be absolute: ${repoPath}` };
+  }
+  if (!fs.existsSync(repoPath)) {
+    return { ok: false, error: `Repo path does not exist: ${repoPath}` };
+  }
+  if (!fs.statSync(repoPath).isDirectory()) {
+    return { ok: false, error: `Repo path is not a directory: ${repoPath}` };
+  }
+
+  // Check for duplicates
+  if (group.repos.some(r => r.path === repoPath)) {
+    return { ok: false, error: `Repo path already in group: ${repoPath}` };
+  }
+
+  // Validate role
+  if (typeof role !== 'string' || role.length === 0) {
+    return { ok: false, error: 'Role must be a non-empty string' };
+  }
+
+  // Add repo
+  try {
+    group.repos.push({
+      role,
+      path: repoPath,
+      planning: planning !== false ? true : false
+    });
+    saveGroup(group);
+    if (planning !== false) {
+      writeMarker(repoPath, groupName, role);
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: `Failed to add repo: ${err.message}` };
+  }
+}
+
+/**
+ * Remove a repo from a group
+ * If group becomes empty, delete the group config file entirely.
+ */
+function removeRepo(groupName, repoPath) {
+  // Load group
+  const group = loadGroup(groupName);
+  if (!group) {
+    return { ok: false, error: `Group '${groupName}' does not exist` };
+  }
+
+  // Find and remove repo
+  const initialLength = group.repos.length;
+  group.repos = group.repos.filter(r => r.path !== repoPath);
+
+  if (group.repos.length === initialLength) {
+    return { ok: false, error: `Repo not found in group: ${repoPath}` };
+  }
+
+  try {
+    removeMarker(repoPath);
+
+    // If group is now empty, delete the group config file
+    if (group.repos.length === 0) {
+      const filePath = path.join(POLYREPOS_DIR, `${groupName}.json`);
+      fs.unlinkSync(filePath);
+      return { ok: true, deleted_group: true };
+    } else {
+      saveGroup(group);
+      return { ok: true };
+    }
+  } catch (err) {
+    return { ok: false, error: `Failed to remove repo: ${err.message}` };
+  }
+}
+
+/**
+ * List all polyrepo groups
+ */
+function listGroups() {
+  try {
+    ensurePolyreposDir();
+    if (!fs.existsSync(POLYREPOS_DIR)) {
+      return [];
+    }
+    const files = fs.readdirSync(POLYREPOS_DIR);
+    const groups = [];
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      const group = loadGroup(file.replace(/\.json$/, ''));
+      if (group) {
+        groups.push(group);
+      }
+    }
+    return groups;
+  } catch (err) {
+    console.error(`${TAG} Failed to list groups:`, err.message);
+    return [];
+  }
+}
+
+/**
+ * Load a single group by name
+ */
+function listGroup(name) {
+  return loadGroup(name);
+}
+
+/**
+ * CLI Subcommand Handler
+ */
+function handleCLI() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`${TAG} Polyrepo Config Management
+
+Usage:
+  node polyrepo.cjs create <name>
+  node polyrepo.cjs add <group> <path> [role] [--no-planning]
+  node polyrepo.cjs remove <group> <path>
+  node polyrepo.cjs list [group]
+  node polyrepo.cjs info
+  node polyrepo.cjs docs [show|set|remove]
+  node polyrepo.cjs --help
+
+Commands:
+  create <name>           Create an empty polyrepo group
+  add <group> <path> [role] [--no-planning]
+                          Add a repo to a group (role defaults to basename)
+  remove <group> <path>   Remove a repo from a group
+  list [group]            List all groups or repos in a specific group
+  info                    Show this repo's polyrepo group membership
+  docs show               Show doc paths for current repo
+  docs set <key> <path>   Set a doc path (user, developer, examples, or custom)
+  docs remove <key>       Remove a doc path
+  --help                  Show this help message
+`);
+    return;
+  }
+
+  if (cmd === 'create') {
+    const name = args[1];
+    if (!name) {
+      console.error(`${TAG} create: missing name argument`);
+      process.exit(1);
+    }
+    const result = createGroup(name, []);
+    if (result.ok) {
+      process.stdout.write(`${TAG} Created group '${name}' at ${POLYREPOS_DIR}/${name}.json\n`);
+    } else {
+      console.error(`${TAG} Error: ${result.error}`);
+      process.exit(1);
+    }
+  } else if (cmd === 'add') {
+    const group = args[1];
+    const repoPath = args[2];
+    let role = args[3];
+    const noPlanning = args.includes('--no-planning');
+
+    if (!group || !repoPath) {
+      console.error(`${TAG} add: missing group or path argument`);
+      process.exit(1);
+    }
+
+    // Default role to basename if not provided
+    if (!role || role.startsWith('--')) {
+      role = path.basename(repoPath);
+    }
+
+    const result = addRepo(group, repoPath, role, !noPlanning);
+    if (result.ok) {
+      process.stdout.write(`${TAG} Added '${role}' (${repoPath}) to group '${group}'\n`);
+    } else {
+      console.error(`${TAG} Error: ${result.error}`);
+      process.exit(1);
+    }
+  } else if (cmd === 'remove') {
+    const group = args[1];
+    const repoPath = args[2];
+    if (!group || !repoPath) {
+      console.error(`${TAG} remove: missing group or path argument`);
+      process.exit(1);
+    }
+    const result = removeRepo(group, repoPath);
+    if (result.ok) {
+      if (result.deleted_group) {
+        process.stdout.write(`${TAG} Removed repo from group '${group}'. Group was empty, so config deleted.\n`);
+      } else {
+        process.stdout.write(`${TAG} Removed repo from group '${group}'\n`);
+      }
+    } else {
+      console.error(`${TAG} Error: ${result.error}`);
+      process.exit(1);
+    }
+  } else if (cmd === 'list') {
+    const groupName = args[1];
+    if (groupName) {
+      const group = listGroup(groupName);
+      if (!group) {
+        console.error(`${TAG} Group '${groupName}' not found`);
+        process.exit(1);
+      }
+      process.stdout.write(`\nPolyrepo Group: ${group.name}\n`);
+      for (const repo of group.repos) {
+        const planning = repo.planning ? '[planning]' : '[no planning]';
+        process.stdout.write(`  ${repo.role.padEnd(15)} ${repo.path.padEnd(30)} ${planning}\n`);
+      }
+      process.stdout.write('\n');
+    } else {
+      const groups = listGroups();
+      if (groups.length === 0) {
+        process.stdout.write(`${TAG} No polyrepo groups defined\n`);
+      } else {
+        process.stdout.write('\nPolyrepo Groups:\n');
+        for (const group of groups) {
+          process.stdout.write(`  ${group.name} (${group.repos.length} repos)\n`);
+          for (const repo of group.repos) {
+            const planning = repo.planning ? '[planning]' : '[no planning]';
+            process.stdout.write(`    ${repo.role.padEnd(15)} ${repo.path.padEnd(30)} ${planning}\n`);
+          }
+        }
+        process.stdout.write('\n');
+      }
+    }
+  } else if (cmd === 'info') {
+    const cwd = process.cwd();
+    const marker = readMarker(cwd);
+    if (!marker) {
+      process.stdout.write(`${TAG} This repo is not part of any polyrepo group\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`\nThis repo belongs to polyrepo group: ${marker.name}\n`);
+    process.stdout.write(`Role: ${marker.role}\n`);
+    const group = listGroup(marker.name);
+    if (group) {
+      const repo = group.repos.find(r => r.path === cwd);
+      process.stdout.write(`Planning: ${(repo ? repo.planning : true) ? 'yes' : 'no'}\n`);
+    } else {
+      process.stdout.write(`Planning: yes\n`);
+    }
+    if (marker.docs) {
+      process.stdout.write(`Docs:\n`);
+      for (const [key, val] of Object.entries(marker.docs)) {
+        process.stdout.write(`  ${key.padEnd(12)} ${val}\n`);
+      }
+    }
+    process.stdout.write('\n');
+  } else if (cmd === 'docs') {
+    const subcmd = args[1];
+    const cwd = process.cwd();
+    if (!subcmd || subcmd === 'show') {
+      const marker = readMarker(cwd);
+      if (!marker) {
+        console.error(`${TAG} No polyrepo marker found in current directory`);
+        process.exit(1);
+      }
+      if (!marker.docs || Object.keys(marker.docs).length === 0) {
+        process.stdout.write(`${TAG} No docs paths configured for this repo\n`);
+      } else {
+        process.stdout.write(`\nDocs paths for ${marker.name} (${marker.role}):\n`);
+        for (const [key, val] of Object.entries(marker.docs)) {
+          process.stdout.write(`  ${key.padEnd(12)} ${val}\n`);
+        }
+        process.stdout.write('\n');
+      }
+    } else if (subcmd === 'set') {
+      // docs set <key> <path>
+      const key = args[2];
+      const docPath = args[3];
+      if (!key || !docPath) {
+        console.error(`${TAG} docs set: usage: docs set <key> <path>`);
+        console.error(`  Keys: user, developer, examples (or any custom key)`);
+        process.exit(1);
+      }
+      const result = setDocs(cwd, { [key]: docPath });
+      if (result.ok) {
+        process.stdout.write(`${TAG} Set docs.${key} = ${docPath}\n`);
+      } else {
+        console.error(`${TAG} Error: ${result.error}`);
+        process.exit(1);
+      }
+    } else if (subcmd === 'remove') {
+      const key = args[2];
+      if (!key) {
+        console.error(`${TAG} docs remove: usage: docs remove <key>`);
+        process.exit(1);
+      }
+      const result = setDocs(cwd, { [key]: null });
+      if (result.ok) {
+        process.stdout.write(`${TAG} Removed docs.${key}\n`);
+      } else {
+        console.error(`${TAG} Error: ${result.error}`);
+        process.exit(1);
+      }
+    } else {
+      console.error(`${TAG} docs: unknown subcommand '${subcmd}'. Use: show, set, remove`);
+      process.exit(1);
+    }
+  } else {
+    console.error(`${TAG} Unknown command: ${cmd}`);
+    process.exit(1);
+  }
+}
+
+// Export for testability
+module.exports = {
+  createGroup,
+  addRepo,
+  removeRepo,
+  listGroups,
+  listGroup,
+  loadGroup,
+  saveGroup,
+  writeMarker,
+  readMarker,
+  removeMarker,
+  setDocs,
+  ensurePolyreposDir,
+  POLYREPOS_DIR,
+  MARKER_FILE
+};
+
+// Run CLI if executed directly
+if (require.main === module) {
+  handleCLI();
+}

package/bin/prism-priority.cjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+'use strict';
+// bin/prism-priority.cjs
+// PRISM failure probability priority ranker for roadmap signal injection.
+// Requirements: SIG-03
+//
+// Usage:
+//   node bin/prism-priority.cjs [--path=check-results.ndjson]
+//
+// Reads check-results.ndjson, extracts PRISM failure entries, ranks by
+// P(failure) x impact, and outputs a formatted priority signal block
+// for injection into plan-phase.md quorum context.
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Impact score map ─────────────────────────────────────────────────────────
+const IMPACT_SCORES = {
+  'prism:quorum':           10,
+  'prism:mcp-availability': 7,
+};
+const DEFAULT_IMPACT = 5;
+
+/**
+ * readPrismResults(ndjsonPath) — reads check-results.ndjson and filters PRISM entries.
+ * @param {string} [ndjsonPath] - path to check-results.ndjson
+ * @returns {Array<{ check_id: string, result: string, summary: string, timestamp: string, metadata: object }>}
+ */
+function readPrismResults(ndjsonPath) {
+  const p = ndjsonPath || path.join(process.cwd(), '.planning', 'formal', 'check-results.ndjson');
+  try {
+    if (!fs.existsSync(p)) return [];
+    const raw = fs.readFileSync(p, 'utf8');
+    const lines = raw.split('\n').filter(l => l.trim().length > 0);
+
+    // Parse and filter for PRISM entries
+    const prismEntries = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.formalism === 'prism') {
+          prismEntries.push({
+            check_id:  entry.check_id || 'unknown',
+            result:    entry.result || 'unknown',
+            summary:   entry.summary || '',
+            timestamp: entry.timestamp || '',
+            metadata:  entry.metadata || {},
+          });
+        }
+      } catch (_) { /* skip malformed lines */ }
+    }
+
+    // Group by check_id, keep only most recent entry per check_id
+    const byCheckId = new Map();
+    for (const entry of prismEntries) {
+      const existing = byCheckId.get(entry.check_id);
+      if (!existing || entry.timestamp > existing.timestamp) {
+        byCheckId.set(entry.check_id, entry);
+      }
+    }
+
+    return Array.from(byCheckId.values());
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * rankFailureModes(prismResults) — ranks failure modes by P(failure) x impact.
+ * @param {Array<{ check_id: string, result: string, summary: string, timestamp: string, metadata: object }>} prismResults
+ * @returns {Array<{ check_id: string, priority: number, p_failure: number, impact: number, summary: string }>}
+ */
+function rankFailureModes(prismResults) {
+  const failures = prismResults.filter(e => e.result === 'fail' || e.result === 'warn');
+  if (failures.length === 0) return [];
+
+  const ranked = failures.map(entry => {
+    // Determine P(failure)
+    let p_failure;
+    if (entry.result === 'fail') {
+      p_failure = 1.0;
+    } else {
+      // warn results — uncertain, use 0.5
+      p_failure = 0.5;
+    }
+
+    // Determine impact
+    const impact = IMPACT_SCORES[entry.check_id] || DEFAULT_IMPACT;
+
+    // Compute priority
+    const priority = Math.round(p_failure * impact * 100) / 100;
+
+    return {
+      check_id:  entry.check_id,
+      priority,
+      p_failure,
+      impact,
+      summary:   entry.summary,
+    };
+  });
+
+  // Sort descending by priority
+  ranked.sort((a, b) => b.priority - a.priority);
+
+  return ranked;
+}
+
+/**
+ * formatPrioritySignal(rankedModes) — produces formatted text block for quorum injection.
+ * @param {Array<{ check_id: string, priority: number, p_failure: number, impact: number, summary: string }>} rankedModes
+ * @returns {string|null} - formatted text block, or null if no failures
+ */
+function formatPrioritySignal(rankedModes) {
+  if (!rankedModes || rankedModes.length === 0) return null;
+
+  const lines = [
+    '=== PRISM Priority Signal ===',
+    'Failure modes ranked by P(failure) x impact:',
+  ];
+
+  for (let i = 0; i < rankedModes.length; i++) {
+    const mode = rankedModes[i];
+    lines.push(
+      (i + 1) + '. [' + mode.check_id + '] priority=' + mode.priority.toFixed(1) +
+      ' -- P(fail)=' + mode.p_failure.toFixed(1) +
+      ', impact=' + mode.impact +
+      ' -- "' + mode.summary + '"'
+    );
+  }
+
+  lines.push('=============================');
+
+  return lines.join('\n');
+}
+
+// ── CLI entrypoint ───────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const pathArg = args.find(a => a.startsWith('--path='));
+  const ndjsonPath = pathArg ? pathArg.split('=')[1] : undefined;
+
+  const results = readPrismResults(ndjsonPath);
+  const ranked  = rankFailureModes(results);
+  const signal  = formatPrioritySignal(ranked);
+
+  if (signal) {
+    process.stdout.write(signal + '\n');
+  } else {
+    process.stderr.write('No PRISM failures found\n');
+  }
+}
+
+module.exports = { readPrismResults, rankFailureModes, formatPrioritySignal };