agileflow 3.4.0 → 3.4.2

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.2] - 2026-03-07
+
+### Added
+- DEPTH=ultradeep|extreme for SEO and Ads audit commands
+
+## [3.4.1] - 2026-03-06
+
+### Added
+- DEPTH=extreme audit mode, CI feedback loops, and DX quick wins
+
 ## [3.4.0] - 2026-02-28
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-124-blue)](https://docs.agileflow.projectquestorg.com/docs/commands)
-[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-111-orange)](https://docs.agileflow.projectquestorg.com/docs/agents)
+[![Commands](https://img.shields.io/badge/commands-143-blue)](https://docs.agileflow.projectquestorg.com/docs/commands)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-131-orange)](https://docs.agileflow.projectquestorg.com/docs/agents)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](https://docs.agileflow.projectquestorg.com/docs/features/skills)
 
 **AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
@@ -54,8 +54,8 @@ Traditional project management tools create friction between planning and execut
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](https://docs.agileflow.projectquestorg.com/docs/commands) | 124 | Slash commands for agile workflows |
-| [Agents/Experts](https://docs.agileflow.projectquestorg.com/docs/agents) | 111 | Specialized agents with self-improving knowledge bases |
+| [Commands](https://docs.agileflow.projectquestorg.com/docs/commands) | 143 | Slash commands for agile workflows |
+| [Agents/Experts](https://docs.agileflow.projectquestorg.com/docs/agents) | 131 | Specialized agents with self-improving knowledge bases |
 | [Skills](https://docs.agileflow.projectquestorg.com/docs/features/skills) | Dynamic | Browse and install from skills.sh marketplace via `/agileflow:skill:recommend` |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-welcome.js

@@ -1320,6 +1320,49 @@ function getExpertiseCountFast(rootDir) {
   return result;
 }
 
+/**
+ * Check if installed commands are in sync with source.
+ * Counts .md files in three directories:
+ * - .agileflow/commands/ (core install)
+ * - .claude/commands/agileflow/ excluding agents/ (IDE install)
+ * - packages/cli/src/core/commands/ (dogfooding source, if exists)
+ * Returns { sourceCount, coreCount, ideCount, stale, staleCoreInstall } or null on error.
+ */
+function checkCommandSync(rootDir) {
+  try {
+    const countMdFiles = dir => {
+      if (!fs.existsSync(dir)) return 0;
+      return fs.readdirSync(dir, { recursive: true }).filter(f => String(f).endsWith('.md')).length;
+    };
+
+    const agileflowDir = getAgileflowDir(rootDir);
+    const coreCount = countMdFiles(path.join(agileflowDir, 'commands'));
+
+    // IDE install: .claude/commands/agileflow/ excluding agents/ subdir
+    const ideDir = path.join(rootDir, '.claude', 'commands', 'agileflow');
+    let ideCount = 0;
+    if (fs.existsSync(ideDir)) {
+      ideCount = fs.readdirSync(ideDir, { recursive: true }).filter(f => {
+        const s = String(f);
+        return s.endsWith('.md') && !s.startsWith('agents/') && !s.startsWith('agents\\');
+      }).length;
+    }
+
+    // Dogfooding source (only exists in the AgileFlow repo itself)
+    const sourceDir = path.join(rootDir, 'packages', 'cli', 'src', 'core', 'commands');
+    const sourceCount = countMdFiles(sourceDir);
+
+    // Determine staleness
+    const referenceCount = sourceCount > 0 ? sourceCount : coreCount;
+    const stale = referenceCount > 0 && ideCount < referenceCount;
+    const staleCoreInstall = sourceCount > 0 && coreCount < sourceCount;
+
+    return { sourceCount, coreCount, ideCount, stale, staleCoreInstall };
+  } catch (e) {
+    return null;
+  }
+}
+
 // Full validation function (kept for /agileflow:validate-expertise command)
 function validateExpertise(rootDir) {
   const result = { total: 0, passed: 0, warnings: 0, failed: 0, issues: [] };
@@ -1894,6 +1937,9 @@ function main() {
   }
   _mark('expertise');
 
+  const commandSync = checkCommandSync(rootDir);
+  _mark('cmdSync');
+
   const damageControl = checkDamageControl(rootDir, cache);
   _mark('damageCtl');
 
@@ -2057,6 +2103,21 @@ function main() {
     );
   }
 
+  // Show command sync staleness notification
+  if (commandSync && commandSync.stale) {
+    const ref = commandSync.sourceCount > 0 ? commandSync.sourceCount : commandSync.coreCount;
+    console.log('');
+    console.log(
+      `${c.amber}⚠️  ${ref - commandSync.ideCount} command(s) out of sync${c.reset} ${c.dim}(IDE has ${commandSync.ideCount}/${ref})${c.reset}`
+    );
+    if (commandSync.staleCoreInstall) {
+      console.log(
+        `   ${c.dim}Core install also stale: ${commandSync.coreCount}/${commandSync.sourceCount}${c.reset}`
+      );
+    }
+    console.log(`   ${c.slate}Auto-syncing in background...${c.reset}`);
+  }
+
   // Show tmux installation notice if tmux auto-spawn is enabled but tmux not installed
   if (tmuxAutoSpawnEnabled && !tmuxCheck.available) {
     console.log('');
@@ -2141,6 +2202,24 @@ function main() {
 
   _mark('deferred');
 
+  // Spawn background command sync if stale
+  if (commandSync && commandSync.stale) {
+    try {
+      const isDogfooding = commandSync.sourceCount > 0;
+      if (isDogfooding) {
+        const cliPath = path.join(rootDir, 'packages', 'cli', 'tools', 'cli', 'agileflow-cli.js');
+        if (fs.existsSync(cliPath)) {
+          spawnBackground('node', [cliPath, 'update', '--force', '-d', rootDir], { cwd: rootDir });
+        }
+      } else {
+        spawnBackground('npx', ['agileflow', 'update', '--force'], { cwd: rootDir });
+      }
+    } catch (e) {
+      // Command sync spawn failed, non-critical
+    }
+  }
+  _mark('cmdSyncSpawn');
+
   // Record hook metrics
   if (timer && hookMetrics) {
     hookMetrics.recordHookMetrics(timer, 'success', null, { rootDir });

package/scripts/claude-tmux.sh

@@ -41,6 +41,7 @@ SHOW_HELP=false
 ATTACH_ONLY=false
 FORCE_NEW=false
 REFRESH_CONFIG=false
+CONFIGURE_SESSION=""
 USE_RESUME=false
 RESUME_SESSION_ID=""
 
@@ -74,6 +75,10 @@ for arg in "$@"; do
       REFRESH_CONFIG=true
       shift
       ;;
+    --configure-session=*)
+      CONFIGURE_SESSION="${arg#*=}"
+      shift
+      ;;
     --help|-h)
       SHOW_HELP=true
       shift
@@ -128,7 +133,6 @@ FREEZE RECOVERY:
   Alt+R            Respawn pane (fresh shell)
 
 OTHER:
-  Alt+b            Scroll mode (browse history)
   Alt+h            Show keybind help panel
 EOF
   exit 0
@@ -347,40 +351,6 @@ configure_tmux_session() {
   # Alt+z to zoom/unzoom pane (fullscreen toggle)
   tmux bind-key -n M-z resize-pane -Z
 
-  # Alt+b to enter copy mode (for scrolling / browsing history)
-  # NOTE: Do NOT use Alt+[ here — \e[ is the CSI prefix for arrow keys and
-  # function keys. Binding M-[ in the root table causes accidental copy-mode
-  # entry whenever an escape sequence is split by network latency, making the
-  # terminal appear to "lose focus" until Escape is pressed.
-  tmux bind-key -n M-b copy-mode
-
-  # Disable ALL command-prompt bindings in copy mode — they open a text input
-  # in the status bar which intercepts keystrokes and confuses the workflow.
-  # Navigation (arrows, scroll, mouse, PgUp/PgDn) and exit (q/Escape) still work.
-  #
-  # Emacs copy-mode: goto-line, search, jump-to-char, repeat-count
-  tmux unbind-key -T copy-mode g
-  tmux unbind-key -T copy-mode C-r
-  tmux unbind-key -T copy-mode C-s
-  tmux unbind-key -T copy-mode f
-  tmux unbind-key -T copy-mode F
-  tmux unbind-key -T copy-mode t
-  tmux unbind-key -T copy-mode T
-  for i in 1 2 3 4 5 6 7 8 9; do
-    tmux unbind-key -T copy-mode "M-$i"
-  done
-  # Vi copy-mode: goto-line, search, jump-to-char, repeat-count
-  tmux unbind-key -T copy-mode-vi :
-  tmux unbind-key -T copy-mode-vi /
-  tmux unbind-key -T copy-mode-vi ?
-  tmux unbind-key -T copy-mode-vi f
-  tmux unbind-key -T copy-mode-vi F
-  tmux unbind-key -T copy-mode-vi t
-  tmux unbind-key -T copy-mode-vi T
-  for i in 1 2 3 4 5 6 7 8 9; do
-    tmux unbind-key -T copy-mode-vi "$i"
-  done
-
   # ─── Session Creation Keybindings ──────────────────────────────────────────
   # Alt+s to create a new Claude window (starts fresh, future re-runs in same pane resume)
   # Window gets sequential name (claude-2, claude-3, ...) so windows are distinguishable
@@ -438,13 +408,19 @@ configure_tmux_session() {
     printf '  Alt+R      Respawn pane (fresh)\\n';\
     printf '\\n';\
     printf '  \\033[1;38;5;208mOTHER\\033[0m\\n';\
-    printf '  Alt+b      Scroll mode\\n';\
     printf '  Alt+k      Unfreeze (Ctrl+C x2)\\n';\
     printf '  Alt+h      This help\\n';\
     printf '\\n';\
     read -n 1 -s -r -p '  Press any key to close'"
 }
 
+# Handle --configure-session flag — apply theme to a specific session and exit
+# Used by spawn-audit-sessions.js to give audit sessions the same status bar
+if [ -n "$CONFIGURE_SESSION" ]; then
+  configure_tmux_session "$CONFIGURE_SESSION"
+  exit 0
+fi
+
 # Handle --refresh flag — re-apply config to all existing claude-* sessions
 if [ "$REFRESH_CONFIG" = true ]; then
   REFRESHED=0

package/scripts/lib/ac-test-matcher.js

@@ -0,0 +1,452 @@
+/**
+ * ac-test-matcher.js - Automated Acceptance Criteria to Test Mapping
+ *
+ * Reads story AC from status.json, scans test files for keyword overlap,
+ * and returns matched/unmatched AC with confidence levels.
+ *
+ * Usage:
+ *   const { matchACToTests } = require('./lib/ac-test-matcher');
+ *
+ *   const result = matchACToTests('US-0042', projectRoot);
+ *   // result = {
+ *   //   storyId: 'US-0042',
+ *   //   total: 5,
+ *   //   matched: [{ index: 0, ac: '...', confidence: 'high', testFiles: [...] }],
+ *   //   unmatched: [{ index: 2, ac: '...' }],
+ *   //   coverage: 0.6
+ *   // }
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { getProjectRoot, getStatusPath } = require('../../lib/paths');
+const { safeReadJSON } = require('../../lib/errors');
+
+// ============================================================================
+// Keyword Extraction
+// ============================================================================
+
+/**
+ * Extract meaningful keywords from an AC string.
+ * Filters out stop words and short tokens.
+ */
+const STOP_WORDS = new Set([
+  'the',
+  'a',
+  'an',
+  'is',
+  'are',
+  'was',
+  'were',
+  'be',
+  'been',
+  'being',
+  'have',
+  'has',
+  'had',
+  'do',
+  'does',
+  'did',
+  'will',
+  'would',
+  'could',
+  'should',
+  'may',
+  'might',
+  'must',
+  'shall',
+  'can',
+  'need',
+  'dare',
+  'to',
+  'of',
+  'in',
+  'for',
+  'on',
+  'with',
+  'at',
+  'by',
+  'from',
+  'as',
+  'into',
+  'through',
+  'during',
+  'before',
+  'after',
+  'above',
+  'below',
+  'and',
+  'but',
+  'or',
+  'nor',
+  'not',
+  'so',
+  'yet',
+  'both',
+  'either',
+  'neither',
+  'each',
+  'every',
+  'all',
+  'any',
+  'few',
+  'more',
+  'most',
+  'other',
+  'some',
+  'such',
+  'no',
+  'only',
+  'own',
+  'same',
+  'than',
+  'too',
+  'very',
+  'just',
+  'that',
+  'this',
+  'these',
+  'those',
+  'it',
+  'its',
+  'when',
+  'where',
+  'how',
+  'what',
+  'which',
+  'who',
+  'whom',
+  'then',
+  'there',
+  'here',
+  'if',
+  'else',
+  'while',
+  'about',
+  'up',
+  'out',
+  'also',
+  'given',
+  'user',
+  'system',
+  'able',
+]);
+
+function extractKeywords(text) {
+  if (!text || typeof text !== 'string') return [];
+  // Split on non-alphanumeric (keep hyphenated words)
+  const tokens = text
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length >= 3 && !STOP_WORDS.has(t));
+
+  return [...new Set(tokens)];
+}
+
+// ============================================================================
+// Test File Discovery
+// ============================================================================
+
+/** Common test file patterns */
+const TEST_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /_test\.[jt]sx?$/,
+  /_test\.go$/,
+  /test_.*\.py$/,
+  /.*_test\.py$/,
+  /\.test\.ts$/,
+];
+
+/**
+ * Recursively find test files under a directory.
+ * Skips node_modules, dist, .git, coverage, etc.
+ */
+function findTestFiles(dir, maxDepth = 5) {
+  const results = [];
+  const skipDirs = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.agileflow',
+    '.claude',
+    'vendor',
+  ]);
+
+  function walk(currentDir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          walk(path.join(currentDir, entry.name), depth + 1);
+        }
+      } else if (entry.isFile()) {
+        if (TEST_PATTERNS.some(pat => pat.test(entry.name))) {
+          results.push(path.join(currentDir, entry.name));
+        }
+      }
+    }
+  }
+
+  walk(dir, 0);
+  return results;
+}
+
+// ============================================================================
+// Test Content Scanning
+// ============================================================================
+
+/**
+ * Read a test file and extract its content for keyword matching.
+ * Returns lowercased content (describe/it blocks, comments, etc.)
+ */
+function readTestContent(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return content.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+// ============================================================================
+// AC-to-Test Matching
+// ============================================================================
+
+/**
+ * Calculate keyword overlap between AC keywords and test file content.
+ * Returns a confidence score.
+ */
+function calculateConfidence(acKeywords, testContent) {
+  if (acKeywords.length === 0) return 0;
+  let matchCount = 0;
+  for (const kw of acKeywords) {
+    if (testContent.includes(kw)) {
+      matchCount++;
+    }
+  }
+  const ratio = matchCount / acKeywords.length;
+  return ratio;
+}
+
+/**
+ * Determine confidence level from ratio.
+ */
+function confidenceLevel(ratio) {
+  if (ratio >= 0.6) return 'high';
+  if (ratio >= 0.3) return 'medium';
+  if (ratio > 0) return 'low';
+  return 'none';
+}
+
+/**
+ * Match acceptance criteria to test files.
+ *
+ * @param {string} storyId - Story ID (e.g., 'US-0042')
+ * @param {string} [rootDir] - Project root (auto-detected if omitted)
+ * @returns {{ storyId, total, matched, unmatched, coverage, error? }}
+ */
+function matchACToTests(storyId, rootDir) {
+  rootDir = rootDir || getProjectRoot();
+
+  if (!rootDir) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'Project root not found',
+    };
+  }
+
+  // Load story from status.json
+  const statusPath = getStatusPath(rootDir);
+  const result = safeReadJSON(statusPath, { defaultValue: { stories: {} } });
+  const status = result.ok ? result.data : null;
+  if (!status || !status.stories) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'status.json not found or invalid',
+    };
+  }
+
+  const story = status.stories[storyId];
+  if (!story) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: `Story ${storyId} not found`,
+    };
+  }
+
+  const acList = story.acceptance_criteria || story.ac || [];
+  if (!Array.isArray(acList) || acList.length === 0) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'No acceptance criteria defined',
+    };
+  }
+
+  // Find test files
+  const testFiles = findTestFiles(rootDir);
+  if (testFiles.length === 0) {
+    return {
+      storyId,
+      total: acList.length,
+      matched: [],
+      unmatched: acList.map((ac, i) => ({
+        index: i,
+        ac: typeof ac === 'string' ? ac : ac.text || String(ac),
+      })),
+      coverage: 0,
+      error: 'No test files found',
+    };
+  }
+
+  // Read all test content (cached in memory for this run)
+  const testContentMap = {};
+  for (const tf of testFiles) {
+    testContentMap[tf] = readTestContent(tf);
+  }
+
+  // Match each AC against test files
+  const matched = [];
+  const unmatched = [];
+
+  for (let i = 0; i < acList.length; i++) {
+    const acText = typeof acList[i] === 'string' ? acList[i] : acList[i].text || String(acList[i]);
+    const keywords = extractKeywords(acText);
+
+    if (keywords.length === 0) {
+      unmatched.push({ index: i, ac: acText });
+      continue;
+    }
+
+    // Find best matching test files
+    const fileMatches = [];
+    for (const [filePath, content] of Object.entries(testContentMap)) {
+      const ratio = calculateConfidence(keywords, content);
+      if (ratio > 0) {
+        fileMatches.push({
+          file: path.relative(rootDir, filePath),
+          ratio,
+          confidence: confidenceLevel(ratio),
+        });
+      }
+    }
+
+    // Sort by match ratio descending
+    fileMatches.sort((a, b) => b.ratio - a.ratio);
+
+    // Take top 3 matches
+    const topMatches = fileMatches.slice(0, 3);
+    const bestConfidence = topMatches.length > 0 ? topMatches[0].confidence : 'none';
+
+    if (bestConfidence === 'high' || bestConfidence === 'medium') {
+      matched.push({
+        index: i,
+        ac: acText,
+        confidence: bestConfidence,
+        keywords,
+        testFiles: topMatches.map(m => ({ file: m.file, confidence: m.confidence })),
+      });
+    } else {
+      unmatched.push({
+        index: i,
+        ac: acText,
+        keywords,
+        testFiles:
+          topMatches.length > 0
+            ? topMatches.map(m => ({ file: m.file, confidence: m.confidence }))
+            : undefined,
+      });
+    }
+  }
+
+  return {
+    storyId,
+    total: acList.length,
+    matched,
+    unmatched,
+    coverage: acList.length > 0 ? matched.length / acList.length : 0,
+  };
+}
+
+/**
+ * Write ac_status to status.json for a story based on match results.
+ *
+ * @param {string} storyId - Story ID
+ * @param {Object} matchResult - Result from matchACToTests
+ * @param {Object} [manualOverrides] - Manual AC verification { index: 'verified' }
+ * @param {string} [rootDir] - Project root
+ */
+function writeACStatus(storyId, matchResult, manualOverrides = {}, rootDir) {
+  rootDir = rootDir || getProjectRoot();
+  const statusPath = getStatusPath(rootDir);
+  const result = safeReadJSON(statusPath);
+  if (!result.ok || !result.data || !result.data.stories || !result.data.stories[storyId]) return;
+  const status = result.data;
+
+  const acStatus = {};
+
+  // Auto-verified from high-confidence matches
+  for (const m of matchResult.matched) {
+    if (m.confidence === 'high') {
+      acStatus[m.index] = 'auto-verified';
+    } else {
+      acStatus[m.index] = 'likely-covered';
+    }
+  }
+
+  // Unmatched remain unverified
+  for (const u of matchResult.unmatched) {
+    acStatus[u.index] = 'unverified';
+  }
+
+  // Apply manual overrides
+  for (const [idx, val] of Object.entries(manualOverrides)) {
+    acStatus[idx] = val;
+  }
+
+  status.stories[storyId].ac_status = acStatus;
+  status.stories[storyId].ac_coverage = matchResult.coverage;
+
+  const { safeWriteJSON: writeJSON } = require('../../lib/errors');
+  writeJSON(statusPath, status);
+}
+
+module.exports = {
+  matchACToTests,
+  writeACStatus,
+  // Exported for testing
+  extractKeywords,
+  findTestFiles,
+  calculateConfidence,
+  confidenceLevel,
+};