@nforma.ai/nforma 0.2.1

package/hooks/dist/qgsd-prompt.js

@@ -0,0 +1,653 @@
+#!/usr/bin/env node
+// hooks/qgsd-prompt.js
+// UserPromptSubmit hook — three responsibilities:
+//
+// 1. CIRCUIT BREAKER RECOVERY: If the circuit breaker is active, inject the
+//    oscillation-resolution-mode workflow into Claude's context so resolution
+//    starts automatically on the next user message.
+//
+// 2. PENDING TASK INJECTION: If a pending-task file exists, atomically claim it
+//    and inject it as a queued command (survives /clear). Session-scoped files
+//    take priority over the generic file to prevent cross-session delivery.
+//
+// 3. QUORUM INJECTION: If the prompt is a GSD planning command, inject quorum
+//    instructions so Claude runs multi-model review before presenting output.
+//
+// Output mechanism: hookSpecificOutput.additionalContext (NOT systemMessage)
+// systemMessage only shows a UI warning; additionalContext goes into Claude's context.
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { spawnSync } = require('child_process');
+const { loadConfig, slotToToolCall } = 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):
+
+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...")
+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 ...
+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
+   (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)
+
+Fail-open: if a model is UNAVAILABLE (quota/error), note it and proceed with available models.
+Failover rule: if a slot returns an error or quota exceeded, skip it and continue with remaining active slots.
+The Stop hook reads the transcript — skipping quorum will block your response.`;
+
+// Appends a structured conformance event to .planning/conformance-events.jsonl.
+// Uses appendFileSync (atomic for writes < POSIX PIPE_BUF = 4096 bytes).
+// Always wrapped in try/catch — hooks are fail-open; never crashes on logging failure.
+// NEVER writes to stdout — stdout is the Claude Code hook decision channel.
+function appendConformanceEvent(event) {
+  try {
+    const pp = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+    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');
+  }
+}
+
+// Locate the oscillation-resolution-mode workflow.
+// Tries global install path first (~/.claude/qgsd/), then local (.claude/qgsd/).
+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'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return fs.readFileSync(p, 'utf8');
+  }
+  return null;
+}
+
+// Atomically claim and read a pending-task file, if one exists.
+// Checks session-scoped file first (.claude/pending-task-<sessionId>.txt) to prevent
+// cross-session delivery, then falls back to the generic .claude/pending-task.txt.
+// Uses fs.renameSync for atomic claiming — POSIX guarantees only one process wins.
+// Returns the task string, or null if no pending task exists.
+function consumePendingTask(cwd, sessionId) {
+  const claudeDir = path.join(cwd, '.claude');
+  if (!fs.existsSync(claudeDir)) return null;
+
+  const candidates = [];
+  if (sessionId) candidates.push(path.join(claudeDir, `pending-task-${sessionId}.txt`));
+  candidates.push(path.join(claudeDir, 'pending-task.txt'));
+
+  for (const pendingFile of candidates) {
+    if (!fs.existsSync(pendingFile)) continue;
+
+    const claimedFile = pendingFile + '.claimed';
+    try {
+      fs.renameSync(pendingFile, claimedFile); // atomic claim — only one session wins
+    } catch {
+      continue; // another session claimed it first, or file vanished — skip
+    }
+
+    try {
+      const task = fs.readFileSync(claimedFile, 'utf8').trim();
+      fs.unlinkSync(claimedFile);
+      if (task) return task;
+    } catch {
+      try { fs.unlinkSync(claimedFile); } catch {} // best-effort cleanup
+    }
+  }
+  return null;
+}
+
+// Parses --n N flag from a prompt string.
+// Returns N (integer >= 1) if found, or null if absent/invalid.
+function parseQuorumSizeFlag(prompt) {
+  const m = prompt.match(/--n\s+(\d+)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return (Number.isInteger(n) && n >= 1) ? n : null;
+}
+
+// Maps task envelope risk_level to a fan-out count (total participants including Claude).
+// Proportional to maxSize (n) using ceil(tier/3 * n):
+//   low/routine (tier 1) → ceil(n/3)   — e.g. n=3→1, n=6→2
+//   medium      (tier 2) → ceil(2n/3)  — e.g. n=3→2, n=6→4
+//   high        (tier 3) → n           — full pool
+//   absent/invalid       → n           — fail-open: conservative
+// Result is always in [1..maxSize].
+function mapRiskLevelToCount(riskLevel, maxSize) {
+  const n = maxSize;
+  if (riskLevel === 'low' || riskLevel === 'routine') return Math.max(1, Math.ceil(n / 3));
+  if (riskLevel === 'medium') return Math.max(1, Math.ceil(2 * n / 3));
+  // 'high', undefined, null, invalid string → fail-open to maxSize
+  return n;
+}
+
+// Returns slot names that have timed out within the last ttlMinutes.
+// Reads quorum-failures.json written by call-quorum-slot.cjs on every failure.
+function getRecentlyTimedOutSlots(cwd, ttlMinutes = 30) {
+  try {
+    const pp = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+    const logPath = pp.resolveWithFallback(cwd, 'quorum-failures');
+    if (!fs.existsSync(logPath)) return [];
+    const records = JSON.parse(fs.readFileSync(logPath, 'utf8'));
+    if (!Array.isArray(records)) return [];
+    const cutoff = Date.now() - ttlMinutes * 60 * 1000;
+    return records
+      .filter(r => r.error_type === 'TIMEOUT' && new Date(r.last_seen).getTime() > cutoff)
+      .map(r => r.slot);
+  } catch (_) { return []; }
+}
+
+// Locate providers.json from multiple search paths (borrowed from call-quorum-slot.cjs).
+function findProviders() {
+  const searchPaths = [
+    path.join(__dirname, '..', 'bin', 'providers.json'),
+    path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+  ];
+  for (const p of searchPaths) {
+    try {
+      if (fs.existsSync(p)) {
+        return JSON.parse(fs.readFileSync(p, 'utf8')).providers;
+      }
+    } catch (_) { /* try next */ }
+  }
+  return null;
+}
+
+// Triggers a fresh health probe before reading the cache.
+// Runs check-provider-health.cjs with a 3s timeout via spawnSync.
+// Fail-open: if spawn fails or times out, dispatch continues with stale/missing cache.
+function triggerHealthProbe() {
+  try {
+    const searchPaths = [
+      path.join(__dirname, '..', 'bin', 'check-provider-health.cjs'),
+      path.join(os.homedir(), '.claude', 'qgsd-bin', 'check-provider-health.cjs'),
+    ];
+    let checkPath = null;
+    for (const p of searchPaths) {
+      if (fs.existsSync(p)) { checkPath = p; break; }
+    }
+    if (!checkPath) return; // no probe script found — fail-open
+    spawnSync('node', [checkPath, '--json'], { timeout: 3000, stdio: 'ignore' });
+  } catch (_) { /* fail-open: probe failure does not block dispatch */ }
+}
+
+// Filters slots by availability window from scoreboard.
+// Reads .planning/quorum-scoreboard.json availability section.
+// Slots whose available_at_iso is in the future are excluded (cooling down).
+// Fail-open: if scoreboard missing, malformed, or any error, returns all slots unchanged.
+function getAvailableSlots(slots, cwd) {
+  try {
+    const pp = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+    const sbPath = pp.resolveWithFallback(cwd, 'quorum-scoreboard');
+    if (!fs.existsSync(sbPath)) return slots;
+    const scoreboard = JSON.parse(fs.readFileSync(sbPath, 'utf8'));
+    if (!scoreboard || !scoreboard.availability) return slots;
+    const now = Date.now();
+    return slots.filter(s => {
+      const avail = scoreboard.availability[s.slot];
+      if (!avail || !avail.available_at_iso) return true;
+      try {
+        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()})`);
+          return false;
+        }
+        return true;
+      } catch (_) { return true; }
+    });
+  } catch (_) { return slots; } // fail-open: any error → return all slots
+}
+
+// Sorts slots by flakiness (primary) then success rate (secondary) from scoreboard slot stats.
+// Reads .planning/quorum-scoreboard.json slots section.
+// Scoreboard keys are composite: "slotName:modelId" (e.g., "claude-1:deepseek-ai/DeepSeek-V3.2").
+// Extract slot name: const slotName = key.split(':')[0];
+// Example: const allModelsForSlot = Object.entries(scoreboard.slots)
+//   .filter(([k]) => k.startsWith(slotName + ':'))
+//   .map(([_, v]) => v);
+// Then sum their tp/fn values.
+// Fail-open: if scoreboard missing or any error, returns slots in original order.
+function sortBySuccessRate(slots, cwd) {
+  try {
+    const pp = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+    const sbPath = pp.resolveWithFallback(cwd, 'quorum-scoreboard');
+    if (!fs.existsSync(sbPath)) return [...slots];
+    const scoreboard = JSON.parse(fs.readFileSync(sbPath, 'utf8'));
+    if (!scoreboard || !scoreboard.slots) return [...slots];
+
+    // Read flakiness score for a slot — primary sort key
+    const getFlakiness = (slotName) => {
+      // Look up flakiness_score from scoreboard slots entries for this slot name
+      const entries = Object.entries(scoreboard.slots)
+        .filter(([k]) => k === slotName || k.startsWith(slotName + ':'));
+      if (entries.length === 0) return 0; // fail-open: unknown = reliable
+      // Use the max flakiness across any model for this slot
+      return Math.max(...entries.map(([_, v]) => v.flakiness_score ?? 0));
+    };
+
+    // Aggregate tp/fn across all model entries for a given slot name — secondary sort key
+    const getRate = (slotName) => {
+      const entries = Object.entries(scoreboard.slots)
+        .filter(([k]) => k.split(':')[0] === slotName)
+        .map(([_, v]) => v);
+      if (entries.length === 0) return 0.5; // default for unknown
+      const totalTp = entries.reduce((sum, e) => sum + (e.tp || 0), 0);
+      const totalFn = entries.reduce((sum, e) => sum + (e.fn || 0), 0);
+      const rate = (totalTp + totalFn) === 0 ? 0.5 : totalTp / (totalTp + totalFn);
+      return rate;
+    };
+
+    // Sort by flakiness ascending (lower = more reliable = first), then success rate descending
+    const sorted = [...slots].sort((a, b) => {
+      const flakDiff = getFlakiness(a.slot) - getFlakiness(b.slot);
+      if (flakDiff !== 0) return flakDiff;
+      return getRate(b.slot) - getRate(a.slot);
+    });
+
+    console.error('[qgsd-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.
+// 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');
+    if (!fs.existsSync(cachePath)) return [];
+    const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    if (!cache || !cache.entries) return [];
+
+    const providers = findProviders();
+    if (!providers) return [];
+
+    // Extract hostnames from DOWN cache entries.
+    // Cache keys are baseUrls like "https://api.akashml.com/v1".
+    // Extract hostname and strip common domain suffixes to get a match key (e.g., "akashml").
+    const downHostnames = [];
+    const now = Date.now();
+    for (const [baseUrl, entry] of Object.entries(cache.entries)) {
+      // Match TTL used by check-provider-health.cjs: 180s healthy, 300s unhealthy
+      const ttl = entry.healthy ? 180000 : 300000;
+      if (now - entry.cachedAt >= ttl) continue; // expired cache entry — ignore
+      if (entry.healthy) continue; // provider is UP — not skipping
+
+      try {
+        // Extract hostname and normalize to match provider field values in providers.json
+        const hostname = new URL(baseUrl).hostname; // e.g., "api.akashml.com"
+        let normalized = hostname.replace(/^api\./, ''); // remove "api." prefix
+        normalized = normalized.replace(/\.(com|ai|xyz|io)$/, ''); // remove TLD
+        downHostnames.push(normalized);
+      } catch (_) { /* malformed URL — skip this entry */ }
+    }
+
+    if (downHostnames.length === 0) return [];
+
+    // Find all slots backed by DOWN providers.
+    // Match provider field against each down hostname.
+    const skipSlots = [];
+    for (const provider of providers) {
+      if (!provider.provider) continue;
+      for (const downHostname of downHostnames) {
+        // Match: provider field contains or is contained by downHostname (e.g., "akashml" == "akashml")
+        if (provider.provider.includes(downHostname) || downHostname.includes(provider.provider)) {
+          skipSlots.push(provider.name);
+          break;
+        }
+      }
+    }
+    return skipSlots;
+  } catch (_) { return []; } // fail-open: any error → proceed with no provider skips
+}
+
+// Check if the circuit breaker is active (and not disabled) for a given git root.
+function isBreakerActive(cwd) {
+  const gitResult = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd, encoding: 'utf8', timeout: 5000,
+  });
+  if (gitResult.status !== 0 || gitResult.error) return false;
+  const gitRoot = gitResult.stdout.trim();
+  const statePath = path.join(gitRoot, '.claude', 'circuit-breaker-state.json');
+  if (!fs.existsSync(statePath)) return false;
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    return state.active === true && state.disabled !== true;
+  } catch { return false; }
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => raw += chunk);
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw);
+    const prompt    = (input.prompt || '').trim();
+    const cwd       = input.cwd || process.cwd();
+    const sessionId = input.session_id || null;
+
+    // ── Priority 1: Circuit breaker active → inject resolution workflow ──────
+    if (isBreakerActive(cwd)) {
+      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`;
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: context,
+        }
+      }));
+      process.exit(0);
+    }
+
+    // ── Priority 2: Pending task → inject queued command ─────────────────────
+    const pendingTask = consumePendingTask(cwd, sessionId);
+    if (pendingTask) {
+      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.)`,
+        }
+      }));
+      process.exit(0);
+    }
+
+    // ── Priority 3: Planning command → inject quorum instructions ────────────
+    const config = loadConfig(cwd);
+    const commands = config.quorum_commands;
+
+    // Parse --n N override from the raw prompt
+    const quorumSizeOverride = parseQuorumSizeFlag(prompt);
+
+    // Dynamic fallback step generation from quorum_active (COMP-02)
+    const activeSlots = (config.quorum_active && config.quorum_active.length > 0)
+      ? config.quorum_active
+      : null; // null = use hardcoded fallback list
+
+    let instructions;
+
+    // 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`;
+    } else if (config.quorum_instructions) {
+      // Explicit quorum_instructions in config — use as-is
+      instructions = config.quorum_instructions;
+    } else if (activeSlots) {
+      // Build ordered slot list, sub agents first when preferSub is set
+      const agentCfg = config.agent_config || {};
+      const preferSub = !(config.quorum && config.quorum.preferSub === false);
+      // Resolve maxSize ceiling: per-profile override > global default > hardcoded 3
+      // --n N is a separate cap applied on top (see below).
+      const profileKey = (() => {
+        try {
+          const cfgPath = path.join(process.cwd(), '.planning', 'config.json');
+          const pcfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+          return pcfg.model_profile || null;
+        } catch (_) { return null; }
+      })();
+      const perProfileN = profileKey && config.quorum?.maxSizeByProfile?.[profileKey];
+      const globalN = (config.quorum && Number.isInteger(config.quorum.maxSize) && config.quorum.maxSize >= 1)
+        ? config.quorum.maxSize : 3;
+      const maxSize = Number.isInteger(perProfileN) && perProfileN >= 1 ? perProfileN : globalN;
+
+      // Read risk_level from hook input context (passed by orchestrator via additionalContext or context_yaml)
+      // Context YAML format: "risk_level: routine\n..." in input.context or input.context_yaml
+      const contextYaml = (input.context || input.context_yaml || '').toString();
+      const riskLevelMatch = contextYaml.match(/^risk_level:\s*(\S+)/m);
+      const riskLevelFromContext = riskLevelMatch ? riskLevelMatch[1].trim() : null;
+
+      // Compute fan-out count. Priority chain:
+      // 1. risk_level from context YAML → adaptive fan-out count
+      // 2. config.quorum.maxSize (default ceiling)
+      // 3. --n N user flag: treated as a MAXIMUM cap, not a mandatory value.
+      //    min(risk-driven count, N) — so --n 3 with risk_level=low (→2) uses 2, not 3.
+      // 4. available pool size (hard cap, applied via slice)
+      const riskDrivenCount = mapRiskLevelToCount(riskLevelFromContext, maxSize);
+      const fanOutCount = quorumSizeOverride !== null
+        ? Math.min(riskDrivenCount, quorumSizeOverride)
+        : riskDrivenCount;
+
+      let orderedSlots = activeSlots.map(slot => ({
+        slot,
+        authType: (agentCfg[slot] && agentCfg[slot].auth_type) || 'api',
+      }));
+
+      // 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`;
+      } else {
+        if (preferSub) {
+          orderedSlots.sort((a, b) => {
+            if (a.authType === 'sub' && b.authType !== 'sub') return -1;
+            if (a.authType !== 'sub' && b.authType === 'sub') return 1;
+            return 0;
+          });
+        }
+
+        // externalSlotCap = fanOutCount - 1 (Claude accounts for the +1 in total participants)
+        const externalSlotCap = fanOutCount - 1;
+        let cappedSlots = orderedSlots.slice(0, externalSlotCap);
+
+      // DISP-01: Trigger fresh health probe before reading cache
+      triggerHealthProbe();
+
+      // Filter out slots backed by DOWN providers before building dynamic steps.
+      const recentTimeouts = getRecentlyTimedOutSlots(cwd);
+      const providerSkips = getDownProviderSlots();
+      const allSkipSlots = [...new Set([...recentTimeouts, ...providerSkips])];
+      const skipSet = new Set(allSkipSlots);
+      cappedSlots = cappedSlots.filter(s => !skipSet.has(s.slot));
+
+      // DISP-02: Filter by availability window (exclude cooling-down slots)
+      const beforeAvail = cappedSlots.map(s => s.slot);
+      cappedSlots = getAvailableSlots(cappedSlots, cwd);
+      const availabilitySkips = beforeAvail.filter(s => !cappedSlots.some(c => c.slot === s));
+
+      // DISP-03: Sort by descending success rate
+      cappedSlots = sortBySuccessRate(cappedSlots, cwd);
+
+      // 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));
+        if (relaxedSlots.length > 0) {
+          cappedSlots = [relaxedSlots[0]];
+        } else {
+          cappedSlots = [orderedSlots[0]]; // last resort: any slot at all
+        }
+        console.error(`[qgsd-dispatch] FALLBACK: all slots filtered, restored ${cappedSlots[0].slot}`);
+      }
+
+      // Generate step list, with optional section headers when preferSub is on
+      let stepLines = [];
+      let stepNum = 1;
+      const hasMixed = preferSub && cappedSlots.some(s => s.authType === 'sub') && cappedSlots.some(s => s.authType !== 'sub');
+      let inApiSection = false;
+      for (const { slot, authType } of cappedSlots) {
+        if (hasMixed && authType !== 'sub' && !inApiSection) {
+          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>")`);
+        stepNum++;
+      }
+      const dynamicSteps = stepLines.join('\n');
+      const afterSteps = cappedSlots.length + 1;
+
+      // Compute T1 unused sub-CLI slots: sub agents cut by the fan-out cap.
+      // These are the preferred replacement tier when a dispatched slot returns UNAVAIL.
+      // They must be tried before any T2 ccr/api slots (claude-1..6).
+      const cappedSlotNames = new Set(cappedSlots.map(s => s.slot));
+      const t1Unused = orderedSlots
+        .filter(s => s.authType === 'sub' && !cappedSlotNames.has(s.slot))
+        .map(s => s.slot);
+      const t2Slots = orderedSlots
+        .filter(s => s.authType !== 'sub' && !cappedSlotNames.has(s.slot))
+        .map(s => s.slot);
+
+      // Build a structured dispatch sequence (enumerated steps, not prose rules).
+      // Structured sequences are less ambiguous than conditional prose for LLM execution.
+      let failoverRule;
+      if (t1Unused.length > 0) {
+        failoverRule =
+          `SLOT DISPATCH SEQUENCE (FALLBACK-01) — execute in order, skip UNAVAIL:\n` +
+          `  Step 1 PRIMARY:        [${cappedSlots.map(s => s.slot).join(', ')}]\n` +
+          `  Step 2 T1 sub-CLI:     [${t1Unused.join(', ')}]  ← try these BEFORE any T2 slot\n` +
+          `  Step 3 T2 ccr:         [${t2Slots.length > 0 ? t2Slots.join(', ') : 'none'}]\n` +
+          `UNAVAIL slots do not count toward the ${maxSize} required quorum votes.`;
+      } else {
+        failoverRule =
+          `Failover rule: if a slot-worker returns UNAVAIL or error, skip it — ` +
+          `errors do not count toward the ${maxSize} required.`;
+      }
+
+      // Emit a conformance event when FALLBACK-01 is active so audit tooling can detect
+      // cases where T2 was used without T1 being exhausted first.
+      if (t1Unused.length > 0) {
+        try {
+          const pp = require(require('path').join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+          const logPath = pp.resolve(cwd, 'conformance-events');
+          require('fs').appendFileSync(logPath, JSON.stringify({
+            type: 'quorum_fallback_t1_required',
+            t1Slots: t1Unused,
+            t2Slots,
+            primarySlots: cappedSlots.map(s => s.slot),
+            fanOutCount,
+            ts: new Date().toISOString(),
+          }) + '\n', 'utf8');
+        } catch (_) { /* non-fatal — conformance logging must not block quorum */ }
+      }
+
+      // Always emit --n N so Stop hook's parseQuorumSizeFlag reads the correct ceiling.
+      // When user passed --n N explicitly: show OVERRIDE note.
+      // Build the quorum size note emitted into Claude's context.
+      // --n N is a maximum cap; the actual fanOutCount may be lower due to risk_level.
+      let minNote;
+      if (quorumSizeOverride !== null) {
+        const capNote = fanOutCount < quorumSizeOverride
+          ? `--n ${quorumSizeOverride} (max) → ${fanOutCount} via risk_level=${riskLevelFromContext}`
+          : `--n ${quorumSizeOverride}`;
+        minNote = ` (${capNote}: Claude + ${externalSlotCap} external slot${externalSlotCap !== 1 ? 's' : ''})`;
+      } else if (riskLevelFromContext && fanOutCount < maxSize) {
+        minNote = ` (--n ${fanOutCount} — envelope risk_level: ${riskLevelFromContext} → ${externalSlotCap} external slot${externalSlotCap !== 1 ? 's' : ''})`;
+      } else {
+        minNote = ` (--n ${fanOutCount})`;
+      }
+
+      let skipNote = '';
+      if (recentTimeouts.length > 0) {
+        skipNote += `SKIP (TIMEOUT < 30min ago): [${recentTimeouts.join(', ')}] — do NOT dispatch these slots.\n`;
+      }
+      if (providerSkips.length > 0) {
+        skipNote += `SKIP (PROVIDER DOWN): [${providerSkips.join(', ')}] — entire provider unreachable, skip all backed slots.\n`;
+      }
+      if (availabilitySkips.length > 0) {
+        skipNote += `SKIP (COOLING DOWN): [${availabilitySkips.join(', ')}] — available_at in future, skipping.\n`;
+      }
+
+      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` +
+        (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 + 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` +
+        `       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` +
+        `  ${afterSteps + 3}. Include the token <!-- GSD_DECISION --> in your FINAL output\n\n` +
+        `Fail-open: if a model is UNAVAILABLE (quota/error), note it and proceed with available models.\n` +
+        `The Stop hook reads the transcript — skipping quorum will block your response.`;
+      }
+    } else {
+      // Neither quorum_instructions nor quorum_active configured — use hardcoded fallback
+      instructions = DEFAULT_QUORUM_INSTRUCTIONS_FALLBACK;
+    }
+
+    // Append model override block if any preferences are set.
+    // Skip when activeSlots is configured: Task-based dispatch uses call-quorum-slot.cjs which
+    // reads the model from providers.json — injecting mcp__*__* tool names here would
+    // re-introduce the direct-MCP escape hatch that the activeSlots branch eliminates.
+    const prefs = config.model_preferences || {};
+    const overrideEntries = Object.entries(prefs).filter(([, m]) => m && typeof m === 'string');
+    if (overrideEntries.length > 0 && !activeSlots) {
+      // Agent key → primary quorum tool call mapping
+      const AGENT_TOOL_MAP = {
+        'codex-cli-1':  'mcp__codex-cli-1__review',
+        'gemini-cli-1': 'mcp__gemini-cli-1__gemini',
+        'opencode-1':   'mcp__opencode-1__opencode',
+        'copilot-1':    'mcp__copilot-1__ask',
+        'claude-1':     'mcp__claude-1__claude',
+        'claude-2':     'mcp__claude-2__claude',
+        'claude-3':     'mcp__claude-3__claude',
+        'claude-4':     'mcp__claude-4__claude',
+        'claude-5':     'mcp__claude-5__claude',
+        'claude-6':     'mcp__claude-6__claude',
+      };
+      const lines = overrideEntries.map(([agent, model]) => {
+        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' +
+        '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|$)');
+    if (!cmdPattern.test(prompt)) {
+      process.exit(0); // Silent pass — UPS-05
+    }
+
+    appendConformanceEvent({
+      ts:              new Date().toISOString(),
+      phase:           'IDLE',
+      action:          'quorum_start',
+      slots_available: 0,
+      vote_result:     null,
+      outcome:         null,
+      schema_version,
+    });
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: instructions,
+      }
+    }));
+    process.exit(0);
+
+  } catch (e) {
+    process.exit(0); // Fail-open on any error
+  }
+});
+
+// Export helpers for unit testing (tree-shaken at runtime — no cost)
+// The file is a script and exits via process.exit() before reaching this line in normal operation.
+// When require()d by tests, the stdin handler is registered but never fires, so module.exports is set.
+if (typeof module !== 'undefined') {
+  module.exports = module.exports || {};
+  module.exports.mapRiskLevelToCount = mapRiskLevelToCount;
+  module.exports.parseQuorumSizeFlag = parseQuorumSizeFlag;
+  module.exports.getAvailableSlots = getAvailableSlots;
+  module.exports.sortBySuccessRate = sortBySuccessRate;
+}