@nforma.ai/nforma 0.2.1 → 0.28.0

package/hooks/dist/config-loader.js

@@ -4,7 +4,7 @@
 //
 // Exports: loadConfig(projectDir?), DEFAULT_CONFIG
 //
-// Load order: DEFAULT_CONFIG → ~/.claude/qgsd.json (global) → .claude/qgsd.json in projectDir (project)
+// Load order: DEFAULT_CONFIG → ~/.claude/nf.json (global) → .claude/nf.json in projectDir (project)
 // Merge: shallow spread — project values fully replace global values for any overlapping key.
 // Warnings: all written to process.stderr — stdout is never touched (it is the hook decision channel).
 
@@ -15,7 +15,7 @@ const path = require('path');
 const os = require('os');
 
 // Maps the family name of a slot (trailing -N stripped) to the MCP tool suffix to call.
-// Used by both qgsd-prompt.js (step generation) and qgsd-stop.js (evidence detection).
+// Used by both nf-prompt.js (step generation) and nf-stop.js (evidence detection).
 const SLOT_TOOL_SUFFIX = {
   'codex-cli': 'review',
   'codex':     'review',
@@ -35,6 +35,42 @@ function slotToToolCall(slotName) {
   return 'mcp__' + slotName + '__' + suffix;
 }
 
+const HOOK_PROFILE_MAP = {
+  minimal: new Set([
+    'nf-circuit-breaker',
+    'nf-precompact',
+  ]),
+  standard: new Set([
+    'nf-circuit-breaker',
+    'nf-precompact',
+    'nf-prompt',
+    'nf-stop',
+    'gsd-context-monitor',
+    'nf-spec-regen',
+    'nf-token-collector',
+    'nf-slot-correlator',
+    'nf-session-start',
+    'nf-statusline',
+  ]),
+  strict: new Set([
+    'nf-circuit-breaker',
+    'nf-precompact',
+    'nf-prompt',
+    'nf-stop',
+    'gsd-context-monitor',
+    'nf-spec-regen',
+    'nf-token-collector',
+    'nf-slot-correlator',
+    'nf-session-start',
+    'nf-statusline',
+  ]),
+};
+
+function shouldRunHook(hookBasename, profile) {
+  const validProfile = HOOK_PROFILE_MAP[profile] ? profile : 'standard';
+  return HOOK_PROFILE_MAP[validProfile].has(hookBasename);
+}
+
 const DEFAULT_CONFIG = {
   quorum_commands: [
     'plan-phase', 'new-project', 'new-milestone',
@@ -72,6 +108,20 @@ const DEFAULT_CONFIG = {
     warn_pct: 70,
     critical_pct: 90,
   },
+  budget: {
+    session_limit_tokens: null,   // null = disabled (fail-open)
+    warn_pct: 60,                 // inject warning at this % of session_limit_tokens
+    downgrade_pct: 85,            // auto-downgrade model profile at this %
+  },
+  stall_detection: {
+    timeout_s: 90,                // mark slot stalled after this many seconds
+    consecutive_threshold: 2,     // require N consecutive stalled dispatches
+    check_commits: true,          // only escalate if no new commits
+  },
+  smart_compact: {
+    enabled: true,                // master switch
+    context_warn_pct: 60,        // suggest compact above this context usage %
+  },
   // quorum_active: array of slot names that participate in quorum.
   // [] = all discovered slots participate (fail-open, backward compatible with pre-Phase-40 installs).
   // A non-empty array is an explicit allowlist.
@@ -86,6 +136,7 @@ const DEFAULT_CONFIG = {
   // task_envelope_enabled: master switch for task-envelope.json sidecar writes.
   // Flat key required — nested objects lost in shallow merge.
   task_envelope_enabled: true,
+  hook_profile: 'standard',
 };
 
 // Reads and parses a JSON config file.
@@ -97,7 +148,7 @@ function readConfigFile(filePath) {
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
   } catch (e) {
-    process.stderr.write('[qgsd] WARNING: Malformed config at ' + filePath + ': ' + e.message + '\n');
+    process.stderr.write('[nf] WARNING: Malformed config at ' + filePath + ': ' + e.message + '\n');
     return null;
   }
 }
@@ -107,33 +158,33 @@ function readConfigFile(filePath) {
 // Returns the (possibly corrected) config object.
 function validateConfig(config) {
   if (!Array.isArray(config.quorum_commands)) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: quorum_commands must be an array; using defaults\n');
+    process.stderr.write('[nf] WARNING: nf.json: quorum_commands must be an array; using defaults\n');
     config.quorum_commands = DEFAULT_CONFIG.quorum_commands;
   }
 
   if (typeof config.required_models !== 'object' || config.required_models === null) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: required_models must be an object; using defaults\n');
+    process.stderr.write('[nf] WARNING: nf.json: required_models must be an object; using defaults\n');
     config.required_models = DEFAULT_CONFIG.required_models;
   }
 
   if (!['open', 'closed'].includes(config.fail_mode)) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: fail_mode "' + config.fail_mode + '" invalid; defaulting to "open"\n');
+    process.stderr.write('[nf] WARNING: nf.json: fail_mode "' + config.fail_mode + '" invalid; defaulting to "open"\n');
     config.fail_mode = 'open';
   }
 
   // Validate circuit_breaker sub-object
   if (typeof config.circuit_breaker !== 'object' || config.circuit_breaker === null) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: circuit_breaker must be an object; using defaults\n');
+    process.stderr.write('[nf] WARNING: nf.json: circuit_breaker must be an object; using defaults\n');
     config.circuit_breaker = { ...DEFAULT_CONFIG.circuit_breaker };
   } else {
     // Validate oscillation_depth independently
     if (!Number.isInteger(config.circuit_breaker.oscillation_depth) || config.circuit_breaker.oscillation_depth < 1) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: circuit_breaker.oscillation_depth must be a positive integer; defaulting to 3\n');
+      process.stderr.write('[nf] WARNING: nf.json: circuit_breaker.oscillation_depth must be a positive integer; defaulting to 3\n');
       config.circuit_breaker.oscillation_depth = 3;
     }
     // Validate commit_window independently
     if (!Number.isInteger(config.circuit_breaker.commit_window) || config.circuit_breaker.commit_window < 1) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: circuit_breaker.commit_window must be a positive integer; defaulting to 6\n');
