@nforma.ai/nforma 0.2.1 → 0.28.0

package/hooks/dist/{qgsd-precompact.js → nf-precompact.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// hooks/qgsd-precompact.js
-// PreCompact hook — injects QGSD session state as additionalContext before context compaction.
+// hooks/nf-precompact.js
+// PreCompact hook — injects nForma session state as additionalContext before context compaction.
 // Reads .planning/STATE.md "Current Position" section and any pending task files.
 // Output survives compaction and appears in the first message of the compacted context.
 // Fails open on all errors — never blocks compaction.
@@ -30,7 +30,7 @@ function extractCurrentPosition(stateContent) {
   return section.trim() || null;
 }
 
-// Read pending task files without consuming them (unlike qgsd-prompt.js's consumePendingTask).
+// Read pending task files without consuming them (unlike nf-prompt.js's consumePendingTask).
 // Checks .claude/pending-task.txt and .claude/pending-task-*.txt files.
 // Returns an array of { filename, content } objects for each file found.
 function readPendingTasks(cwd) {
@@ -46,7 +46,7 @@ function readPendingTasks(cwd) {
       const content = fs.readFileSync(genericFile, 'utf8').trim();
       if (content) results.push({ filename: 'pending-task.txt', content });
     } catch (e) {
-      process.stderr.write('[qgsd-precompact] Could not read ' + genericFile + ': ' + e.message + '\n');
+      process.stderr.write('[nf-precompact] Could not read ' + genericFile + ': ' + e.message + '\n');
     }
   }
 
@@ -60,12 +60,12 @@ function readPendingTasks(cwd) {
           const content = fs.readFileSync(filePath, 'utf8').trim();
           if (content) results.push({ filename: entry, content });
         } catch (e) {
-          process.stderr.write('[qgsd-precompact] Could not read ' + filePath + ': ' + e.message + '\n');
+          process.stderr.write('[nf-precompact] Could not read ' + filePath + ': ' + e.message + '\n');
         }
       }
     }
   } catch (e) {
-    process.stderr.write('[qgsd-precompact] Could not read .claude dir: ' + e.message + '\n');
+    process.stderr.write('[nf-precompact] Could not read .claude dir: ' + e.message + '\n');
   }
 
   return results;
