specweave 1.0.239 → 1.0.240

package/plugins/specweave/scripts/read-grill-context.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# read-grill-context.sh - Load increment context for /sw:grill code review
+#
+# Executed by UserPromptSubmit hook when /sw:grill is detected.
+# Outputs structured context + review instructions that get injected
+# into the LLM's conversation via additionalContext.
+#
+# Usage: bash read-grill-context.sh [incrementId]
+#
+# If no incrementId given, auto-detects from active-increment.json.
+# Supports partial ID matching (e.g., "0042" matches "0042-auth-feature").
+#
+# Compatible with bash 3.x (macOS default)
+
+set -e
+
+INCREMENT_ID="${1:-}"
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "No SpecWeave project found (missing .specweave/)"
+  exit 1
+fi
+
+INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+
+# Auto-detect active increment if no ID given
+if [[ -z "$INCREMENT_ID" ]]; then
+  if [[ -f "$STATE_DIR/active-increment.json" ]] && command -v jq >/dev/null 2>&1; then
+    INCREMENT_ID=$(jq -r '.ids[0] // empty' "$STATE_DIR/active-increment.json" 2>/dev/null)
+  fi
+
+  if [[ -z "$INCREMENT_ID" ]]; then
+    echo "No increment ID provided and no active increment found."
+    echo "Usage: /sw:grill <incrementId>"
+    exit 1
+  fi
+fi
+
+# Find increment folder (exact or partial match)
+FOUND_DIR=""
+if [[ -d "$INCREMENTS_DIR/$INCREMENT_ID" ]]; then
+  FOUND_DIR="$INCREMENTS_DIR/$INCREMENT_ID"
+else
+  # Partial match
+  for dir in "$INCREMENTS_DIR"/[0-9]*/; do
+    dirname=$(basename "$dir")
+    if [[ "$dirname" == "$INCREMENT_ID"* ]]; then
+      FOUND_DIR="${dir%/}"  # Strip trailing slash from glob
+      INCREMENT_ID="$dirname"
+      break
+    fi
+  done
+fi
+
+if [[ -z "$FOUND_DIR" ]] || [[ ! -d "$FOUND_DIR" ]]; then
+  echo "Increment not found: ${1:-$INCREMENT_ID}"
+  exit 1
+fi
+
+# Read metadata
+STATUS="unknown"
+TYPE="feature"
+PRIORITY="P1"
+if [[ -f "$FOUND_DIR/metadata.json" ]] && command -v jq >/dev/null 2>&1; then
+  STATUS=$(jq -r '.status // "unknown"' "$FOUND_DIR/metadata.json" 2>/dev/null)
+  TYPE=$(jq -r '.type // "feature"' "$FOUND_DIR/metadata.json" 2>/dev/null)
+  PRIORITY=$(jq -r '.priority // "P1"' "$FOUND_DIR/metadata.json" 2>/dev/null)
+fi
+
+# Count tasks
+# NOTE: grep -c exits 1 on zero matches but still outputs "0".
+# Using || true prevents set -e from killing the script without doubling output.
+TASK_TOTAL=0
+TASK_COMPLETED=0
+TASK_PCT=0
+if [[ -f "$FOUND_DIR/tasks.md" ]]; then
+  TASK_TOTAL=$(grep -c '### T-[0-9]' "$FOUND_DIR/tasks.md" 2>/dev/null) || true
+  TASK_COMPLETED=$(grep -ci '\*\*Status\*\*:\s*\[x\]' "$FOUND_DIR/tasks.md" 2>/dev/null) || true
+  [[ -z "$TASK_TOTAL" ]] && TASK_TOTAL=0
+  [[ -z "$TASK_COMPLETED" ]] && TASK_COMPLETED=0
+  if [[ "$TASK_TOTAL" -gt 0 ]]; then
+    TASK_PCT=$((TASK_COMPLETED * 100 / TASK_TOTAL))
+  fi
+fi
+
+# Count ACs from spec.md
+AC_TOTAL=0
+AC_COMPLETED=0
+AC_PCT=0
+if [[ -f "$FOUND_DIR/spec.md" ]]; then
+  AC_TOTAL=$(grep -cE '^\s*- \[[ x]\] \*\*AC-' "$FOUND_DIR/spec.md" 2>/dev/null) || true
+  AC_COMPLETED=$(grep -cE '^\s*- \[x\] \*\*AC-' "$FOUND_DIR/spec.md" 2>/dev/null) || true
+  [[ -z "$AC_TOTAL" ]] && AC_TOTAL=0
+  [[ -z "$AC_COMPLETED" ]] && AC_COMPLETED=0
+  if [[ "$AC_TOTAL" -gt 0 ]]; then
+    AC_PCT=$((AC_COMPLETED * 100 / AC_TOTAL))
+  fi
+fi
+
+# Output structured grill context
+cat <<GRILL_CONTEXT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GRILL MODE ACTIVATED — ${INCREMENT_ID}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CONTEXT:
+  Status: ${STATUS} | Type: ${TYPE} | Priority: ${PRIORITY}
+  Tasks: ${TASK_COMPLETED}/${TASK_TOTAL} (${TASK_PCT}%)
+  ACs:   ${AC_COMPLETED}/${AC_TOTAL} (${AC_PCT}%)
+
+INCREMENT FILES:
+  spec.md:  ${FOUND_DIR}/spec.md
+  tasks.md: ${FOUND_DIR}/tasks.md
+  plan.md:  ${FOUND_DIR}/plan.md
+
+INSTRUCTIONS — You are now in GRILL MODE. Act as a demanding senior engineer:
+
+1. Read the increment's spec.md to understand WHAT should have been built
+2. Read tasks.md to understand WHAT was done
+3. Find all changed files:
+   git diff --name-only \$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD develop 2>/dev/null || echo HEAD~10)..HEAD 2>/dev/null
+   If git is not available, read the tasks for file references.
+4. For EACH significant changed file, check:
+   - Correctness: Does it satisfy the ACs? Edge cases? Null handling?
+   - Security: Injection? XSS? Auth bypass? Secrets in code?
+   - Performance: O(n²)? N+1 queries? Memory leaks? Blocking ops?
+   - Maintainability: God functions? Magic numbers? Inconsistent patterns?
+5. Categorize every issue found:
+   BLOCKER  — Production will break, MUST fix
+   CRITICAL — Security/data risk, MUST fix
+   MAJOR    — Significant gap, should fix
+   MINOR    — Code quality, can fix later
+   SUGGESTION — Nice to have improvement
+
+OUTPUT FORMAT:
+  For each issue: [{SEVERITY}] Title | File:line | Problem | Fix
+  End with: VERDICT: PASS (no blockers/criticals) or FAIL (has blockers/criticals)
+
+If FAIL: List blocking issues and stop. Do NOT proceed with /sw:done.
+If PASS: Code is ready for closure.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GRILL_CONTEXT