+      process.stderr.write('[nf] WARNING: nf.json: circuit_breaker.commit_window must be a positive integer; defaulting to 6\n');
       config.circuit_breaker.commit_window = 6;
     }
     // Fill in missing sub-keys with defaults (handles partial circuit_breaker objects)
@@ -150,18 +201,18 @@ function validateConfig(config) {
       config.circuit_breaker.haiku_model = DEFAULT_CONFIG.circuit_breaker.haiku_model;
     }
     if (typeof config.circuit_breaker.haiku_reviewer !== 'boolean') {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: circuit_breaker.haiku_reviewer must be boolean; defaulting to true\n');
+      process.stderr.write('[nf] WARNING: nf.json: circuit_breaker.haiku_reviewer must be boolean; defaulting to true\n');
       config.circuit_breaker.haiku_reviewer = true;
     }
     if (typeof config.circuit_breaker.haiku_model !== 'string') {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: circuit_breaker.haiku_model must be a string; using default\n');
+      process.stderr.write('[nf] WARNING: nf.json: circuit_breaker.haiku_model must be a string; using default\n');
       config.circuit_breaker.haiku_model = DEFAULT_CONFIG.circuit_breaker.haiku_model;
     }
   }
 
   // Validate quorum_active
   if (!Array.isArray(config.quorum_active)) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: quorum_active must be an array; using []\n');