@@ -85,14 +85,14 @@ process.stdin.on('end', () => {
 
     if (!fs.existsSync(statePath)) {
       // No STATE.md — minimal context
-      additionalContext = 'QGSD session resumed after compaction. Run `cat .planning/STATE.md` for project state.';
+      additionalContext = 'nForma session resumed after compaction. Run `cat .planning/STATE.md` for project state.';
     } else {
       let stateContent;
       try {
         stateContent = fs.readFileSync(statePath, 'utf8');
       } catch (e) {
-        process.stderr.write('[qgsd-precompact] Could not read STATE.md: ' + e.message + '\n');
-        additionalContext = 'QGSD session resumed after compaction. Run `cat .planning/STATE.md` for project state.';
+        process.stderr.write('[nf-precompact] Could not read STATE.md: ' + e.message + '\n');
+        additionalContext = 'nForma session resumed after compaction. Run `cat .planning/STATE.md` for project state.';
         emitOutput(additionalContext);
         return;
       }
@@ -101,7 +101,7 @@ process.stdin.on('end', () => {
       const pendingTasks = readPendingTasks(cwd);
 
       const lines = [
-        'QGSD CONTINUATION CONTEXT (auto-injected at compaction)',
+        'nForma CONTINUATION CONTEXT (auto-injected at compaction)',
         '',
         '## Current Position',
         currentPosition || '(Could not extract Current Position section — run `cat .planning/STATE.md` for full state.)',
@@ -113,13 +113,13 @@ process.stdin.on('end', () => {
         // Include the first pending task found (generic file takes priority)
         lines.push(pendingTasks[0].content);
         if (pendingTasks.length > 1) {
-          process.stderr.write('[qgsd-precompact] Multiple pending task files found; injecting first: ' + pendingTasks[0].filename + '\n');
+          process.stderr.write('[nf-precompact] Multiple pending task files found; injecting first: ' + pendingTasks[0].filename + '\n');
         }
       }
 
       lines.push('');
       lines.push('## Resume Instructions');
-      lines.push('You are mid-session on a QGSD project. The context above shows where you were.');
+      lines.push('You are mid-session on a nForma project. The context above shows where you were.');
       lines.push('- If a PLAN.md is in progress, continue executing from the current plan.');
       lines.push('- If a pending task is shown above, execute it next.');
       lines.push('- Run `cat .planning/STATE.md` to get full project state if needed.');
@@ -131,7 +131,7 @@ process.stdin.on('end', () => {
     emitOutput(additionalContext);
 
   } catch (e) {
-    process.stderr.write('[qgsd-precompact] Fatal error: ' + e.message + '\n');
+    process.stderr.write('[nf-precompact] Fatal error: ' + e.message + '\n');
     process.exit(0); // Fail open — never block compaction
   }
 });

package/hooks/dist/nf-precompact.test.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Test suite for hooks/nf-precompact.js
+// Uses Node.js built-in test runner: node --test hooks/nf-precompact.test.js
+//
+// Unit tests target exported helpers (extractCurrentPosition, readPendingTasks).
+// Integration tests spawn the hook as a child process with mock stdin.
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOOK_PATH = path.join(__dirname, 'nf-precompact.js');
+const { extractCurrentPosition, readPendingTasks } = require(HOOK_PATH);
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeTmpDir() {
+  const dir = path.join(os.tmpdir(), 'nf-pc-' + Date.now() + '-' + Math.random().toString(36).slice(2));
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function runHook(stdinPayload, opts = {}) {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: JSON.stringify(stdinPayload),
+    encoding: 'utf8',
+    timeout: 5000,
+    ...opts,
+  });
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status,
+    parsed: (() => { try { return JSON.parse(result.stdout); } catch { return null; } })(),
+  };
+}
+
+function writeStateFile(dir, content) {
+  const planningDir = path.join(dir, '.planning');
+  fs.mkdirSync(planningDir, { recursive: true });
+  fs.writeFileSync(path.join(planningDir, 'STATE.md'), content, 'utf8');
+}
+
+function writeClaudeFile(dir, filename, content) {
+  const claudeDir = path.join(dir, '.claude');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(path.join(claudeDir, filename), content, 'utf8');
+}
+
+// ─── extractCurrentPosition unit tests ──────────────────────────────────────
+
+test('extractCurrentPosition: returns section between marker and next header', () => {
+  const content = [
+    '# Project State',
+    '',
+    '## Current Position',
+    '',
+    'Phase: v0.19-04 — COMPLETE',
+    'Status: ready to plan v0.19-05',
+    '',
+    '## Performance Metrics',
+    '',
+    'some other section',
+  ].join('\n');
+
+  const result = extractCurrentPosition(content);
+  assert.ok(result.includes('Phase: v0.19-04'), 'Should include phase line');
+  assert.ok(!result.includes('Performance Metrics'), 'Should not bleed into next section');
+});
+
+test('extractCurrentPosition: returns to EOF when no following header', () => {
+  const content = [
+    '## Other Section',
+    'irrelevant',
+    '',
+    '## Current Position',
+    '',
+    'Last section content here',
+  ].join('\n');
+
+  const result = extractCurrentPosition(content);
+  assert.ok(result.includes('Last section content here'));
+});
+
+test('extractCurrentPosition: returns null when marker is absent', () => {
+  const content = '## Something Else\ncontent\n## Another\nmore content';
+  assert.equal(extractCurrentPosition(content), null);
+});
+
+test('extractCurrentPosition: returns null when section is empty', () => {
+  const content = '## Current Position\n\n## Next Section\ncontent';
+  assert.equal(extractCurrentPosition(content), null);
+});
+
+// ─── readPendingTasks unit tests ─────────────────────────────────────────────
+
+test('readPendingTasks: returns empty array when .claude dir does not exist', () => {
+  const tmpDir = makeTmpDir();
+  const results = readPendingTasks(tmpDir);
+  assert.deepEqual(results, []);
+});
+
+test('readPendingTasks: returns generic pending-task.txt', () => {
+  const tmpDir = makeTmpDir();
+  writeClaudeFile(tmpDir, 'pending-task.txt', '/qgsd:execute-phase v0.19-05');
+
+  const results = readPendingTasks(tmpDir);
+  assert.equal(results.length, 1);
+  assert.equal(results[0].filename, 'pending-task.txt');
+  assert.equal(results[0].content, '/qgsd:execute-phase v0.19-05');
+});
+
+test('readPendingTasks: returns session-scoped pending-task-SESSION.txt', () => {
+  const tmpDir = makeTmpDir();
+  writeClaudeFile(tmpDir, 'pending-task-abc123.txt', '/qgsd:quick --full fix tests');
+
+  const results = readPendingTasks(tmpDir);
+  assert.equal(results.length, 1);
+  assert.equal(results[0].filename, 'pending-task-abc123.txt');
+  assert.equal(results[0].content, '/qgsd:quick --full fix tests');
+});
+
+test('readPendingTasks: excludes .claimed files', () => {
+  const tmpDir = makeTmpDir();
+  writeClaudeFile(tmpDir, 'pending-task-abc123.txt.claimed', 'already consumed');
+
+  const results = readPendingTasks(tmpDir);
+  assert.deepEqual(results, []);
+});
+
+test('readPendingTasks: skips empty pending-task files', () => {
+  const tmpDir = makeTmpDir();
+  writeClaudeFile(tmpDir, 'pending-task.txt', '   \n  ');
+
+  const results = readPendingTasks(tmpDir);
+  assert.deepEqual(results, []);
+});
+
+test('readPendingTasks: does NOT delete files (non-consuming)', () => {
+  const tmpDir = makeTmpDir();
+  writeClaudeFile(tmpDir, 'pending-task.txt', 'some task');
+  const filePath = path.join(tmpDir, '.claude', 'pending-task.txt');
+
+  readPendingTasks(tmpDir);
+
+  assert.ok(fs.existsSync(filePath), 'File should still exist after read (non-consuming)');
+});
+
+// ─── Full subprocess (stdin→stdout) integration tests ───────────────────────
+
+test('subprocess: exits 0 and emits additionalContext when STATE.md has Current Position', () => {
+  const tmpDir = makeTmpDir();
+  writeStateFile(tmpDir, [
+    '# Project State',
+    '',
+    '## Current Position',
+    '',
+    'Phase: v0.19-05 — in progress',
+    'Plan: 01 — DONE',
+    '',
+    '## Performance Metrics',
+    'other stuff',
+  ].join('\n'));
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0);
+  assert.ok(parsed, 'stdout should be valid JSON');
+  assert.ok(parsed.hookSpecificOutput, 'should have hookSpecificOutput');
+  assert.equal(parsed.hookSpecificOutput.hookEventName, 'PreCompact');
+  const ctx = parsed.hookSpecificOutput.additionalContext;
+  assert.ok(ctx.includes('nForma CONTINUATION CONTEXT'), 'should include header');
+  assert.ok(ctx.includes('v0.19-05'), 'should include current position content');
+  assert.ok(ctx.includes('Resume Instructions'), 'should include resume instructions');
+});
+
+test('subprocess: includes pending task when pending-task.txt exists', () => {
+  const tmpDir = makeTmpDir();
+  writeStateFile(tmpDir, '## Current Position\n\nPhase: v0.19-05\n\n## Other\nstuff');
+  writeClaudeFile(tmpDir, 'pending-task.txt', '/qgsd:execute-phase v0.19-05');
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0);
+  const ctx = parsed.hookSpecificOutput.additionalContext;
+  assert.ok(ctx.includes('Pending Task'), 'should include Pending Task section');
+  assert.ok(ctx.includes('/qgsd:execute-phase v0.19-05'), 'should include task content');
+});
+
+test('subprocess: emits minimal fallback when STATE.md is absent', () => {
+  const tmpDir = makeTmpDir(); // no STATE.md written
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0);
+  assert.ok(parsed.hookSpecificOutput.additionalContext.includes('resumed after compaction'));
+});
+
+test('subprocess: fails open on invalid JSON stdin (exit 0)', () => {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: 'not valid json {{',
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  assert.equal(result.status, 0, 'should exit 0 on JSON parse error (fail-open)');
+});
+
+test('subprocess: falls back to process.cwd() when cwd field is absent', () => {
+  // Pass empty object — no cwd field. Hook should default to process.cwd() and not crash.
+  const { exitCode, parsed } = runHook({});
+
+  assert.equal(exitCode, 0);
+  assert.ok(parsed || true, 'Should produce valid output or minimal fallback');
+});
+
+test('subprocess: hookEventName is PreCompact', () => {
+  const tmpDir = makeTmpDir();
+  writeStateFile(tmpDir, '## Current Position\n\nsome state\n\n## Next\nmore');
+
+  const { parsed } = runHook({ cwd: tmpDir });
+  assert.equal(parsed.hookSpecificOutput.hookEventName, 'PreCompact');
+});

package/hooks/dist/{qgsd-prompt.js → nf-prompt.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// hooks/qgsd-prompt.js
+// hooks/nf-prompt.js
 // UserPromptSubmit hook — three responsibilities:
 //
 // 1. CIRCUIT BREAKER RECOVERY: If the circuit breaker is active, inject the
@@ -22,21 +22,21 @@ const fs   = require('fs');
 const path = require('path');
 const os   = require('os');
 const { spawnSync } = require('child_process');
-const { loadConfig, slotToToolCall } = require('./config-loader');
+const { loadConfig, slotToToolCall, shouldRunHook } = require('./config-loader');
 const { schema_version } = require('./conformance-schema.cjs');
 
 const DEFAULT_QUORUM_INSTRUCTIONS_FALLBACK = `QUORUM REQUIRED (structural enforcement — Stop hook will verify)
 
-Run the full R3 quorum protocol inline (dispatch_pattern from commands/qgsd/quorum.md):
+Run the full R3 quorum protocol inline (dispatch_pattern from commands/nf/quorum.md):
 
 1. State Claude's own position (vote) first — APPROVE or BLOCK with 1-2 sentence rationale
-2. Run provider pre-flight: node ~/.claude/qgsd-bin/check-provider-health.cjs --json
-3. Build $DISPATCH_LIST first (quorum.md Adaptive Fan-Out: read risk_level → compute FAN_OUT_COUNT → first FAN_OUT_COUNT-1 slots). Then dispatch $DISPATCH_LIST as sibling qgsd-quorum-slot-worker Tasks in one message turn — do NOT dispatch slots outside $DISPATCH_LIST:
-   Task(subagent_type="qgsd-quorum-slot-worker", prompt="slot: <slot>\\nround: 1\\n...")
+2. Run provider pre-flight: node ~/.claude/nf-bin/check-provider-health.cjs --json
+3. Build $DISPATCH_LIST first (quorum.md Adaptive Fan-Out: read risk_level → compute FAN_OUT_COUNT → first FAN_OUT_COUNT-1 slots). Then dispatch $DISPATCH_LIST as sibling nf-quorum-slot-worker Tasks in one message turn — do NOT dispatch slots outside $DISPATCH_LIST:
+   Task(subagent_type="nf-quorum-slot-worker", prompt="slot: <slot>\\nround: 1\\n...")
 4. Synthesize results inline. Deliberate up to 10 rounds per R3.3 if no consensus.
-5. Update scoreboard: node ~/.claude/qgsd-bin/update-scoreboard.cjs merge-wave ...
+5. Update scoreboard: node ~/.claude/nf-bin/update-scoreboard.cjs merge-wave ...
 6. [HEAL-01] After each deliberation round's merge-wave, check early escalation:
-   node ~/.claude/qgsd-bin/quorum-consensus-gate.cjs --min-quorum=2 --remaining-rounds=R
+   node ~/.claude/nf-bin/quorum-consensus-gate.cjs --min-quorum=2 --remaining-rounds=R
    (R = maxDeliberation - currentRound). Exit code 1 = stop deliberating, proceed to decision (early escalation — P(consensus|remaining) below threshold).
 7. Include the token <!-- GSD_DECISION --> in your FINAL output (only when delivering
    the completed plan, research, verification report, or filtered question list)
@@ -55,16 +55,16 @@ function appendConformanceEvent(event) {
     const logPath = pp.resolve(process.cwd(), 'conformance-events');
     fs.appendFileSync(logPath, JSON.stringify(event) + '\n', 'utf8');
   } catch (err) {
-    process.stderr.write('[qgsd] conformance log write failed: ' + err.message + '\n');
+    process.stderr.write('[nf] conformance log write failed: ' + err.message + '\n');
   }
 }
 
 // Locate the oscillation-resolution-mode workflow.
-// Tries global install path first (~/.claude/qgsd/), then local (.claude/qgsd/).
+// Tries global install path first (~/.claude/nf/), then local (.claude/nf/).
 function findResolutionWorkflow(cwd) {
   const candidates = [
-    path.join(os.homedir(), '.claude', 'qgsd', 'workflows', 'oscillation-resolution-mode.md'),
-    path.join(cwd, '.claude', 'qgsd', 'workflows', 'oscillation-resolution-mode.md'),
+    path.join(os.homedir(), '.claude', 'nf', 'workflows', 'oscillation-resolution-mode.md'),
+    path.join(cwd, '.claude', 'nf', 'workflows', 'oscillation-resolution-mode.md'),
   ];
   for (const p of candidates) {
     if (fs.existsSync(p)) return fs.readFileSync(p, 'utf8');
@@ -150,7 +150,7 @@ function getRecentlyTimedOutSlots(cwd, ttlMinutes = 30) {
 function findProviders() {
   const searchPaths = [
     path.join(__dirname, '..', 'bin', 'providers.json'),
-    path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+    path.join(os.homedir(), '.claude', 'nf-bin', 'providers.json'),
   ];
   for (const p of searchPaths) {
     try {
@@ -169,7 +169,7 @@ function triggerHealthProbe() {
   try {
     const searchPaths = [
       path.join(__dirname, '..', 'bin', 'check-provider-health.cjs'),
-      path.join(os.homedir(), '.claude', 'qgsd-bin', 'check-provider-health.cjs'),
+      path.join(os.homedir(), '.claude', 'nf-bin', 'check-provider-health.cjs'),
     ];
     let checkPath = null;
     for (const p of searchPaths) {
@@ -199,7 +199,7 @@ function getAvailableSlots(slots, cwd) {
         const ts = new Date(avail.available_at_iso).getTime();
         if (isNaN(ts)) return true; // malformed date: fail-open
         if (ts > now) {
-          console.error(`[qgsd-dispatch] AVAILABILITY EXCLUDE: ${s.slot} -- available_at_iso=${avail.available_at_iso} is in the future (now=${new Date().toISOString()})`);
+          console.error(`[nf-dispatch] AVAILABILITY EXCLUDE: ${s.slot} -- available_at_iso=${avail.available_at_iso} is in the future (now=${new Date().toISOString()})`);
           return false;
         }
         return true;
@@ -254,18 +254,18 @@ function sortBySuccessRate(slots, cwd) {
       return getRate(b.slot) - getRate(a.slot);
     });
 
-    console.error('[qgsd-dispatch] DISPATCH ORDER (flakiness,rate): [' +
+    console.error('[nf-dispatch] DISPATCH ORDER (flakiness,rate): [' +
       sorted.map(s => `${s.slot}(f=${getFlakiness(s.slot).toFixed(2)},r=${getRate(s.slot).toFixed(3)})`).join(', ') + ']');
     return sorted;
   } catch (_) { return [...slots]; } // fail-open: any error → return original order
 }
 
 // Returns slot names whose backing provider is DOWN (probed unhealthy).
-// Reads ~/.claude/qgsd-provider-cache.json and matches providers from providers.json.
+// Reads ~/.claude/nf-provider-cache.json and matches providers from providers.json.
 // When a provider's endpoint is DOWN, ALL slots backed by that provider are skipped.
 function getDownProviderSlots() {
   try {
-    const cachePath = path.join(os.homedir(), '.claude', 'qgsd-provider-cache.json');
+    const cachePath = path.join(os.homedir(), '.claude', 'nf-provider-cache.json');
     if (!fs.existsSync(cachePath)) return [];
     const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
     if (!cache || !cache.entries) return [];
@@ -342,7 +342,7 @@ process.stdin.on('end', () => {
       const workflow = findResolutionWorkflow(cwd);
       const context = workflow
         ? `CIRCUIT BREAKER ACTIVE — OSCILLATION RESOLUTION MODE\n\nYou MUST follow this procedure immediately before doing anything else:\n\n${workflow}`
-        : `CIRCUIT BREAKER ACTIVE — OSCILLATION RESOLUTION MODE\n\nOscillation has been detected in recent commits. Tool calls are NOT blocked — you can still read and write files — but you MUST resolve the oscillation before making further commits.\nFollow the oscillation resolution procedure in R5 of CLAUDE.md:\n1. Run: git log --oneline --name-only -6 to identify the oscillating file set.\n2. Run quorum diagnosis with structural coupling framing.\n3. Present unified solution to user for approval.\n4. Do NOT commit until user approves AND runs: npx qgsd --reset-breaker`;
+        : `CIRCUIT BREAKER ACTIVE — OSCILLATION RESOLUTION MODE\n\nOscillation has been detected in recent commits. Tool calls are NOT blocked — you can still read and write files — but you MUST resolve the oscillation before making further commits.\nFollow the oscillation resolution procedure in R5 of CLAUDE.md:\n1. Run: git log --oneline --name-only -6 to identify the oscillating file set.\n2. Run quorum diagnosis with structural coupling framing.\n3. Present unified solution to user for approval.\n4. Do NOT commit until user approves AND runs: npx nforma --reset-breaker`;
       process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
@@ -358,7 +358,7 @@ process.stdin.on('end', () => {
       process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: `PENDING QUEUED TASK — Execute this immediately before anything else:\n\n${pendingTask}\n\n(This task was queued via /qgsd:queue before the previous /clear.)`,
+          additionalContext: `PENDING QUEUED TASK — Execute this immediately before anything else:\n\n${pendingTask}\n\n(This task was queued via /nf:queue before the previous /clear.)`,
         }
       }));
       process.exit(0);
@@ -366,6 +366,13 @@ process.stdin.on('end', () => {
 
     // ── Priority 3: Planning command → inject quorum instructions ────────────
     const config = loadConfig(cwd);
+
+    // Profile guard — exit early if this hook is not active for the current profile
+    const profile = config.hook_profile || 'standard';
+    if (!shouldRunHook('nf-prompt', profile)) {
+      process.exit(0);
+    }
+
     const commands = config.quorum_commands;
 
     // Parse --n N override from the raw prompt
@@ -380,7 +387,7 @@ process.stdin.on('end', () => {
 
     // Solo mode: --n 1 means Claude-only quorum — bypass all external slot dispatches
     if (quorumSizeOverride === 1) {
-      instructions = `<!-- QGSD_SOLO_MODE -->\nSOLO MODE ACTIVE (--n 1): Self-quorum only. Skip ALL external slot-worker Task dispatches. Claude's vote is the quorum. Write <!-- GSD_DECISION --> in your final output. The Stop hook is informed.\n\n`;
+      instructions = `<!-- NF_SOLO_MODE -->\nSOLO MODE ACTIVE (--n 1): Self-quorum only. Skip ALL external slot-worker Task dispatches. Claude's vote is the quorum. Write <!-- GSD_DECISION --> in your final output. The Stop hook is informed.\n\n`;
     } else if (config.quorum_instructions) {
       // Explicit quorum_instructions in config — use as-is
       instructions = config.quorum_instructions;
@@ -427,8 +434,8 @@ process.stdin.on('end', () => {
       // Guard: empty roster — no external agents configured at all
       if (orderedSlots.length === 0) {
         // Fail-open to solo mode: Claude is the only quorum participant
-        console.error('[qgsd-dispatch] WARNING: no external agents in roster — falling back to solo quorum');
-        instructions = `<!-- QGSD_SOLO_MODE -->\nSOLO MODE ACTIVE (empty roster): No external agents configured in providers.json or quorum_active. Claude's vote is the quorum. Write <!-- GSD_DECISION --> in your final output. The Stop hook is informed.\n\nTo add agents, run /qgsd:mcp-setup or edit ~/.claude/qgsd.json quorum_active.\n`;
+        console.error('[nf-dispatch] WARNING: no external agents in roster — falling back to solo quorum');
+        instructions = `<!-- NF_SOLO_MODE -->\nSOLO MODE ACTIVE (empty roster): No external agents configured in providers.json or quorum_active. Claude's vote is the quorum. Write <!-- GSD_DECISION --> in your final output. The Stop hook is informed.\n\nTo add agents, run /nf:mcp-setup or edit ~/.claude/nf.json quorum_active.\n`;
       } else {
         if (preferSub) {
           orderedSlots.sort((a, b) => {
@@ -460,6 +467,54 @@ process.stdin.on('end', () => {
       // DISP-03: Sort by descending success rate
       cappedSlots = sortBySuccessRate(cappedSlots, cwd);
 
+      // ── CACHE CHECK: Short-circuit quorum dispatch on valid cache hit ──────
+      try {
+        const cacheModule = require(path.join(__dirname, '..', 'bin', 'quorum-cache.cjs'));
+        const cacheDir = path.join(cwd, '.planning', '.quorum-cache');
+        const cacheKey = cacheModule.computeCacheKey(prompt, contextYaml, cappedSlots, config.quorum_active, cacheModule.getGitHead());
+
+        const cachedEntry = cacheModule.readCache(cacheKey, cacheDir);
+        if (cachedEntry && cacheModule.isCacheValid(cachedEntry, cacheModule.getGitHead(), config.quorum_active || [])) {
+          // Cache hit — serve cached result without dispatching slots
+          const ageMs = Date.now() - new Date(cachedEntry.created).getTime();
+          const timeAgo = ageMs < 3600000
+            ? Math.round(ageMs / 60000) + 'm ago'
+            : Math.round(ageMs / 3600000) + 'h ago';
+
+          appendConformanceEvent({
+            ts:              new Date().toISOString(),
+            phase:           'DECIDING',
+            action:          'cache_hit',
+            cache_key:       cacheKey.slice(0, 12),
+            slots_available: cachedEntry.slot_count,
+            vote_result:     cachedEntry.vote_result,
+            outcome:         'APPROVE',
+            schema_version,
+          });
+
+          const cacheInstructions = `<!-- NF_CACHE_HIT -->\n<!-- NF_CACHE_KEY:${cacheKey} -->\nQUORUM CACHE HIT: Identical dispatch was completed ${timeAgo}.\nCached result: ${cachedEntry.vote_result} of ${cachedEntry.slot_count} slots approved.\nDecision: ${cachedEntry.outcome}\nSkip all slot-worker Task dispatches. Use this cached quorum result.\nInclude <!-- GSD_DECISION --> in your final output.`;
+
+          process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+              hookEventName: 'UserPromptSubmit',
+              additionalContext: cacheInstructions,
+            }
+          }));
+          process.exit(0);
+        }
+
+        // Cache miss — store key for embedding in instructions and pending entry write
+        var _nfCacheKey = cacheKey;
+        var _nfCacheModule = cacheModule;
+        var _nfCacheDir = cacheDir;
+      } catch (cacheErr) {
+        // Fail-open: cache errors never prevent normal quorum dispatch
+        process.stderr.write('[nf] cache check failed (fail-open): ' + (cacheErr.message || cacheErr) + '\n');
+        var _nfCacheKey = null;
+        var _nfCacheModule = null;
+        var _nfCacheDir = null;
+      }
+
       // SC-4: Graceful fallback — ensure at least one slot in dispatch list
       if (cappedSlots.length === 0 && orderedSlots.length > 0) {
         const relaxedSlots = orderedSlots.filter(s => !skipSet.has(s.slot));
@@ -468,7 +523,7 @@ process.stdin.on('end', () => {
         } else {
           cappedSlots = [orderedSlots[0]]; // last resort: any slot at all
         }
-        console.error(`[qgsd-dispatch] FALLBACK: all slots filtered, restored ${cappedSlots[0].slot}`);
+        console.error(`[nf-dispatch] FALLBACK: all slots filtered, restored ${cappedSlots[0].slot}`);
       }
 
       // Generate step list, with optional section headers when preferSub is on
@@ -481,7 +536,7 @@ process.stdin.on('end', () => {
           stepLines.push('  [API agents — overflow if sub count insufficient]');
           inApiSection = true;
         }
-        stepLines.push(`  ${stepNum}. Task(subagent_type="qgsd-quorum-slot-worker", prompt="slot: ${slot}\\nround: 1\\ntimeout_ms: 60000\\nrepo_dir: <cwd>\\nmode: A\\nquestion: <question>")`);
+        stepLines.push(`  ${stepNum}. Task(subagent_type="nf-quorum-slot-worker", prompt="slot: ${slot}\\nround: 1\\ntimeout_ms: 60000\\nrepo_dir: <cwd>\\nmode: A\\nquestion: <question>")`);
         stepNum++;
       }
       const dynamicSteps = stepLines.join('\n');
@@ -559,18 +614,18 @@ process.stdin.on('end', () => {
       }
 
       instructions = `QUORUM REQUIRED${minNote} (structural enforcement — Stop hook will verify)\n\n` +
-        `Run the full R3 quorum protocol inline (dispatch_pattern from commands/qgsd/quorum.md):\n` +
-        `Dispatch ALL active slots as parallel sibling qgsd-quorum-slot-worker Tasks in ONE message turn.\n` +
-        `NEVER call mcp__*__* tools directly — use Task(subagent_type="qgsd-quorum-slot-worker") ONLY:\n` +
+        `Run the full R3 quorum protocol inline (dispatch_pattern from commands/nf/quorum.md):\n` +
+        `Dispatch ALL active slots as parallel sibling nf-quorum-slot-worker Tasks in ONE message turn.\n` +
+        `NEVER call mcp__*__* tools directly — use Task(subagent_type="nf-quorum-slot-worker") ONLY:\n` +
         (hasMixed ? '  [Subscription agents — preferred, flat-fee]\n' : '') +
         dynamicSteps + '\n\n' +
         skipNote +
         failoverRule + '\n\n' +
         `After quorum:\n` +
         `  ${afterSteps}. Synthesize results inline. Deliberate up to 10 rounds per R3.3 if no consensus.\n` +
-        `  ${afterSteps + 1}. Update scoreboard: node ~/.claude/qgsd-bin/update-scoreboard.cjs merge-wave ...\n` +
+        `  ${afterSteps + 1}. Update scoreboard: node ~/.claude/nf-bin/update-scoreboard.cjs merge-wave ...\n` +
         `  ${afterSteps + 2}. [HEAL-01] After EACH deliberation round's merge-wave, check early escalation:\n` +
-        `       node ~/.claude/qgsd-bin/quorum-consensus-gate.cjs --min-quorum=2 --remaining-rounds=R\n` +
+        `       node ~/.claude/nf-bin/quorum-consensus-gate.cjs --min-quorum=2 --remaining-rounds=R\n` +
         `       where R = (maxDeliberation - currentRound). For example, on round 2 of 7 max: --remaining-rounds=5.\n` +
         `       If exit code 1 (shouldEscalate=true, P(consensus|remaining) below 10% threshold), stop deliberating and proceed to decision immediately.\n` +
         `       This prevents wasting rounds when consensus is mathematically unlikely.\n` +
@@ -607,17 +662,39 @@ process.stdin.on('end', () => {
         const tool = AGENT_TOOL_MAP[agent] || ('mcp__' + agent);
         return '  - When calling ' + tool + ', include model="' + model + '" in the tool input';
       }).join('\n');
-      instructions += '\n\nModel overrides (from qgsd.json model_preferences):\n' +
+      instructions += '\n\nModel overrides (from nf.json model_preferences):\n' +
         'The following agents have preferred models configured. Pass the specified model parameter:\n' +
         lines;
     }
 
-    // Anchored allowlist — requires /gsd: or /qgsd: prefix and word boundary after command name.
-    const cmdPattern = new RegExp('^\\s*\\/q?gsd:(' + commands.join('|') + ')(\\s|$)');
+    // Anchored allowlist — requires /nf:, /gsd:, or /qgsd: prefix and word boundary after command name.
+    // Strict mode: match ANY /nf: or /gsd: or /qgsd: command, not just quorum_commands list.
+    const cmdPattern = profile === 'strict'
+      ? /^\s*\/(nf|q?gsd):[\w][\w-]*(\s|$)/
+      : new RegExp('^\\s*\\/(nf|q?gsd):(' + commands.join('|') + ')(\\s|$)');
     if (!cmdPattern.test(prompt)) {
       process.exit(0); // Silent pass — UPS-05
     }
 
+    // ── CACHE MISS: Embed cache key marker and write pending entry ──────────
+    if (typeof _nfCacheKey === 'string' && _nfCacheKey && _nfCacheModule && _nfCacheDir) {
+      try {
+        instructions = `<!-- NF_CACHE_KEY:${_nfCacheKey} -->\n` + instructions;
+        _nfCacheModule.writeCache(_nfCacheKey, {
+          version: 1,
+          key: _nfCacheKey,
+          created: new Date().toISOString(),
+          ttl_ms: (config.cache_ttl_ms || 3600000),
+          git_head: _nfCacheModule.getGitHead(),
+          quorum_active: (config.quorum_active || []).slice(),
+          slot_count: cappedSlots ? cappedSlots.length : 0,
+        }, _nfCacheDir);
+      } catch (pendingErr) {
+        // Fail-open: pending entry write failure never blocks dispatch
+        process.stderr.write('[nf] cache pending write failed (fail-open): ' + (pendingErr.message || pendingErr) + '\n');
+      }
+    }
+
     appendConformanceEvent({
       ts:              new Date().toISOString(),
       phase:           'IDLE',