agileflow 3.4.1 → 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/audit-registry.js

@@ -188,6 +188,42 @@ const AUDIT_TYPES = {
     ],
   },
 
+  seo: {
+    name: 'SEO Audit',
+    prefix: 'SEO',
+    color: '#ff9e64', // rose/orange
+    command: 'seo/audit',
+    analyzers: {
+      technical: { subagent_type: 'seo-analyzer-technical', label: 'Technical SEO' },
+      content: { subagent_type: 'seo-analyzer-content', label: 'Content Quality' },
+      schema: { subagent_type: 'seo-analyzer-schema', label: 'Schema Markup' },
+      images: { subagent_type: 'seo-analyzer-images', label: 'Image Optimization' },
+      performance: { subagent_type: 'seo-analyzer-performance', label: 'Core Web Vitals' },
+      sitemap: { subagent_type: 'seo-analyzer-sitemap', label: 'Sitemap' },
+    },
+    consensus: { subagent_type: 'seo-consensus', label: 'SEO Consensus' },
+    quick_analyzers: ['technical', 'content', 'schema', 'images', 'performance', 'sitemap'],
+    deep_analyzers: ['technical', 'content', 'schema', 'images', 'performance', 'sitemap'],
+  },
+
+  ads: {
+    name: 'Ads Audit',
+    prefix: 'Ads',
+    color: '#89ddff', // ice
+    command: 'ads/audit',
+    analyzers: {
+      google: { subagent_type: 'ads-audit-google', label: 'Google Ads' },
+      meta: { subagent_type: 'ads-audit-meta', label: 'Meta Ads' },
+      budget: { subagent_type: 'ads-audit-budget', label: 'Budget & Bidding' },
+      creative: { subagent_type: 'ads-audit-creative', label: 'Creative Quality' },
+      tracking: { subagent_type: 'ads-audit-tracking', label: 'Conversion Tracking' },
+      compliance: { subagent_type: 'ads-audit-compliance', label: 'Compliance' },
+    },
+    consensus: { subagent_type: 'ads-consensus', label: 'Ads Consensus' },
+    quick_analyzers: ['google', 'meta', 'budget', 'creative', 'tracking', 'compliance'],
+    deep_analyzers: ['google', 'meta', 'budget', 'creative', 'tracking', 'compliance'],
+  },
+
   legal: {
     name: 'Legal Risk',
     prefix: 'Legal',

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/scripts/lib/tmux-group-colors.js

@@ -23,8 +23,8 @@ const GROUP_PALETTE = [
   { name: 'amber', hex: '#e0af68', audit: 'test' },
   { name: 'violet', hex: '#bb9af7', audit: 'completeness' },
   { name: 'lime', hex: '#9ece6a', audit: 'legal' },
-  { name: 'rose', hex: '#ff9e64', audit: null },
-  { name: 'ice', hex: '#89ddff', audit: null },
+  { name: 'rose', hex: '#ff9e64', audit: 'seo' },
+  { name: 'ice', hex: '#89ddff', audit: 'ads' },
 ];
 
 /**

package/scripts/spawn-audit-sessions.js

@@ -420,7 +420,7 @@ async function spawnAuditInTmux(options) {
 
   if (!auditType) {
     console.error(`Unknown audit type: ${options.audit}`);
-    console.error(`Valid types: logic, security, performance, test, completeness, legal`);
+    console.error(`Valid types: logic, security, performance, test, completeness, legal, seo, ads`);
     process.exit(1);
   }
 

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

@@ -1,6 +1,6 @@
 ---
 description: Full multi-platform paid advertising audit with 6 parallel analyzers, industry detection, weighted Ads Health Score 0-100, and prioritized action plan
-argument-hint: "<account-data> [PLATFORMS=all]"
+argument-hint: "<account-data> [DEPTH=quick|deep|ultradeep|extreme] [PLATFORMS=all]"
 compact_context:
   priority: high
   preserve_rules:
@@ -8,10 +8,14 @@ compact_context:
     - "CRITICAL: Deploy 6 analyzers IN PARALLEL in ONE message with multiple Task calls"
     - "CRITICAL: Wait for all results before running consensus (use TaskOutput with block=true)"
     - "CRITICAL: Weighted scoring - Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%"
+    - "MUST parse DEPTH argument: quick (default), deep, ultradeep, extreme"
     - "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
     - industry_type
     - analyzers_deployed
@@ -27,7 +31,10 @@ Deploy 6 specialized advertising analyzers in parallel to audit ad accounts, the
 ## Quick Reference
 
 ```
-/agileflow:ads:audit <account-data>                       # Full audit (all platforms detected)
+/agileflow:ads:audit <account-data>                       # Quick audit (all platforms detected)
+/agileflow:ads:audit <account-data> DEPTH=deep             # Deep audit (more thorough)
+/agileflow:ads:audit <account-data> DEPTH=ultradeep        # Each analyzer in its own tmux session
+/agileflow:ads:audit <account-data> DEPTH=extreme          # Platform-partitioned audit
 /agileflow:ads:audit <account-data> PLATFORMS=google,meta  # Specific platforms only
 ```
 
@@ -74,13 +81,81 @@ Deploy 6 specialized advertising analyzers in parallel to audit ad accounts, the
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | account-data | Text, file path, or description | Required | Account data to audit |
+| DEPTH | quick, deep, ultradeep, extreme | quick | quick = standard, deep = comprehensive, ultradeep = tmux sessions, extreme = platform partitions |
 | PLATFORMS | google,meta,linkedin,tiktok,microsoft,youtube | all detected | Limit to specific platforms |
 
 ---
 
 ## Step-by-Step Process
 
-### STEP 1: Parse Account Data
+### STEP 1: Parse Arguments & Account Data
+
+```
+DEPTH = quick (default), deep, ultradeep, or extreme
+PLATFORMS = all detected (default) or comma-separated list
+```
+
+**DEPTH behavior**:
+- `quick` (default): Deploy all 6 analyzers in-process. Standard analysis.
+- `deep`: Deploy all 6 analyzers in-process. More thorough, includes lower-priority findings.
+- `ultradeep`: Spawn each analyzer as a separate Claude Code session in tmux. Requires tmux. Falls back to `deep` if tmux unavailable.
+- `extreme`: Partition-based multi-agent audit. Account data is split by platform and each platform runs ALL analyzers.
+
+**ULTRADEEP mode** (DEPTH=ultradeep):
+1. Show cost estimate:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=ads --target=account-data --model=MODEL --dry-run
+   ```
+2. Confirm with user before launching
+3. Spawn sessions (use `--json` to capture trace ID):
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=ads --target=account-data --model=MODEL --json
+   ```
+   Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
+4. Wait for all analyzers to complete:
+   ```bash
+   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)
+5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator.
+6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
+
+**EXTREME mode** (DEPTH=extreme):
+Partition-based multi-agent audit. Instead of auditing all platforms together, each platform runs ALL 6 analyzers independently.
+1. Identify active platforms from account data (Google, Meta, LinkedIn, TikTok, etc.)
+2. Group into partitions by platform (each platform = 1 partition)
+   - If user provided PARTITIONS=N (a number), merge smaller platforms into N groups
+   - If user provided PARTITIONS=google,meta, use those exact platforms
+3. Show the partition plan and agent count to the user, confirm before launching:
+   Example: "3 platforms x 6 analyzers = 18 agents. Estimated cost: $X. Proceed?"
+4. Spawn sessions with partitions:
+   ```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 check-sessions.js)
+6. Run consensus on combined results from all platform partitions
+
+**PARTITIONS argument** (only used with DEPTH=extreme):
+| Value | Behavior |
+|-------|----------|
+| Not set | AI decides partitions (1 per detected platform) |
+| `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
@@ -111,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.
 
@@ -355,8 +430,11 @@ After consensus completes, show summary and offer next steps:
 
 **Quick Usage**:
 ```
-/agileflow:ads:audit <account-data>                # Full audit
-/agileflow:ads:audit <data> PLATFORMS=google,meta   # Specific platforms
+/agileflow:ads:audit <account-data>                       # Quick audit
+/agileflow:ads:audit <account-data> DEPTH=deep             # Deep audit
+/agileflow:ads:audit <account-data> DEPTH=ultradeep        # Tmux sessions
+/agileflow:ads:audit <account-data> DEPTH=extreme          # Platform partition audit
+/agileflow:ads:audit <data> PLATFORMS=google,meta           # Specific platforms
 ```
 
 **What It Does**: Parse data -> Detect industry -> Deploy 6 analyzers in parallel -> Consensus weights scores -> Ads Health Score 0-100 -> Prioritized action plan

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.