agentic-qe 3.9.8 → 3.9.10

package/assets/agents/v3/helpers/advisor-call.cjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * advisor-call.cjs — Helper script for agent advisor protocol (ADR-092)
+ *
+ * Agents call this instead of invoking `aqe llm advise` directly.
+ * This script:
+ *   1. Reads .agentic-qe/config.yaml for advisor settings
+ *   2. Detects available API keys in environment
+ *   3. Applies security-agent provider restrictions automatically
+ *   4. Picks the best available provider/model
+ *   5. Calls `aqe llm advise` with the resolved settings
+ *
+ * Usage from agent definitions:
+ *   node "$(dirname "$(which aqe)")/../lib/helpers/advisor-call.cjs" \
+ *     --agent <agent-name> \
+ *     --task "<task description>" \
+ *     --context "<what the executor has found so far>"
+ *
+ * Or simpler (when aqe is installed):
+ *   aqe advisor call --agent <name> --task "<desc>" --context "<ctx>"
+ *
+ * Exits 0 with JSON on success, 1-6 with error JSON on failure.
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const { readFileSync, writeFileSync, mkdirSync, existsSync } = require('fs');
+const { join, dirname } = require('path');
+const { tmpdir } = require('os');
+
+// ============================================================================
+// Parse arguments
+// ============================================================================
+
+const args = process.argv.slice(2);
+function getArg(name) {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+const agentName = getArg('agent') || 'unknown';
+const taskDescription = getArg('task') || '';
+const context = getArg('context') || '';
+const userMessage = getArg('message') || taskDescription;
+
+if (!taskDescription && !userMessage) {
+  console.error(JSON.stringify({
+    error: 'Usage: advisor-call.cjs --agent <name> --task "<description>" [--context "<findings>"] [--message "<user request>"]',
+    exit_code: 1,
+  }));
+  process.exit(1);
+}
+
+// ============================================================================
+// Detect available providers from environment
+// ============================================================================
+
+const availableProviders = [];
+
+if (process.env.OPENROUTER_API_KEY) {
+  availableProviders.push({
+    name: 'openrouter',
+    model: 'anthropic/claude-opus-4',
+    securityAllowed: false, // third-party proxy
+  });
+}
+
+if (process.env.ANTHROPIC_API_KEY) {
+  availableProviders.push({
+    name: 'claude',
+    model: 'claude-opus-4-6',
+    securityAllowed: true,
+  });
+}
+
+if (process.env.OLLAMA_HOST || process.env.OLLAMA_BASE_URL) {
+  availableProviders.push({
+    name: 'ollama',
+    model: process.env.OLLAMA_ADVISOR_MODEL || 'llama3.1:70b',
+    securityAllowed: true, // self-hosted
+  });
+}
+
+if (availableProviders.length === 0) {
+  console.error(JSON.stringify({
+    error: 'No advisor provider available. Set one of: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OLLAMA_HOST',
+    exit_code: 4,
+  }));
+  process.exit(4);
+}
+
+// ============================================================================
+// Read project config for advisor overrides
+// ============================================================================
+
+let advisorConfig = {};
+const configPaths = [
+  join(process.cwd(), '.agentic-qe', 'config.yaml'),
+  join(process.cwd(), '.agentic-qe', 'config.json'),
+];
+
+for (const cfgPath of configPaths) {
+  try {
+    if (!existsSync(cfgPath)) continue;
+    const raw = readFileSync(cfgPath, 'utf-8');
+
+    if (cfgPath.endsWith('.yaml') || cfgPath.endsWith('.yml')) {
+      // Simple YAML parse for advisor section (no dependency required)
+      const advisorMatch = raw.match(/^advisor:\s*\n((?:  .+\n)*)/m);
+      if (advisorMatch) {
+        const lines = advisorMatch[1].split('\n').filter(Boolean);
+        for (const line of lines) {
+          const kv = line.match(/^\s+(\w+):\s*"?([^"#\n]+)"?/);
+          if (kv) advisorConfig[kv[1].trim()] = kv[2].trim();
+        }
+      }
+    } else {
+      const json = JSON.parse(raw);
+      if (json.advisor) advisorConfig = json.advisor;
+    }
+    break;
+  } catch {
+    // config not available — use defaults
+  }
+}
+
+// ============================================================================
+// Select provider based on agent domain + security constraints
+// ============================================================================
+
+const isSecurityAgent = /^qe-security|^qe-pentest/.test(agentName);
+
+let selectedProvider;
+
+// Config override takes priority
+if (advisorConfig.provider) {
+  selectedProvider = availableProviders.find(p => p.name === advisorConfig.provider);
+}
+
+// Security agents: filter to allowed providers only
+if (!selectedProvider && isSecurityAgent) {
+  selectedProvider = availableProviders.find(p => p.securityAllowed);
+  if (!selectedProvider) {
+    console.error(JSON.stringify({
+      error: `Security agent "${agentName}" requires direct Anthropic (ANTHROPIC_API_KEY) or self-hosted Ollama. OpenRouter is not allowed for security agents.`,
+      exit_code: 6,
+    }));
+    process.exit(6);
+  }
+}
+
+// Default: first available provider (preference: openrouter > claude > ollama)
+if (!selectedProvider) {
+  selectedProvider = availableProviders[0];
+}
+
+// Config model override
+const model = advisorConfig.model || selectedProvider.model;
+const maxUses = advisorConfig.maxUses || '3';
+const redactMode = advisorConfig.redact || 'strict';
+
+// M2 fix: resolve domain-specific advisor prompt from agent name
+const DOMAIN_PROMPTS = {
+  'test-generation': 'You are the advisor for a test-generation executor. Respond in under 100 words, enumerated steps. Name concrete classes, methods, dependencies. Focus on: what to mock, priority coverage methods, edge cases the executor will miss, test structure.',
+  'security-compliance': 'You are the advisor for a security executor. Respond in under 100 words, enumerated steps. Name concrete attack vectors, CWE IDs, code locations. Focus on: input validation gaps, auth/authz issues, data exposure, dependency CVEs. Prioritize by exploitability.',
+  'coverage-analysis': 'You are the advisor for a coverage analysis executor. Respond in under 100 words, enumerated steps. Name concrete uncovered files, functions, branches. Focus on: highest business risk gaps, missed branch types, quick wins.',
+  'cross-domain': 'You are the advisor for a fleet commander. Respond in under 100 words, enumerated steps. Focus on: which domains need attention, agent delegation, coordination risks, missing subtasks.',
+};
+
+const AGENT_DOMAIN_MAP = {
+  'qe-test-architect': 'test-generation',
+  'qe-test-generator': 'test-generation',
+  'qe-coverage-specialist': 'coverage-analysis',
+  'qe-coverage-analyzer': 'coverage-analysis',
+  'qe-security-auditor': 'security-compliance',
+  'qe-security-scanner': 'security-compliance',
+  'qe-pentest-validator': 'security-compliance',
+  'qe-fleet-commander': 'cross-domain',
+  'qe-queen-coordinator': 'cross-domain',
+  'qe-risk-assessor': 'cross-domain',
+  'qe-root-cause-analyzer': 'cross-domain',
+};
+
+const agentDomain = AGENT_DOMAIN_MAP[agentName];
+const domainPrompt = agentDomain ? DOMAIN_PROMPTS[agentDomain] : null;
+
+// ============================================================================
+// Write transcript and call aqe llm advise
+// ============================================================================
+
+const transcriptDir = join(tmpdir(), 'aqe-advisor');
+mkdirSync(transcriptDir, { recursive: true });
+const transcriptPath = join(transcriptDir, `transcript-${Date.now()}.json`);
+
+const transcript = {
+  taskDescription,
+  messages: [
+    { role: 'user', content: userMessage },
+    ...(context ? [{ role: 'assistant', content: context }] : []),
+  ],
+};
+
+writeFileSync(transcriptPath, JSON.stringify(transcript));
+
+// Find aqe binary
+let aqeBin = 'aqe';
+try {
+  execFileSync('which', ['aqe'], { encoding: 'utf-8' });
+} catch {
+  // aqe not on PATH — try npx
+  aqeBin = 'npx';
+}
+
+const cliArgs = aqeBin === 'npx'
+  ? ['aqe', 'llm', 'advise']
+  : ['llm', 'advise'];
+
+cliArgs.push(
+  '--transcript', transcriptPath,
+  '--agent', agentName,
+  '--provider', selectedProvider.name,
+  '--model', model,
+  '--redact', redactMode,
+  '--json',
+);
+
+// M2 fix: pass domain-specific prompt if resolved
+if (domainPrompt) {
+  cliArgs.push('--advisor-prompt', domainPrompt);
+}
+
+try {
+  const result = execFileSync(aqeBin, cliArgs, {
+    encoding: 'utf-8',
+    timeout: 60000,
+    env: process.env,
+  });
+
+  // Forward the JSON result, filtering out non-JSON lines (e.g., UnifiedMemory init)
+  const lines = result.split('\n');
+  let inJson = false;
+  let jsonDepth = 0;
+  const jsonLines = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!inJson && trimmed.startsWith('{')) {
+      inJson = true;
+    }
+    if (inJson) {
+      jsonLines.push(line);
+      jsonDepth += (trimmed.match(/{/g) || []).length;
+      jsonDepth -= (trimmed.match(/}/g) || []).length;
+      if (jsonDepth <= 0) break;
+    }
+  }
+
+  if (jsonLines.length > 0) {
+    console.log(jsonLines.join('\n'));
+  }
+
+  // Clean up transcript
+  try { require('fs').unlinkSync(transcriptPath); } catch {}
+
+  process.exit(0);
+} catch (err) {
+  const exitCode = err.status || 1;
+  const stderr = err.stderr || err.message || 'Unknown error';
+
+  console.error(JSON.stringify({
+    error: stderr.slice(0, 500),
+    exit_code: exitCode,
+    provider: selectedProvider.name,
+    model,
+    agent: agentName,
+  }));
+
+  // Clean up
+  try { require('fs').unlinkSync(transcriptPath); } catch {}
+
+  process.exit(exitCode);
+}

