@nforma.ai/nforma 0.2.1 → 0.29.0

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// hooks/qgsd-circuit-breaker.js
+// hooks/nf-circuit-breaker.js
 // PreToolUse hook — oscillation detection, state persistence, and notification for circuit breaker.
 //
 // Reads JSON from stdin (Claude Code PreToolUse event payload), checks for oscillation
@@ -94,30 +94,38 @@ function getCommitDiff(gitRoot, olderHash, newerHash, files) {
 
 // Second-pass reversion check: given the hashes (newest-first) belonging to
 // run-groups for an oscillating file set key, and the files in that set,
-// determines whether the pattern is true oscillation or TDD progression.
+// determines whether the pattern is true oscillation or TDD/workflow progression.
+//
+// Algorithm: sum net change (additions - deletions) across all consecutive pairs,
+// AND track whether at least one pair has negative net change (content removal).
 //
-// Algorithm: sum net change (additions - deletions) across all consecutive pairs.
 // - Positive total net change → file grew overall → TDD progression (not oscillation).
-// - Zero or negative total net change → file didn't grow → true oscillation.
+// - Zero or negative total net change WITH at least one pair showing net deletions
+//   → true oscillation (content was added then removed).
+// - Zero or negative total net change with NO pair showing net deletions
+//   (all pairs are zero-net substitutions) → NOT oscillation. This is monotonic
+//   workflow progression (e.g., template → linter substitution → population).
 //
 // This correctly handles TDD patterns where a line like `module.exports` is modified
 // (1 deletion, 1 addition per commit) alongside net-new lines — the net change remains
 // positive because new functions are added each time.
 //
-// For true oscillation (same content toggled back and forth), each pair is symmetric
-// (same number added as removed) so the total net change is zero.
+// For true oscillation (same content toggled back and forth), at least one pair
+// will show a net-negative change (lines removed that were added in a prior pair).
 //
 // hashes: all commit hashes (newest-first) in the oscillating run-groups
 // files: file paths in the oscillating set
 // gitRoot: git repository root
 //
-// Returns true if real oscillation (net change <= 0), false if TDD progression (net change > 0).
+// Returns true if real oscillation (net change <= 0 AND at least one negative pair).
+// Returns false if all pairs are zero-net substitutions (monotonic workflow progression).
 // Returns true also if ALL pairs errored out (git unavailable → fall back to original behavior).
 function hasReversionInHashes(gitRoot, hashes, files) {
   // hashes are newest-first; consecutive pairs: (hashes[i], hashes[i-1]) where
   // hashes[i] is older (higher index = earlier in time), hashes[i-1] is newer.
   // We diff older → newer: git diff <hashes[i]> <hashes[i-1]>
   let totalNetChange = 0;
+  let hasNegativePair = false;
   let errorsOnly = true;
 
   for (let i = hashes.length - 1; i >= 1; i--) {
@@ -142,15 +150,18 @@ function hasReversionInHashes(gitRoot, hashes, files) {
       else if (line.startsWith('-')) deletions++;
     }
 
-    totalNetChange += (additions - deletions);
+    const pairNet = additions - deletions;
+    totalNetChange += pairNet;
+    if (pairNet < 0) hasNegativePair = true;
   }
 
   // If all pairs errored out → fall back to original behavior (treat as oscillation)
   if (errorsOnly) return true;
 
   // Positive net change → file grew overall → TDD progression, not oscillation
-  // Zero or negative net change → file didn't grow → real oscillation
-  return totalNetChange <= 0;
+  // Zero or negative net change WITH at least one negative pair → real oscillation
+  // Zero or negative net change with NO negative pair → monotonic substitution workflow, not oscillation
+  return totalNetChange <= 0 && hasNegativePair;
 }
 
 // Detects true oscillation: returns { detected: bool, fileSet: string[] }
@@ -301,7 +312,7 @@ function writeState(statePath, fileSet, snapshot) {
     };
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
   } catch (e) {
-    process.stderr.write(`[qgsd] WARNING: Could not write circuit breaker state: ${e.message}\n`);
+    process.stderr.write(`[nf] WARNING: Could not write circuit breaker state: ${e.message}\n`);
     // Fail-open: do not block execution
   }
 }
@@ -329,7 +340,7 @@ function appendFalseNegative(statePath, fileSet) {
     });
     fs.writeFileSync(fnLogPath, JSON.stringify(existing, null, 2), 'utf8');
   } catch (e) {
-    process.stderr.write(`[qgsd] WARNING: Could not write false-negative log: ${e.message}\n`);
+    process.stderr.write(`[nf] WARNING: Could not write false-negative log: ${e.message}\n`);
     // Fail-open: do not block execution
   }
 }
