@nforma.ai/nforma 0.2.1

package/hooks/dist/qgsd-session-start.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// hooks/qgsd-session-start.js
+// SessionStart hook — syncs QGSD keychain secrets into ~/.claude.json
+// on every session start so mcpServers env blocks always reflect current keychain state.
+//
+// Runs synchronously (hook expects process to exit) — uses async IIFE with catch.
+
+'use strict';
+
+const path = require('path');
+const os   = require('os');
+const fs   = require('fs');
+
+// ─── Stdin accumulation (for hook input JSON containing cwd) ─────────────────
+let _stdinRaw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => _stdinRaw += c);
+
+let _stdinReady;
+const _stdinPromise = new Promise(resolve => { _stdinReady = resolve; });
+process.stdin.on('end', () => _stdinReady());
+
+// Locate secrets.cjs — try installed global path first, then local dev path.
+//
+// IMPORTANT: install.js copies bin/*.cjs to ~/.claude/qgsd-bin/ (not ~/.claude/qgsd/bin/).
+// See bin/install.js line ~1679: binDest = path.join(targetDir, 'qgsd-bin')
+// where targetDir = os.homedir() + '/.claude'.
+function findSecrets() {
+  const candidates = [
+    path.join(os.homedir(), '.claude', 'qgsd-bin', 'secrets.cjs'),  // installed path
+    path.join(__dirname, '..', 'bin', 'secrets.cjs'),                 // local dev path
+  ];
+  for (const p of candidates) {
+    try {
+      return require(p);
+    } catch (_) {}
+  }
+  return null;
+}
+
+(async () => {
+  // Resolve project cwd from hook input JSON
+  await _stdinPromise;
+  let _hookCwd = process.cwd();
+  try { _hookCwd = JSON.parse(_stdinRaw).cwd || process.cwd(); } catch (_) {}
+
+  const secrets = findSecrets();
+  if (!secrets) {
+    // silently skip — QGSD may not be installed yet or keytar absent
+    process.exit(0);
+  }
+  try {
+    await secrets.syncToClaudeJson(secrets.SERVICE);
+  } catch (e) {
+    // Non-fatal — write to stderr for debug logs, but never block session start
+    process.stderr.write('[qgsd-session-start] sync error: ' + e.message + '\n');
+  }
+
+  // Populate CCR config from keytar (fail-silent — CCR may not be installed)
+  try {
+    const { execFileSync } = require('child_process');
+    const nodeFsRef = require('fs');
+    const ccrCandidates = [
+      path.join(os.homedir(), '.claude', 'qgsd-bin', 'ccr-secure-config.cjs'),
+      path.join(__dirname, '..', 'bin', 'ccr-secure-config.cjs'),
+    ];
+    let ccrConfigPath = null;
+    for (const p of ccrCandidates) {
+      if (nodeFsRef.existsSync(p)) { ccrConfigPath = p; break; }
+    }
+    if (ccrConfigPath) {
+      execFileSync(process.execPath, [ccrConfigPath], { stdio: 'pipe', timeout: 10000 });
+    }
+  } catch (e) {
+    process.stderr.write('[qgsd-session-start] CCR config error: ' + e.message + '\n');
+  }
+
+  // Telemetry surfacing — inject top unsurfaced issue as additionalContext
+  // Guard: only active when running inside the QGSD dev repo itself
+  try {
+    const pkgPath = path.join(_hookCwd, 'package.json');
+    const isQgsdRepo = fs.existsSync(pkgPath) &&
+      JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name === 'qgsd';
+    const fixesPath = path.join(_hookCwd, '.planning', 'telemetry', 'pending-fixes.json');
+    if (isQgsdRepo && fs.existsSync(fixesPath)) {
+      const fixes = JSON.parse(fs.readFileSync(fixesPath, 'utf8'));
+      const issue = (fixes.issues || []).find(i => !i.surfaced && i.priority >= 50);
+      if (issue) {
+        issue.surfaced = true;
+        issue.surfacedAt = new Date().toISOString();
+        fs.writeFileSync(fixesPath, JSON.stringify(fixes, null, 2), 'utf8');
+        const ctx = 'Telemetry alert [priority=' + issue.priority + ']: ' + issue.description + '\nSuggested fix: ' + issue.action;
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: ctx }
+        }));
+      }
+    }
+  } catch (_) {}
+
+  // Memory staleness check — warn about outdated MEMORY.md entries
+  try {
+    const validateMemoryCandidates = [
+      path.join(os.homedir(), '.claude', 'qgsd-bin', 'validate-memory.cjs'),
+      path.join(__dirname, '..', 'bin', 'validate-memory.cjs'),
+    ];
+    let validateMemoryMod = null;
+    for (const p of validateMemoryCandidates) {
+      try { validateMemoryMod = require(p); break; } catch (_) {}
+    }
+    if (validateMemoryMod) {
+      const { findings } = validateMemoryMod.validateMemory({ cwd: _hookCwd, quiet: true });
+      if (findings.length > 0) {
+        const summary = findings
+          .map(f => '[memory-check] ' + f.message)
+          .join('\n');
+        process.stderr.write(summary + '\n');
+      }
+    }
+  } catch (_) {}
+
+  process.exit(0);
+})();