package/assets/agents/v3/qe-coverage-specialist.md

@@ -1,16 +1,35 @@
 ---
 name: qe-coverage-specialist
 version: "3.0.0"
-updated: "2026-01-10"
+updated: "2026-04-12"
 description: O(log n) sublinear coverage analysis with risk-weighted gap detection and HNSW vector indexing
 v2_compat:
   name: qe-coverage-analyzer
   deprecated_in: "3.0.0"
   removed_in: "4.0.0"
 domain: coverage-analysis
+advisor:
+  enabled: true
+  provider: openrouter
+  model: anthropic/claude-opus-4
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on coverage analysis. The helper auto-detects the best provider from the user's environment.
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-coverage-specialist \
+  --task "Analyze coverage gaps for <target>" \
+  --context "Coverage data shows: <summary of uncovered areas>"
+```
+
+Call BEFORE deciding which gaps to prioritize. Skip for simple single-file checks.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Coverage Specialist, the primary agent for intelligent coverage analysis in Agentic QE v3.
 Mission: Achieve O(log n) coverage gap detection using HNSW vector indexing with risk-weighted prioritization.

package/assets/agents/v3/qe-fleet-commander.md

@@ -1,13 +1,32 @@
 ---
 name: qe-fleet-commander
 version: "3.0.0"
-updated: "2026-01-10"
+updated: "2026-04-12"
 description: Fleet management with agent lifecycle, workload distribution, and cross-domain coordination at scale
 v2_compat: qe-fleet-commander
 domain: cross-domain
+advisor:
+  enabled: true
+  provider: openrouter
+  model: anthropic/claude-opus-4
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on fleet coordination. The helper auto-detects the best provider from the user's environment.
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-fleet-commander \
+  --task "Coordinate <task description>" \
+  --context "Fleet state: <N agents active>, domains: <list>, plan: <decomposition>"
+```
+
+Call BEFORE task decomposition and BEFORE declaring a multi-agent coordination complete.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Fleet Commander, the fleet management and orchestration expert in Agentic QE v3.
 Mission: Oversee and coordinate all QE agents across the fleet, managing resource allocation, workload distribution, agent health, and cross-domain orchestration at scale.

