agileflow 3.4.2 → 3.4.3

package/scripts/check-sessions.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * check-sessions.js - Top-level entry point for monitoring tmux audit sessions
+ *
+ * Thin wrapper around lib/tmux-audit-monitor.js for easy discovery and calling.
+ *
+ * Subcommands:
+ *   list                                 - List all active audit traces
+ *   status  <trace_id>                   - Check progress of a specific audit trace
+ *   wait    <trace_id> [--timeout=1800]  - Block until audit trace completes
+ *   collect <trace_id>                   - Collect findings from completed analyzers
+ *   retry   <trace_id> [--analyzer=key]  - Retry stalled analyzers
+ *   kill    <trace_id> [--keep-files]    - Clean shutdown
+ *
+ * All output is JSON to stdout. Progress goes to stderr.
+ *
+ * Usage:
+ *   node .agileflow/scripts/check-sessions.js list
+ *   node .agileflow/scripts/check-sessions.js status abc123ef
+ *   node .agileflow/scripts/check-sessions.js wait abc123ef --timeout=600
+ */
+
+const USAGE = `Usage: check-sessions.js <subcommand> [trace_id] [options]
+
+Subcommands:
+  list                              List all active audit traces
+  status  <trace_id>                Check progress of a specific audit trace
+  wait    <trace_id> [--timeout=N]  Block until audit trace completes (default: 1800s)
+  collect <trace_id>                Collect findings from completed analyzers
+  retry   <trace_id> [--analyzer=X] Retry stalled analyzers
+  kill    <trace_id> [--keep-files] Clean shutdown of audit sessions
+
+Options:
+  --timeout=N       Seconds to wait before timeout (default: 1800)
+  --poll=N          Seconds between status checks (default: 5)
+  --analyzer=KEY    Retry specific analyzer only
+  --model=MODEL     Model override for retry
+  --keep-files      Don't remove sentinel files on kill
+  --help            Show this help message`;
+
+function jsonOut(obj) {
+  console.log(JSON.stringify(obj));
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.error(USAGE);
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  // Delegate to tmux-audit-monitor.js
+  let monitor;
+  try {
+    monitor = require('./lib/tmux-audit-monitor');
+  } catch (err) {
+    jsonOut({ ok: false, error: `Failed to load tmux-audit-monitor: ${err.message}` });
+    process.exit(1);
+  }
+
+  const subcommand = args[0];
+  const traceId = args[1];
+  const restArgs = args.slice(2);
+  const rootDir = process.cwd();
+  const opts = monitor.parseSubcommandArgs(restArgs);
+
+  // Validate traceId for commands that require it
+  const needsTraceId = ['status', 'wait', 'collect', 'retry', 'kill'];
+  if (needsTraceId.includes(subcommand) && !traceId) {
+    jsonOut({ ok: false, error: 'trace_id required' });
+    process.exit(1);
+  }
+
+  try {
+    switch (subcommand) {
+      case 'status':
+        monitor.cmdStatus(rootDir, traceId);
+        break;
+
+      case 'wait':
+        // Not awaited — event loop stays alive via sleep() timer inside cmdWait
+        monitor.cmdWait(rootDir, traceId, opts.timeout, opts.poll).catch(err => {
+          jsonOut({ ok: false, error: err.message });
+          process.exit(1);
+        });
+        break;
+
+      case 'collect':
+        monitor.cmdCollect(rootDir, traceId);
+        break;
+
+      case 'retry':
+        monitor.cmdRetry(rootDir, traceId, opts.analyzer, opts.model);
+        break;
+
+      case 'kill':
+        monitor.cmdKill(rootDir, traceId, opts.keepFiles);
+        break;
+
+      case 'list':
+        monitor.cmdList(rootDir);
+        break;
+
+      default:
+        jsonOut({ ok: false, error: `Unknown subcommand: ${subcommand}` });
+        process.exit(1);
+    }
+  } catch (err) {
+    jsonOut({ ok: false, error: err.message });
+    process.exit(1);
+  }
+}
+
+module.exports = { USAGE };

package/scripts/lib/quality-gates.js

@@ -20,6 +20,7 @@
 const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { buildSpawnArgs } = require('../../lib/validate-commands');
 
 // ============================================================================
 // Constants
