/specs-e2e-verification

name: specs-e2e-verification
description: "Executes real end-to-end verification against a running application after specification implementation. Detects the application type, starts the local runtime (Docker, Node, Spring Boot, etc.), runs real tests (curl for REST APIs, Playwright for web SPAs, computer-use for desktop apps), verifies acceptance criteria from the functional specification, generates a markdown report, and tears down the environment. Use when: user asks to verify a completed spec with real tests, run e2e checks after implementation, validate acceptance criteria in a live environment, or test the feature for real after task completion."
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, AskUserQuestion

Specs E2E Verification

Overview

Performs **real environment verification** after a specification has been implemented and cleaned up. This skill bridges the gap between unit-tested code and observable runtime behavior by:

1. Detecting the application type from project files 2. Starting the local runtime (Docker Compose, dev server, Spring Boot, etc.) 3. Deriving tests from `[IMP]` acceptance criteria in the functional specification 4. Executing real tests (`curl`, Playwright, computer-use) 5. Mapping results to acceptance criteria 6. Generating a verification report 7. Tearing down the environment

**Input**: `docs/specs/[id]/` (spec folder with functional specification and tasks) **Output**: `docs/specs/[id]/e2e-report-YYYY-MM-DD-HHMMSS.md`

When to Use

• Use after `specs.task-implementation` and `specs.code-cleanup` to confirm the feature works in reality.
• Use when a developer says "test it for real", "verify the API actually works", "run e2e checks", or "validate acceptance criteria live".
• Use to generate evidence of feature completion before closing a specification.
• Do NOT use for unit testing, static analysis, or code review — this is runtime behavioral verification only.

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `--spec` | Yes | Path to the specification folder (e.g., `docs/specs/001-feature/`) | | `--task` | No | Specific task ID to limit verification scope (e.g., `TASK-003`) | | `--keep-alive` | No | If present, skip teardown and leave the environment running | | `--timeout` | No | Startup and test timeout in seconds (default: 120) | | `--insecure` | No | If present, allow curl to use `-k` / `--insecure` (TLS bypass opt-in) |

Best Practices

• **Safety first**: Never run destructive commands (`rm -rf`, `docker system prune`, `sudo`).
• **Detect, don’t assume**: Use file heuristics to determine the app type; ask the user only when ambiguous.
• **AC-driven**: Every test must trace back to an `[IMP]` acceptance criterion from the functional specification.
• **Clean up**: Always teardown unless `--keep-alive` is passed; warn about leftover processes.
• **No code changes**: This skill is read-only regarding source code. It may create reports but never patches logic.
• **Use TodoWrite**: Track progress across all 8 phases.

Instructions

Phase 1: Parse Arguments and Load Context

1. Parse `$ARGUMENTS`:

• `--spec` (required): spec folder path. Validate that the directory exists and contains at least one functional specification file (`YYYY-MM-DD--*.md`). If missing or invalid, abort with an error.
• `--task` (optional): task ID filter (e.g., `TASK-003`). If provided, validate that `tasks/<task-id>.md` exists inside the spec folder.
• `--keep-alive` (optional): boolean flag. If present, skip teardown at the end.
• `--timeout` (optional): positive integer in seconds. Default is `120`. Validate that the value is a positive integer; if not, abort with an error.
• `--insecure` (optional): boolean flag. If present, curl commands MAY use `-k` / `--insecure` for local development with self-signed certificates. By default, TLS bypass is forbidden (REQ-NR003).

2. Read the functional specification and extract:

• All acceptance criteria with their taxonomy tags (`[IMP]`, `[SEF]`, `[EXT]`)
• Only `[IMP]` criteria will generate runtime tests

3. If `--task` is provided, read the task file and limit scope to its `provides` files and related AC.

4. Use `TodoWrite` to create a todo list for all 8 phases.

Phase 1.5: Security Validation Gate

Before any command is executed, run the following security checks:

1. **Command Whitelist Check**:

• The startup command derived in Phase 3 MUST match a pattern documented in `references/test-execution-patterns.md`.
• IF the command is NOT in the whitelist → use `AskUserQuestion` to request explicit user confirmation before execution.
• Whitelisted commands include: `docker compose up -d --build`, `./mvnw spring-boot:run`, `./gradlew bootRun`, `npm run dev`, `npm run start:dev`, `npm start`, `cargo tauri build --debug`, `cargo tauri dev`, `npm run electron:dev`, `npx electron .`, `open *.app`, and equivalent local process launchers.
• Any command containing `sudo`, `rm -rf`, `docker system prune`, `mkfs`, `dd`, or similar destructive operations is NOT whitelisted and SHALL be rejected.

2. **Forbidden Pattern Scan** (REQ-NR001):

• Scan the derived startup command and all generated test commands for:
• `sudo` → abort with: "Forbidden: sudo is not permitted during E2E verification."
• `rm -rf` → abort with: "Forbidden: rm -rf is not permitted during E2E verification."
• `docker system prune` → abort with: "Forbidden: docker system prune is not permitted during E2E verification."
• Any `rm`, `drop`, `destroy`, `prune` targeting databases, volumes, or local data → abort with: "Forbidden: destructive data operations are not permitted."
• IF any forbidden pattern is detected → abort immediately; do NOT proceed to startup.

3. **TLS Enforcement Check** (REQ-NR003):

• For any generated curl command:
• IF it contains `-k` or `--insecure` AND `--insecure` was NOT passed → abort with: "Fo