package/assets/agents/v3/qe-pentest-validator.md

@@ -1,13 +1,32 @@
 ---
 name: qe-pentest-validator
 version: "3.6.0"
-updated: "2026-02-08"
+updated: "2026-04-12"
 description: Graduated exploit validation with parallel vulnerability pipelines, browser-based attack execution, and "No Exploit, No Report" quality gate
 v2_compat: null
 domain: security-compliance
+advisor:
+  enabled: true
+  provider: claude
+  model: claude-opus-4-6
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on exploit validation. The helper auto-detects the provider. Security agents are automatically restricted to direct Anthropic or self-hosted Ollama (OpenRouter is blocked).
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-pentest-validator \
+  --task "Validate <vulnerability type> in <target>" \
+  --context "SAST found <finding>. Attempting exploitation via <approach>."
+```
+
+Call BEFORE each exploitation attempt and BEFORE declaring a finding validated or false-positive. Skip for obvious true-positives with clear reproduction steps.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Pentest Validator, the exploit validation agent in Agentic QE v3.
 Mission: Validate security findings through graduated exploitation - proving vulnerabilities are real before reporting them. Adopts the "No Exploit, No Report" philosophy to eliminate false positives.

package/assets/agents/v3/qe-queen-coordinator.md

@@ -1,7 +1,7 @@
 ---
 name: qe-queen-coordinator
 version: "3.1.0"
-updated: "2026-01-30"
+updated: "2026-04-12"
 description: V3 QE Queen Coordinator - MCP-powered swarm orchestration with real fleet coordination
 v2_compat: null # New in v3
 domain: coordination
@@ -11,9 +11,28 @@ dependencies:
       required: true
     - name: claude-flow
       required: false
+advisor:
+  enabled: true
+  provider: openrouter
+  model: anthropic/claude-opus-4
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on fleet orchestration decisions. The helper auto-detects the best provider.
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-queen-coordinator \
+  --task "Orchestrate <objective>" \
+  --context "Fleet state: <agents active>, domains: <list>, current plan: <decomposition>"
+```
+
+Call BEFORE decomposing a complex multi-domain objective and BEFORE finalizing agent delegation.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Queen Coordinator, the sovereign orchestrator of the Agentic QE v3 fleet.
 Mission: Lead hierarchical coordination of 40+ specialized QE agents to achieve >90% coverage, zero-defect releases, and <5min test feedback.

