agileflow 2.91.0 → 2.92.0

package/scripts/validators/security-validator.js

@@ -22,7 +22,7 @@ const fs = require('fs');
 const path = require('path');
 
 let input = '';
-process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
   try {
     const context = JSON.parse(input);
@@ -60,7 +60,21 @@ process.stdin.on('end', () => {
 });
 
 function isBinaryFile(filePath) {
-  const binaryExtensions = ['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.eot', '.pdf', '.zip', '.tar', '.gz'];
+  const binaryExtensions = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.eot',
+    '.pdf',
+    '.zip',
+    '.tar',
+    '.gz',
+  ];
   const ext = path.extname(filePath).toLowerCase();
   return binaryExtensions.includes(ext);
 }
@@ -93,7 +107,6 @@ function validateSecurity(filePath) {
 
     // Check for insecure randomness
     issues.push(...checkInsecureRandom(content));
-
   } catch (e) {
     issues.push(`Read error: ${e.message}`);
   }
@@ -114,15 +127,33 @@ function checkSecrets(content, fileName) {
     { pattern: /['"]sk-[a-zA-Z0-9]{20,}['"]/, message: 'Possible OpenAI API key detected' },
     { pattern: /['"]AIza[a-zA-Z0-9_-]{35}['"]/, message: 'Possible Google API key detected' },
     { pattern: /['"]AKIA[A-Z0-9]{16}['"]/, message: 'Possible AWS access key detected' },
-    { pattern: /['"]ghp_[a-zA-Z0-9]{36}['"]/, message: 'Possible GitHub personal access token detected' },
+    {
+      pattern: /['"]ghp_[a-zA-Z0-9]{36}['"]/,
+      message: 'Possible GitHub personal access token detected',
+    },
     { pattern: /['"]npm_[a-zA-Z0-9]{36}['"]/, message: 'Possible npm token detected' },
 
     // Generic patterns
-    { pattern: /password\s*[:=]\s*['"][^'"${\s]{8,}['"](?!\s*;?\s*\/\/\s*example)/i, message: 'Possible hardcoded password detected' },
-    { pattern: /api[_-]?key\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/i, message: 'Possible hardcoded API key detected' },
-    { pattern: /secret\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/i, message: 'Possible hardcoded secret detected' },
-    { pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/, message: 'Private key detected in source code' },
-    { pattern: /-----BEGIN\s+CERTIFICATE-----/, message: 'Certificate detected in source code (verify this is intentional)' },
+    {
+      pattern: /password\s*[:=]\s*['"][^'"${\s]{8,}['"](?!\s*;?\s*\/\/\s*example)/i,
+      message: 'Possible hardcoded password detected',
+    },
+    {
+      pattern: /api[_-]?key\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/i,
+      message: 'Possible hardcoded API key detected',
+    },
+    {
+      pattern: /secret\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/i,
+      message: 'Possible hardcoded secret detected',
+    },
+    {
+      pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/,
+      message: 'Private key detected in source code',
+    },
+    {
+      pattern: /-----BEGIN\s+CERTIFICATE-----/,
+      message: 'Certificate detected in source code (verify this is intentional)',
+    },
   ];
 
   for (const { pattern, message } of secretPatterns) {
@@ -144,11 +175,27 @@ function checkSqlInjection(content, ext) {
 
   // Check for string concatenation in SQL
   const sqlInjectionPatterns = [
-    { pattern: /['"`]\s*SELECT\s+.*\+\s*\w+/i, message: 'Possible SQL injection: string concatenation in SELECT query' },
-    { pattern: /['"`]\s*INSERT\s+.*\+\s*\w+/i, message: 'Possible SQL injection: string concatenation in INSERT query' },
-    { pattern: /['"`]\s*UPDATE\s+.*\+\s*\w+/i, message: 'Possible SQL injection: string concatenation in UPDATE query' },
-    { pattern: /['"`]\s*DELETE\s+.*\+\s*\w+/i, message: 'Possible SQL injection: string concatenation in DELETE query' },
-    { pattern: /\$\{[^}]+\}.*WHERE/i, message: 'Possible SQL injection: template literal in WHERE clause - use parameterized queries' },
+    {
+      pattern: /['"`]\s*SELECT\s+.*\+\s*\w+/i,
+      message: 'Possible SQL injection: string concatenation in SELECT query',
+    },
+    {
+      pattern: /['"`]\s*INSERT\s+.*\+\s*\w+/i,
+      message: 'Possible SQL injection: string concatenation in INSERT query',
+    },
+    {
+      pattern: /['"`]\s*UPDATE\s+.*\+\s*\w+/i,
+      message: 'Possible SQL injection: string concatenation in UPDATE query',
+    },
+    {
+      pattern: /['"`]\s*DELETE\s+.*\+\s*\w+/i,
+      message: 'Possible SQL injection: string concatenation in DELETE query',
+    },
+    {
+      pattern: /\$\{[^}]+\}.*WHERE/i,
+      message:
+        'Possible SQL injection: template literal in WHERE clause - use parameterized queries',
+    },
   ];
 
   for (const { pattern, message } of sqlInjectionPatterns) {
@@ -169,11 +216,23 @@ function checkXss(content, ext) {
   }
 
   const xssPatterns = [
-    { pattern: /innerHTML\s*=\s*[^'"`]/, message: 'Direct innerHTML assignment detected - sanitize content or use textContent' },
-    { pattern: /dangerouslySetInnerHTML/, message: 'dangerouslySetInnerHTML used - ensure content is sanitized' },
-    { pattern: /document\.write\s*\(/, message: 'document.write() is dangerous - use DOM manipulation instead' },
+    {
+      pattern: /innerHTML\s*=\s*[^'"`]/,
+      message: 'Direct innerHTML assignment detected - sanitize content or use textContent',
+    },
+    {
+      pattern: /dangerouslySetInnerHTML/,
+      message: 'dangerouslySetInnerHTML used - ensure content is sanitized',
+    },
+    {
+      pattern: /document\.write\s*\(/,
+      message: 'document.write() is dangerous - use DOM manipulation instead',
+    },
     { pattern: /v-html\s*=/, message: 'v-html directive detected - ensure content is sanitized' },
-    { pattern: /\{@html\s+/, message: 'Svelte @html directive detected - ensure content is sanitized' },
+    {
+      pattern: /\{@html\s+/,
+      message: 'Svelte @html directive detected - ensure content is sanitized',
+    },
   ];
 
   for (const { pattern, message } of xssPatterns) {
@@ -196,14 +255,32 @@ function checkCommandInjection(content, ext) {
 
   const cmdInjectionPatterns = [
     // JavaScript/Node
-    { pattern: /exec\s*\(\s*[`'"]\s*\$\{/, message: 'Possible command injection: template literal in exec()' },
-    { pattern: /exec\s*\(\s*\w+\s*\+/, message: 'Possible command injection: string concatenation in exec()' },
-    { pattern: /execSync\s*\(\s*[`'"]\s*\$\{/, message: 'Possible command injection: template literal in execSync()' },
-    { pattern: /spawn\s*\(\s*[`'"]\s*\$\{/, message: 'Possible command injection: template literal in spawn()' },
+    {
+      pattern: /exec\s*\(\s*[`'"]\s*\$\{/,
+      message: 'Possible command injection: template literal in exec()',
+    },
+    {
+      pattern: /exec\s*\(\s*\w+\s*\+/,
+      message: 'Possible command injection: string concatenation in exec()',
+    },
+    {
+      pattern: /execSync\s*\(\s*[`'"]\s*\$\{/,
+      message: 'Possible command injection: template literal in execSync()',
+    },
+    {
+      pattern: /spawn\s*\(\s*[`'"]\s*\$\{/,
+      message: 'Possible command injection: template literal in spawn()',
+    },
 
     // Python
-    { pattern: /os\.system\s*\(\s*f['"]/, message: 'Possible command injection: f-string in os.system()' },
-    { pattern: /subprocess\.(call|run|Popen)\s*\(\s*f['"]/, message: 'Possible command injection: f-string in subprocess - use list args instead' },
+    {
+      pattern: /os\.system\s*\(\s*f['"]/,
+      message: 'Possible command injection: f-string in os.system()',
+    },
+    {
+      pattern: /subprocess\.(call|run|Popen)\s*\(\s*f['"]/,
+      message: 'Possible command injection: f-string in subprocess - use list args instead',
+    },
   ];
 
   for (const { pattern, message } of cmdInjectionPatterns) {
@@ -224,9 +301,18 @@ function checkPathTraversal(content, ext) {
   }
 
   const pathTraversalPatterns = [
-    { pattern: /path\.join\s*\([^)]*req\.(params|query|body)/, message: 'Possible path traversal: user input in path.join()' },
-    { pattern: /readFile(Sync)?\s*\([^)]*req\.(params|query|body)/, message: 'Possible path traversal: user input in file read' },
-    { pattern: /open\s*\(\s*f['"].*\{.*\}/, message: 'Possible path traversal: user input in file open (Python)' },
+    {
+      pattern: /path\.join\s*\([^)]*req\.(params|query|body)/,
+      message: 'Possible path traversal: user input in path.join()',
+    },
+    {
+      pattern: /readFile(Sync)?\s*\([^)]*req\.(params|query|body)/,
+      message: 'Possible path traversal: user input in file read',
+    },
+    {
+      pattern: /open\s*\(\s*f['"].*\{.*\}/,
+      message: 'Possible path traversal: user input in file open (Python)',
+    },
   ];
 
   for (const { pattern, message } of pathTraversalPatterns) {
@@ -242,10 +328,22 @@ function checkInsecureCrypto(content) {
   const issues = [];
 
   const insecureCryptoPatterns = [
-    { pattern: /createHash\s*\(\s*['"]md5['"]\s*\)/, message: 'MD5 is insecure for cryptographic use - use SHA-256 or better' },
-    { pattern: /createHash\s*\(\s*['"]sha1['"]\s*\)/, message: 'SHA-1 is deprecated - use SHA-256 or better' },
-    { pattern: /hashlib\.md5\s*\(/, message: 'MD5 is insecure for cryptographic use - use SHA-256 or better' },
-    { pattern: /DES|3DES|RC4/, message: 'Insecure encryption algorithm detected - use AES-256-GCM' },
+    {
+      pattern: /createHash\s*\(\s*['"]md5['"]\s*\)/,
+      message: 'MD5 is insecure for cryptographic use - use SHA-256 or better',
+    },
+    {
+      pattern: /createHash\s*\(\s*['"]sha1['"]\s*\)/,
+      message: 'SHA-1 is deprecated - use SHA-256 or better',
+    },
+    {
+      pattern: /hashlib\.md5\s*\(/,
+      message: 'MD5 is insecure for cryptographic use - use SHA-256 or better',
+    },
+    {
+      pattern: /DES|3DES|RC4/,
+      message: 'Insecure encryption algorithm detected - use AES-256-GCM',
+    },
     { pattern: /ECB/, message: 'ECB mode is insecure - use GCM or CBC with proper IV' },
   ];
 
@@ -262,8 +360,14 @@ function checkInsecureRandom(content) {
   const issues = [];
 
   const insecureRandomPatterns = [
-    { pattern: /Math\.random\s*\(\s*\).*(?:token|key|secret|password|auth|session)/i, message: 'Math.random() used for security-sensitive value - use crypto.randomBytes()' },
-    { pattern: /random\.random\s*\(\s*\).*(?:token|key|secret|password|auth|session)/i, message: 'random.random() is not cryptographically secure - use secrets module' },
+    {
+      pattern: /Math\.random\s*\(\s*\).*(?:token|key|secret|password|auth|session)/i,
+      message: 'Math.random() used for security-sensitive value - use crypto.randomBytes()',
+    },
+    {
+      pattern: /random\.random\s*\(\s*\).*(?:token|key|secret|password|auth|session)/i,
+      message: 'random.random() is not cryptographically secure - use secrets module',
+    },
   ];
 
   for (const { pattern, message } of insecureRandomPatterns) {

package/scripts/validators/story-format-validator.js

@@ -22,8 +22,11 @@
 const fs = require('fs');
 const path = require('path');
 
+// Import status constants from single source of truth
+const { VALID_STATUSES } = require('../lib/story-state-machine');
+
 let input = '';
-process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
   try {
     const context = JSON.parse(input);
@@ -110,7 +113,6 @@ function validateStoryFormat(filePath) {
         }
       }
     }
-
   } catch (e) {
     if (e instanceof SyntaxError) {
       issues.push(`Invalid JSON: ${e.message}`);
@@ -132,7 +134,9 @@ function validateSingleStory(story, index) {
   } else {
     // ID format validation (US-XXXX or EP-XXXX)
     if (!/^(US|EP|TECH|BUG)-\d{4}$/.test(story.id)) {
-      issues.push(`Story ${storyRef}: ID should match pattern US-XXXX, EP-XXXX, TECH-XXXX, or BUG-XXXX`);
+      issues.push(
+        `Story ${storyRef}: ID should match pattern US-XXXX, EP-XXXX, TECH-XXXX, or BUG-XXXX`
+      );
     }
   }
 
@@ -140,23 +144,40 @@ function validateSingleStory(story, index) {
     issues.push(`Story ${storyRef}: missing 'title' or 'name' field`);
   }
 
-  // Status validation
-  const validStatuses = ['pending', 'ready', 'in_progress', 'in-progress', 'in_review', 'in-review', 'completed', 'blocked', 'archived'];
-  if (story.status && !validStatuses.includes(story.status)) {
-    issues.push(`Story ${storyRef}: invalid status "${story.status}". Valid: ${validStatuses.join(', ')}`);
+  // Status validation (using canonical values from story-state-machine.js)
+  // Also accept legacy formats for backward compatibility
+  const legacyStatuses = ['pending', 'in-progress', 'in-review'];
+  const allAcceptedStatuses = [...VALID_STATUSES, ...legacyStatuses];
+  if (story.status && !allAcceptedStatuses.includes(story.status)) {
+    issues.push(
+      `Story ${storyRef}: invalid status "${story.status}". Valid: ${VALID_STATUSES.join(', ')}`
+    );
   }
 
   // Priority validation
   const validPriorities = ['critical', 'high', 'medium', 'low'];
   if (story.priority && !validPriorities.includes(story.priority)) {
-    issues.push(`Story ${storyRef}: invalid priority "${story.priority}". Valid: ${validPriorities.join(', ')}`);
+    issues.push(
+      `Story ${storyRef}: invalid priority "${story.priority}". Valid: ${validPriorities.join(', ')}`
+    );
   }
 
   // Owner validation (if present)
   if (story.owner) {
-    const validOwners = ['AG-UI', 'AG-API', 'AG-CI', 'AG-DB', 'AG-TEST', 'AG-DOC', 'AG-SEC', 'human'];
+    const validOwners = [
+      'AG-UI',
+      'AG-API',
+      'AG-CI',
+      'AG-DB',
+      'AG-TEST',
+      'AG-DOC',
+      'AG-SEC',
+      'human',
+    ];
     if (!validOwners.includes(story.owner)) {
-      issues.push(`Story ${storyRef}: unknown owner "${story.owner}". Valid: ${validOwners.join(', ')}`);
+      issues.push(
+        `Story ${storyRef}: unknown owner "${story.owner}". Valid: ${validOwners.join(', ')}`
+      );
     }
   }
 

package/scripts/validators/test-result-validator.js

@@ -20,7 +20,7 @@
  */
 
 let input = '';
-process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
   try {
     const context = JSON.parse(input);
@@ -28,7 +28,16 @@ process.stdin.on('end', () => {
     const result = context.result || '';
 
     // Only validate test-related commands
-    const testCommands = ['npm test', 'npm run test', 'jest', 'pytest', 'cargo test', 'go test', 'vitest', 'mocha'];
+    const testCommands = [
+      'npm test',
+      'npm run test',
+      'jest',
+      'pytest',
+      'cargo test',
+      'go test',
+      'vitest',
+      'mocha',
+    ];
     const isTestCommand = testCommands.some(tc => command.includes(tc));
 
     if (!isTestCommand) {
@@ -76,7 +85,9 @@ function validateTestResult(command, result) {
   // Check for coverage warnings (if coverage was run)
   if (resultLower.includes('coverage')) {
     // Look for coverage percentage
-    const coverageMatch = result.match(/(\d+(?:\.\d+)?)\s*%\s*(?:coverage|statements|branches|functions|lines)/i);
+    const coverageMatch = result.match(
+      /(\d+(?:\.\d+)?)\s*%\s*(?:coverage|statements|branches|functions|lines)/i
+    );
     if (coverageMatch) {
       const coverage = parseFloat(coverageMatch[1]);
       if (coverage < 70) {
@@ -86,7 +97,11 @@ function validateTestResult(command, result) {
   }
 
   // Check for "no tests" scenarios
-  if (resultLower.includes('no tests') || resultLower.includes('no test') || resultLower.includes('0 tests')) {
+  if (
+    resultLower.includes('no tests') ||
+    resultLower.includes('no test') ||
+    resultLower.includes('0 tests')
+  ) {
     issues.push('No tests were run - ensure test files exist and are properly configured');
   }
 

package/scripts/validators/workflow-validator.js

@@ -22,7 +22,7 @@ const fs = require('fs');
 const path = require('path');
 
 let input = '';
-process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
   try {
     const context = JSON.parse(input);
@@ -77,7 +77,10 @@ function isWorkflowFile(filePath) {
   }
 
   // Azure Pipelines
-  if (normalizedPath.endsWith('azure-pipelines.yml') || normalizedPath.endsWith('azure-pipelines.yaml')) {
+  if (
+    normalizedPath.endsWith('azure-pipelines.yml') ||
+    normalizedPath.endsWith('azure-pipelines.yaml')
+  ) {
     return true;
   }
 
@@ -115,7 +118,6 @@ function validateWorkflow(filePath) {
 
     // General CI/CD security checks
     issues.push(...validateCISecurity(content));
-
   } catch (e) {
     issues.push(`Read error: ${e.message}`);
   }
@@ -181,7 +183,10 @@ function validateGitHubActions(content) {
   }
 
   // Check for potentially dangerous permissions
-  if (content.includes('permissions: write-all') || content.includes('permissions:\n  contents: write')) {
+  if (
+    content.includes('permissions: write-all') ||
+    content.includes('permissions:\n  contents: write')
+  ) {
     console.log('Note: Broad write permissions detected - ensure this is necessary');
   }
 
@@ -228,7 +233,9 @@ function validateCISecurity(content) {
 
   // Check for curl | bash pattern (security risk)
   if (content.includes('curl') && content.includes('| bash')) {
-    issues.push('curl | bash pattern detected - this is a security risk, use verified installation methods');
+    issues.push(
+      'curl | bash pattern detected - this is a security risk, use verified installation methods'
+    );
   }
 
   // Check for npm install without lockfile

package/src/core/agents/codebase-query.md

@@ -108,7 +108,31 @@ node packages/cli/scripts/query-codebase.js --export="login"
 
 # Show dependencies
 node packages/cli/scripts/query-codebase.js --deps="src/auth.js"
+
+# Show equivalent bash workflow (educational)
+node packages/cli/scripts/query-codebase.js --query="auth" --explain
+
+# Verbose mode shows step-by-step exploration
+node packages/cli/scripts/query-codebase.js --query="auth" --verbose
+```
+
+### Understanding the Approach (--explain)
+Use `--explain` to see the equivalent bash commands:
+```
+📖 Equivalent Bash Workflow:
+
+# Step 1: List available directories (ls)
+ls -la /project/src/
+
+# Step 2: Find files matching pattern (find)
+find /project -name "*auth*" -type f
+
+# Step 3: Search content within files (grep)
+grep -rl "auth" /project/src/
+
+# This tool combines all three with indexing for speed.
 ```
+This follows the Unix "everything is a file" philosophy - using file system navigation instead of vector databases (RAG).
 
 ### Result Format
 ```

package/src/core/commands/adr.md

@@ -269,6 +269,120 @@ After successfully creating the ADR, offer next steps:
 
 ---
 
+## Expected Output
+
+### Successful ADR Creation
+
+```
+📋 Creating ADR: ADR-0042
+
+Checking existing ADRs...
+✅ Next sequential number: 0042
+
+Title: Use PostgreSQL for persistence
+Status: accepted
+
+Files to create:
+───────────────────────────────────
+1. docs/03-decisions/adr-0042-postgresql.md
+
+Preview:
+─────────────────────────────────────────────
+---
+number: 0042
+title: Use PostgreSQL for persistence
+date: 2026-01-21
+status: accepted
+tags: [database, architecture]
+---
+
+# ADR-0042: Use PostgreSQL for persistence
+
+## Context
+Need reliable ACID-compliant database for financial transactions.
+Evaluated MongoDB (eventual consistency), Redis (memory limits),
+and PostgreSQL (full ACID with JSON support).
+
+## Decision
+Use PostgreSQL 16 with native JSON support for document storage
+while maintaining ACID guarantees.
+
+## Consequences
+### Positive
+- Full ACID compliance for financial data
+- Native JSON/JSONB for flexible schemas
+- Mature ecosystem and tooling
+
+### Negative
+- Team needs PostgreSQL training
+- Slightly more complex operational setup
+- Vertical scaling limitations
+
+## Related
+- [ADR-0041](adr-0041-db-evaluation.md)
+- [US-0055](../06-stories/US-0055.md)
+─────────────────────────────────────────────
+
+[AskUserQuestion: "Create this ADR? (YES/NO)"]
+
+✅ ADR-0042 created successfully!
+   docs/03-decisions/adr-0042-postgresql.md
+
+[AskUserQuestion: "What would you like to do next?"]
+```
+
+### Missing Required Inputs
+
+```
+❌ Missing required inputs
+
+The following inputs are required:
+  • NUMBER - 4-digit sequential ID (e.g., 0042)
+  • TITLE - Decision title
+  • CONTEXT - Why this decision is needed
+  • DECISION - What was chosen
+  • CONSEQUENCES - Trade-offs (positive and negative)
+
+Usage:
+/agileflow:adr NUMBER=0042 TITLE="Use PostgreSQL" CONTEXT="Need ACID..." DECISION="PostgreSQL chosen" CONSEQUENCES="Better integrity, learning curve"
+```
+
+### Non-Sequential Number Warning
+
+```
+⚠️ Non-sequential ADR number
+
+Requested: ADR-0100
+Last ADR: ADR-0042
+Next expected: ADR-0043
+
+Do you want to:
+  1. Use sequential number (0043) - Recommended
+  2. Keep requested number (0100)
+  3. Cancel
+
+[AskUserQuestion: Select option]
+```
+
+### ADR Already Exists
+
+```
+❌ ADR-0042 already exists
+
+Existing ADR:
+  Title: Use PostgreSQL for persistence
+  Date: 2026-01-15
+  Status: accepted
+
+To update this ADR:
+  /agileflow:adr:update NUMBER=0042 STATUS=superseded
+
+To create a new ADR:
+  /agileflow:adr NUMBER=0043 TITLE="..."
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:adr:list` - View all ADRs with status