@nforma.ai/nforma 0.2.1

package/bin/sync-baseline-requirements.cjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Internal helper: merge baseline into existing requirements.
+ * Handles the core sync logic (steps 2-7 from original implementation).
+ */
+function _syncFromBaseline(baseline, projectRoot) {
+  const root = projectRoot || process.cwd();
+
+  // 2. Read existing requirements
+  const reqPath = path.join(root, '.planning', 'formal', 'requirements.json');
+  let rawEnvelope;
+  let requirements;
+
+  if (fs.existsSync(reqPath)) {
+    try {
+      rawEnvelope = JSON.parse(fs.readFileSync(reqPath, 'utf8'));
+      requirements = rawEnvelope.requirements || [];
+    } catch (_) {
+      rawEnvelope = {};
+      requirements = [];
+    }
+  } else {
+    // Create .formal directory if needed
+    fs.mkdirSync(path.join(root, '.planning', 'formal'), { recursive: true });
+    rawEnvelope = {};
+    requirements = [];
+  }
+
+  // 3. Build lookup of existing requirement texts -> id
+  const existingTexts = new Map(requirements.map(r => [r.text, r.id]));
+
+  // 4. Build map of highest existing ID number per prefix
+  const maxId = {};
+  for (const r of requirements) {
+    if (!r.id) continue;
+    const dashIdx = r.id.lastIndexOf('-');
+    if (dashIdx === -1) continue;
+    const prefix = r.id.substring(0, dashIdx);
+    const num = parseInt(r.id.substring(dashIdx + 1), 10);
+    if (!isNaN(num)) {
+      maxId[prefix] = Math.max(maxId[prefix] || 0, num);
+    }
+  }
+
+  const added = [];
+  const skipped = [];
+  const totalBefore = requirements.length;
+
+  // 5-6. Process each baseline category
+  for (const cat of baseline.categories) {
+    if (!cat.requirements || cat.requirements.length === 0) continue;
+
+    // Derive prefix from first requirement's ID (e.g., "UX-01" -> "UX")
+    const firstId = cat.requirements[0].id;
+    const dashIdx = firstId.lastIndexOf('-');
+    const prefix = firstId.substring(0, dashIdx);
+
+    for (const req of cat.requirements) {
+      if (existingTexts.has(req.text)) {
+        // 6a. Skip duplicate
+        skipped.push({
+          id: req.id,
+          text: req.text,
+          existingId: existingTexts.get(req.text),
+        });
+      } else {
+        // 6c. Assign next available ID
+        maxId[prefix] = (maxId[prefix] || 0) + 1;
+        const padLen = maxId[prefix] > 99 ? String(maxId[prefix]).length : 2;
+        const newId = prefix + '-' + String(maxId[prefix]).padStart(padLen, '0');
+
+        const newReq = {
+          id: newId,
+          text: req.text,
+          category: cat.name,
+          phase: 'baseline',
+          status: 'Pending',
+          provenance: {
+            source_file: 'qgsd-baseline',
+            milestone: 'baseline',
+          },
+        };
+
+        requirements.push(newReq);
+        existingTexts.set(req.text, newId);
+        added.push({ id: newId, text: req.text });
+      }
+    }
+  }
+
+  // 7. Write if anything was added
+  if (added.length > 0) {
+    const contentHash = 'sha256:' + crypto
+      .createHash('sha256')
+      .update(JSON.stringify(requirements, null, 2))
+      .digest('hex');
+
+    // Defensive: only write if hash actually changed
+    const existingHash = rawEnvelope.content_hash || null;
+    if (existingHash !== contentHash) {
+      const envelope = {
+        aggregated_at: new Date().toISOString(),
+        content_hash: contentHash,
+        frozen_at: rawEnvelope.frozen_at || null,
+        schema_version: rawEnvelope.schema_version || undefined,
+        requirements,
+      };
+
+      // Remove undefined keys
+      if (envelope.schema_version === undefined) delete envelope.schema_version;
+
+      fs.writeFileSync(reqPath, JSON.stringify(envelope, null, 2) + '\n');
+    }
+  }
+
+  return {
+    added,
+    skipped,
+    total_before: totalBefore,
+    total_after: requirements.length,
+  };
+}
+
+/**
+ * Merge baseline requirements into .planning/formal/requirements.json.
+ * Idempotent: matches on exact `text` field to skip duplicates.
+ * Assigns next-available IDs per category prefix for new entries.
+ *
+ * @param {string} profile - One of: web, mobile, desktop, api, cli, library
+ * @param {string} [projectRoot] - Path to project root, defaults to process.cwd()
+ * @returns {{ added: Array, skipped: Array, total_before: number, total_after: number }}
+ */
+function syncBaselineRequirements(profile, projectRoot) {
+  const root = projectRoot || process.cwd();
+
+  // 1. Load baseline requirements
+  let baseline;
+  try {
+    const { loadBaselineRequirements } = require('./load-baseline-requirements.cjs');
+    baseline = loadBaselineRequirements(profile);
+  } catch (err) {
+    console.error(`Error loading baseline requirements: ${err.message}`);
+    process.exit(2);
+  }
+
+  return _syncFromBaseline(baseline, root);
+}
+
+/**
+ * Merge intent-based baseline requirements into .planning/formal/requirements.json.
+ * Idempotent: matches on exact `text` field to skip duplicates.
+ * Assigns next-available IDs per category prefix for new entries.
+ *
+ * @param {Object} intent - Intent object with base_profile and optional dimensions
+ * @param {string} [projectRoot] - Path to project root, defaults to process.cwd()
+ * @returns {{ added: Array, skipped: Array, total_before: number, total_after: number }}
+ */
+function syncBaselineRequirementsFromIntent(intent, projectRoot) {
+  const root = projectRoot || process.cwd();
+
+  // 1. Load baseline requirements from intent
+  let baseline;
+  try {
+    const { loadBaselineRequirementsFromIntent } = require('./load-baseline-requirements.cjs');
+    baseline = loadBaselineRequirementsFromIntent(intent);
+  } catch (err) {
+    console.error(`Error loading baseline requirements: ${err.message}`);
+    process.exit(2);
+  }
+
+  return _syncFromBaseline(baseline, root);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function printReport(result, profile) {
+  console.log(`Baseline sync: ${profile} profile`);
+  console.log(`  Before: ${result.total_before} requirements`);
+  console.log(`  Added:  ${result.added.length} new requirements`);
+  console.log(`  Skipped: ${result.skipped.length} (already present by text match)`);
+  console.log(`  After:  ${result.total_after} requirements`);
+
+  if (result.added.length > 0) {
+    console.log('\nAdded:');
+    for (const a of result.added) {
+      console.log(`  + [${a.id}] ${a.text}`);
+    }
+  }
+
+  if (result.skipped.length > 0) {
+    console.log('\nSkipped:');
+    for (const s of result.skipped) {
+      console.log(`  ~ [${s.id}] matched existing [${s.existingId}]`);
+    }
+  }
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  // --json flag
+  const jsonOutput = args.includes('--json');
+
+  // --detect is deprecated (auto-detect is now the default behavior) — silently strip it
+  const cleanArgs = args.filter(arg => arg !== '--detect');
+
+  // Priority: --intent-file > --profile > config.json intent > config.json profile > AUTO-DETECT
+
+  // Check --intent-file
+  const intentFileIdx = cleanArgs.indexOf('--intent-file');
+  if (intentFileIdx !== -1 && cleanArgs[intentFileIdx + 1]) {
+    try {
+      const intentFilePath = cleanArgs[intentFileIdx + 1];
+      const intentContent = fs.readFileSync(intentFilePath, 'utf8');
+      const intent = JSON.parse(intentContent);
+      const result = syncBaselineRequirementsFromIntent(intent);
+      if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printReport(result, `intent (base_profile: ${intent.base_profile})`);
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error loading intent file: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Parse --profile
+  const profileIdx = cleanArgs.indexOf('--profile');
+  let profile = null;
+
+  if (profileIdx !== -1 && cleanArgs[profileIdx + 1]) {
+    profile = cleanArgs[profileIdx + 1];
+  } else {
+    // Try reading from .planning/config.json (intent first, then profile)
+    try {
+      const config = JSON.parse(fs.readFileSync(
+        path.join(process.cwd(), '.planning/config.json'), 'utf8'
+      ));
+      if (config.intent) {
+        const result = syncBaselineRequirementsFromIntent(config.intent);
+        if (jsonOutput) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          printReport(result, `config intent (base_profile: ${config.intent.base_profile})`);
+        }
+        process.exit(0);
+      }
+      profile = config.profile;
+    } catch (_) {}
+  }
+
+  // If no profile found, auto-detect (new default behavior)
+  if (!profile) {
+    try {
+      const { detectProjectIntent } = require('./detect-project-intent.cjs');
+      const detectionResult = detectProjectIntent(process.cwd());
+      const intent = detectionResult.suggested;
+      const result = syncBaselineRequirementsFromIntent(intent);
+      if (jsonOutput) {
+        console.log(JSON.stringify({ ...result, detection: detectionResult }, null, 2));
+      } else {
+        printReport(result, `auto-detected intent (base_profile: ${intent.base_profile})`);
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error auto-detecting project intent: ${err.message}`);
+      console.error('Hint: use --profile <web|mobile|desktop|api|cli|library> to specify manually');
+      process.exit(1);
+    }
+  }
+
+  const result = syncBaselineRequirements(profile);
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printReport(result, profile);
+  }
+}
+
+module.exports = { syncBaselineRequirements, syncBaselineRequirementsFromIntent };

package/bin/task-envelope.cjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+// bin/task-envelope.cjs
+// Task envelope CLI tool for structured research→plan→quorum handoff
+// Provides: init, update, read, validate commands + exported validation functions
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Schema definition
+const ENVELOPE_SCHEMA = {
+  schema_version: 'string (must be "1")',
+  phase: 'string (must match v\\d+\\.\\d+-\\d{2})',
+  created_at: 'string (ISO 8601, auto-generated)',
+  risk_level: 'string (low|medium|high)',
+  research: 'object (optional)',
+  plan: 'object (optional)',
+  quorum: 'object (optional)'
+};
+
+// Validate envelope against schema
+function validateEnvelope(obj) {
+  const errors = [];
+
+  if (!obj || typeof obj !== 'object') {
+    errors.push('Envelope must be an object');
+    return { valid: false, errors };
+  }
+
+  // Check schema_version
+  if (typeof obj.schema_version !== 'string' || obj.schema_version !== '1') {
+    errors.push('schema_version must be string "1"');
+  }
+
+  // Check phase format: v\d+\.\d+-\d{2}
+  if (!obj.phase || typeof obj.phase !== 'string' || !/^v\d+\.\d+-\d{2}/.test(obj.phase)) {
+    errors.push('phase must match format v\\d+\\.\\d+-\\d{2} (e.g., v0.18-03)');
+  }
+
+  // Check risk_level
+  if (!obj.risk_level || !['low', 'medium', 'high'].includes(obj.risk_level)) {
+    errors.push('risk_level must be one of: low, medium, high');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// Find phase directory in .planning/phases/
+function findPhaseDir(phaseId) {
+  const phasesDir = path.join(process.cwd(), '.planning', 'phases');
+
+  if (!fs.existsSync(phasesDir)) {
+    return null;
+  }
+
+  // Look for directory matching phaseId or phaseId-*
+  const dirs = fs.readdirSync(phasesDir);
+  const match = dirs.find(d => d === phaseId || d.startsWith(phaseId + '-'));
+
+  if (!match) {
+    return null;
+  }
+
+  return path.join(phasesDir, match);
+}
+
+// Get envelope path for a phase
+function getEnvelopePath(phaseId) {
+  const phaseDir = findPhaseDir(phaseId);
+  if (!phaseDir) {
+    return null;
+  }
+  return path.join(phaseDir, 'task-envelope.json');
+}
+
+// Write JSON atomically: tmpPath + renameSync
+function writeAtomicJson(targetPath, obj) {
+  const dir = path.dirname(targetPath);
+
+  // Ensure directory exists
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = `${targetPath}.${Date.now()}.tmp`;
+
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(obj, null, 2), 'utf8');
+    fs.renameSync(tmpPath, targetPath);
+    return true;
+  } catch (e) {
+    // Clean up temp file if rename failed
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {}
+    throw e;
+  }
+}
+
+// Parse comma-separated arguments into array
+function parseCommaList(str) {
+  if (!str) return [];
+  return str.split(',').map(s => s.trim()).filter(s => s.length > 0);
+}
+
+// main: handle CLI commands
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    process.stderr.write('[task-envelope] ERROR: no command specified\n');
+    process.stderr.write('Usage: task-envelope.cjs <init|update|read|validate> [options]\n');
+    process.exit(1);
+  }
+
+  const command = args[0];
+
+  try {
+    if (command === 'init') {
+      commandInit(args);
+    } else if (command === 'update') {
+      commandUpdate(args);
+    } else if (command === 'read') {
+      commandRead(args);
+    } else if (command === 'validate') {
+      commandValidate(args);
+    } else {
+      process.stderr.write(`[task-envelope] ERROR: unknown command "${command}"\n`);
+      process.exit(1);
+    }
+  } catch (e) {
+    process.stderr.write(`[task-envelope] ERROR: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Command: init
+function commandInit(args) {
+  // Parse arguments
+  let phase, objective = '', constraints = '', targetFiles = [], confidence = 'HIGH', riskLevel = 'medium';
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--phase' && i + 1 < args.length) {
+      phase = args[++i];
+    } else if (args[i] === '--objective' && i + 1 < args.length) {
+      objective = args[++i];
+    } else if (args[i] === '--constraints' && i + 1 < args.length) {
+      constraints = args[++i];
+    } else if (args[i] === '--target-files' && i + 1 < args.length) {
+      targetFiles = parseCommaList(args[++i]);
+    } else if (args[i] === '--confidence' && i + 1 < args.length) {
+      confidence = args[++i];
+    } else if (args[i] === '--risk-level' && i + 1 < args.length) {
+      riskLevel = args[++i];
+    }
+  }
+
+  if (!phase) {
+    process.stderr.write('[task-envelope] ERROR: --phase is required\n');
+    process.exit(1);
+  }
+
+  // Validate risk_level
+  const validRiskLevels = ['low', 'medium', 'high'];
+  let finalRiskLevel = riskLevel;
+  if (!validRiskLevels.includes(riskLevel)) {
+    process.stderr.write(`[task-envelope] WARNING: invalid risk_level "${riskLevel}"; using "medium"\n`);
+    finalRiskLevel = 'medium';
+  }
+
+  // Find phase directory
+  const phaseDir = findPhaseDir(phase);
+  if (!phaseDir) {
+    process.stderr.write(`[task-envelope] ERROR: phase directory not found for "${phase}"\n`);
+    process.exit(1);
+  }
+
+  // Create envelope object
+  const envelope = {
+    schema_version: '1',
+    phase,
+    created_at: new Date().toISOString(),
+    risk_level: finalRiskLevel,
+    research: {
+      objective,
+      constraints,
+      target_files: targetFiles,
+      confidence
+    }
+  };
+
+  // Validate and write
+  const validation = validateEnvelope(envelope);
+  if (!validation.valid) {
+    process.stderr.write(`[task-envelope] ERROR: invalid envelope: ${validation.errors.join('; ')}\n`);
+    process.exit(1);
+  }
+
+  const envelopePath = path.join(phaseDir, 'task-envelope.json');
+  writeAtomicJson(envelopePath, envelope);
+  console.log(`[task-envelope] initialized: ${envelopePath}`);
+}
+
+// Command: update
+function commandUpdate(args) {
+  // Parse arguments
+  let section = null;
+  let phase, planPath, keyDecisions = [], waveCount = null;
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--section' && i + 1 < args.length) {
+      section = args[++i];
+    } else if (args[i] === '--phase' && i + 1 < args.length) {
+      phase = args[++i];
+    } else if (args[i] === '--plan-path' && i + 1 < args.length) {
+      planPath = args[++i];
+    } else if (args[i] === '--key-decisions' && i + 1 < args.length) {
+      keyDecisions = parseCommaList(args[++i]);
+    } else if (args[i] === '--wave-count' && i + 1 < args.length) {
+      waveCount = parseInt(args[++i], 10);
+    }
+  }
+
+  if (!section) {
+    process.stderr.write('[task-envelope] ERROR: --section is required for update\n');
+    process.exit(1);
+  }
+
+  if (!phase) {
+    process.stderr.write('[task-envelope] ERROR: --phase is required\n');
+    process.exit(1);
+  }
+
+  if (section === 'plan' && !planPath) {
+    process.stderr.write('[task-envelope] ERROR: --plan-path is required for --section plan\n');
+    process.exit(1);
+  }
+
+  // Find phase directory
+  const phaseDir = findPhaseDir(phase);
+  if (!phaseDir) {
+    process.stderr.write(`[task-envelope] ERROR: phase directory not found for "${phase}"\n`);
+    process.exit(1);
+  }
+
+  const envelopePath = path.join(phaseDir, 'task-envelope.json');
+
+  // Read existing envelope or create minimal one
+  let envelope;
+  if (fs.existsSync(envelopePath)) {
+    const content = fs.readFileSync(envelopePath, 'utf8');
+    envelope = JSON.parse(content);
+  } else {
+    // Create minimal envelope structure
+    envelope = {
+      schema_version: '1',
+      phase,
+      created_at: new Date().toISOString(),
+      risk_level: 'medium'
+    };
+  }
+
+  // Update section
+  if (section === 'plan') {
+    envelope.plan = {
+      plan_path: planPath,
+      key_decisions: keyDecisions
+    };
+    if (waveCount !== null && !isNaN(waveCount)) {
+      envelope.plan.wave_count = waveCount;
+    }
+  }
+
+  // Validate and write
+  const validation = validateEnvelope(envelope);
+  if (!validation.valid) {
+    process.stderr.write(`[task-envelope] ERROR: invalid envelope: ${validation.errors.join('; ')}\n`);
+    process.exit(1);
+  }
+
+  writeAtomicJson(envelopePath, envelope);
+  console.log(`[task-envelope] updated: ${envelopePath}`);
+}
+
+// Command: read
+function commandRead(args) {
+  // Parse arguments
+  let phase;
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--phase' && i + 1 < args.length) {
+      phase = args[++i];
+    }
+  }
+
+  if (!phase) {
+    process.stderr.write('[task-envelope] ERROR: --phase is required\n');
+    process.exit(1);
+  }
+
+  const envelopePath = getEnvelopePath(phase);
+  if (!envelopePath || !fs.existsSync(envelopePath)) {
+    process.stderr.write(`[task-envelope] ERROR: envelope not found for "${phase}"\n`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(envelopePath, 'utf8');
+  const envelope = JSON.parse(content);
+  console.log(JSON.stringify(envelope, null, 2));
+}
+
+// Command: validate
+function commandValidate(args) {
+  // Parse arguments
+  let phase;
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--phase' && i + 1 < args.length) {
+      phase = args[++i];
+    }
+  }
+
+  if (!phase) {
+    process.stderr.write('[task-envelope] ERROR: --phase is required\n');
+    process.exit(1);
+  }
+
+  const envelopePath = getEnvelopePath(phase);
+  if (!envelopePath || !fs.existsSync(envelopePath)) {
+    console.log(JSON.stringify({ valid: false, errors: ['envelope not found'] }));
+    return;
+  }
+
+  const content = fs.readFileSync(envelopePath, 'utf8');
+  let envelope;
+  try {
+    envelope = JSON.parse(content);
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: ['malformed JSON'] }));
+    return;
+  }
+
+  const result = validateEnvelope(envelope);
+  console.log(JSON.stringify(result));
+}
+
+// Exports for testing
+module.exports = {
+  validateEnvelope,
+  ENVELOPE_SCHEMA
+};
+
+// Run main if executed directly
+if (require.main === module) {
+  main();
+}