@@ -352,7 +363,7 @@ function writeOscillationLog(logPath, log) {
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     fs.writeFileSync(logPath, JSON.stringify(log, null, 2), 'utf8');
   } catch (e) {
-    process.stderr.write(`[qgsd] WARNING: Could not write oscillation log: ${e.message}\n`);
+    process.stderr.write(`[nf] WARNING: Could not write oscillation log: ${e.message}\n`);
   }
 }
 
@@ -387,7 +398,7 @@ 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');
   }
 }
 
@@ -416,12 +427,12 @@ function buildBlockReason(state) {
     lines.push('');
   }
   lines.push(
-    'Invoke Oscillation Resolution Mode per R5 in CLAUDE.md — see qgsd-core/workflows/oscillation-resolution-mode.md for the full procedure.',
+    'Invoke Oscillation Resolution Mode per R5 in CLAUDE.md — see core/workflows/oscillation-resolution-mode.md for the full procedure.',
     '',
     'Read-only operations are still allowed (e.g. git log --oneline to review the commit history).',
     'You must manually commit a root-cause fix before write operations are unblocked.',
     '',
-    "After committing the fix, run 'npx qgsd --reset-breaker' to clear the circuit breaker state.",
+    "After committing the fix, run 'npx nforma --reset-breaker' to clear the circuit breaker state.",
   );
   return lines.join('\n');
 }
@@ -453,11 +464,11 @@ function buildWarningNotice(state) {
   }
 
   lines.push(
-    'Invoke Oscillation Resolution Mode per R5 in CLAUDE.md — see qgsd-core/workflows/oscillation-resolution-mode.md for the full procedure.',
+    'Invoke Oscillation Resolution Mode per R5 in CLAUDE.md — see core/workflows/oscillation-resolution-mode.md for the full procedure.',
     '',
-    'After committing the fix, run \'npx qgsd --reset-breaker\' to clear the circuit breaker state.',
-    'To temporarily disable the circuit breaker for deliberate iterative work, run \'npx qgsd --disable-breaker\'.',
-    'Re-enable with \'npx qgsd --enable-breaker\' when done.'
+    'After committing the fix, run \'npx nforma --reset-breaker\' to clear the circuit breaker state.',
+    'To temporarily disable the circuit breaker for deliberate iterative work, run \'npx nforma --disable-breaker\'.',
+    'Re-enable with \'npx nforma --enable-breaker\' when done.'
   );
 
   return lines.join('\n');
@@ -568,10 +579,10 @@ req.end();
             // Clear state file so PreToolUse stops warning
             const statePath = path.join(gitRoot, '.claude', 'circuit-breaker-state.json');
             try { if (fs.existsSync(statePath)) fs.rmSync(statePath); } catch {}
-            process.stderr.write(`[qgsd] INFO: Oscillation resolved by Haiku — circuit breaker cleared.\n`);
+            process.stderr.write(`[nf] INFO: Oscillation resolved by Haiku — circuit breaker cleared.\n`);
           }
         } catch (e) {
-          process.stderr.write(`[qgsd] WARNING: PostToolUse Haiku check failed: ${e.message}\n`);
+          process.stderr.write(`[nf] WARNING: PostToolUse Haiku check failed: ${e.message}\n`);
         }
         process.exit(0);
       }
@@ -627,7 +638,7 @@ req.end();
         if (verdict === 'REFINEMENT') {
           // Haiku confirmed this is iterative refinement, not a bug loop — do not notify.
           // Log false-negative for auditability (stderr + persistent file).
-          process.stderr.write(`[qgsd] INFO: circuit breaker false-negative — Haiku classified oscillation as REFINEMENT (files: ${result.fileSet.join(', ')}). Allowing tool call to proceed.\n`);
+          process.stderr.write(`[nf] INFO: circuit breaker false-negative — Haiku classified oscillation as REFINEMENT (files: ${result.fileSet.join(', ')}). Allowing tool call to proceed.\n`);
           appendFalseNegative(statePath, result.fileSet);
           process.exit(0);
         }
@@ -656,7 +667,7 @@ req.end();
       };
       writeOscillationLog(logPath, oscLog);
 
-      // Write state so qgsd-prompt.js picks it up on next user message
+      // Write state so nf-prompt.js picks it up on next user message
       writeState(statePath, result.fileSet, fileSets);
 
       appendConformanceEvent({

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/{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',