package/plugins/specweave-testing/commands/e2e-setup.md

@@ -8,22 +8,22 @@ Set up comprehensive Playwright E2E testing with best practices, page objects, a
 
 You are an expert E2E testing engineer who implements production-ready Playwright test suites.
 
-## CLI vs MCP Mode
+## CLI-First Rule (MANDATORY)
 
-SpecWeave supports two modes for Playwright browser automation:
+**ALWAYS use Playwright CLI** (`npx playwright test`, `npx playwright codegen`) for all test setup, execution, and debugging. **DO NOT** use MCP Playwright tools (`browser_click`, `browser_snapshot`, `browser_navigate`, etc.) — they bypass playwright.config.ts, ignore fixtures/reporters, and waste tokens.
 
-- **@playwright/cli** (recommended for test execution): Token-efficient, file-based output, CI-friendly
-- **@playwright/mcp** (for interactive exploration): Rich inline snapshots, good for debugging
+MCP Playwright is only acceptable for `/sw-testing:ui-inspect` (interactive DOM inspection). For everything else, use the CLI via Bash.
 
-Install CLI mode: `npm install -g @playwright/cli@latest`
+```bash
+# Install Playwright
+npm init playwright@latest
 
-Configure preference in `.specweave/config.json`:
-```json
-{
-  "testing": {
-    "playwright": { "preferCli": true }
-  }
-}
+# Run tests
+npx playwright test
+
+# Debug
+npx playwright test --debug
+npx playwright test --ui
 ```
 
 ## Your Task

package/plugins/specweave-testing/commands/ui-automate.md

@@ -19,9 +19,9 @@ Create and execute automated browser workflows using Playwright. Generate script
 3. **Error Handling**: Add retry logic, timeouts, and fallbacks
 4. **Output Collection**: Capture screenshots, data, and validation results
 
-> **Why Code-First?** Anthropic research shows [code execution beats MCP tool calls](https://www.anthropic.com/engineering/code-execution-with-mcp) with 98% token reduction. Playwright code is reusable, committable, CI-runnable, and deterministic.
-
-> **CLI Mode Available**: When `@playwright/cli` is installed, this command routes to the CLI by default for maximum token efficiency (~250 chars per interaction vs ~5K+ via MCP). The CLI keeps browser state external and returns file references instead of inline DOM trees. Install: `npm install -g @playwright/cli@latest`
+> **Code-First, CLI-First (MANDATORY)**: Generate Playwright scripts as `.ts` files and run them via CLI (`npx playwright test` or `npx tsx script.ts`). **DO NOT** use MCP Playwright tools (`browser_click`, `browser_fill_form`, `browser_navigate`, etc.) for automation — they produce ephemeral tool calls instead of reusable code, consume 20x more tokens, and cannot be committed or run in CI.
+>
+> Anthropic research confirms [code execution beats MCP tool calls](https://www.anthropic.com/engineering/code-execution-with-mcp) with 98% token reduction.
 
 ## Workflow Types
 

package/plugins/specweave-testing/commands/ui-inspect.md

@@ -65,11 +65,11 @@ Provides:
 
 ## Browser Mode
 
-This command **prefers MCP mode** for rich DOM introspection. When the Playwright MCP plugin provides inline accessibility tree snapshots, the AI can reason about page structure and find optimal selectors.
+This command is the **only SpecWeave testing command where MCP Playwright is appropriate**. It uses MCP's `browser_snapshot` for rich DOM introspection — the AI can reason about the accessibility tree inline and find optimal selectors.
 
-If MCP is unavailable, falls back to `@playwright/cli snapshot` which saves the accessibility tree to a file (`.playwright-cli/*.yml`). The AI can then read the file, but loses the ability to iterate on snapshots without re-reading.
+If MCP is unavailable, falls back to `@playwright/cli snapshot` which saves the accessibility tree to a file (`.playwright-cli/*.yml`).
 
-**Recommended**: Keep the Playwright MCP plugin installed for best `ui-inspect` experience.
+**Important**: MCP Playwright is appropriate here for interactive inspection. For all other testing tasks (running tests, writing test code, automation scripts), always use the Playwright CLI via Bash instead. See `/sw-testing:e2e-setup` for details.
 
 ## Requirements
 

package/plugins/specweave-testing/lib/playwright-cli-detector.js

@@ -1,14 +1,18 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 let cachedResult = null;
+function clearCache() {
+  cachedResult = null;
+}
 function detectPlaywrightCli(options = {}) {
   const { useCache = false } = options;
   if (useCache && cachedResult) {
     return cachedResult;
   }
+  const whichCmd = process.platform === "win32" ? "where" : "which";
   let path;
   let version;
   try {
-    path = execSync("which playwright-cli", {
+    path = execFileSync(whichCmd, ["playwright-cli"], {
       encoding: "utf-8",
       timeout: 5e3
     }).trim();
@@ -18,7 +22,7 @@ function detectPlaywrightCli(options = {}) {
     return result2;
   }
   try {
-    version = execSync("playwright-cli --version", {
+    version = execFileSync("playwright-cli", ["--version"], {
       encoding: "utf-8",
       timeout: 5e3
     }).trim();
@@ -29,5 +33,6 @@ function detectPlaywrightCli(options = {}) {
   return result;
 }
 export {
+  clearCache,
   detectPlaywrightCli
 };

package/plugins/specweave-testing/lib/playwright-cli-detector.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
 export interface CliDetectionResult {
   installed: boolean;
@@ -12,6 +12,10 @@ export interface DetectOptions {
 
 let cachedResult: CliDetectionResult | null = null;
 
+export function clearCache(): void {
+  cachedResult = null;
+}
+
 export function detectPlaywrightCli(options: DetectOptions = {}): CliDetectionResult {
   const { useCache = false } = options;
 
@@ -19,11 +23,12 @@ export function detectPlaywrightCli(options: DetectOptions = {}): CliDetectionRe
     return cachedResult;
   }
 
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
   let path: string | undefined;
   let version: string | undefined;
 
   try {
-    path = execSync('which playwright-cli', {
+    path = execFileSync(whichCmd, ['playwright-cli'], {
       encoding: 'utf-8',
       timeout: 5_000,
     }).trim();
@@ -34,7 +39,7 @@ export function detectPlaywrightCli(options: DetectOptions = {}): CliDetectionRe
   }
 
   try {
-    version = execSync('playwright-cli --version', {
+    version = execFileSync('playwright-cli', ['--version'], {
       encoding: 'utf-8',
       timeout: 5_000,
     }).trim();

package/plugins/specweave-testing/lib/playwright-cli-runner.js

@@ -1,21 +1,24 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 class PlaywrightCliRunner {
   constructor(config = {}) {
     this.config = {
       headed: config.headed ?? false,
       browser: config.browser ?? "chrome",
-      session: config.session,
       timeout: config.timeout ?? 3e4,
-      ...config
+      session: config.session
     };
   }
-  exec(command) {
-    const sessionFlag = this.config.session ? `-s=${this.config.session} ` : "";
-    const fullCommand = `playwright-cli ${sessionFlag}${command}`;
+  exec(args) {
+    const fullArgs = [];
+    if (this.config.session) {
+      fullArgs.push(`-s=${this.config.session}`);
+    }
+    fullArgs.push(...args);
     try {
-      const output = execSync(fullCommand, {
+      const output = execFileSync("playwright-cli", fullArgs, {
         encoding: "utf-8",
-        timeout: this.config.timeout
+        timeout: this.config.timeout,
+        maxBuffer: 1024 * 1024
       }).trim();
       return { ok: true, output };
     } catch (e) {
@@ -23,34 +26,36 @@ class PlaywrightCliRunner {
     }
   }
   open(url) {
-    const headedFlag = this.config.headed ? " --headed" : "";
-    const urlPart = url ? ` ${url}` : "";
-    return this.exec(`open${urlPart}${headedFlag}`);
+    const args = ["open"];
+    if (url) args.push(url);
+    if (this.config.headed) args.push("--headed");
+    return this.exec(args);
   }
   navigate(url) {
-    return this.exec(`goto ${url}`);
+    return this.exec(["goto", url]);
   }
   snapshot() {
-    return this.exec("snapshot");
+    return this.exec(["snapshot"]);
   }
   screenshot(filename) {
-    const flag = filename ? ` --filename ${filename}` : "";
-    return this.exec(`screenshot${flag}`);
+    const args = ["screenshot"];
+    if (filename) args.push("--filename", filename);
+    return this.exec(args);
   }
   close() {
-    return this.exec("close");
+    return this.exec(["close"]);
   }
   click(ref) {
-    return this.exec(`click ${ref}`);
+    return this.exec(["click", ref]);
   }
   type(text) {
-    return this.exec(`type "${text}"`);
+    return this.exec(["type", text]);
   }
   fill(ref, text) {
-    return this.exec(`fill ${ref} "${text}"`);
+    return this.exec(["fill", ref, text]);
   }
   evaluate(fn) {
-    return this.exec(`eval "${fn}"`);
+    return this.exec(["eval", fn]);
   }
 }
 export {

package/plugins/specweave-testing/lib/playwright-cli-runner.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
 export interface CliRunnerConfig {
   headed?: boolean;
@@ -19,19 +19,22 @@ export class PlaywrightCliRunner {
     this.config = {
       headed: config.headed ?? false,
       browser: config.browser ?? 'chrome',
-      session: config.session,
       timeout: config.timeout ?? 30_000,
-      ...config,
+      session: config.session,
     };
   }
 
-  private exec(command: string): CliResult {
-    const sessionFlag = this.config.session ? `-s=${this.config.session} ` : '';
-    const fullCommand = `playwright-cli ${sessionFlag}${command}`;
+  private exec(args: string[]): CliResult {
+    const fullArgs: string[] = [];
+    if (this.config.session) {
+      fullArgs.push(`-s=${this.config.session}`);
+    }
+    fullArgs.push(...args);
     try {
-      const output = execSync(fullCommand, {
+      const output = execFileSync('playwright-cli', fullArgs, {
         encoding: 'utf-8',
         timeout: this.config.timeout,
+        maxBuffer: 1024 * 1024,
       }).trim();
       return { ok: true, output };
     } catch (e: unknown) {
@@ -40,41 +43,43 @@ export class PlaywrightCliRunner {
   }
 
   open(url?: string): CliResult {
-    const headedFlag = this.config.headed ? ' --headed' : '';
-    const urlPart = url ? ` ${url}` : '';
-    return this.exec(`open${urlPart}${headedFlag}`);
+    const args = ['open'];
+    if (url) args.push(url);
+    if (this.config.headed) args.push('--headed');
+    return this.exec(args);
   }
 
   navigate(url: string): CliResult {
-    return this.exec(`goto ${url}`);
+    return this.exec(['goto', url]);
   }
 
   snapshot(): CliResult {
-    return this.exec('snapshot');
+    return this.exec(['snapshot']);
   }
 
   screenshot(filename?: string): CliResult {
-    const flag = filename ? ` --filename ${filename}` : '';
-    return this.exec(`screenshot${flag}`);
+    const args = ['screenshot'];
+    if (filename) args.push('--filename', filename);
+    return this.exec(args);
   }
 
   close(): CliResult {
-    return this.exec('close');
+    return this.exec(['close']);
   }
 
   click(ref: string): CliResult {
-    return this.exec(`click ${ref}`);
+    return this.exec(['click', ref]);
   }
 
   type(text: string): CliResult {
-    return this.exec(`type "${text}"`);
+    return this.exec(['type', text]);
   }
 
   fill(ref: string, text: string): CliResult {
-    return this.exec(`fill ${ref} "${text}"`);
+    return this.exec(['fill', ref, text]);
   }
 
   evaluate(fn: string): CliResult {
-    return this.exec(`eval "${fn}"`);
+    return this.exec(['eval', fn]);
   }
 }

package/plugins/specweave-testing/skills/e2e-testing/SKILL.md

@@ -230,43 +230,44 @@ e2e/
 └── playwright.config.ts
 ```
 
-## Browser Automation Mode: CLI vs MCP
+## Browser Automation: CLI-First Rule
 
-SpecWeave provides dual-mode browser automation for optimal token efficiency:
+**MANDATORY**: Always use Playwright CLI (`npx playwright test`, Bash tool) for test execution, automation scripts, and CI/CD workflows. **DO NOT** use MCP Playwright tools (`browser_click`, `browser_snapshot`, `browser_navigate`, etc.) for these tasks.
 
-| Mode | Tool | Best For | Token Cost |
-|------|------|----------|------------|
-| **CLI** | `@playwright/cli` (Bash) | Test execution, automation, CI/CD | ~250 chars/action |
-| **MCP** | Playwright MCP plugin | Interactive inspection, self-healing | ~5K+ chars/action |
+MCP Playwright tools consume ~20x more tokens per action and bypass your test configuration (playwright.config.ts, fixtures, reporters). They are the wrong tool for testing.
 
-### When to Use CLI Mode
-- Running E2E test suites (`npx playwright test`)
-- Generating automation scripts
-- CI/CD pipelines (headless by default)
-- Token-constrained sessions
-- Network mocking and auth state management
+### When to Use What
 
-### When to Use MCP Mode
-- Interactive page exploration and debugging
-- Self-healing test repair (needs full DOM reasoning)
-- Element inspection with accessibility tree
+| Task | Tool | Why |
+|------|------|-----|
+| Run tests | `npx playwright test` (Bash) | Uses project config, parallel execution, reporters |
+| Write test code | Write/Edit tools | Produces committable, CI-runnable `.spec.ts` files |
+| Generate tests | `npx playwright codegen` (Bash) | Records user actions as code |
+| Debug failures | `npx playwright test --debug` or `--ui` (Bash) | Full trace viewer, time-travel debugging |
+| **Exception**: inspect live DOM | MCP `browser_snapshot` | Only when you need to reason about current page structure interactively |
 
-### Install CLI
+### Why CLI Over MCP for Testing
+
+1. **Headless control**: CLI respects `playwright.config.ts` headless settings; MCP always opens a visible browser
+2. **Config integration**: CLI uses your fixtures, projects, retries, reporters; MCP ignores them all
+3. **Token efficiency**: CLI returns concise pass/fail output (~250 chars); MCP returns full DOM trees (~5K+ chars per action)
+4. **Reproducibility**: CLI tests are deterministic `.spec.ts` files; MCP interactions are ephemeral tool calls
+5. **CI/CD ready**: CLI output works directly in GitHub Actions, Jenkins, etc.
+
+### Install Playwright CLI
 ```bash
-npm install -g @playwright/cli@latest
+npm init playwright@latest
+# or for existing projects:
+npx playwright install
 ```
 
-### Configuration
-Set preference in `.specweave/config.json`:
-```json
-{
-  "testing": {
-    "playwright": { "preferCli": true }
-  }
-}
-```
+### The Only MCP Exception
+
+Use MCP Playwright tools **only** for:
+- `/sw-testing:ui-inspect` — interactive element inspection requiring DOM reasoning
+- One-off page exploration when you need to see what's on a page right now
 
-The `sw-testing` skill layer routes automatically based on task type.
+For everything else — writing tests, running tests, generating tests, debugging tests — use the CLI via Bash.
 
 ## Related Skills
 

package/plugins/specweave-testing/skills/qa-engineer/SKILL.md

@@ -158,6 +158,8 @@ You are an expert QA engineer with deep knowledge of testing strategies, test au
 
 ### 6. End-to-End Testing
 
+**CLI-First Rule**: Always use Playwright CLI (`npx playwright test`) for E2E test execution. DO NOT use MCP Playwright tools (`browser_click`, `browser_snapshot`, etc.) for running or writing tests — they bypass playwright.config.ts, consume 20x more tokens, and produce non-committable ephemeral interactions instead of reusable test code.
+
 **Playwright Excellence**:
 - Page Object Model (POM)
 - Fixtures for setup/teardown