package/assets/agents/v3/qe-risk-assessor.md

@@ -1,13 +1,32 @@
 ---
 name: qe-risk-assessor
 version: "3.0.0"
-updated: "2026-01-10"
+updated: "2026-04-12"
 description: Quality risk assessment with multi-factor scoring, impact analysis, and mitigation recommendations
 domain: quality-assessment
 v3_new: true
+advisor:
+  enabled: true
+  provider: openrouter
+  model: anthropic/claude-opus-4
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on risk assessment decisions. The helper auto-detects the best provider.
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-risk-assessor \
+  --task "Assess quality risk for <target>" \
+  --context "Risk factors identified: <list>. Current scoring: <summary>"
+```
+
+Call BEFORE assigning final risk scores and BEFORE recommending mitigation strategies. The advisor can identify risk factors you may have underweighted.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Risk Assessor, the quality risk assessment expert in Agentic QE v3.
 Mission: Assess and quantify quality risks across code, tests, and releases using multi-factor risk models and predictive analytics.

package/assets/agents/v3/qe-root-cause-analyzer.md

@@ -16,9 +16,28 @@ dependencies:
   mcp_servers:
     - name: agentic-qe
       required: true
+advisor:
+  enabled: true
+  provider: openrouter
+  model: anthropic/claude-opus-4
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on root cause investigations. The helper auto-detects the best provider.
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-root-cause-analyzer \
+  --task "Root cause analysis for <failure description>" \
+  --context "Evidence gathered: <logs, traces, timeline>. Current hypothesis: <theory>"
+```
+
+Call BEFORE committing to a root cause hypothesis and BEFORE recommending prevention strategies. Early wrong turns in RCA compound — the advisor can challenge your hypothesis.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Root Cause Analyzer, the failure investigation expert in Agentic QE v3.
 Mission: Perform systematic root cause analysis on test failures, production incidents, and defects to identify underlying causes and prevent recurrence.

package/assets/agents/v3/qe-security-auditor.md

@@ -1,13 +1,32 @@
 ---
 name: qe-security-auditor
 version: "3.0.0"
-updated: "2026-01-10"
+updated: "2026-04-12"
 description: Security audit specialist with OWASP coverage, compliance validation, and remediation workflows
 v2_compat: null # New in v3
 domain: security-compliance
+advisor:
+  enabled: true
+  provider: claude
+  model: claude-opus-4-6
+  max_uses: 3
+  redact: strict
 ---
 
 <qe_agent_definition>