package/hooks/dist/qgsd-slot-correlator.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// hooks/qgsd-slot-correlator.js
+// SubagentStart hook — writes a correlation placeholder file for qgsd-quorum-slot-worker subagents.
+//
+// At SubagentStart time, the prompt/slot name is not available in the hook payload.
+// This hook writes a stub correlation file { agent_id, ts, slot: null } so the
+// token collector (SubagentStop) can locate and clean up the file per agent_id.
+// The slot is resolved from last_assistant_message preamble by the token collector.
+//
+// Guards:
+//   - Only processes agent_type === 'qgsd-quorum-slot-worker' (exits 0 otherwise)
+//   - If agent_id is absent: exits 0 gracefully
+//   - Fail-open: any unhandled error exits 0
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+function main() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const input = JSON.parse(raw);
+
+      // Guard: only process qgsd-quorum-slot-worker subagents
+      if (input.agent_type !== 'qgsd-quorum-slot-worker') {
+        process.exit(0);
+      }
+
+      // Guard: agent_id required to write a meaningful correlation file
+      if (!input.agent_id) {
+        process.exit(0);
+      }
+
+      const pp = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+      const corrPath = pp.resolve(process.cwd(), 'quorum-correlation', { agentId: input.agent_id });
+
+      try {
+        fs.writeFileSync(corrPath, JSON.stringify({
+          agent_id: input.agent_id,
+          ts:       new Date().toISOString(),
+          slot:     null, // SubagentStart does not include prompt — slot resolved at SubagentStop
+        }), 'utf8');
+      } catch (_) {} // observational — never fails
+
+      process.exit(0);
+
+    } catch (_) {
+      // Fail-open
+      process.exit(0);
+    }
+  });
+}
+
+main();

package/hooks/dist/qgsd-spec-regen.js

@@ -0,0 +1,86 @@
+'use strict';
+// hooks/qgsd-spec-regen.js
+// PostToolUse hook: when Claude writes to qgsd-workflow.machine.ts,
+// automatically trigger generate-formal-specs.cjs to regenerate TLA+/Alloy specs.
+//
+// LOOP-02 (v0.21-03): Self-Calibrating Feedback Loops
+//
+// Input (stdin): Claude Code PostToolUse JSON payload
+//   { tool_name, tool_input: { file_path }, tool_response, cwd, context_window }
+//
+// Output (stdout): JSON { hookSpecificOutput: { hookEventName, additionalContext } }
+//   OR: no output (exit 0) when the hook is a no-op.
+//
+// Fail-open: exits 0 in ALL cases — never blocks the Write tool.
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw);
+    const toolName = input.tool_name || '';
+    const filePath = (input.tool_input && input.tool_input.file_path) || '';
+
+    // Only act on Write calls to qgsd-workflow.machine.ts
+    if (toolName !== 'Write' || !filePath.includes('qgsd-workflow.machine.ts')) {
+      process.exit(0); // No-op — not a machine file write
+    }
+
+    // Resolve generate-formal-specs.cjs relative to cwd (the project root)
+    const cwd = input.cwd || process.cwd();
+    const genScript = path.join(cwd, 'bin', 'generate-formal-specs.cjs');
+
+    const result = spawnSync(process.execPath, [genScript], {
+      encoding: 'utf8',
+      cwd: cwd,
+      timeout: 60000, // 60s: spec generation can take a moment
+    });
+
+    let msg;
+    if (result.status === 0 && !result.error) {
+      msg = '[spec-regen] Formal specs regenerated (generate-formal-specs.cjs + xstate-to-tla.cjs) from XState machine.';
+    } else {
+      msg = '[spec-regen] WARNING: generate-formal-specs.cjs failed after machine file write. Run manually to regenerate specs.\n' +
+            (result.stderr ? result.stderr.slice(0, 500) : '') +
+            (result.error ? String(result.error) : '');
+    }
+
+    // Also regenerate QGSDQuorum_xstate.tla (xstate-to-tla.cjs)
+    const xstateScript = path.join(cwd, 'bin', 'xstate-to-tla.cjs');
+    const machineFile = path.join(cwd, 'src', 'machines', 'qgsd-workflow.machine.ts');
+    const guardsConfig = path.join(cwd, '.planning', 'formal', 'tla', 'guards', 'qgsd-workflow.json');
+
+    if (fs.existsSync(xstateScript) && fs.existsSync(guardsConfig)) {
+      const xstateResult = spawnSync(process.execPath, [
+        xstateScript, machineFile,
+        '--config=' + guardsConfig,
+        '--module=QGSDQuorum'
+      ], {
+        encoding: 'utf8',
+        cwd: cwd,
+        timeout: 60000,
+      });
+
+      if (xstateResult.status !== 0 || xstateResult.error) {
+        msg += '\n[spec-regen] WARNING: xstate-to-tla.cjs failed. Run manually.';
+        if (xstateResult.stderr) msg += '\n' + xstateResult.stderr.slice(0, 300);
+      }
+    }
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: msg,
+      },
+    }));
+    process.exit(0); // Always exit 0 — fail-open
+  } catch (e) {
+    // Malformed JSON or unexpected error — fail-open, no output
+    process.exit(0);
+  }
+});

package/hooks/dist/qgsd-statusline.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Claude Code Statusline - GSD Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to 80% limit)
+    // Claude Code enforces an 80% context limit, so we scale to show 100% at that point
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const rawUsed = Math.max(0, Math.min(100, 100 - rem));
+      // Scale: 80% real usage = 100% displayed
+      const used = Math.min(100, Math.round((rawUsed / 80) * 100));
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on scaled usage (thresholds adjusted for new scale)
+      if (used < 63) {        // ~50% real
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 81) { // ~65% real
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 95) { // ~76% real
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {
+        // Silently fail on file system errors - don't break statusline
+      }
+    }
+
+    // QGSD update available?
+    let gsdUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'qgsd-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          gsdUpdate = '\x1b[33m⬆ /qgsd:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});