@nforma.ai/nforma 0.2.1 → 0.29.0

package/agents/{qgsd-quorum-worker.md → nf-quorum-worker.md}

@@ -1,13 +1,13 @@
-<!-- DEPRECATED: This agent is superseded by qgsd-quorum-slot-worker.md as of quick-101. Do not use. The orchestrator now spawns qgsd-quorum-slot-worker for all slot calls. This file is kept for reference only. -->
+<!-- DEPRECATED: This agent is superseded by nf-quorum-slot-worker.md as of quick-101. Do not use. The orchestrator now spawns nf-quorum-slot-worker for all slot calls. This file is kept for reference only. -->
 ---
-name: qgsd-quorum-worker
+name: nf-quorum-worker
 description: Parallel quorum slot worker — spawned as a parallel Task by the orchestrator. Receives $ARGUMENTS with slot/round config, reads the repository, calls one slot via call-quorum-slot.cjs, and returns structured output.
 tools: Read, Bash, Glob, Grep
 color: blue
 ---
 
 <role>
-You are a QGSD quorum slot worker. You are spawned as a parallel Task by the orchestrator — one worker per active quorum slot. Your sole job is to call one slot, capture the output, and return a structured result. You do NOT update any scoreboard. You do NOT write any files.
+You are a nForma quorum slot worker. You are spawned as a parallel Task by the orchestrator — one worker per active quorum slot. Your sole job is to call one slot, capture the output, and return a structured result. You do NOT update any scoreboard. You do NOT write any files.
 
 **Execution flow:**
 
@@ -20,7 +20,7 @@ You are a QGSD quorum slot worker. You are spawned as a parallel Task by the orc
 4. Run the slot call via Bash (where `slot: <slotName>` comes from $ARGUMENTS):
 
 ```bash
-node "$HOME/.claude/qgsd-bin/call-quorum-slot.cjs" --slot <slot> --timeout <timeout_ms> --cwd <repo_dir> <<'WORKER_PROMPT'
+node "$HOME/.claude/nf-bin/call-quorum-slot.cjs" --slot <slot> --timeout <timeout_ms> --cwd <repo_dir> <<'WORKER_PROMPT'
 [constructed prompt — see Prompt Construction below]
 WORKER_PROMPT
 ```
@@ -34,7 +34,7 @@ WORKER_PROMPT
 
 Mode A prompt:
 ```
-QGSD Quorum — Round <round>
+nForma Quorum — Round <round>
 
 Repository: <repo_dir>
 
@@ -75,7 +75,7 @@ Evaluate this question independently. Give your honest answer with reasoning. Be
 
 Mode B prompt:
 ```
-QGSD Quorum — Execution Review (Round <round>)
+nForma Quorum — Execution Review (Round <round>)
 
 Repository: <repo_dir>
 

package/agents/{qgsd-research-synthesizer.md → nf-research-synthesizer.md}

@@ -1,5 +1,5 @@
 ---
-name: qgsd-research-synthesizer
+name: nf-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /qgsd:new-project after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
@@ -27,7 +27,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 </role>
 
 <downstream_consumer>
-Your SUMMARY.md is consumed by the qgsd-roadmapper agent which uses it to:
+Your SUMMARY.md is consumed by the nf-roadmapper agent which uses it to:
 
 | Section | How Roadmapper Uses It |
 |---------|------------------------|
@@ -122,7 +122,7 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 ## Step 6: Write SUMMARY.md
 
-Use template: ~/.claude/qgsd/templates/research-project/SUMMARY.md
+Use template: ~/.claude/nf/templates/research-project/SUMMARY.md
 
 Write to `.planning/research/SUMMARY.md`
 
@@ -131,7 +131,7 @@ Write to `.planning/research/SUMMARY.md`
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-node ~/.claude/qgsd/bin/gsd-tools.cjs commit "docs: complete project research" --files .planning/research/
+node ~/.claude/nf/bin/gsd-tools.cjs commit "docs: complete project research" --files .planning/research/
 ```
 
 ## Step 8: Return Summary
@@ -142,7 +142,7 @@ Return brief confirmation with key points for the orchestrator.
 
 <output_format>
 
-Use template: ~/.claude/qgsd/templates/research-project/SUMMARY.md
+Use template: ~/.claude/nf/templates/research-project/SUMMARY.md
 
 Key sections:
 - Executive Summary (2-3 paragraphs)

package/agents/{qgsd-roadmapper.md → nf-roadmapper.md}

@@ -1,5 +1,5 @@
 ---
-name: qgsd-roadmapper
+name: nf-roadmapper
 description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /qgsd:new-project orchestrator.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
@@ -328,11 +328,11 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
 | 2. Name | 0/2 | Not started | - |
 ```
 