+    process.stderr.write('[nf] WARNING: nf.json: quorum_active must be an array; using []\n');
     config.quorum_active = [];
   } else {
     config.quorum_active = config.quorum_active.filter(
@@ -174,7 +225,7 @@ function validateConfig(config) {
     config.quorum = { ...DEFAULT_CONFIG.quorum };
   } else {
     if (!Number.isInteger(config.quorum.minSize) || config.quorum.minSize < 1) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: quorum.minSize must be a positive integer; defaulting to 4\n');
+      process.stderr.write('[nf] WARNING: nf.json: quorum.minSize must be a positive integer; defaulting to 4\n');
       config.quorum.minSize = DEFAULT_CONFIG.quorum.minSize;
     }
     if (typeof config.quorum.preferSub !== 'boolean') {
@@ -184,15 +235,15 @@ function validateConfig(config) {
 
   // Validate agent_config
   if (typeof config.agent_config !== 'object' || config.agent_config === null || Array.isArray(config.agent_config)) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: agent_config must be an object; using {}\n');
+    process.stderr.write('[nf] WARNING: nf.json: agent_config must be an object; using {}\n');
     config.agent_config = {};
   } else {
     for (const [slot, meta] of Object.entries(config.agent_config)) {
       if (typeof meta !== 'object' || meta === null) {
-        process.stderr.write('[qgsd] WARNING: qgsd.json: agent_config.' + slot + ' must be an object; removing\n');
+        process.stderr.write('[nf] WARNING: nf.json: agent_config.' + slot + ' must be an object; removing\n');
         delete config.agent_config[slot];
       } else if (meta.auth_type && !['sub', 'api'].includes(meta.auth_type)) {
-        process.stderr.write('[qgsd] WARNING: qgsd.json: agent_config.' + slot + '.auth_type must be "sub" or "api"; defaulting to "api"\n');
+        process.stderr.write('[nf] WARNING: nf.json: agent_config.' + slot + '.auth_type must be "sub" or "api"; defaulting to "api"\n');
         meta.auth_type = 'api';
       }
     }
@@ -200,13 +251,13 @@ function validateConfig(config) {
 
   // Validate model_preferences
   if (typeof config.model_preferences !== 'object' || config.model_preferences === null || Array.isArray(config.model_preferences)) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: model_preferences must be an object; using {}\n');
+    process.stderr.write('[nf] WARNING: nf.json: model_preferences must be an object; using {}\n');
     config.model_preferences = {};
   } else {
     // Remove invalid entries (non-string values) with a warning
     for (const [key, val] of Object.entries(config.model_preferences)) {
       if (typeof val !== 'string' || val.trim() === '') {
-        process.stderr.write('[qgsd] WARNING: qgsd.json: model_preferences.' + key + ' must be a non-empty string; removing\n');
+        process.stderr.write('[nf] WARNING: nf.json: model_preferences.' + key + ' must be a non-empty string; removing\n');
         delete config.model_preferences[key];
       }
     }
@@ -214,21 +265,21 @@ function validateConfig(config) {
 
   // Validate context_monitor sub-object
   if (typeof config.context_monitor !== 'object' || config.context_monitor === null) {
-    process.stderr.write('[qgsd] WARNING: qgsd.json: context_monitor must be an object; using defaults\n');
+    process.stderr.write('[nf] WARNING: nf.json: context_monitor must be an object; using defaults\n');
     config.context_monitor = { ...DEFAULT_CONFIG.context_monitor };
   } else {
     if (!Number.isInteger(config.context_monitor.warn_pct) ||
         config.context_monitor.warn_pct < 1 || config.context_monitor.warn_pct > 99) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: context_monitor.warn_pct must be an integer 1-99; defaulting to 70\n');
+      process.stderr.write('[nf] WARNING: nf.json: context_monitor.warn_pct must be an integer 1-99; defaulting to 70\n');
       config.context_monitor.warn_pct = DEFAULT_CONFIG.context_monitor.warn_pct;
     }
     if (!Number.isInteger(config.context_monitor.critical_pct) ||
         config.context_monitor.critical_pct < 1 || config.context_monitor.critical_pct > 100) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: context_monitor.critical_pct must be an integer 1-100; defaulting to 90\n');
+      process.stderr.write('[nf] WARNING: nf.json: context_monitor.critical_pct must be an integer 1-100; defaulting to 90\n');
       config.context_monitor.critical_pct = DEFAULT_CONFIG.context_monitor.critical_pct;
     }
     if (config.context_monitor.warn_pct >= config.context_monitor.critical_pct) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: context_monitor.warn_pct must be less than critical_pct; resetting to defaults\n');
+      process.stderr.write('[nf] WARNING: nf.json: context_monitor.warn_pct must be less than critical_pct; resetting to defaults\n');
       config.context_monitor.warn_pct = DEFAULT_CONFIG.context_monitor.warn_pct;
       config.context_monitor.critical_pct = DEFAULT_CONFIG.context_monitor.critical_pct;
     }
@@ -241,17 +292,113 @@ function validateConfig(config) {
     }
   }
 
+  // Validate budget sub-object
+  if (typeof config.budget !== 'object' || config.budget === null) {
+    process.stderr.write('[nf] WARNING: nf.json: budget must be an object; using defaults\n');
+    config.budget = { ...DEFAULT_CONFIG.budget };
+  } else {
+    // Validate session_limit_tokens: must be null, undefined, or integer >= 1000
+    if (config.budget.session_limit_tokens !== null && config.budget.session_limit_tokens !== undefined) {
+      if (!Number.isInteger(config.budget.session_limit_tokens) || config.budget.session_limit_tokens < 1000) {
+        process.stderr.write('[nf] WARNING: nf.json: budget.session_limit_tokens must be null or integer >= 1000; defaulting to null\n');
+        config.budget.session_limit_tokens = null;
+      }
+    }
+    // Validate warn_pct: integer 1-99, default 60
+    if (!Number.isInteger(config.budget.warn_pct) || config.budget.warn_pct < 1 || config.budget.warn_pct > 99) {
+      process.stderr.write('[nf] WARNING: nf.json: budget.warn_pct must be an integer 1-99; defaulting to 60\n');
+      config.budget.warn_pct = DEFAULT_CONFIG.budget.warn_pct;
+    }
+    // Validate downgrade_pct: integer 1-100, default 85
+    if (!Number.isInteger(config.budget.downgrade_pct) || config.budget.downgrade_pct < 1 || config.budget.downgrade_pct > 100) {
+      process.stderr.write('[nf] WARNING: nf.json: budget.downgrade_pct must be an integer 1-100; defaulting to 85\n');
+      config.budget.downgrade_pct = DEFAULT_CONFIG.budget.downgrade_pct;
+    }
+    // Validate warn_pct < downgrade_pct
+    if (config.budget.warn_pct >= config.budget.downgrade_pct) {
+      process.stderr.write('[nf] WARNING: nf.json: budget.warn_pct must be less than downgrade_pct; resetting to defaults\n');
+      config.budget.warn_pct = DEFAULT_CONFIG.budget.warn_pct;
+      config.budget.downgrade_pct = DEFAULT_CONFIG.budget.downgrade_pct;
+    }
+    // Fill missing sub-keys with defaults
+    if (config.budget.session_limit_tokens === undefined) {
+      config.budget.session_limit_tokens = DEFAULT_CONFIG.budget.session_limit_tokens;
+    }
+    if (config.budget.warn_pct === undefined) {
+      config.budget.warn_pct = DEFAULT_CONFIG.budget.warn_pct;
+    }
+    if (config.budget.downgrade_pct === undefined) {
+      config.budget.downgrade_pct = DEFAULT_CONFIG.budget.downgrade_pct;
+    }
+  }
+
+  // Validate stall_detection sub-object
+  if (typeof config.stall_detection !== 'object' || config.stall_detection === null) {
+    process.stderr.write('[nf] WARNING: nf.json: stall_detection must be an object; using defaults\n');
+    config.stall_detection = { ...DEFAULT_CONFIG.stall_detection };
+  } else {
+    // Validate timeout_s: positive integer, default 90
+    if (!Number.isInteger(config.stall_detection.timeout_s) || config.stall_detection.timeout_s < 1) {
+      process.stderr.write('[nf] WARNING: nf.json: stall_detection.timeout_s must be a positive integer; defaulting to 90\n');
+      config.stall_detection.timeout_s = DEFAULT_CONFIG.stall_detection.timeout_s;
+    }
+    // Validate consecutive_threshold: positive integer >= 1, default 2
+    if (!Number.isInteger(config.stall_detection.consecutive_threshold) || config.stall_detection.consecutive_threshold < 1) {
+      process.stderr.write('[nf] WARNING: nf.json: stall_detection.consecutive_threshold must be a positive integer; defaulting to 2\n');
+      config.stall_detection.consecutive_threshold = DEFAULT_CONFIG.stall_detection.consecutive_threshold;
+    }
+    // Validate check_commits: boolean, default true
+    if (typeof config.stall_detection.check_commits !== 'boolean') {
+      process.stderr.write('[nf] WARNING: nf.json: stall_detection.check_commits must be a boolean; defaulting to true\n');
+      config.stall_detection.check_commits = DEFAULT_CONFIG.stall_detection.check_commits;
+    }
+    // Fill missing sub-keys with defaults
+    if (config.stall_detection.timeout_s === undefined) {
+      config.stall_detection.timeout_s = DEFAULT_CONFIG.stall_detection.timeout_s;
+    }
+    if (config.stall_detection.consecutive_threshold === undefined) {
+      config.stall_detection.consecutive_threshold = DEFAULT_CONFIG.stall_detection.consecutive_threshold;
+    }
+    if (config.stall_detection.check_commits === undefined) {
+      config.stall_detection.check_commits = DEFAULT_CONFIG.stall_detection.check_commits;
+    }
+  }
+
+  // Validate smart_compact sub-object
+  if (typeof config.smart_compact !== 'object' || config.smart_compact === null) {
+    process.stderr.write('[nf] WARNING: nf.json: smart_compact must be an object; using defaults\n');
+    config.smart_compact = { ...DEFAULT_CONFIG.smart_compact };
+  } else {
+    // Validate enabled: boolean, default true
+    if (typeof config.smart_compact.enabled !== 'boolean') {
+      process.stderr.write('[nf] WARNING: nf.json: smart_compact.enabled must be a boolean; defaulting to true\n');
+      config.smart_compact.enabled = DEFAULT_CONFIG.smart_compact.enabled;
+    }
+    // Validate context_warn_pct: integer 1-99, default 60
+    if (!Number.isInteger(config.smart_compact.context_warn_pct) || config.smart_compact.context_warn_pct < 1 || config.smart_compact.context_warn_pct > 99) {
+      process.stderr.write('[nf] WARNING: nf.json: smart_compact.context_warn_pct must be an integer 1-99; defaulting to 60\n');
+      config.smart_compact.context_warn_pct = DEFAULT_CONFIG.smart_compact.context_warn_pct;
+    }
+    // Fill missing sub-keys with defaults
+    if (config.smart_compact.enabled === undefined) {
+      config.smart_compact.enabled = DEFAULT_CONFIG.smart_compact.enabled;
+    }
+    if (config.smart_compact.context_warn_pct === undefined) {
+      config.smart_compact.context_warn_pct = DEFAULT_CONFIG.smart_compact.context_warn_pct;
+    }
+  }
+
   // Validate model_tier_planner and model_tier_worker
   const VALID_TIERS = ['haiku', 'sonnet', 'opus'];
   if (config.model_tier_planner !== undefined) {
     if (typeof config.model_tier_planner !== 'string' || !VALID_TIERS.includes(config.model_tier_planner)) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: model_tier_planner must be "haiku", "sonnet", or "opus"; removing\n');
+      process.stderr.write('[nf] WARNING: nf.json: model_tier_planner must be "haiku", "sonnet", or "opus"; removing\n');
       delete config.model_tier_planner;
     }
   }
   if (config.model_tier_worker !== undefined) {
     if (typeof config.model_tier_worker !== 'string' || !VALID_TIERS.includes(config.model_tier_worker)) {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: model_tier_worker must be "haiku", "sonnet", or "opus"; removing\n');
+      process.stderr.write('[nf] WARNING: nf.json: model_tier_worker must be "haiku", "sonnet", or "opus"; removing\n');
       delete config.model_tier_worker;
     }
   }
@@ -259,32 +406,41 @@ function validateConfig(config) {
   // Validate task_envelope_enabled
   if (config.task_envelope_enabled !== undefined) {
     if (typeof config.task_envelope_enabled !== 'boolean') {
-      process.stderr.write('[qgsd] WARNING: qgsd.json: task_envelope_enabled must be a boolean; using default true\n');
+      process.stderr.write('[nf] WARNING: nf.json: task_envelope_enabled must be a boolean; using default true\n');
       config.task_envelope_enabled = true;
     }
   }
 
+  // Validate hook_profile
+  const VALID_PROFILES = ['minimal', 'standard', 'strict'];
+  if (config.hook_profile !== undefined) {
+    if (typeof config.hook_profile !== 'string' || !VALID_PROFILES.includes(config.hook_profile)) {
+      process.stderr.write('[nf] WARNING: nf.json: hook_profile must be "minimal", "standard", or "strict"; defaulting to "standard"\n');
+      config.hook_profile = 'standard';
+    }
+  }
+
   return config;
 }
 
-// Loads the two-layer QGSD config.
+// Loads the two-layer nForma config.
 //
-// Layer 1 (global): ~/.claude/qgsd.json
-// Layer 2 (project): <projectDir>/.claude/qgsd.json  (defaults to process.cwd())
+// Layer 1 (global): ~/.claude/nf.json
+// Layer 2 (project): <projectDir>/.claude/nf.json  (defaults to process.cwd())
 //
 // Merge is shallow: { ...DEFAULT_CONFIG, ...global, ...project }
 // If both layers are missing/malformed, returns DEFAULT_CONFIG with a warning.
 // All warnings go to stderr — stdout is never touched.
 function loadConfig(projectDir) {
-  const globalPath = path.join(os.homedir(), '.claude', 'qgsd.json');
-  const projectPath = path.join(projectDir || process.cwd(), '.claude', 'qgsd.json');
+  const globalPath = path.join(os.homedir(), '.claude', 'nf.json');
+  const projectPath = path.join(projectDir || process.cwd(), '.claude', 'nf.json');
 
   const globalObj = readConfigFile(globalPath);
   const projectObj = readConfigFile(projectPath);
 
   let config;
   if (!globalObj && !projectObj) {
-    process.stderr.write('[qgsd] WARNING: No qgsd.json found at ' + globalPath + ' or ' + projectPath + '; using hardcoded defaults\n');
+    process.stderr.write('[nf] WARNING: No nf.json found at ' + globalPath + ' or ' + projectPath + '; using hardcoded defaults\n');
     config = { ...DEFAULT_CONFIG };
   } else {
     config = { ...DEFAULT_CONFIG, ...(globalObj || {}), ...(projectObj || {}) };
@@ -294,4 +450,4 @@ function loadConfig(projectDir) {
   return config;
 }
 
-module.exports = { loadConfig, DEFAULT_CONFIG, SLOT_TOOL_SUFFIX, slotToToolCall };
+module.exports = { loadConfig, validateConfig, DEFAULT_CONFIG, SLOT_TOOL_SUFFIX, slotToToolCall, shouldRunHook, HOOK_PROFILE_MAP };

package/hooks/dist/conformance-schema.cjs

@@ -1,10 +1,10 @@
 'use strict';
 // bin/conformance-schema.cjs
 // Single source of truth for conformance event field enumerations.
-// Imported by hooks (qgsd-stop.js, qgsd-prompt.js, qgsd-circuit-breaker.js) and validate-traces.cjs.
+// Imported by hooks (nf-stop.js, nf-prompt.js, nf-circuit-breaker.js) and validate-traces.cjs.
 // NEVER add external require() calls — hooks have zero runtime dependencies.
 
-const VALID_ACTIONS  = ['quorum_start', 'quorum_complete', 'quorum_block', 'deliberation_round', 'circuit_break'];
+const VALID_ACTIONS  = ['quorum_start', 'quorum_complete', 'quorum_block', 'deliberation_round', 'circuit_break', 'cache_hit', 'budget_warn', 'budget_downgrade', 'stall_detected', 'security_sweep'];
 const VALID_PHASES   = ['IDLE', 'COLLECTING_VOTES', 'DELIBERATING', 'DECIDED'];
 const VALID_OUTCOMES = ['APPROVE', 'BLOCK', 'UNAVAILABLE', 'DELIBERATE'];
 const schema_version = '1';

package/hooks/dist/gsd-context-monitor.js

@@ -1,18 +1,67 @@
 #!/usr/bin/env node
 // hooks/gsd-context-monitor.js
-// PostToolUse hook — context window monitor.
+// PostToolUse hook — context window monitor with budget tracking and smart compact.
 //
 // Reads context_window metrics from the PostToolUse event payload.
 // Injects WARNING or CRITICAL into additionalContext when context usage
-// exceeds configurable thresholds. Fails open on all errors.
+// exceeds configurable thresholds. Also injects budget warnings and
+// smart compact suggestions at clean workflow boundaries.
+// Fails open on all errors.
 //
 // Config: context_monitor.warn_pct (default 70%) and
-//         context_monitor.critical_pct (default 90%) in qgsd.json.
+//         context_monitor.critical_pct (default 90%) in nf.json.
 // Two-layer merge via shared config-loader.
 
 'use strict';
 
-const { loadConfig } = require('./config-loader');
+const path = require('path');
+const fs = require('fs');
+const { loadConfig, shouldRunHook } = require('./config-loader');
+
+// Append a conformance event to conformance-events.jsonl (fail-open)
+function appendConformanceEvent(event) {
+  try {
+    let eventsPath;
+    try {
+      const planningPaths = require(path.join(__dirname, '..', 'bin', 'planning-paths.cjs'));
+      eventsPath = planningPaths.resolveWithFallback(process.cwd(), 'conformance-events');
+    } catch {
+      eventsPath = path.join(process.cwd(), '.planning', 'telemetry', 'conformance-events.jsonl');
+    }
+    const dir = path.dirname(eventsPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(eventsPath, JSON.stringify(event) + '\n', 'utf8');
+  } catch {
+    // Fail-open
+  }
+}
+
+// Detect if the just-completed tool call represents a clean workflow boundary
+function detectCleanBoundary(toolName, toolInput) {
+  if (toolName !== 'Bash' || !toolInput) return null;
+  const input = typeof toolInput === 'string' ? toolInput : (toolInput.command || '');
+  if (input.includes('gsd-tools.cjs phase-complete')) return 'phase_complete';
+  if (input.includes('gsd-tools.cjs commit') && input.includes('VERIFICATION')) return 'verification_done';
+  if (input.includes('gsd-tools.cjs commit')) return 'commit';
+  return null;
+}
+
+// Format a smart compact suggestion
+function formatCompactSuggestion(usedPct, boundaryType) {
+  return `SMART COMPACT SUGGESTION: Context at ${usedPct}% -- clean workflow boundary (${boundaryType}).
+Consider running /compact now.
+
+What survives compaction:
+  + STATE.md Current Position (phase, plan, last activity)
+  + Pending task files (.claude/pending-task*.txt)
+  + CLAUDE.md project rules
+
+What will be lost:
+  - Conversation history and reasoning
+  - File contents read during this session
+  - Quorum deliberation transcripts
+  - Intermediate tool outputs`;
+}
 
 let raw = '';
 process.stdin.setEncoding('utf8');
@@ -21,6 +70,13 @@ process.stdin.on('end', () => {
   try {
     const input = JSON.parse(raw);
 
+    // Profile guard — exit early if this hook is not active for the current profile
+    const config = loadConfig(input.cwd || process.cwd());
+    const profile = config.hook_profile || 'standard';
+    if (!shouldRunHook('gsd-context-monitor', profile)) {
+      process.exit(0);
+    }
+
     const ctxWindow = input.context_window;
     if (!ctxWindow || ctxWindow.remaining_percentage == null) {
       process.exit(0); // No context data — fail-open
@@ -29,30 +85,79 @@ process.stdin.on('end', () => {
     const remaining = ctxWindow.remaining_percentage;
     const usedPct = Math.round(100 - remaining);
 
-    const config = loadConfig(input.cwd || process.cwd());
     const monitorCfg = config.context_monitor || {};
     const warnPct = monitorCfg.warn_pct != null ? monitorCfg.warn_pct : 70;
     const criticalPct = monitorCfg.critical_pct != null ? monitorCfg.critical_pct : 90;
 
-    let message;
+    // Context window message
+    let contextMessage = null;
     if (usedPct >= criticalPct) {
-      message =
+      contextMessage =
         `CONTEXT MONITOR CRITICAL: Context window ${usedPct}% used (${Math.round(remaining)}% remaining). ` +
         'STOP new work immediately. Save state and inform the user that context is nearly exhausted. ' +
-        'If using QGSD, run /qgsd:pause-work to save execution state.';
+        'Run /nf:pause-work to save execution state.';
     } else if (usedPct >= warnPct) {
-      message =
+      contextMessage =
         `CONTEXT MONITOR WARNING: Context window ${usedPct}% used (${Math.round(remaining)}% remaining). ` +
         'Begin wrapping up current task. Do not start new complex work. ' +
-        'If using QGSD, consider /qgsd:pause-work to save state.';
-    } else {
-      process.exit(0); // Below warning threshold — no injection needed
+        'Consider /nf:pause-work to save state.';
+    }
+
+    // Budget tracking
+    let budgetMessage = null;
+    const budgetTracker = (() => {
+      try { return require(path.join(__dirname, '..', 'bin', 'budget-tracker.cjs')); }
+      catch { return null; }
+    })();
+
+    if (budgetTracker) {
+      const status = budgetTracker.computeBudgetStatus(usedPct, config.budget || {}, config.agent_config || {});
+      if (status.active && status.shouldDowngrade) {
+        const downgradeResult = budgetTracker.triggerProfileDowngrade(input.cwd || process.cwd());
+        budgetMessage = budgetTracker.formatBudgetWarning(status, downgradeResult);
+        appendConformanceEvent({
+          action: 'budget_downgrade',
+          ts: new Date().toISOString(),
+          budget_used_pct: status.budgetUsedPct,
+          estimated_tokens: status.estimatedTokens,
+          downgrade: downgradeResult,
+        });
+      } else if (status.active && status.shouldWarn) {
+        budgetMessage = budgetTracker.formatBudgetWarning(status, null);
+        appendConformanceEvent({
+          action: 'budget_warn',
+          ts: new Date().toISOString(),
+          budget_used_pct: status.budgetUsedPct,
+          estimated_tokens: status.estimatedTokens,
+        });
+      }
     }
 
+    // Smart compact suggestion
+    let compactMessage = null;
+    const smartCfg = config.smart_compact || {};
+    if (smartCfg.enabled !== false) {
+      const compactThreshold = smartCfg.context_warn_pct || 60;
+      if (usedPct >= compactThreshold) {
+        const boundary = detectCleanBoundary(input.tool_name, input.tool_input);
+        if (boundary) {
+          compactMessage = formatCompactSuggestion(usedPct, boundary);
+        }
+      }
+    }
+
+    // Combine all messages
+    const messages = [contextMessage, budgetMessage, compactMessage].filter(Boolean);
+    if (messages.length === 0) {
+      process.exit(0);
+    }
+
+    const combined = messages.join('\n\n');
+
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PostToolUse',
-        additionalContext: message,
+        additionalContext: combined,
       },
     }));
     process.exit(0);

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Check for QGSD updates in background, write result to cache
+// Check for nForma updates in background, write result to cache
 // Called by SessionStart hook - runs once per session
 
 const fs = require('fs');
@@ -10,11 +10,11 @@ const { spawn } = require('child_process');
 const homeDir = os.homedir();
 const cwd = process.cwd();
 const cacheDir = path.join(homeDir, '.claude', 'cache');
-const cacheFile = path.join(cacheDir, 'qgsd-update-check.json');
+const cacheFile = path.join(cacheDir, 'nf-update-check.json');
 
 // VERSION file locations (check project first, then global)
-const projectVersionFile = path.join(cwd, '.claude', 'qgsd', 'VERSION');
-const globalVersionFile = path.join(homeDir, '.claude', 'qgsd', 'VERSION');
+const projectVersionFile = path.join(cwd, '.claude', 'nf', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'nf', 'VERSION');
 
 // Ensure cache directory exists
 if (!fs.existsSync(cacheDir)) {
@@ -42,7 +42,7 @@ const child = spawn(process.execPath, ['-e', `
 
   let latest = null;
   try {
-    latest = execSync('npm view @nforma.ai/qgsd version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+    latest = execSync('npm view @nforma.ai/nforma version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
   } catch (e) {}
 
   const result = {