+<advisor_protocol>
+You have access to an advisor for strategic guidance on security audits. The helper auto-detects the provider. Security agents are automatically restricted to direct Anthropic or self-hosted Ollama (OpenRouter is blocked).
+
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-security-auditor \
+  --task "Security audit of <target>" \
+  --context "Found so far: <findings summary>"
+```
+
+Call BEFORE committing to a finding severity assessment and BEFORE declaring the audit complete.
+</advisor_protocol>
+
 <identity>
 You are the V3 QE Security Auditor, the comprehensive security audit expert in Agentic QE v3.
 Mission: Conduct comprehensive security audits of code, configurations, and infrastructure to identify vulnerabilities, ensure compliance, and recommend remediation strategies.

package/assets/agents/v3/qe-test-architect.md

@@ -1,13 +1,21 @@
 ---
 name: qe-test-architect
 version: "3.0.0"
-updated: "2026-01-10"
+updated: "2026-04-11"
 description: AI-powered test generation with sublinear optimization, multi-framework support, and self-learning capabilities
 v2_compat:
   name: qe-test-generator
   deprecated_in: "3.0.0"
   removed_in: "4.0.0"
 domain: test-generation
+advisor:
+  enabled: true                    # ADR-092 Phase 0 target agent
+  provider: openrouter             # Phase 0 default; any HybridRouter provider supported
+  model: anthropic/claude-opus-4   # Strong reasoning model via OpenRouter
+  max_uses: 3                      # Per-task advisor call cap
+  budget_usd_per_task: 0.05        # Per-call budget ceiling
+  required: false                  # Phase 5 flips this to true for quality-gate enforcement
+  redact: strict                   # Phase 1 activates; Phase 0 uses happy path
 ---
 
 <qe_agent_definition>
@@ -37,6 +45,30 @@ Planned:
 - AI-powered test data synthesis at scale
 </implementation_status>
 
+<advisor_protocol>
+You have access to an advisor backed by a stronger model. The helper script auto-detects which provider and model to use from the user's environment and project config.
+
+To call the advisor:
+```bash
+node .claude/helpers/v3/advisor-call.cjs \
+  --agent qe-test-architect \
+  --task "Generate pytest tests for <module>" \
+  --context "I read the source. It has classes X, Y, Z with deps on A, B."
+```
+
+If `aqe` is not on PATH, use `npx` instead:
+```bash
+npx -y agentic-qe llm advise --stdin --agent qe-test-architect --json <<< '{"taskDescription":"...","messages":[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]}'
+```
+
+WHEN TO CALL:
+- BEFORE writing any test code — after reading the source file(s), call for a strategic plan
+- When stuck — errors recurring, approach not converging
+- Before declaring the task complete — verify your approach
+
+The advisor responds in under 100 words with enumerated steps naming concrete classes, methods, and mock targets. Give the advice serious weight. On short tasks (1-2 files, obvious strategy), skip the call.
+</advisor_protocol>
+
 <default_to_action>
 Generate tests immediately when provided with source code and requirements.
 Make autonomous decisions about test types and coverage strategies when goals are clear.

package/assets/skills/README.md

@@ -4,9 +4,9 @@ This directory contains Quality Engineering skills managed by Agentic QE.
 
 ## Summary
 
-- **Total QE Skills**: 84
+- **Total QE Skills**: 85
 - **V2 Methodology Skills**: 62
-- **V3 Domain Skills**: 23
+- **V3 Domain Skills**: 24
 - **Platform Skills**: 30 (Claude Flow managed)
 - **Validation Infrastructure**: ✅ Installed
 
@@ -80,11 +80,12 @@ Version-agnostic quality engineering best practices from the QE community.
 - **wms-testing-patterns**: Warehouse Management System testing patterns for inventory operations, pick/pack/ship workflows, wave management, EDI X12/EDIFACT compliance, RF/barcode scanning, and WMS-ERP integration. Use when testing WMS platforms (Blue Yonder, Manhattan, SAP EWM).
 - **xp-practices**: Apply XP practices including pair programming, ensemble programming, continuous integration, and sustainable pace. Use when implementing agile development practices, improving team collaboration, or adopting technical excellence practices.
 
-## V3 Domain Skills (23)
+## V3 Domain Skills (24)
 
 V3-specific implementation guides for the 12 DDD bounded contexts plus on-demand hooks, investigation runbooks, and measurement tools.
 
 - **pentest-validation**: Orchestrate security finding validation through graduated exploitation. 4-phase pipeline: recon (SAST/DAST), analysis (code review), validation (exploit proof), report (No Exploit, No Report gate). Eliminates false positives by proving exploitability.
+- **qe-browser**: Browser automation fleet skill built on Vibium (WebDriver BiDi, ~10MB Go binary, auto-installed by `aqe init`). Ships 5 helpers: typed assertions with 16 check kinds, multi-step batch executor, pixel-perfect visual-diff against baselines, prompt-injection scanner with 14 patterns, and semantic intent scorer with 15 intents (accept_cookies, submit_form, fill_email, etc.). Emits a `skipped` envelope with exit code 2 if vibium isn't installed. Supersedes per-skill browser glue in a11y-ally, e2e-flow-verifier, visual-testing-advanced, and 8 other skills. See [ADR-091](../../../docs/implementation/adrs/ADR-091-qe-browser-skill-vibium-engine.md).
 - **qe-chaos-resilience**: Chaos engineering and resilience testing including fault injection, load testing, and system recovery validation.
 - **qe-code-intelligence**: Knowledge graph-based code understanding with semantic search and 80% token reduction through intelligent context retrieval.
 - **qe-coverage-analysis**: O(log n) sublinear coverage gap detection with risk-weighted analysis and intelligent test prioritization.