-Reference full template: `~/.claude/qgsd/templates/roadmap.md`
+Reference full template: `~/.claude/nf/templates/roadmap.md`
 
 ## STATE.md Structure
 
-Use template from `~/.claude/qgsd/templates/state.md`.
+Use template from `~/.claude/nf/templates/state.md`.
 
 Key sections:
 - Project Reference (core value, current focus)

package/agents/{qgsd-verifier.md → nf-verifier.md}

@@ -1,5 +1,5 @@
 ---
-name: qgsd-verifier
+name: nf-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
@@ -57,7 +57,7 @@ Set `is_re_verification = false`, proceed with Step 1.
 ```bash
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
-node ~/.claude/qgsd/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM"
+node ~/.claude/nf/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM"
 grep -E "^| $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
 ```
 
@@ -94,7 +94,7 @@ must_haves:
 If no must_haves in frontmatter, check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ~/.claude/qgsd/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+PHASE_DATA=$(node ~/.claude/nf/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -137,7 +137,7 @@ For each truth:
 Use gsd-tools for artifact verification against must_haves in PLAN frontmatter:
 
 ```bash
-ARTIFACT_RESULT=$(node ~/.claude/qgsd/bin/gsd-tools.cjs verify artifacts "$PLAN_PATH")
+ARTIFACT_RESULT=$(node ~/.claude/nf/bin/gsd-tools.cjs verify artifacts "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
@@ -186,7 +186,7 @@ Key links are critical connections. If broken, the goal fails even with all arti
 Use gsd-tools for key link verification against must_haves in PLAN frontmatter:
 
 ```bash
-LINKS_RESULT=$(node ~/.claude/qgsd/bin/gsd-tools.cjs verify key-links "$PLAN_PATH")
+LINKS_RESULT=$(node ~/.claude/nf/bin/gsd-tools.cjs verify key-links "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
@@ -268,12 +268,12 @@ Identify files modified in this phase from SUMMARY.md key-files section, or extr
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ~/.claude/qgsd/bin/gsd-tools.cjs summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
+SUMMARY_FILES=$(node ~/.claude/nf/bin/gsd-tools.cjs summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
 
 # Option 2: Verify commits exist (if commit hashes documented)
 COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-SUMMARY.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
-  COMMITS_VALID=$(node ~/.claude/qgsd/bin/gsd-tools.cjs verify commits $COMMIT_HASHES)
+  COMMITS_VALID=$(node ~/.claude/nf/bin/gsd-tools.cjs verify commits $COMMIT_HASHES)
 fi
 
 # Fallback: grep for files
@@ -502,7 +502,7 @@ Omit this section entirely.
 ---
 
 _Verified: {timestamp}_
-_Verifier: Claude (qgsd-verifier)_
+_Verifier: Claude (nf-verifier)_
 ```
 
 ## Return to Orchestrator

package/bin/accept-debug-invariant.cjs

@@ -4,7 +4,7 @@
 // Debug invariant write path (ARCH-03): writes a PROPERTY definition directly
 // to a canonical .planning/formal/tla/ spec with full provenance tracking.
 //
-// When /qgsd:debug accepts a new invariant candidate, this script writes it to
+// When /nf:debug accepts a new invariant candidate, this script writes it to
 // the canonical spec and records update_source=debug + session_id in model-registry.json.
 //
 // Usage:
@@ -31,7 +31,7 @@ function findProjectRoot(startPath) {
     if (parent === current) break; // filesystem root
     current = parent;
   }
-  return path.join(__dirname, '..'); // fallback to QGSD project root
+  return path.join(__dirname, '..'); // fallback to nForma project root
 }
 
 // ── Parse CLI arguments ───────────────────────────────────────────────────────

package/bin/account-manager.cjs

@@ -2,11 +2,11 @@
 'use strict';
 
 /**
- * account-manager.cjs — OAuth account pool manager for QGSD providers
+ * account-manager.cjs — OAuth account pool manager for nForma providers
  *
  * Manages multiple OAuth credentials for providers with oauth_rotation config.
  * The implementation is a state machine that directly mirrors
- * .planning/formal/tla/QGSDAccountManager.tla — each TLA+ action is one FSM event.
+ * .planning/formal/tla/NFAccountManager.tla — each TLA+ action is one FSM event.
  *
  * Usage:
  *   node bin/account-manager.cjs add --login [--name alias] [--provider gemini-1]
@@ -19,7 +19,7 @@
  * Credential layout (configurable via oauth_rotation in providers.json):
  *   active_file  — ~/.gemini/oauth_creds.json  (the live credential Gemini CLI reads)
  *   creds_dir    — ~/.gemini/accounts/          (pool: one .json per account)
- *   active_ptr   — ~/.gemini/accounts/.qgsd-active  (sidecar: name of active account)
+ *   active_ptr   — ~/.gemini/accounts/.nf-active  (sidecar: name of active account)
  */
 
 const fs     = require('fs');
@@ -27,7 +27,7 @@ const path   = require('path');
 const os     = require('os');
 const { spawn } = require('child_process');
 
-// ─── FSM states and events (mirrors QGSDAccountManager.tla) ──────────────────
+// ─── FSM states and events (mirrors NFAccountManager.tla) ──────────────────
 
 const S = Object.freeze({
   IDLE:      'IDLE',
@@ -53,7 +53,7 @@ const E = Object.freeze({
   RESET:         'RESET',
 });
 
-// Transition table derived from QGSDAccountManager.tla Next relation.
+// Transition table derived from NFAccountManager.tla Next relation.
 // TRANSITIONS[currentState][event] = nextState
 const TRANSITIONS = {
   [S.IDLE]: {
@@ -115,7 +115,7 @@ function expandHome(p) {
 function findProviders() {
   const search = [
     path.join(__dirname, 'providers.json'),
-    path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+    path.join(os.homedir(), '.claude', 'nf-bin', 'providers.json'),
   ];
   try {
     const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'));
@@ -184,7 +184,7 @@ function getActiveFile(provider) {
 // Sidecar pointer file — stores just the account name of the current active.
 // Avoids content-diffing which breaks when tokens are silently refreshed.
 function getActivePtr(credsDir) {
-  return path.join(credsDir, '.qgsd-active');
+  return path.join(credsDir, '.nf-active');
 }
 
 function listPool(credsDir) {
@@ -402,7 +402,7 @@ const C = {
 
 
 function printAccountsHeader(provider, pool, active) {
-  const tag    = `QGSD · Accounts · ${provider.name}  ·  ${provider.display_provider ?? ''}`;
+  const tag    = `nForma · Accounts · ${provider.name}  ·  ${provider.display_provider ?? ''}`;
   const border = '─'.repeat(tag.length + 4);
   console.log('');
   console.log(`  ${C.cyan}╭${border}╮${C.reset}`);
@@ -657,11 +657,11 @@ function usage(prefix = 'node bin/account-manager.cjs') {
     '  --login             Spawn auth login inline; auto-detect email from id_token',
     '  --name <email>      Account name/email (overrides auto-detection)',
     '',
-    'Formal spec: .planning/formal/tla/QGSDAccountManager.tla',
+    'Formal spec: .planning/formal/tla/NFAccountManager.tla',
   ].join('\n'));
 }
 
-// ─── Exported entry point (called by qgsd.cjs) ─────────────────────────
+// ─── Exported entry point (called by nf.cjs) ─────────────────────────
 
 async function run(argv, usagePrefix) {
   const getArg  = (f) => { const i = argv.indexOf(f); return i !== -1 && argv[i + 1] ? argv[i + 1] : null; };

package/bin/aggregate-requirements.cjs

@@ -68,7 +68,7 @@ function parseTraceability(content) {
 }
 
 // Extract milestone from document title
-// Matches: # Requirements: QGSD vX.XX ... or similar
+// Matches: # Requirements: nForma vX.XX ... or similar
 function extractMilestone(content) {
   const match = content.match(/#\s+Requirements:.*?(v[\d.]+)/);
   return match ? match[1] : 'unknown';

package/bin/analyze-assumptions.cjs

@@ -511,13 +511,13 @@ function generateGapReport(crossRefResults) {
   const partial = crossRefResults.filter(a => a.coverage === 'partial').length;
   const uncovered = crossRefResults.filter(a => a.coverage === 'uncovered').length;
 
-  // Generate metric names with qgsd_ prefix and collision detection
+  // Generate metric names with nf_ prefix and collision detection
   const metricNameCounts = new Map();
   const gaps = crossRefResults
     .filter(a => a.coverage !== 'covered')
     .map(a => {
-      // Generate canonical metric name: qgsd_ + lowercase + replace non-alnum with _
-      const baseName = 'qgsd_' + a.name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+      // Generate canonical metric name: nf_ + lowercase + replace non-alnum with _
+      const baseName = 'nf_' + a.name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
       // Track for collision detection
       const count = metricNameCounts.get(baseName) || 0;
       metricNameCounts.set(baseName, count + 1);

package/bin/analyze-state-space.cjs

@@ -59,23 +59,23 @@ const MERGE_BUDGET = {
 
 // ── CFG → TLA module mapping ────────────────────────────────────────────────
 // Reverse map: cfg base name (without .cfg) → TLA module name
-// Needed because cfg naming is inconsistent (MCbreaker vs MCQGSDQuorum etc.)
+// Needed because cfg naming is inconsistent (MCbreaker vs MCNFQuorum etc.)
 
 const CFG_TO_MODULE = {
-  'MCbreaker':             'QGSDCircuitBreaker',
-  'MCoscillation':         'QGSDOscillation',
-  'MCconvergence':         'QGSDConvergence',
-  'MCdeliberation':        'QGSDDeliberation',
-  'MCprefilter':           'QGSDPreFilter',
-  'MCsafety':              'QGSDQuorum',
-  'MCliveness':            'QGSDQuorum',
-  'MCQGSDQuorum':          'QGSDQuorum_xstate',
-  'MCaccount-manager':     'QGSDAccountManager',
-  'MCMCPEnv':              'QGSDMCPEnv',
+  'MCbreaker':             'NFCircuitBreaker',
+  'MCoscillation':         'NFOscillation',
+  'MCconvergence':         'NFConvergence',
+  'MCdeliberation':        'NFDeliberation',
+  'MCprefilter':           'NFPreFilter',
+  'MCsafety':              'NFQuorum',
+  'MCliveness':            'NFQuorum',
+  'MCNFQuorum':          'NFQuorum_xstate',
+  'MCaccount-manager':     'NFAccountManager',
+  'MCMCPEnv':              'NFMCPEnv',
   'MCTUINavigation':       'TUINavigation',
-  'MCStopHook':            'QGSDStopHook',
-  'MCrecruiting-safety':   'QGSDRecruiting',
-  'MCrecruiting-liveness': 'QGSDRecruiting',
+  'MCStopHook':            'NFStopHook',
+  'MCrecruiting-safety':   'NFRecruiting',
+  'MCrecruiting-liveness': 'NFRecruiting',
 };
 
 // ── Parsing Utilities ───────────────────────────────────────────────────────

package/bin/assumption-register.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * assumption-register.cjs — Parses assumption-gaps.md into a structured JSON
+ * register with validation status and linked L2 states.
+ *
+ * Requirements: SEM-03
+ *
+ * Usage:
+ *   node bin/assumption-register.cjs            # print summary to stdout
+ *   node bin/assumption-register.cjs --json     # print full register JSON to stdout
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = process.env.PROJECT_ROOT || path.join(__dirname, '..');
+const FORMAL = path.join(ROOT, '.planning', 'formal');
+const GAPS_PATH = path.join(FORMAL, 'assumption-gaps.md');
+const OUT_DIR = path.join(FORMAL, 'semantics');
+const OUT_FILE = path.join(OUT_DIR, 'assumption-register.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Parser ──────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a markdown table string into structured assumption entries.
+ * @param {string} content - Raw markdown content containing a pipe-delimited table
+ * @returns {Array} Parsed assumption entries
+ */
+function parseMarkdownTable(content) {
+  const lines = content.split('\n');
+  const assumptions = [];
+  let skipped = 0;
+
+  for (const line of lines) {
+    // Skip non-table lines, header rows, separator rows
+    if (!line.startsWith('|')) continue;
+    if (line.includes('---')) continue;
+
+    const cells = line.split('|').map(c => c.trim()).filter(c => c !== '');
+    if (cells.length < 7) {
+      // Check if this is the header row
+      if (cells[0] === '#' || cells[0] === 'Metric') continue;
+      skipped++;
+      continue;
+    }
+
+    const numCell = cells[0];
+    // Skip header row
+    if (numCell === '#') continue;
+
+    const id = parseInt(numCell, 10);
+    if (isNaN(id)) {
+      skipped++;
+      continue;
+    }
+
+    assumptions.push({
+      id,
+      source: cells[1],
+      name: cells[2],
+      type: cells[3],
+      coverage: cells[4],
+      proposed_metric: cells[5].replace(/^`|`$/g, ''),
+      metric_type: cells[6],
+      validation_status: 'untested',
+      linked_l2_states: []
+    });
+  }
+
+  if (skipped > 0) {
+    process.stderr.write(`Warning: skipped ${skipped} malformed table lines\n`);
+  }
+
+  return assumptions;
+}
+
+/**
+ * Parse assumption-gaps.md file into structured entries.
+ * @param {string} gapsPath - Path to the assumption-gaps.md file
+ * @returns {Array} Parsed assumption entries
+ */
+function parseAssumptionGaps(gapsPath) {
+  const content = fs.readFileSync(gapsPath, 'utf8');
+  return parseMarkdownTable(content);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+function main() {
+  if (!fs.existsSync(GAPS_PATH)) {
+    console.error(`ERROR: assumption-gaps.md not found at ${GAPS_PATH}`);
+    process.exit(1);
+  }
+
+  const assumptions = parseAssumptionGaps(GAPS_PATH);
+
+  if (assumptions.length < 500) {
+    console.error(`ERROR: Only parsed ${assumptions.length} assumptions, expected >= 500`);
+    process.exit(1);
+  }
+
+  // Build summary
+  const byType = {};
+  const byCoverage = {};
+  for (const a of assumptions) {
+    byType[a.type] = (byType[a.type] || 0) + 1;
+    byCoverage[a.coverage] = (byCoverage[a.coverage] || 0) + 1;
+  }
+
+  const register = {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    assumptions,
+    summary: {
+      total_parsed: assumptions.length,
+      by_type: byType,
+      by_coverage: byCoverage,
+      by_validation_status: {
+        untested: assumptions.length,
+        validated: 0,
+        invalidated: 0
+      }
+    }
+  };
+
+  if (!fs.existsSync(OUT_DIR)) fs.mkdirSync(OUT_DIR, { recursive: true });
+  fs.writeFileSync(OUT_FILE, JSON.stringify(register, null, 2) + '\n');
+
+  if (JSON_FLAG) {
+    process.stdout.write(JSON.stringify(register, null, 2) + '\n');
+  } else {
+    console.log(`Assumption Register written to ${path.relative(ROOT, OUT_FILE)}`);
+    console.log(`  Total parsed: ${assumptions.length}`);
+    console.log(`  By type: ${Object.entries(byType).map(([k,v]) => `${k}=${v}`).join(' ')}`);
+    console.log(`  By coverage: ${Object.entries(byCoverage).map(([k,v]) => `${k}=${v}`).join(' ')}`);
+  }
+}
+
+// Export for testing
+module.exports = { parseAssumptionGaps, parseMarkdownTable };
+
+if (require.main === module) main();

package/bin/attribute-trace-divergence.cjs

@@ -70,7 +70,7 @@ function classifyDivergence(ttrace) {
 
   const recommendation = implBugConfidence >= specBugConfidence
     ? `impl-bug: check hook implementation — context field initialization or event payload mapping`
-    : `spec-bug: review XState guard "${failingGuard || 'unknown'}" in qgsd-workflow.machine.ts`;
+    : `spec-bug: review XState guard "${failingGuard || 'unknown'}" in nf-workflow.machine.ts`;
 
   return { specBugConfidence, implBugConfidence, failingGuard, recommendation, evidence };
 }

package/bin/auth-drivers/gh-cli.cjs

@@ -6,7 +6,7 @@
  * Accounts live in the macOS/system keychain managed by gh.
  * There is no credential file to copy — all operations delegate to gh.
  * This is the single source of truth for gh auth status parsing,
- * replacing duplicated regex in qgsd.cjs and gh-account-rotate.cjs.
+ * replacing duplicated regex in nf.cjs and gh-account-rotate.cjs.
  *
  * Applies to: copilot-1
  *

package/bin/auth-drivers/pool.cjs

@@ -19,7 +19,7 @@ const acm = require('../account-manager.cjs');
 
 /**
  * list(provider) → [{ name, active }]
- * Reads the pool directory and the .qgsd-active pointer — no subprocess.
+ * Reads the pool directory and the .nf-active pointer — no subprocess.
  */
 function list(provider) {
   const credsDir = acm.getCredsDir(provider);

package/bin/autoClosePtoF.cjs

@@ -1,6 +1,6 @@
 /**
  * P->F auto-close remediation dispatch
- * Dispatches parameter updates via /qgsd:quick for drift entries,
+ * Dispatches parameter updates via /nf:quick for drift entries,
  * flags investigation for issue/invariant entries.
  *
  * Requirements: PF-04, PF-05
@@ -63,11 +63,11 @@ function autoClosePtoF(residual, options = {}) {
     const isParameter = entry.issue_type === 'drift' && isNumericFn(entry.formal_ref, { specDir });
 
     if (isParameter) {
-      // Parameter update track: dispatch /qgsd:quick
+      // Parameter update track: dispatch /nf:quick
       let dispatchOk = false;
 
       if (spawnFn) {
-        const result = spawnFn('qgsd-quick.cjs', [
+        const result = spawnFn('nf-quick.cjs', [
           `Update formal parameter ${entry.formal_ref} to match production`,
           `Production measurement: ${entry.meta?.measured_value}`,
           `Current formal: ${div.expected}`,

package/bin/budget-tracker.cjs

@@ -0,0 +1,77 @@
+'use strict';
+// bin/budget-tracker.cjs
+// Token budget calculation, profile downgrade logic, and subscription slot exclusion.
+// Uses only node:fs, node:path. No external dependencies.
+
+const fs = require('fs');
+const path = require('path');
+
+// Profile downgrade sequence: quality -> balanced -> budget -> null (minimum)
+const DOWNGRADE_CHAIN = { quality: 'balanced', balanced: 'budget', budget: null };
+
+/**
+ * Compute budget status from context window usage percentage.
+ * @param {number} usedPct - Context window used percentage (0-100).
+ * @param {object} budgetConfig - budget config section from nf.json.
+ * @param {object} agentConfig - agent_config section from nf.json (unused for now, reserved for sub exclusion).
+ * @returns {object} Budget status object.
+ */
+function computeBudgetStatus(usedPct, budgetConfig, agentConfig) {
+  if (!budgetConfig || budgetConfig.session_limit_tokens == null) {
+    return { active: false };
+  }
+
+  const estimatedTokens = Math.round((usedPct / 100) * 200000);
+  const budgetUsedPct = Math.round((estimatedTokens / budgetConfig.session_limit_tokens) * 100);
+
+  return {
+    active: true,
+    estimatedTokens,
+    budgetUsedPct,
+    shouldWarn: budgetUsedPct >= (budgetConfig.warn_pct || 60),
+    shouldDowngrade: budgetUsedPct >= (budgetConfig.downgrade_pct || 85),
+  };
+}
+
+/**
+ * Trigger a model profile downgrade by writing to .planning/config.json.
+ * @param {string} cwd - Project working directory.
+ * @returns {object} Downgrade result.
+ */
+function triggerProfileDowngrade(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    const current = config.model_profile || 'balanced';
+    const next = DOWNGRADE_CHAIN[current];
+    if (next === undefined || next === null) {
+      return { downgraded: false, current };
+    }
+    config.model_profile = next;
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    return { downgraded: true, from: current, to: next };
+  } catch (e) {
+    return { downgraded: false, error: e.message };
+  }
+}
+
+/**
+ * Format a budget warning message for additionalContext injection.
+ * @param {object} status - Output from computeBudgetStatus.
+ * @param {object|null} downgradeResult - Output from triggerProfileDowngrade (or null).
+ * @returns {string} Warning message.
+ */
+function formatBudgetWarning(status, downgradeResult) {
+  if (status.shouldDowngrade && downgradeResult && downgradeResult.downgraded) {
+    return `BUDGET ALERT: Context at ${status.budgetUsedPct}% of token budget. Model profile downgraded from '${downgradeResult.from}' to '${downgradeResult.to}'. Consider running /compact.`;
+  }
+  if (status.shouldWarn) {
+    return `BUDGET WARNING: Context at ${status.budgetUsedPct}% of token budget (${status.estimatedTokens} estimated tokens of ${status.active ? (status.budgetUsedPct > 0 ? Math.round(status.estimatedTokens * 100 / status.budgetUsedPct) : 0) : 0} limit). Monitor usage and consider /compact at next clean boundary.`;
+  }
+  return '';
+}
+
+module.exports = { DOWNGRADE_CHAIN, computeBudgetStatus, triggerProfileDowngrade, formatBudgetWarning };