feat(e2e): agentic verification loop with MCP Playwright browser layer

.claude-plugin/marketplace.json

@@ -9,6 +9,27 @@
   "plugins": [
     {
       "name": "ralph-specum",
+      "description": "Spec-driven development with bidirectional chat protocol between executor and reviewer. Research, requirements, design, tasks, autonomous execution, and epic triage. Fresh context per task.",
+      "version": "4.9.6",
+      "author": {
+        "name": "tzachbon"
+      },
+      "source": "./plugins/ralph-specum",
+      "category": "development",
+      "tags": [
+        "ralph",
+        "spec-driven",
+        "autonomous",
+        "research",
+        "tasks",
+        "epic",
+        "triage"
+      ]
+    },
+    {
+      "name": "ralph-speckit",
+      "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
+      "version": "0.5.2",
       "description": "Spec-driven development with research, requirements, design, tasks, autonomous execution, and epic triage. Fresh context per task.",
       "version": "4.9.1",
       "author": {

.gitignore

@@ -34,4 +34,8 @@ test-ac-*/
 
 # Claude
 .claude/worktrees/**
-.omc/**
+.omc/**
+node_modules/
+.serena/
+.qwen/
+.mcp.json

.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

README.fork.md

@@ -0,0 +1,167 @@
+# Smart Ralph — Fork Notes
+
+> **Upstream:** [`tzachbon/smart-ralph`](https://github.com/tzachbon/smart-ralph)
+> **Fork:** [`informatico-madrid/smart-ralph`](https://github.com/informatico-madrid/smart-ralph)
+
+This document tracks every deliberate divergence from upstream. It exists so that:
+
+1. The `README.md` stays clean and mergeable with upstream at any time
+2. There is a clear record of what to include in a future PR back to upstream
+3. Any contributor to this fork understands what was changed and why
+
+---
+
+## Fork Goals (TL;DR)
+
+The upstream Smart Ralph spec loop ends at **Phase 4: Quality Gates** (lint, types, CI).
+
+This fork extends it with a **Phase 5: Agentic Verification Loop** — browser-based end-to-end verification driven by `@playwright/mcp`, where the agent navigates, asserts, and reports against the spec's acceptance criteria before marking a task complete.
+
+The core thesis: tests written by the agent are only as good as the agent's ability to run them in a real browser. Phase 5 closes that gap.
+
+---
+
+## What Changed vs Upstream
+
+### New: Phase 5 — Agentic Verification Loop
+
+Upstream's `spec-executor` agent stops after quality gates. This fork adds a fifth phase:
+
+```
+Phase 1: Make It Work      (upstream — unchanged)
+Phase 2: Refactoring       (upstream — unchanged)
+Phase 3: Testing           (upstream — unchanged)
+Phase 4: Quality Gates     (upstream — unchanged)
+Phase 5: Verification ←   NEW in this fork
+```
+
+Phase 5 is driven by **VE tasks** (Verification Execution) generated by `task-planner` and executed by `spec-executor` using MCP Playwright browser tools.
+
+**Files added:**
+
+| File | Purpose |
+|---|---|
+| `plugins/ralph-specum/skills/e2e/mcp-playwright.skill.md` | Full browser verification protocol — tool selection, verification sequence, signal format, degradation strategy |
+| `plugins/ralph-specum/skills/e2e/playwright-session.skill.md` | Session lifecycle — context isolation, auth flow, cleanup, state persistence |
+| `plugins/ralph-specum/skills/e2e/playwright-env.skill.md` | Environment context resolution — URL, auth type, credentials, seed data, browser config, safety limits |
+| `plugins/ralph-specum/skills/e2e/ui-map.skill.md` | UI component map — stable selector registry so VE tasks don't hand-write CSS selectors |
+| `plugins/ralph-specum/skills/e2e/ui-map-init.skill.md` | Initialise the UI map by crawling the live app with MCP Playwright |
+| `.gitignore` additions | `playwright-env.local.md` — contains env var references and local config, never committed |
+
+**Files modified:**
+
+| File | What changed |
+|---|---|
+| `plugins/ralph-specum/agents/task-planner.md` | Added VE task format, `[VE]` markers, and Verification Contract generation rules |
+| `plugins/ralph-specum/agents/spec-executor.md` | Added Phase 5 execution rules, VE task handling, skill loading order |
+| `plugins/ralph-specum/templates/tasks.md` | Added Phase 5 section with VE task template and Verification Contract template |
+| `plugins/ralph-specum/templates/requirements.md` | Added Entry Points section (UI routes the agent needs to navigate) |
+| `CLAUDE.md` (Key Files section) | Added references to Phase 5 skill files |
+
+---
+
+## New Concepts Not in Upstream
+
+### VE Tasks
+
+VE tasks (`[VE]`) are a new task type, generated in Phase 5, that instruct the `spec-executor` to verify a specific acceptance criterion via browser. They follow this format in `tasks.md`:
+
+```markdown
+- [ ] [VE] AC-1.2 — verify user can submit the login form and land on dashboard
+```
+
+VE tasks are non-destructive by default. The agent reads `RALPH_ALLOW_WRITE` from the environment before performing any write action in a real environment.
+
+### Verification Contract
+
+A structured block appended to `requirements.md` after the requirements phase, listing:
+- UI entry points (URLs the agent will navigate to)
+- Auth type required
+- Seed data dependencies
+- Expected signals (`VERIFICATION_PASS` / `VERIFICATION_FAIL`)
+
+### playwright-env.local.md
+
+A per-project local file (gitignored) that resolves environment context for the agent before any browser interaction. See [`playwright-env.local.md.example`](playwright-env.local.md.example) for the full template with all auth type variants.
+
+### Auth Types Supported
+
+| Type | Env var that activates it |
+|---|---|
+| `none` | `RALPH_AUTH_TYPE=none` |
+| `form` | `RALPH_AUTH_TYPE=form` |
+| `token` | `RALPH_AUTH_TYPE=token` |
+| `cookie` | `RALPH_AUTH_TYPE=cookie` |
+| `oauth` | `RALPH_AUTH_TYPE=oauth` |
+| `basic` | `RALPH_AUTH_TYPE=basic` |
+
+Credentials are **never stored in files**. They live exclusively in environment variables (see example file).
+
+---
+
+## Signal Protocol
+
+Phase 5 emits structured signals at the end of every VE task:
+
+```
+VERIFICATION_PASS    — AC verified, screenshot attached
+VERIFICATION_FAIL    — AC failed, full diagnosis (console + network + snapshot)
+VERIFICATION_DEGRADED — MCP not available, static fallback used
+ESCALATE             — Human intervention required
+```
+
+The stop-watcher captures `ESCALATE` and blocks the loop until the human resolves the blocker.
+
+---
+
+## What Upstream Does Not Have (and Why)
+
+| Feature | Why not upstream (yet) |
+|---|---|
+| Phase 5 VE loop | Requires `@playwright/mcp` — adds an optional dependency upstream doesn't mandate |
+| `playwright-env.local.md` protocol | Project-specific config pattern; upstream is project-agnostic |
+| Auth-aware browser sessions | Outside scope of upstream's self-contained workflow |
+| `RALPH_ALLOW_WRITE` safety gate | Needed when agent runs against staging/production — upstream only targets local dev |
+
+---
+
+## PR Contribution Plan
+
+When the Phase 5 work stabilises, the intended upstream contribution is:
+
+1. **Phase 5 as opt-in** — activated only when `@playwright/mcp` is detected (already implemented via Protocol A/B in `mcp-playwright.skill.md`)
+2. **`[VE]` task type** — additive to `task-planner` and `tasks.md` template, no breaking change
+3. **Verification Contract** — additive section in `requirements.md` template
+4. **`playwright-env.local.md.example`** — example only, never committed with real values
+
+The auth credential handling and `playwright-env.local.md` are **out of scope for the upstream PR** — too project-specific. Those stay in the fork.
+
+---
+
+## Staying in Sync with Upstream
+
+```bash
+# Add upstream remote (once)
+git remote add upstream https://github.com/tzachbon/smart-ralph.git
+
+# Pull upstream changes
+git fetch upstream
+git merge upstream/main
+
+# Conflicts to expect:
+# - agents/task-planner.md   (VE task additions)
+# - agents/spec-executor.md  (Phase 5 additions)
+# - templates/tasks.md       (Phase 5 section)
+# - templates/requirements.md (Entry Points + Verification Contract)
+# - CLAUDE.md                (Key Files additions)
+```
+
+When merging upstream, preserve the Phase 5 additions in the files above. Everything else should merge cleanly.
+
+---
+
+## Version
+
+This fork is based on upstream `v3.x` (self-contained loop, no ralph-loop dependency).
+
+Fork maintained by [@informatico-madrid](https://github.com/informatico-madrid).