agileflow 3.1.0 → 3.2.1

package/scripts/lib/browser-qa-status.js

@@ -0,0 +1,192 @@
+/**
+ * browser-qa-status.js - Agentic test status integration for status.json
+ *
+ * Adds and manages `agentic_test_status` field on stories in status.json.
+ * This field is separate from `test_status` (which tracks deterministic Jest tests).
+ *
+ * Status values:
+ *   - "validated" : >=80% pass rate in agentic browser tests
+ *   - "warning"   : 70-79% pass rate (needs investigation)
+ *   - "failed"    : <70% pass rate (potential bug)
+ *   - "not_run"   : No agentic tests executed yet
+ *
+ * Usage:
+ *   const { updateAgenticTestStatus, getAgenticTestStatus } = require('./lib/browser-qa-status');
+ *
+ *   // Update a story's agentic test status
+ *   updateAgenticTestStatus(projectRoot, 'US-0050', {
+ *     status: 'validated',
+ *     pass_rate: 0.87,
+ *     scenarios_run: 3,
+ *     last_run: '2026-02-16T14:30:00Z',
+ *     evidence_path: '.agileflow/ui-review/runs/2026-02-16_14-30-00/'
+ *   });
+ *
+ *   // Read a story's agentic test status
+ *   const result = getAgenticTestStatus(projectRoot, 'US-0050');
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATUS_FILE = 'docs/09-agents/status.json';
+
+/**
+ * Read status.json safely
+ * @param {string} projectRoot - Project root directory
+ * @returns {object|null} Parsed status.json or null on error
+ */
+function readStatusJson(projectRoot) {
+  const statusPath = path.join(projectRoot, STATUS_FILE);
+  if (!fs.existsSync(statusPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(statusPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write status.json safely
+ * @param {string} projectRoot - Project root directory
+ * @param {object} data - Status data to write
+ * @returns {boolean} Success status
+ */
+function writeStatusJson(projectRoot, data) {
+  const statusPath = path.join(projectRoot, STATUS_FILE);
+  try {
+    data.updated = new Date().toISOString();
+    fs.writeFileSync(statusPath, JSON.stringify(data, null, 2) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Update a story's agentic test status
+ * @param {string} projectRoot - Project root directory
+ * @param {string} storyId - Story ID (e.g., 'US-0050')
+ * @param {object} result - Agentic test result
+ * @param {'validated'|'warning'|'failed'|'not_run'} result.status - Overall status
+ * @param {number} result.pass_rate - Pass rate (0-1)
+ * @param {number} result.scenarios_run - Number of scenarios executed
+ * @param {string} result.last_run - ISO timestamp of last run
+ * @param {string} result.evidence_path - Path to evidence directory
+ * @returns {boolean} Success status
+ */
+function updateAgenticTestStatus(projectRoot, storyId, result) {
+  const status = readStatusJson(projectRoot);
+  if (!status) return false;
+
+  if (!status.stories || !status.stories[storyId]) {
+    return false;
+  }
+
+  status.stories[storyId].agentic_test_status = result.status;
+  status.stories[storyId].agentic_test_details = {
+    pass_rate: result.pass_rate,
+    scenarios_run: result.scenarios_run,
+    last_run: result.last_run,
+    evidence_path: result.evidence_path,
+  };
+
+  return writeStatusJson(projectRoot, status);
+}
+
+/**
+ * Get a story's agentic test status
+ * @param {string} projectRoot - Project root directory
+ * @param {string} storyId - Story ID (e.g., 'US-0050')
+ * @returns {object|null} Agentic test status or null
+ */
+function getAgenticTestStatus(projectRoot, storyId) {
+  const status = readStatusJson(projectRoot);
+  if (!status || !status.stories || !status.stories[storyId]) return null;
+
+  const story = status.stories[storyId];
+  return {
+    status: story.agentic_test_status || 'not_run',
+    details: story.agentic_test_details || null,
+  };
+}
+
+/**
+ * Update multiple stories' agentic test statuses from a run summary
+ * @param {string} projectRoot - Project root directory
+ * @param {Array} scenarioResults - Array of scenario results
+ * @param {string} scenarioResults[].story_id - Story ID
+ * @param {'validated'|'warning'|'failed'} scenarioResults[].status - Status
+ * @param {number} scenarioResults[].pass_rate - Pass rate
+ * @param {string} evidencePath - Path to run evidence directory
+ * @returns {{ updated: number, skipped: number }}
+ */
+function updateBatchAgenticStatus(projectRoot, scenarioResults, evidencePath) {
+  const status = readStatusJson(projectRoot);
+  if (!status) return { updated: 0, skipped: 0 };
+
+  let updated = 0;
+  let skipped = 0;
+  const timestamp = new Date().toISOString();
+
+  for (const result of scenarioResults) {
+    if (!result.story_id) {
+      skipped++;
+      continue;
+    }
+
+    if (!status.stories || !status.stories[result.story_id]) {
+      skipped++;
+      continue;
+    }
+
+    status.stories[result.story_id].agentic_test_status = result.status;
+    status.stories[result.story_id].agentic_test_details = {
+      pass_rate: result.pass_rate,
+      scenarios_run: 1,
+      last_run: timestamp,
+      evidence_path: evidencePath,
+    };
+    updated++;
+  }
+
+  if (updated > 0) {
+    writeStatusJson(projectRoot, status);
+  }
+
+  return { updated, skipped };
+}
+
+/**
+ * Get summary of all agentic test statuses across stories
+ * @param {string} projectRoot - Project root directory
+ * @returns {{ validated: number, warning: number, failed: number, not_run: number, total: number }}
+ */
+function getAgenticTestSummary(projectRoot) {
+  const status = readStatusJson(projectRoot);
+  const summary = { validated: 0, warning: 0, failed: 0, not_run: 0, total: 0 };
+
+  if (!status || !status.stories) return summary;
+
+  for (const story of Object.values(status.stories)) {
+    summary.total++;
+    const agenticStatus = story.agentic_test_status || 'not_run';
+    if (summary[agenticStatus] !== undefined) {
+      summary[agenticStatus]++;
+    } else {
+      summary.not_run++;
+    }
+  }
+
+  return summary;
+}
+
+module.exports = {
+  updateAgenticTestStatus,
+  getAgenticTestStatus,
+  updateBatchAgenticStatus,
+  getAgenticTestSummary,
+  readStatusJson,
+  writeStatusJson,
+  STATUS_FILE,
+};

package/scripts/lib/command-prereqs.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * command-prereqs.js
+ *
+ * Declarative prerequisite checker for AgileFlow commands.
+ * Validates that environment signals are met before command execution
+ * and provides actionable warnings with fix instructions.
+ *
+ * Uses:
+ *   - resolveSignalPath() from feature-catalog.js for signal checking
+ *   - mtime-based caching pattern from damage-control-utils.js
+ *   - safeLoad() from yaml-utils.js for YAML parsing
+ *
+ * All functions fail-open: errors return empty/safe defaults.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Import resolveSignalPath from feature-catalog
+const { resolveSignalPath } = require('./feature-catalog');
+
+// Lazy-load yaml-utils (may not be available in all environments)
+let safeLoad;
+try {
+  safeLoad = require('../../lib/yaml-utils').safeLoad;
+} catch {
+  // Fallback: no YAML parsing available
+  safeLoad = null;
+}
+
+// Inline colors (standalone - no dependency on colors.js for hook compat)
+const c = {
+  coral: '\x1b[38;5;203m',
+  amber: '\x1b[38;5;215m',
+  mintGreen: '\x1b[38;5;158m',
+  skyBlue: '\x1b[38;5;117m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  reset: '\x1b[0m',
+};
+
+// Severity display config
+const SEVERITY = {
+  critical: { icon: '\u2718', color: c.coral, label: 'CRITICAL' },
+  high: { icon: '!', color: c.amber, label: 'HIGH' },
+  medium: { icon: '\u25CB', color: c.dim, label: 'MEDIUM' },
+};
+
+// =============================================================================
+// Config Cache (mtime-based invalidation, same pattern as damage-control-utils)
+// =============================================================================
+
+const _prereqCache = {
+  /** @type {string|null} */ filePath: null,
+  /** @type {number} */ mtime: 0,
+  /** @type {object|null} */ config: null,
+};
+
+/**
+ * Clear the prereq config cache (for testing or forced reload).
+ */
+function clearPrereqCache() {
+  _prereqCache.filePath = null;
+  _prereqCache.mtime = 0;
+  _prereqCache.config = null;
+}
+
+// Config search paths (installed location, then source template)
+const CONFIG_PATHS = [
+  '.agileflow/templates/command-prerequisites.yaml',
+  '.agileflow/templates/command-prerequisites.yml',
+  '.agileflow/config/command-prerequisites.yaml',
+];
+
+/**
+ * Load prerequisite configuration from YAML with mtime-based caching.
+ * Returns safe defaults on any error (fail-open).
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {{ commands: Object, settings: Object }} Parsed config
+ */
+function loadPrereqConfig(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const defaultConfig = { commands: {}, settings: { fail_open: true, max_warnings: 5 } };
+
+  if (!safeLoad) {
+    return defaultConfig;
+  }
+
+  for (const configPath of CONFIG_PATHS) {
+    const fullPath = path.join(root, configPath);
+    if (!fs.existsSync(fullPath)) continue;
+
+    try {
+      const stat = fs.statSync(fullPath);
+      const mtime = stat.mtimeMs;
+
+      // Return cached if file hasn't changed
+      if (
+        _prereqCache.filePath === fullPath &&
+        _prereqCache.mtime === mtime &&
+        _prereqCache.config
+      ) {
+        return _prereqCache.config;
+      }
+
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const parsed = safeLoad(content);
+
+      if (!parsed || typeof parsed !== 'object') {
+        continue;
+      }
+
+      const config = {
+        commands: parsed.commands || {},
+        settings: { ...defaultConfig.settings, ...(parsed.settings || {}) },
+      };
+
+      // Store in cache
+      _prereqCache.filePath = fullPath;
+      _prereqCache.mtime = mtime;
+      _prereqCache.config = config;
+
+      return config;
+    } catch {
+      // Continue to next path
+    }
+  }
+
+  return defaultConfig;
+}
+
+// =============================================================================
+// Prerequisite Checking (pure function)
+// =============================================================================
+
+/**
+ * Check prerequisites for a specific command against current signals.
+ * Pure function - no I/O, no side effects.
+ *
+ * @param {string} commandName - Command to check (e.g. 'deploy', 'babysit')
+ * @param {Object} signals - Extracted signals from smart-detect
+ * @param {{ commands: Object, settings: Object }} config - Loaded prereq config
+ * @returns {{
+ *   command: string,
+ *   hasPrereqs: boolean,
+ *   allMet: boolean,
+ *   results: Array<{ signal: string, description: string, fix: string, severity: string, met: boolean }>,
+ *   unmet: Array<{ signal: string, description: string, fix: string, severity: string }>,
+ *   criticalUnmet: number,
+ *   highUnmet: number
+ * }}
+ */
+function checkCommandPrereqs(commandName, signals, config) {
+  const result = {
+    command: commandName,
+    hasPrereqs: false,
+    allMet: true,
+    results: [],
+    unmet: [],
+    criticalUnmet: 0,
+    highUnmet: 0,
+  };
+
+  if (!commandName || !config || !config.commands) {
+    return result;
+  }
+
+  const commandConfig = config.commands[commandName];
+  if (!commandConfig || !Array.isArray(commandConfig.prerequisites)) {
+    return result;
+  }
+
+  result.hasPrereqs = true;
+  const prereqs = commandConfig.prerequisites;
+
+  for (const prereq of prereqs) {
+    if (!prereq.signal) continue;
+
+    const value = resolveSignalPath(signals || {}, prereq.signal);
+    // Evaluate signal: empty arrays and empty strings are "unmet"
+    // (e.g. git.filesChanged=[] means no changes, which is unmet)
+    const met = Array.isArray(value) ? value.length > 0 : !!value;
+
+    const entry = {
+      signal: prereq.signal,
+      description: prereq.description || prereq.signal,
+      fix: prereq.fix || '',
+      severity: prereq.severity || 'medium',
+      met,
+    };
+
+    result.results.push(entry);
+
+    if (!met) {
+      result.allMet = false;
+      result.unmet.push(entry);
+
+      if (entry.severity === 'critical') {
+        result.criticalUnmet++;
+      } else if (entry.severity === 'high') {
+        result.highUnmet++;
+      }
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Warning Formatting
+// =============================================================================
+
+/**
+ * Format unmet prerequisite warnings with ANSI colors.
+ * Returns empty string if all prerequisites are met.
+ *
+ * @param {{ allMet: boolean, command: string, unmet: Array, criticalUnmet: number }} checkResult
+ * @param {{ max_warnings?: number }} [settings] - Display settings
+ * @returns {string} Formatted warning string (with trailing newline) or empty string
+ */
+function formatPrereqWarnings(checkResult, settings) {
+  if (!checkResult || checkResult.allMet || checkResult.unmet.length === 0) {
+    return '';
+  }
+
+  const maxWarnings = (settings && settings.max_warnings) || 5;
+  const { command, unmet, criticalUnmet } = checkResult;
+
+  const lines = [];
+  const headerColor = criticalUnmet > 0 ? c.coral : c.amber;
+  const headerIcon = criticalUnmet > 0 ? '\u26A0\uFE0F' : '\u2139\uFE0F';
+
+  lines.push('');
+  lines.push(
+    `${headerColor}${c.bold}\u2501\u2501\u2501 ${headerIcon} Command Prerequisites: /${command} \u2501\u2501\u2501${c.reset}`
+  );
+
+  if (criticalUnmet > 0) {
+    lines.push(
+      `${c.coral}${criticalUnmet} critical prerequisite(s) not met - command may fail${c.reset}`
+    );
+  } else {
+    lines.push(
+      `${c.amber}${unmet.length} prerequisite(s) not met - results may be suboptimal${c.reset}`
+    );
+  }
+
+  lines.push('');
+
+  const displayed = unmet.slice(0, maxWarnings);
+  for (const prereq of displayed) {
+    const sev = SEVERITY[prereq.severity] || SEVERITY.medium;
+    lines.push(`  ${sev.color}${sev.icon} [${sev.label}]${c.reset} ${prereq.description}`);
+    if (prereq.fix) {
+      lines.push(`    ${c.dim}\u2192 Fix: ${prereq.fix}${c.reset}`);
+    }
+  }
+
+  if (unmet.length > maxWarnings) {
+    lines.push(`  ${c.dim}... and ${unmet.length - maxWarnings} more${c.reset}`);
+  }
+
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  loadPrereqConfig,
+  checkCommandPrereqs,
+  formatPrereqWarnings,
+  clearPrereqCache,
+  // Exported for testing
+  CONFIG_PATHS,
+  SEVERITY,
+};

package/scripts/lib/configure-detect.js

@@ -83,6 +83,13 @@ function detectConfig(version) {
         level: null,
         patternCount: 0,
       },
+      noaiattribution: {
+        enabled: false,
+        valid: true,
+        issues: [],
+        version: null,
+        outdated: false,
+      },
       askuserquestion: {
         enabled: false,
         valid: true,
@@ -98,6 +105,22 @@ function detectConfig(version) {
         version: null,
         outdated: false,
       },
+      browserqa: {
+        enabled: false,
+        valid: true,
+        issues: [],
+        version: null,
+        outdated: false,
+        playwright_detected: false,
+      },
+      contextverbosity: {
+        enabled: false,
+        valid: true,
+        issues: [],
+        version: null,
+        outdated: false,
+        mode: 'full',
+      },
     },
     metadata: { exists: false, version: null },
     currentVersion: version,
@@ -225,7 +248,7 @@ function detectStopHooks(hook, status) {
 }
 
 /**
- * Detect PreToolUse hooks (damage control)
+ * Detect PreToolUse hooks (damage control, no AI attribution)
  */
 function detectPreToolUseHooks(hooks, status) {
   if (!Array.isArray(hooks) || hooks.length === 0) return;
@@ -248,6 +271,17 @@ function detectPreToolUseHooks(hooks, status) {
       status.features.damagecontrol.issues.push(`Only ${hookCount}/3 hooks configured`);
     }
   }
+
+  // Detect no AI attribution hook
+  const hasNoAiHook = hooks.some(
+    h =>
+      h.matcher === 'Bash' &&
+      Array.isArray(h.hooks) &&
+      h.hooks.some(hk => hk.command?.includes('strip-ai-attribution'))
+  );
+  if (hasNoAiHook) {
+    status.features.noaiattribution.enabled = true;
+  }
 }
 
 /**
@@ -303,9 +337,31 @@ function detectMetadata(status, version) {
     status.features.tmuxautospawn.enabled = true; // Default enabled
   }
 
+  // No AI attribution metadata
+  if (meta.features?.noaiattribution?.enabled) {
+    status.features.noaiattribution.enabled = true;
+  }
+
+  // Browser QA metadata
+  if (meta.features?.browserqa?.enabled) {
+    status.features.browserqa.enabled = true;
+    status.features.browserqa.playwright_detected =
+      meta.features.browserqa.playwright_detected || false;
+  }
+
+  // Context verbosity metadata
+  if (meta.features?.contextVerbosity?.enabled) {
+    status.features.contextverbosity.enabled = true;
+    status.features.contextverbosity.mode = meta.features.contextVerbosity.mode || 'full';
+  }
+
   // Read feature versions and check if outdated (content-based)
   if (meta.features) {
-    const featureKeyMap = { askUserQuestion: 'askuserquestion', tmuxAutoSpawn: 'tmuxautospawn' };
+    const featureKeyMap = {
+      askUserQuestion: 'askuserquestion',
+      tmuxAutoSpawn: 'tmuxautospawn',
+      contextVerbosity: 'contextverbosity',
+    };
     const packageScriptDir = findPackageScriptDir();
 
     Object.entries(meta.features).forEach(([feature, data]) => {
@@ -434,6 +490,14 @@ function printStatus(status) {
     log(`   Damage Control: disabled`, c.dim);
   }
 
+  // No AI Attribution
+  const naa = status.features.noaiattribution;
+  if (naa.enabled) {
+    log(`   No AI Attribution: enabled`, c.green);
+  } else {
+    log(`   No AI Attribution: disabled`, c.dim);
+  }
+
   // AskUserQuestion
   const auq = status.features.askuserquestion;
   if (auq.enabled) {
@@ -452,6 +516,32 @@ function printStatus(status) {
     log(`   Tmux Auto-Spawn: disabled`, c.dim);
   }
 
+  // Browser QA
+  const bqa = status.features.browserqa;
+  if (bqa) {
+    if (bqa.enabled) {
+      let bqaText = 'enabled';
+      if (bqa.playwright_detected) bqaText += ' (Playwright detected)';
+      else bqaText += ' (Playwright not found)';
+      log(
+        `  ${bqa.playwright_detected ? '' : ''} Browser QA: ${bqaText}`,
+        bqa.playwright_detected ? c.green : c.yellow
+      );
+    } else {
+      log(`   Browser QA: disabled`, c.dim);
+    }
+  }
+
+  // Context Verbosity
+  const cv = status.features.contextverbosity;
+  if (cv) {
+    if (cv.enabled) {
+      log(`   Context Verbosity: ${cv.mode}`, c.green);
+    } else {
+      log(`   Context Verbosity: full (default)`, c.dim);
+    }
+  }
+
   // Metadata version
   if (status.metadata.exists) {
     log(`\nMetadata: v${status.metadata.version}`, c.dim);