@@ -206,20 +207,45 @@ function executeGate(gate, options = {}) {
   }
 
   try {
-    const result = spawnSync('sh', ['-c', gate.command], {
-      cwd,
-      env,
-      timeout: gate.timeout,
-      encoding: 'utf8',
-      maxBuffer: 10 * 1024 * 1024, // 10MB
-    });
+    // Try safe spawn first (no shell injection possible)
+    const validation = buildSpawnArgs(gate.command, { strict: false });
+    let result;
+    if (validation.ok) {
+      result = spawnSync(validation.data.file, validation.data.args, {
+        cwd,
+        env,
+        timeout: gate.timeout,
+        encoding: 'utf8',
+        shell: false,
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+      });
+      // If spawn failed (e.g., shell builtin, command not found), fall back to shell
+      if (result.error) {
+        result = spawnSync('sh', ['-c', gate.command], {
+          cwd,
+          env,
+          timeout: gate.timeout,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024, // 10MB
+        });
+      }
+    } else {
+      // Fallback for complex commands (pipes, shell builtins, etc.)
+      result = spawnSync('sh', ['-c', gate.command], {
+        cwd,
+        env,
+        timeout: gate.timeout,
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+      });
+    }
 
     const duration = Date.now() - startTime;
 
     // Check exit code
     if (result.status === 0) {
       // Check threshold if applicable
-      if (gate.type === GATE_TYPES.COVERAGE && gate.threshold) {
+      if (gate.type === GATE_TYPES.COVERAGE && gate.threshold != null) {
         const coverage = parseCoverageOutput(result.stdout + result.stderr);
         if (coverage !== null && coverage < gate.threshold) {
           return {
@@ -320,6 +346,7 @@ function executeGates(gates, options = {}) {
  * @returns {number|null} Coverage percentage or null
  */
 function parseCoverageOutput(output) {
+  if (!output || typeof output !== 'string') return null;
   // Common coverage patterns
   const patterns = [
     /All files[^|]*\|[^|]*\|\s*([\d.]+)/,

package/scripts/lib/signal-detectors.js

@@ -523,18 +523,6 @@ const FEATURE_DETECTORS = {
     return null;
   },
 
-  serve: signals => {
-    const { metadata } = signals;
-    const dashboardEnabled = metadata?.features?.dashboard?.enabled;
-    if (!dashboardEnabled) return null;
-    return recommend('serve', {
-      priority: 'low',
-      trigger: 'Dashboard server available',
-      action: 'offer',
-      phase: 'implementation',
-    });
-  },
-
   'ac-verify': signals => {
     const { story, tests } = signals;
     if (!story || story.status !== 'in-progress') return null;
@@ -767,7 +755,6 @@ const PHASE_MAP = {
     'maintain',
     'packages',
     'deploy',
-    'serve',
   ],
   'post-impl': [
     'ac-verify',

package/scripts/lib/team-events.js

@@ -482,7 +482,7 @@ function saveAggregatedMetrics(rootDir, metrics) {
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     }
 
-    // Notify listeners (e.g., dashboard server) that metrics were saved
+    // Notify listeners that metrics were saved
     try {
       teamMetricsEmitter.emit('metrics_saved', { trace_id: metrics.trace_id });
     } catch (_) {

package/scripts/lib/tmux-audit-monitor.js

@@ -520,7 +520,8 @@ function parseSubcommandArgs(args) {
       const val = arg.split('=')[1];
       if (val) parsed.analyzer = val;
     } else if (arg.startsWith('--model=')) {
-      parsed.model = arg.split('=')[1];
+      const val = arg.split('=')[1];
+      if (val) parsed.model = val;
     } else if (arg === '--keep-files') {
       parsed.keepFiles = true;
     }

package/src/core/commands/ads/audit.md

@@ -12,6 +12,8 @@ compact_context:
     - "MUST detect industry type before deploying analyzers"
     - "Pass all analyzer outputs to ads-consensus for final report"
     - "Quality Gates: No optimization without tracking, 3x Kill Rule, Broad Match needs Smart Bidding"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - depth
     - platforms
@@ -112,7 +114,7 @@ PLATFORMS = all detected (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
@@ -131,7 +133,7 @@ Partition-based multi-agent audit. Instead of auditing all platforms together, e
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=ads --target=account-data --depth=extreme --partitions=google,meta,linkedin --model=MODEL --json
    ```
-5. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+5. Wait and collect results (same as ultradeep - use check-sessions.js)
 6. Run consensus on combined results from all platform partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -141,6 +143,20 @@ Partition-based multi-agent audit. Instead of auditing all platforms together, e
 | `PARTITIONS=3` | AI merges into 3 platform groups |
 | `PARTITIONS=google,meta` | Use these exact platforms |
 
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEPs 2-4 are for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
 Accept data in any format:
 - **Pasted CSV/text** - Parse columns and metrics
 - **File path** - Read CSV/JSON export files
@@ -170,7 +186,7 @@ From the account data, identify:
 - **Active platforms**: Which ad platforms have campaigns
 - **Account maturity**: New (< 3 months), Growing (3-12 months), Mature (12+ months)
 
-### STEP 3: Deploy 6 Analyzers in Parallel
+### STEP 3: Deploy 6 Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL 6 analyzers in a SINGLE message with multiple Task calls.
 

package/src/core/commands/code/accessibility.md

@@ -10,6 +10,8 @@ compact_context:
     - "CRITICAL: Severity scale: BLOCKER | MAJOR | MINOR | ENHANCEMENT"
     - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (semantic|aria|visual|keyboard|forms|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - target_path
     - depth
@@ -70,7 +72,7 @@ Deploy multiple specialized WCAG accessibility analyzers in parallel to find a11
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick = focus on BLOCKER/MAJOR, deep = all severities, ultradeep = separate tmux |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = focus on BLOCKER/MAJOR, deep = all severities, ultradeep = separate tmux, extreme = partitioned tmux |
 | FOCUS | semantic,aria,visual,keyboard,forms,all | all | Which analyzers to deploy |
 | MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents |
 
@@ -116,12 +118,12 @@ FOCUS = all (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
-   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
-   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+   - To check progress without blocking: `node .agileflow/scripts/check-sessions.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/check-sessions.js retry TRACE_ID`
 5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
 6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
 
@@ -138,7 +140,7 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=accessibility --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
    ```
-4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+4. Wait and collect results (same as ultradeep - use check-sessions.js)
 5. Run consensus on combined results from all partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -148,7 +150,21 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
 | `PARTITIONS=5` | AI creates exactly 5 partitions |
 | `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
-### STEP 2: Deploy Analyzers in Parallel
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEP 2 is for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
+### STEP 2: Deploy Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL selected analyzers in a SINGLE message with multiple Task calls.
 

package/src/core/commands/code/api.md

@@ -10,6 +10,8 @@ compact_context:
     - "CRITICAL: Severity scale: BREAKING | INCONSISTENT | GAP | POLISH"
     - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (conventions|errors|versioning|pagination|docs|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - target_path
     - depth
@@ -70,7 +72,7 @@ Deploy multiple specialized API quality analyzers in parallel to assess API desi
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick = BREAKING/INCONSISTENT only, deep = all severities, ultradeep = separate tmux |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = BREAKING/INCONSISTENT only, deep = all severities, ultradeep = separate tmux, extreme = partitioned tmux |
 | FOCUS | conventions,errors,versioning,pagination,docs,all | all | Which analyzers to deploy |
 | MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents |
 
@@ -115,12 +117,12 @@ FOCUS = all (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
-   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
-   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+   - To check progress without blocking: `node .agileflow/scripts/check-sessions.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/check-sessions.js retry TRACE_ID`
 5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
 6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
 
@@ -137,7 +139,7 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=api --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
    ```
-4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+4. Wait and collect results (same as ultradeep - use check-sessions.js)
 5. Run consensus on combined results from all partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -147,7 +149,21 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
 | `PARTITIONS=5` | AI creates exactly 5 partitions |
 | `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
-### STEP 2: Deploy Analyzers in Parallel
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEP 2 is for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
+### STEP 2: Deploy Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL selected analyzers in a SINGLE message with multiple Task calls.
 

package/src/core/commands/code/architecture.md

@@ -10,6 +10,8 @@ compact_context:
     - "CRITICAL: Severity scale: STRUCTURAL | DEGRADED | SMELL | STYLE"
     - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (coupling|layering|complexity|patterns|circular|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - target_path
     - depth
@@ -70,7 +72,7 @@ Deploy multiple specialized architecture analyzers in parallel to assess structu
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick = STRUCTURAL/DEGRADED only, deep = all severities, ultradeep = separate tmux |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = STRUCTURAL/DEGRADED only, deep = all severities, ultradeep = separate tmux, extreme = partitioned tmux |
 | FOCUS | coupling,layering,complexity,patterns,circular,all | all | Which analyzers to deploy |
 | MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents |
 
@@ -115,12 +117,12 @@ FOCUS = all (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
-   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
-   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+   - To check progress without blocking: `node .agileflow/scripts/check-sessions.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/check-sessions.js retry TRACE_ID`
 5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
 6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
 
@@ -137,7 +139,7 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=architecture --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
    ```
-4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+4. Wait and collect results (same as ultradeep - use check-sessions.js)
 5. Run consensus on combined results from all partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -147,7 +149,21 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
 | `PARTITIONS=5` | AI creates exactly 5 partitions |
 | `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
-### STEP 2: Deploy Analyzers in Parallel
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEP 2 is for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
+### STEP 2: Deploy Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL selected analyzers in a SINGLE message with multiple Task calls.
 

package/src/core/commands/code/completeness.md

@@ -11,6 +11,8 @@ compact_context:
     - "CRITICAL: Confidence scoring: CONFIRMED (2+ agree), LIKELY (1 with evidence), INVESTIGATE (1 weak)"
     - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (handlers|routes|api|stubs|state|imports|conditional|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - target_path
     - depth
@@ -74,7 +76,7 @@ Deploy multiple specialized completeness analyzers in parallel to find forgotten
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick = core 5, deep = all 7, ultradeep = separate tmux sessions |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = core 5, deep = all 7, ultradeep = separate tmux sessions, extreme = partitioned tmux sessions |
 | FOCUS | handlers,routes,api,stubs,state,imports,conditional,all | all | Which analyzers to deploy |
 | MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents. Default preserves existing behavior. |
 
@@ -134,12 +136,12 @@ FOCUS = all (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
-   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
-   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+   - To check progress without blocking: `node .agileflow/scripts/check-sessions.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/check-sessions.js retry TRACE_ID`
 5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
 6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
 
@@ -156,7 +158,7 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=completeness --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
    ```
-4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+4. Wait and collect results (same as ultradeep - use check-sessions.js)
 5. Run consensus on combined results from all partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -166,7 +168,21 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
 | `PARTITIONS=5` | AI creates exactly 5 partitions |
 | `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
-### STEP 2: Deploy Analyzers in Parallel
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEP 2 is for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
+### STEP 2: Deploy Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL selected analyzers in a SINGLE message with multiple Task calls.
 

package/src/core/commands/code/legal.md

@@ -10,6 +10,8 @@ compact_context:
     - "CRITICAL: Confidence scoring: CONFIRMED (2+ agree), LIKELY (1 with evidence), INVESTIGATE (1 weak)"
     - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (privacy|terms|a11y|licensing|consumer|security|ai|content|international|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
+    - "DEPTH GATE: ultradeep/extreme MUST spawn tmux sessions via spawn-audit-sessions.js — NEVER deploy in-process"
+    - "Use check-sessions.js to monitor spawned tmux sessions — NEVER write custom polling scripts"
   state_fields:
     - target_path
     - depth
@@ -73,7 +75,7 @@ Deploy multiple specialized legal risk analyzers in parallel to find compliance
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick = core 5, deep = all 9, ultradeep = separate tmux sessions |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = core 5, deep = all 9, ultradeep = separate tmux sessions, extreme = partitioned tmux sessions |
 | FOCUS | privacy,terms,a11y,licensing,consumer,security,ai,content,international,all | all | Which analyzers to deploy |
 | MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents. Default preserves existing behavior. |
 
@@ -124,12 +126,12 @@ FOCUS = all (default) or comma-separated list
    Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
 4. Wait for all analyzers to complete:
    ```bash
-   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   node .agileflow/scripts/check-sessions.js wait TRACE_ID --timeout=1800
    ```
    - Exit 0 = all complete (JSON results on stdout)
    - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
-   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
-   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+   - To check progress without blocking: `node .agileflow/scripts/check-sessions.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/check-sessions.js retry TRACE_ID`
 5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
 6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
 
@@ -146,7 +148,7 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
    ```bash
    node .agileflow/scripts/spawn-audit-sessions.js --audit=legal --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
    ```
-4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+4. Wait and collect results (same as ultradeep - use check-sessions.js)
 5. Run consensus on combined results from all partitions
 
 **PARTITIONS argument** (only used with DEPTH=extreme):
@@ -156,7 +158,21 @@ Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the co
 | `PARTITIONS=5` | AI creates exactly 5 partitions |
 | `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
-### STEP 2: Deploy Analyzers in Parallel
+---
+
+### DEPTH ROUTING GATE
+
+| DEPTH | Route |
+|-------|-------|
+| `quick` or `deep` | Continue to STEP 2 below |
+| `ultradeep` | STOP. Follow ULTRADEEP instructions above. Do NOT proceed to STEP 2. |
+| `extreme` | STOP. Follow EXTREME instructions above. Do NOT proceed to STEP 2. |
+
+**CRITICAL**: STEP 2 is for `quick`/`deep` ONLY. For `ultradeep`/`extreme`, the analyzers run in separate tmux sessions — NOT in-process via Task calls. If you deploy Task calls for ultradeep/extreme, you are doing it wrong. Follow the spawn-audit-sessions.js workflow above, then skip to the consensus step with the collected results.
+
+---
+
+### STEP 2: Deploy Analyzers in Parallel (quick/deep ONLY)
 
 **CRITICAL**: Deploy ALL selected analyzers in a SINGLE message with multiple Task calls.