deepflow 0.1.79 → 0.1.80

package/README.md

@@ -33,6 +33,7 @@ Most spec-driven frameworks start from a finished spec and execute a static plan
 - **Spec as living hypothesis** — Core intent stays fixed, details refine through implementation. "The spec becomes bulletproof because you built it, not before."
 - **Parallel probes reveal the best path** — Uncertain approaches spawn parallel spikes in isolated worktrees. The machine selects the winner (fewer regressions > better coverage > fewer files changed). Failed approaches stay recorded and never repeat.
 - **Metrics decide, not opinions** — No LLM judges another LLM. Build, tests, typecheck, lint, and invariant checks are the only judges. After an agent commits, the orchestrator runs health checks. Pass = keep. Fail = revert + new hypothesis.
+- **Browser verification closes the loop** — L5 launches headless Chromium via Playwright, captures the accessibility tree, and evaluates structured assertions extracted at plan-time from your spec's acceptance criteria. Deterministic pass/fail — no LLM calls during verification. Screenshots saved as evidence.
 - **The loop is the product** — Not "execute a plan" — "evolve the codebase toward the spec's goals through iterative cycles." Each cycle reveals what the previous one couldn't see.
 
 ## What We Learned by Doing
@@ -111,7 +112,7 @@ $ git log --oneline
 1. Runs `/df:plan` if no PLAN.md exists
 2. Snapshots pre-existing tests (ratchet baseline)
 3. Starts a loop (`/loop 1m /df:auto-cycle`) — fresh context each cycle
-4. Each cycle: picks next task → executes in worktree → runs health checks (build/tests/typecheck/lint/invariant-check)
+4. Each cycle: picks next task → executes in worktree → runs health checks (build/tests/typecheck/lint/invariant-check/browser-verify)
 5. Pass = commit stands. Fail = revert + retry next cycle
 6. Circuit breaker: halts after N consecutive reverts on same task
 7. When all tasks done: runs `/df:verify`, merges to main
@@ -142,7 +143,7 @@ $ git log --oneline
 | `/df:spec <name>` | Generate spec from conversation |
 | `/df:plan` | Compare specs to code, create tasks |
 | `/df:execute` | Run tasks with parallel agents |
-| `/df:verify` | Check specs satisfied, merge to main |
+| `/df:verify` | Check specs satisfied (L0-L5), merge to main |
 | `/df:note` | Capture decisions ad-hoc from conversation |
 | `/df:consolidate` | Deduplicate and clean up decisions.md |
 | `/df:resume` | Session continuity briefing |
@@ -179,12 +180,22 @@ your-project/
 
 1. **Discover before specifying, spike before implementing** — Ask, debate, probe — then commit
 2. **You define WHAT, AI figures out HOW** — Specs are the contract
-3. **Metrics decide, not opinions** — Build/test/typecheck/lint/invariant-check are the only judges
+3. **Metrics decide, not opinions** — Build/test/typecheck/lint/invariant-check/browser-verify are the only judges
 4. **Confirm before assume** — Search the code before marking "missing"
 5. **Complete implementations** — No stubs, no placeholders
 6. **Atomic commits** — One task = one commit
 7. **Context-aware** — Checkpoint before limits, resume seamlessly
 
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `browse-fetch` | Fetch external API docs via headless Chromium (replaces context-hub) |
+| `browse-verify` | L5 browser verification — Playwright a11y tree assertions |
+| `atomic-commits` | One logical change per commit |
+| `code-completeness` | Find TODOs, stubs, and missing implementations |
+| `gap-discovery` | Surface missing requirements during ideation |
+
 ## More
 
 - [Concepts](docs/concepts.md) — Philosophy and flow in depth

package/bin/install.js

@@ -184,7 +184,7 @@ async function main() {
   console.log('');
   console.log(`Installed to ${c.cyan}${CLAUDE_DIR}${c.reset}:`);
   console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:auto, /df:note, /df:resume, /df:update');
-  console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, context-hub');
+  console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, browse-fetch, browse-verify');
   console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker, invariant checker');
@@ -469,7 +469,8 @@ async function uninstall() {
     'skills/atomic-commits',
     'skills/code-completeness',
     'skills/gap-discovery',
-    'skills/context-hub',
+    'skills/browse-fetch',
+    'skills/browse-verify',
     'agents/reasoner.md'
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.79",
+  "version": "0.1.80",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",
@@ -39,5 +39,8 @@
   ],
   "engines": {
     "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
   }
 }

package/src/commands/df/auto-cycle.md

@@ -111,7 +111,22 @@ Read the current file first (create if missing), merge the new values, and write
 
 After `/df:execute` returns, check whether the task was reverted (ratchet failed):
 
-**On revert (ratchet failed):**
+**What counts as a failure (increments counter):**
+
+```
+- L0 ✗ (build failed)
+- L1 ✗ (files missing)
+- L2 ✗ (coverage dropped)
+- L4 ✗ (tests failed)
+- L5 ✗ (browser assertions failed — both attempts)
+- L5 ✗ (flaky) (browser assertions failed on both attempts, different assertions)
+
+What does NOT count as a failure:
+- L5 — (no frontend): skipped, not a revert trigger
+- L5 ⚠ (passed on retry): treated as pass, resets counter
+```
+
+**On revert (ratchet failed — any of L0 ✗, L1 ✗, L2 ✗, L4 ✗, L5 ✗, or L5 ✗ flaky):**
 
 ```
 1. Read .deepflow/auto-memory.yaml (create if missing)
@@ -126,7 +141,7 @@ After `/df:execute` returns, check whether the task was reverted (ratchet failed
      → Continue to step 4 (UPDATE REPORT) as normal
 ```
 
-**On success (ratchet passed):**
+**On success (ratchet passed — including L5 — no frontend or L5 ⚠ pass-on-retry):**
 
 ```
 1. Reset consecutive_reverts[task_id] to 0 in .deepflow/auto-memory.yaml

package/src/commands/df/execute.md

@@ -104,7 +104,14 @@ Before spawning: `TaskUpdate(taskId: native_id, status: "in_progress")` — acti
 
 **NEVER use `isolation: "worktree"` on Task calls.** Deepflow manages a shared worktree so wave 2 sees wave 1 commits.
 
-**Spawn ALL ready tasks in ONE message.** Same-file conflicts: spawn sequentially.
+**Spawn ALL ready tasks in ONE message** — EXCEPT file conflicts (see below).
+
+**File conflict enforcement (1 file = 1 writer):**
+Before spawning, check `Files:` lists of all ready tasks. If two+ ready tasks share a file:
+1. Sort conflicting tasks by task number (T1 < T2 < T3)
+2. Spawn only the lowest-numbered task from each conflict group
+3. Remaining tasks stay `pending` — they become ready once the spawned task completes
+4. Log: `"⏳ T{N} deferred — file conflict with T{M} on {filename}"`
 
 **≥2 [SPIKE] tasks for same problem:** Follow Parallel Spike Probes (section 5.7).
 
@@ -138,7 +145,7 @@ Ratchet uses ONLY pre-existing test files from `.deepflow/auto-snapshot.txt`.
 Trigger: ≥2 [SPIKE] tasks with same "Blocked by:" target or identical hypothesis.
 
 1. **Baseline:** Record `BASELINE=$(git rev-parse HEAD)` in shared worktree
-2. **Sub-worktrees:** Per spike: `git worktree add -b df/{spec}/probe-{SPIKE_ID} .deepflow/worktrees/{spec}/probe-{SPIKE_ID} ${BASELINE}`
+2. **Sub-worktrees:** Per spike: `git worktree add -b df/{spec}--probe-{SPIKE_ID} .deepflow/worktrees/{spec}/probe-{SPIKE_ID} ${BASELINE}`
 3. **Spawn:** All probes in ONE message, each targeting its probe worktree. End turn.
 4. **Ratchet:** Per notification, run standard ratchet (5.5) in probe worktree. Record: ratchet_passed, regressions, coverage_delta, files_changed, commit
 5. **Select winner** (after ALL complete, no LLM judge):
@@ -157,7 +164,7 @@ Trigger: ≥2 [SPIKE] tasks with same "Blocked by:" target or identical hypothes
        failure_reason: "{first failed check + error summary}"
        ratchet_metrics: {regressions: N, coverage_delta: N, files_changed: N}
        worktree: ".deepflow/worktrees/{spec}/probe-SPIKE_B-failed"
-       branch: "df/{spec}/probe-SPIKE_B-failed"
+       branch: "df/{spec}--probe-SPIKE_B-failed"
    probe_learnings:  # read by /df:auto-cycle each start
      - spike: "SPIKE_B"
        probe: "probe-SPIKE_B"
@@ -252,7 +259,7 @@ When all tasks done for a `doing-*` spec:
 ## Skills & Agents
 
 - Skill: `atomic-commits` — Clean commit protocol
-- Skill: `context-hub` — Fetch external API docs before coding
+- Skill: `browse-fetch` — Fetch live web pages and external API docs via browser before coding
 
 | Agent | subagent_type | Purpose |
 |-------|---------------|---------|

package/src/commands/df/plan.md

@@ -99,6 +99,34 @@ For each file in a task's "Files:" list, find the full blast radius.
 Files outside original "Files:" → add with `(impact — verify/update)`.
 Skip for spike tasks.
 
+### 4.6. CROSS-TASK FILE CONFLICT DETECTION
+
+After all tasks have their `Files:` lists, detect overlaps that require sequential execution.
+
+**Algorithm:**
+1. Build a map: `file → [task IDs that list it]`
+2. For each file with >1 task: add `Blocked by` edge from later task → earlier task (by task number)
+3. If a dependency already exists (direct or transitive), skip (no redundant edges)
+
+**Example:**
+```
+T1: Files: config.go, feature.go  — Blocked by: none
+T3: Files: config.go              — Blocked by: none
+T5: Files: config.go              — Blocked by: none
+```
+After conflict detection:
+```
+T1: Blocked by: none
+T3: Blocked by: T1 (file conflict: config.go)
+T5: Blocked by: T3 (file conflict: config.go)
+```
+
+**Rules:**
+- Only add the minimum edges needed (chain, not full mesh — T5 blocks on T3, not T1+T3)
+- Append `(file conflict: {filename})` to the Blocked by reason for traceability
+- If a logical dependency already covers the ordering, don't add a redundant conflict edge
+- Cross-spec conflicts: tasks from different specs sharing files get the same treatment
+
 ### 5. COMPARE & PRIORITIZE
 
 Spawn `Task(subagent_type="reasoner", model="opus")`. Map each requirement to DONE / PARTIAL / MISSING / CONFLICT. Check REQ-AC alignment. Flag spec gaps.

package/src/commands/df/verify.md

@@ -131,16 +131,444 @@ Run AFTER L0 passes and L1-L2 complete. Run even if L1-L2 found issues.
 **Flaky test handling** (if `quality.test_retry_on_fail: true` in config):
 - Re-run ONCE on failure. Second pass → "⚠ L4: Passed on retry (possible flaky test)". Second fail → genuine failure.
 
+**L5: Browser Verification** (if frontend detected)
+
+**Step 1: Detect frontend framework** (config override always wins):
+
+```bash
+BROWSER_VERIFY=$(yq '.quality.browser_verify' .deepflow/config.yaml 2>/dev/null)
+
+if [ "${BROWSER_VERIFY}" = "false" ]; then
+  # Explicitly disabled — skip L5 unconditionally
+  echo "L5 — (no frontend)"
+  L5_RESULT="skipped-no-frontend"
+elif [ "${BROWSER_VERIFY}" = "true" ]; then
+  # Explicitly enabled — proceed even without frontend deps
+  FRONTEND_DETECTED=true
+  FRONTEND_FRAMEWORK="configured"
+else
+  # Auto-detect from package.json (both dependencies and devDependencies)
+  FRONTEND_DETECTED=false
+  FRONTEND_FRAMEWORK=""
+
+  if [ -f package.json ]; then
+    # Check for React / Next.js
+    if jq -e '(.dependencies + (.devDependencies // {})) | keys[] | select(. == "react" or . == "react-dom" or . == "next")' package.json >/dev/null 2>&1; then
+      FRONTEND_DETECTED=true
+      # Prefer Next.js label when next is present
+      if jq -e '(.dependencies + (.devDependencies // {}))["next"]' package.json >/dev/null 2>&1; then
+        FRONTEND_FRAMEWORK="Next.js"
+      else
+        FRONTEND_FRAMEWORK="React"
+      fi
+    # Check for Nuxt / Vue
+    elif jq -e '(.dependencies + (.devDependencies // {})) | keys[] | select(. == "vue" or . == "nuxt" or startswith("@vue/"))' package.json >/dev/null 2>&1; then
+      FRONTEND_DETECTED=true
+      if jq -e '(.dependencies + (.devDependencies // {}))["nuxt"]' package.json >/dev/null 2>&1; then
+        FRONTEND_FRAMEWORK="Nuxt"
+      else
+        FRONTEND_FRAMEWORK="Vue"
+      fi
+    # Check for Svelte / SvelteKit
+    elif jq -e '(.dependencies + (.devDependencies // {})) | keys[] | select(. == "svelte" or startswith("@sveltejs/"))' package.json >/dev/null 2>&1; then
+      FRONTEND_DETECTED=true
+      if jq -e '(.dependencies + (.devDependencies // {}))["@sveltejs/kit"]' package.json >/dev/null 2>&1; then
+        FRONTEND_FRAMEWORK="SvelteKit"
+      else
+        FRONTEND_FRAMEWORK="Svelte"
+      fi
+    fi
+  fi
+
+  if [ "${FRONTEND_DETECTED}" = "false" ]; then
+    echo "L5 — (no frontend)"
+    L5_RESULT="skipped-no-frontend"
+  fi
+fi
+```
+
+Packages checked in both `dependencies` and `devDependencies`:
+
+| Package(s) | Detected Framework |
+|------------|--------------------|
+| `next` | Next.js |
+| `react`, `react-dom` | React |
+| `nuxt` | Nuxt |
+| `vue`, `@vue/*` | Vue |
+| `@sveltejs/kit` | SvelteKit |
+| `svelte`, `@sveltejs/*` | Svelte |
+
+Config key `quality.browser_verify`:
+- `false` → always skip L5, output `L5 — (no frontend)`, even if frontend deps are present
+- `true` → always run L5, even if no frontend deps detected
+- absent → auto-detect from package.json as above
+
+No frontend deps found and `quality.browser_verify` not set → output `L5 — (no frontend)`, skip all remaining L5 steps.
+
+**Step 2: Dev server lifecycle**
+
+**2a. Resolve dev command** (config override always wins):
+
+```bash
+# 1. Config override
+DEV_COMMAND=$(yq '.quality.dev_command' .deepflow/config.yaml 2>/dev/null)
+
+# 2. Auto-detect from package.json scripts.dev
+if [ -z "${DEV_COMMAND}" ] || [ "${DEV_COMMAND}" = "null" ]; then
+  if [ -f package.json ] && jq -e '.scripts.dev' package.json >/dev/null 2>&1; then
+    DEV_COMMAND="npm run dev"
+  fi
+fi
+
+# 3. No dev command found → skip L5 dev server steps
+if [ -z "${DEV_COMMAND}" ]; then
+  echo "⚠ L5: No dev command found (scripts.dev not in package.json, quality.dev_command not set). Skipping browser check."
+  L5_RESULT="skipped-no-dev-command"
+fi
+```
+
+**2b. Resolve port:**
+
+```bash
+# Config override wins; fallback to 3000
+DEV_PORT=$(yq '.quality.dev_port' .deepflow/config.yaml 2>/dev/null)
+if [ -z "${DEV_PORT}" ] || [ "${DEV_PORT}" = "null" ]; then
+  DEV_PORT=3000
+fi
+```
+
+**2c. Check if dev server is already running (port already bound):**
+
+```bash
+PORT_IN_USE=false
+if curl -s -o /dev/null -w "%{http_code}" "http://localhost:${DEV_PORT}" | grep -q "200"; then
+  PORT_IN_USE=true
+  echo "ℹ L5: Port ${DEV_PORT} already bound — using existing dev server, will not kill on exit."
+fi
+```
+
+**2d. Start dev server and poll for readiness:**
+
+```bash
+DEV_SERVER_PID=""
+if [ "${PORT_IN_USE}" = "false" ]; then
+  # Start in a new process group so all child processes can be killed together
+  setsid ${DEV_COMMAND} &
+  DEV_SERVER_PID=$!
+fi
+
+# Resolve timeout from config (default 30s)
+TIMEOUT=$(yq '.quality.browser_timeout' .deepflow/config.yaml 2>/dev/null)
+if [ -z "${TIMEOUT}" ] || [ "${TIMEOUT}" = "null" ]; then
+  TIMEOUT=30
+fi
+POLL_INTERVAL=0.5
+MAX_POLLS=$(echo "${TIMEOUT} / ${POLL_INTERVAL}" | bc)
+
+HTTP_STATUS=""
+for i in $(seq 1 ${MAX_POLLS}); do
+  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${DEV_PORT}" 2>/dev/null)
+  [ "${HTTP_STATUS}" = "200" ] && break
+  sleep ${POLL_INTERVAL}
+done
+
+if [ "${HTTP_STATUS}" != "200" ]; then
+  # Kill process group before reporting failure
+  if [ -n "${DEV_SERVER_PID}" ]; then
+    kill -SIGTERM -${DEV_SERVER_PID} 2>/dev/null
+  fi
+  echo "✗ L5 FAIL: dev server did not start within ${TIMEOUT}s"
+  # add fix task to PLAN.md
+  exit 1
+fi
+```
+
+**2e. Teardown — always runs on both pass and fail paths:**
+
+```bash
+cleanup_dev_server() {
+  if [ -n "${DEV_SERVER_PID}" ]; then
+    # Kill the entire process group to catch any child processes spawned by the dev server
+    kill -SIGTERM -${DEV_SERVER_PID} 2>/dev/null
+    # Give it up to 5s to exit cleanly, then force-kill
+    for i in $(seq 1 10); do
+      kill -0 ${DEV_SERVER_PID} 2>/dev/null || break
+      sleep 0.5
+    done
+    kill -SIGKILL -${DEV_SERVER_PID} 2>/dev/null || true
+  fi
+}
+# Register cleanup for both success and failure paths
+trap cleanup_dev_server EXIT
+```
+
+Note: When `PORT_IN_USE=true` (dev server was already running before L5 began), `DEV_SERVER_PID` is empty and `cleanup_dev_server` is a no-op — the pre-existing server is left running.
+
+**Step 3: Read assertions from PLAN.md**
+
+Assertions are written into PLAN.md at plan-time (REQ-8). Extract them for the current spec:
+
+```bash
+# Parse structured browser assertions block from PLAN.md
+# Format expected in PLAN.md under each spec section:
+# browser_assertions:
+#   - selector: "nav"
+#     role: "navigation"
+#     name: "Main navigation"
+#   - selector: "button[type=submit]"
+#     visible: true
+#     text: "Submit"
+ASSERTIONS=$(parse_yaml_block "browser_assertions" PLAN.md)
+```
+
+If no `browser_assertions` block found for the spec → L5 — (no assertions), skip Playwright step.
+
+**Step 3.5: Playwright browser auto-install**
+
+Before launching Playwright, verify the Chromium browser binary is available. Run this check once per session; cache the result to avoid repeated installs.
+
+```bash
+# Marker file path — presence means Playwright Chromium was verified this session
+PW_MARKER="${TMPDIR:-/tmp}/.deepflow-pw-chromium-ok"
+
+if [ ! -f "${PW_MARKER}" ]; then
+  # Dry-run to detect whether the browser binary is already installed
+  if ! npx --yes playwright install --dry-run chromium 2>&1 | grep -q "chromium.*already installed"; then
+    echo "ℹ L5: Playwright Chromium not found — installing (one-time setup)..."
+    if npx --yes playwright install chromium 2>&1; then
+      echo "✓ L5: Playwright Chromium installed successfully."
+      touch "${PW_MARKER}"
+    else
+      echo "✗ L5 FAIL: Playwright Chromium install failed. Browser verification skipped."
+      L5_RESULT="skipped-install-failed"
+      # Skip the remaining L5 steps for this run
+    fi
+  else
+    # Already installed — cache for this session
+    touch "${PW_MARKER}"
+  fi
+fi
+
+# If install failed, skip Playwright launch and jump to L5 outcome reporting
+if [ "${L5_RESULT}" = "skipped-install-failed" ]; then
+  # No assertions can be evaluated — treat as a non-blocking skip with error notice
+  : # fall through to report section
+fi
+```
+
+Skip Steps 4–6 when `L5_RESULT="skipped-install-failed"`.
+
+**Step 4: Playwright verification**
+
+Launch Chromium headlessly via Playwright and evaluate each assertion deterministically — no LLM judgment:
+
+```javascript
+const { chromium } = require('playwright');
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage();
+await page.goto('http://localhost:3000');
+
+const failures = [];
+
+for (const assertion of assertions) {
+  const locator = page.locator(assertion.selector);
+
+  // Capture accessibility tree (replaces deprecated page.accessibility.snapshot())
+  // locator.ariaSnapshot() returns YAML-like text with roles, names, hierarchy
+  const ariaSnapshot = await locator.ariaSnapshot();
+
+  if (assertion.role && !ariaSnapshot.includes(`role: ${assertion.role}`)) {
+    failures.push(`${assertion.selector}: expected role "${assertion.role}", not found in aria snapshot`);
+  }
+  if (assertion.name && !ariaSnapshot.includes(assertion.name)) {
+    failures.push(`${assertion.selector}: expected name "${assertion.name}", not found in aria snapshot`);
+  }
+
+  // Capture bounding boxes for visible assertions
+  if (assertion.visible !== undefined) {
+    const box = await locator.boundingBox();
+    const isVisible = box !== null && box.width > 0 && box.height > 0;
+    if (assertion.visible !== isVisible) {
+      failures.push(`${assertion.selector}: expected visible=${assertion.visible}, got visible=${isVisible}`);
+    }
+  }
+
+  if (assertion.text) {
+    const text = await locator.innerText();
+    if (!text.includes(assertion.text)) {
+      failures.push(`${assertion.selector}: expected text "${assertion.text}", got "${text}"`);
+    }
+  }
+}
+```
+
+Note: `page.accessibility.snapshot()` was removed in Playwright 1.x. Always use `locator.ariaSnapshot()`, which returns YAML-like text describing roles, names, and hierarchy for the matched element subtree.
+
+**Step 5: Screenshot capture**
+
+After evaluation (pass or fail), capture a full-page screenshot:
+
+```javascript
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const specName = 'doing-upload'; // derived from current spec filename
+const screenshotPath = `.deepflow/screenshots/${specName}/${timestamp}.png`;
+await fs.mkdirSync(path.dirname(screenshotPath), { recursive: true });
+await page.screenshot({ path: screenshotPath, fullPage: true });
+```
+
+Screenshot path: `.deepflow/screenshots/{spec-name}/{timestamp}.png`
+
+**Step 6: Retry logic**
+
+On first failure, retry the FULL L5 check once (total 2 attempts). Re-navigate and re-evaluate all assertions from scratch on the retry:
+
+```javascript
+// attempt1_failures populated by Step 4 above
+let attempt2_failures = [];
+
+if (attempt1_failures.length > 0) {
+  // Retry: re-navigate and re-evaluate all assertions (identical logic to Step 4)
+  await page.goto('http://localhost:' + DEV_PORT);
+  attempt2_failures = await evaluateAssertions(page, assertions); // same loop as Step 4
+
+  // Capture a second screenshot for the retry attempt
+  const retryTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const retryScreenshotPath = `.deepflow/screenshots/${specName}/${retryTimestamp}-retry.png`;
+  await page.screenshot({ path: retryScreenshotPath, fullPage: true });
+}
+```
+
+**Outcome matrix:**
+
+| Attempt 1 | Attempt 2 | Result |
+|-----------|-----------|--------|
+| Pass | — (not run) | L5 ✓ |
+| Fail | Pass | L5 ✓ with warning "(passed on retry)" |
+| Fail | Fail — same assertions | L5 ✗ — genuine failure |
+| Fail | Fail — different assertions | L5 ✗ (flaky) |
+
+**Outcome reporting:**
+
+- **First attempt passes:** `✓ L5: All assertions passed` — no retry needed.
+
+- **First fails, retry passes:**
+  ```
+  ⚠ L5: Passed on retry (possible flaky render)
+    First attempt failed on: {list of assertion selectors from attempt 1}
+  ```
+  → L5 pass with warning. No fix task added.
+
+- **Both fail on SAME assertions** (identical set of failing selectors):
+  ```
+  ✗ L5: Browser assertions failed (both attempts)
+    {selector}: {failure detail}
+    {selector}: {failure detail}
+    ...
+  ```
+  → L5 FAIL. Add fix task to PLAN.md.
+
+- **Both fail on DIFFERENT assertions** (flaky — assertion sets differ between attempts):
+  ```
+  ✗ L5: Browser assertions failed (flaky — inconsistent failures across attempts)
+    Attempt 1 failures:
+      {selector}: {failure detail}
+    Attempt 2 failures:
+      {selector}: {failure detail}
+  ```
+  → L5 ✗ (flaky). Add fix task to PLAN.md noting flakiness.
+
+**Fix task generation on L5 failure (both same and flaky):**
+
+When both attempts fail (`L5_RESULT = 'fail'` or `L5_RESULT = 'fail-flaky'`), generate a fix task and append it to PLAN.md under the spec's section:
+
+```javascript
+// 1. Determine next task ID
+// Scan PLAN.md for highest T{n} and increment
+const planContent = fs.readFileSync('PLAN.md', 'utf8');
+const taskIds = [...planContent.matchAll(/\bT(\d+)\b/g)].map(m => parseInt(m[1], 10));
+const nextId = taskIds.length > 0 ? Math.max(...taskIds) + 1 : 1;
+const taskId = `T${nextId}`;
+
+// 2. Collect fix task context
+// - Failing assertions: the structured assertion objects that failed
+const failingAssertions = attempt2_failures.length > 0 ? attempt2_failures : attempt1_failures;
+
+// - DOM snapshot excerpt: capture aria snapshot of body at the time of failure
+const domSnapshotExcerpt = await page.locator('body').ariaSnapshot();
+
+// - Screenshot path: already captured in Step 5 / Step 6 retry
+// screenshotPath / retryScreenshotPath are available from those steps
+
+// 3. Build task description
+const isFlaky = L5_RESULT === 'fail-flaky';
+const flakySuffix = isFlaky ? ' (flaky — inconsistent failures across attempts)' : '';
+const screenshotRef = isFlaky ? retryScreenshotPath : screenshotPath;
+
+const fixTaskBlock = `
+- [ ] ${taskId}: Fix L5 browser assertion failures in ${specName}${flakySuffix}
+  **Failing assertions:**
+${failingAssertions.map(f => `    - ${f}`).join('\n')}
+  **DOM snapshot (aria tree excerpt at failure):**
+  \`\`\`
+${domSnapshotExcerpt.split('\n').slice(0, 40).join('\n')}
+  \`\`\`
+  **Screenshot:** ${screenshotRef}
+`;
+
+// 4. Append fix task under spec section in PLAN.md
+// Find the spec section and append before the next section header or EOF
+const specSectionPattern = new RegExp(`(## ${specName}[\\s\\S]*?)(\n## |$)`);
+const updated = planContent.replace(specSectionPattern, (_, section, next) => section + fixTaskBlock + next);
+fs.writeFileSync('PLAN.md', updated);
+
+console.log(`Fix task added to PLAN.md: ${taskId}: Fix L5 browser assertion failures in ${specName}`);
+```
+
+Fix task context included:
+- **Failing assertions**: the structured assertion data (selector + failure detail) from whichever attempt(s) failed
+- **DOM snapshot excerpt**: first 40 lines of `locator('body').ariaSnapshot()` output at time of failure (textual a11y tree)
+- **Screenshot path**: `.deepflow/screenshots/{spec-name}/{timestamp}.png` (retry screenshot when available)
+- **Flakiness note**: appended to task title when assertion sets differed between attempts
+
+**Comparing assertion sets (same vs. different):**
+
+```javascript
+// Compare by selector strings only — ignore detail text differences
+const attempt1_selectors = attempt1_failures.map(f => f.split(':')[0]).sort();
+const attempt2_selectors = attempt2_failures.map(f => f.split(':')[0]).sort();
+const same_assertions = JSON.stringify(attempt1_selectors) === JSON.stringify(attempt2_selectors);
+
+if (attempt2_failures.length === 0) {
+  // Retry passed
+  L5_RESULT = 'pass-on-retry';
+} else if (same_assertions) {
+  // Genuine failure — same assertions failed both times
+  L5_RESULT = 'fail';
+} else {
+  // Flaky — different assertions failed each time
+  L5_RESULT = 'fail-flaky';
+}
+```
+
+**L5 outcomes:**
+- L5 ✓ — all assertions pass on first attempt
+- L5 ⚠ — passed on retry (possible flaky render); first-attempt failures listed as context
+- L5 ✗ — assertions failed on both attempts (same assertions), fix tasks added
+- L5 ✗ (flaky) — assertions failed on both attempts but on different assertions; fix tasks added noting flakiness
+- L5 — (no frontend) — no frontend deps detected and no config override
+- L5 — (no assertions) — frontend detected but no `browser_assertions` in PLAN.md
+- L5 ✗ (install failed) — Playwright Chromium install failed; browser verification skipped for this run
+
 ### 3. GENERATE REPORT
 
 **Format on success:**
 ```
-doing-upload.md: L0 ✓ | L1 ✓ (5/5 files) | L2 ⚠ (no coverage tool) | L3 — (subsumed) | L4 ✓ (12 tests) | 0 quality issues
+doing-upload.md: L0 ✓ | L1 ✓ (5/5 files) | L2 ⚠ (no coverage tool) | L3 — (subsumed) | L4 ✓ (12 tests) | L5 ✓ | 0 quality issues
 ```
 
 **Format on failure:**
 ```
-doing-upload.md: L0 ✓ | L1 ✗ (3/5 files) | L2 ⚠ | L3 — | L4 ✗ (3 failed)
+doing-upload.md: L0 ✓ | L1 ✗ (3/5 files) | L2 ⚠ | L3 — | L4 ✗ (3 failed) | L5 ✗ (2 assertions failed)
 
 Issues:
   ✗ L1: Missing files: src/api/upload.ts, src/services/storage.ts
@@ -160,6 +588,7 @@ Run /df:execute --continue to fix in the same worktree.
 - L1: All planned files appear in diff
 - L2: Coverage didn't drop (or no coverage tool detected)
 - L4: Tests pass (or no test command detected)
+- L5: Browser assertions pass (or no frontend detected, or no assertions defined)
 
 **If all gates pass:** Proceed to Post-Verification merge.
 
@@ -192,8 +621,9 @@ Files: ...
 | L2: Coverage | Coverage didn't drop | Coverage tool (before/after) | Orchestrator (Bash) |
 | L3: Integration | Build + tests pass | Subsumed by L0 + L4 | — |
 | L4: Tested | Tests pass | Run test command | Orchestrator (Bash) |
+| L5: Browser | UI assertions pass | Playwright + `locator.ariaSnapshot()` | Orchestrator (Bash + Node) |
 
-**Default: L0 through L4.** L0 and L4 skipped ONLY if no build/test command detected (see step 1.5). All checks are machine-verifiable. No LLM agents are used.
+**Default: L0 through L5.** L0 and L4 skipped ONLY if no build/test command detected (see step 1.5). L5 skipped if no frontend detected and no config override. All checks are machine-verifiable. No LLM agents are used.
 
 ## Rules
 - Verify against spec, not assumptions

package/src/skills/browse-fetch/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: browse-fetch
+description: Fetches live web content using headless Chromium via Playwright. Use when you need to read documentation, articles, or any public URL that requires JavaScript rendering. Falls back to WebFetch for simple HTML pages.
+---
+
+# Browse-Fetch
+
+Retrieve live web content with a headless browser. Handles JavaScript-rendered pages, SPAs, and dynamic content that WebFetch cannot reach.
+
+## When to Use
+
+- Reading documentation sites that require JavaScript to render (e.g., React-based docs, Vite, Next.js portals)
+- Fetching the current content of a specific URL provided by the user
+- Extracting article or reference content from a known page before implementing code against it
+
+## Skip When
+
+- The URL is a plain HTML page or GitHub raw file — use WebFetch instead (faster, no overhead)
+- The target requires authentication (login wall) or CAPTCHA — browser cannot bypass; note the block and continue
+
+---
+
+## Browser Core Protocol
+
+This protocol is the reusable foundation for all browser-based skills (browse-fetch, browse-verify, etc.).
+
+### 1. Install Check
+
+Before launching, verify Playwright is available:
+
+```bash
+# Prefer bun if available, fall back to node
+if which bun > /dev/null 2>&1; then RUNTIME=bun; else RUNTIME=node; fi
+
+$RUNTIME -e "require('playwright')" 2>/dev/null \
+  || npx --yes playwright install chromium --with-deps 2>&1 | tail -5
+```
+
+If installation fails, fall back to WebFetch (see Fallback section below).
+
+### 2. Launch Command
+
+```bash
+# Detect runtime
+if which bun > /dev/null 2>&1; then RUNTIME=bun; else RUNTIME=node; fi
+
+$RUNTIME -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+  });
+  const page = await context.newPage();
+
+  // --- navigation + extraction (see sections 3–4) ---
+
+  await browser.close();
+})().catch(e => { console.error(e.message); process.exit(1); });
+"
+```
+
+### 3. Navigation
+
+```js
+// Inside the async IIFE above
+await page.goto(URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
+// Allow JS to settle
+await page.waitForTimeout(1500);
+```
+
+- Use `waitUntil: 'domcontentloaded'` for speed; upgrade to `'networkidle'` only if content is missing.
+- Set `timeout: 30000` (30 s). On timeout, treat as graceful failure (see section 5).
+
+### 4. Content Extraction
+
+Extract the main readable text, not raw HTML:
+
+```js
+// Primary: semantic content containers
+let text = await page.innerText('main, article, [role="main"]').catch(() => '');
+
+// Fallback: full body text
+if (!text || text.trim().length < 100) {
+  text = await page.innerText('body').catch(() => '');
+}
+
+// Truncate to ~4000 tokens (~16000 chars) to stay within context budget
+const MAX_CHARS = 16000;
+if (text.length > MAX_CHARS) {
+  text = text.slice(0, MAX_CHARS) + '\n\n[content truncated — use a more specific selector or paginate]';
+}
+
+console.log(text);
+```
+
+For interactive element inspection (e.g., browse-verify), use `locator.ariaSnapshot()` instead of `innerText`.
+
+### 5. Graceful Failure
+
+Detect and handle blocks without crashing:
+
+```js
+const title = await page.title();
+const url   = page.url();
+
+// Login wall
+if (/sign.?in|log.?in|auth/i.test(title) || url.includes('/login')) {
+  console.log(`[browse-fetch] Blocked by login wall at ${url}. Skipping.`);
+  await browser.close();
+  process.exit(0);
+}
+
+// CAPTCHA
+const bodyText = await page.innerText('body').catch(() => '');
+if (/captcha|robot|human verification/i.test(bodyText)) {
+  console.log(`[browse-fetch] CAPTCHA detected at ${url}. Skipping.`);
+  await browser.close();
+  process.exit(0);
+}
+```
+
+On graceful failure: return the URL and a short explanation, then continue with the task using available context.
+
+### 6. Cleanup
+
+Always close the browser in a `finally` block or after use:
+
+```js
+await browser.close();
+```
+
+---
+
+## Fetch Workflow
+
+**Goal:** retrieve and return the text content of a single URL.
+
+```bash
+# Full inline script — adapt URL and selector per query
+if which bun > /dev/null 2>&1; then RUNTIME=bun; else RUNTIME=node; fi
+
+$RUNTIME -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+  });
+  const page = await context.newPage();
+
+  try {
+    await page.goto('https://example.com/docs/page', {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000
+    });
+    await page.waitForTimeout(1500);
+
+    const title = await page.title();
+    const url   = page.url();
+
+    if (/sign.?in|log.?in|auth/i.test(title) || url.includes('/login')) {
+      console.log('[browse-fetch] Blocked by login wall at ' + url);
+      return;
+    }
+
+    let text = await page.innerText('main, article, [role=\"main\"]').catch(() => '');
+    if (!text || text.trim().length < 100) {
+      text = await page.innerText('body').catch(() => '');
+    }
+
+    const MAX_CHARS = 16000;
+    if (text.length > MAX_CHARS) {
+      text = text.slice(0, MAX_CHARS) + '\n\n[content truncated]';
+    }
+
+    console.log('=== ' + title + ' ===\n' + text);
+  } finally {
+    await browser.close();
+  }
+})().catch(e => { console.error(e.message); process.exit(1); });
+"
+```
+
+Adapt the URL and selector per query. The agent inlines the full script via `node -e` or `bun -e` so no temp files are needed for extractions under ~4000 tokens.
+
+---
+
+## Search + Navigation Protocol
+
+**Time-box:** 60 seconds total. **Page cap:** 5 pages per query.
+
+> Search engines (Google, DuckDuckGo) block headless browsers with CAPTCHAs. Do NOT use Playwright to search them.
+
+Instead, use one of these strategies:
+
+| Strategy | When to use |
+|----------|-------------|
+| Direct URL construction | You know the domain (e.g., `docs.stripe.com/api/charges`) |
+| WebSearch tool | General keyword search before fetching pages |
+| Site-specific search | Navigate to `site.com/search?q=term` if the site exposes it |
+
+**Navigation loop** (up to 5 pages):
+
+1. Construct or obtain the target URL.
+2. Run the fetch workflow above.
+3. If the page lacks the needed information, look for a next-page link or a more specific sub-URL.
+4. Repeat up to 4 more times (5 total).
+5. Stop and summarize what was found within the 60 s window.
+
+---
+
+## Session Cache
+
+The context window is the cache. Extracted content lives in the conversation until it is no longer needed.
+
+For extractions larger than ~4000 tokens, write to a temp file and reference it:
+
+```bash
+# Write large extraction to temp file
+TMPFILE=$(mktemp /tmp/browse-fetch-XXXXXX.txt)
+$RUNTIME -e "...script..." > "$TMPFILE"
+echo "Content saved to $TMPFILE"
+# Read relevant sections with grep or head rather than loading all at once
+```
+
+---
+
+## Fallback Without Playwright
+
+When Playwright is unavailable or fails to install, fall back to the WebFetch tool for:
+
+- Static HTML sites (GitHub README, raw docs, Wikipedia)
+- Any URL the user provides where JavaScript rendering is not required
+
+| Condition | Action |
+|-----------|--------|
+| `playwright` not installed, install fails | Use WebFetch |
+| Page is a known static domain (github.com/raw, pastebin, etc.) | Use WebFetch directly — skip Playwright |
+| Playwright times out twice | Use WebFetch as fallback attempt |
+
+```
+WebFetch: { url: "https://example.com/page", prompt: "Extract the main content" }
+```
+
+If WebFetch also fails, return the URL with an explanation and continue the task.
+
+---
+
+## Rules
+
+- Always run the install check before the first browser launch in a session.
+- Detect runtime with `which bun` first; use `node` if bun is absent.
+- Never navigate to Google or DuckDuckGo with Playwright — use WebSearch tool or direct URLs.
+- Truncate output at ~4000 tokens (~16 000 chars) to protect context budget.
+- On login wall or CAPTCHA, log the block, skip, and continue — never retry infinitely.
+- Close the browser in every code path (use `finally`).
+- Do not persist browser sessions across unrelated tasks.

package/src/skills/browse-verify/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: browse-verify
+description: Verifies UI acceptance criteria by launching a headless browser, extracting the accessibility tree, and evaluating structured assertions deterministically. Use when a spec has browser-based ACs that need automated verification after implementation.
+---
+
+# Browse-Verify
+
+Headless browser verification using Playwright's accessibility tree. Evaluates structured assertions from PLAN.md without LLM calls — purely deterministic matching.
+
+## When to Use
+
+After implementing a spec that contains browser-based acceptance criteria:
+- Visual/layout checks (element presence, text content, roles)
+- Interactive state checks (aria-checked, aria-expanded, aria-disabled)
+- Structural checks (element within a container)
+
+**Skip when:** The spec has no browser-facing ACs, or the implementation is backend-only.
+
+## Prerequisites
+
+- Node.js (preferred) or Bun
+- Playwright 1.x (`npm install playwright` or `npx playwright install`)
+- Chromium browser (auto-installed if missing)
+
+## Runtime Detection
+
+```bash
+# Prefer Node.js; fall back to Bun
+if which node > /dev/null 2>&1; then
+  RUNTIME=node
+elif which bun > /dev/null 2>&1; then
+  RUNTIME=bun
+else
+  echo "Error: neither node nor bun found" && exit 1
+fi
+```
+
+## Browser Auto-Install
+
+Before running, ensure Chromium is available:
+
+```bash
+npx playwright install chromium
+```
+
+Run this once per environment. If it fails due to permissions, instruct the user to run it manually.
+
+## Protocol
+
+### 1. Read Assertions from PLAN.md
+
+Assertions are written into PLAN.md by the `plan` skill during planning. Format:
+
+```yaml
+assertions:
+  - role: button
+    name: "Submit"
+    check: visible
+  - role: checkbox
+    name: "Accept terms"
+    check: state
+    value: checked
+  - role: heading
+    name: "Dashboard"
+    check: visible
+    within: main
+  - role: textbox
+    name: "Email"
+    check: value
+    value: "user@example.com"
+```
+
+Assertion schema:
+
+| Field    | Required | Description |
+|----------|----------|-------------|
+| `role`   | yes      | ARIA role (button, checkbox, heading, textbox, link, etc.) |
+| `name`   | yes      | Accessible name (exact or partial match) |
+| `check`  | yes      | One of: `visible`, `absent`, `state`, `value`, `count` |
+| `value`  | no       | Expected value for `state` or `value` checks |
+| `within` | no       | Ancestor role or selector to scope the search |
+
+### 2. Launch Browser and Navigate
+
+```javascript
+const { chromium } = require('playwright');
+
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage();
+
+await page.goto(TARGET_URL, { waitUntil: 'networkidle' });
+```
+
+`TARGET_URL` is read from the spec's metadata or passed as an argument.
+
+### 3. Extract Accessibility Tree
+
+Use `locator.ariaSnapshot()` — **NOT** `page.accessibility.snapshot()` (removed in Playwright 1.x):
+
+```javascript
+// Full-page aria snapshot (YAML-like role tree)
+const snapshot = await page.locator('body').ariaSnapshot();
+
+// Scoped snapshot within a container
+const containerSnapshot = await page.locator('main').ariaSnapshot();
+```
+
+`ariaSnapshot()` returns a YAML-like string such as:
+
+```yaml
+- heading "Dashboard" [level=1]
+- button "Submit" [disabled]
+- checkbox "Accept terms" [checked]
+- textbox "Email": user@example.com
+```
+
+### 4. Capture Bounding Boxes (optional)
+
+For spatial/layout assertions or debugging:
+
+```javascript
+const element = page.getByRole(role, { name: assertionName });
+const box = await element.boundingBox();
+// box: { x, y, width, height } or null if not visible
+```
+
+### 5. Evaluate Assertions Deterministically
+
+Parse the aria snapshot and evaluate each assertion. No LLM calls during this phase.
+
+```javascript
+function evaluateAssertion(snapshot, assertion) {
+  const { role, name, check, value, within } = assertion;
+
+  // Optionally scope to a sub-tree
+  const tree = within
+    ? extractSubtree(snapshot, within)
+    : snapshot;
+
+  switch (check) {
+    case 'visible':
+      return treeContains(tree, role, name);
+
+    case 'absent':
+      return !treeContains(tree, role, name);
+
+    case 'state':
+      // e.g., value: "checked", "disabled", "expanded"
+      return treeContainsWithState(tree, role, name, value);
+
+    case 'value':
+      // Matches textbox/combobox displayed value
+      return treeContainsWithValue(tree, role, name, value);
+
+    case 'count':
+      return countMatches(tree, role, name) === parseInt(value, 10);
+  }
+}
+```
+
+Matching rules:
+- Role matching is case-insensitive
+- Name matching is case-insensitive substring match (unless wrapped in quotes for exact match)
+- State tokens (`[checked]`, `[disabled]`, `[expanded]`) are parsed from the snapshot line
+
+### 6. Capture Screenshot
+
+After evaluation, capture a screenshot for the audit trail:
+
+```javascript
+const screenshotDir = `.deepflow/screenshots/${specName}`;
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const screenshotPath = `${screenshotDir}/${timestamp}.png`;
+
+await fs.mkdir(screenshotDir, { recursive: true });
+await page.screenshot({ path: screenshotPath, fullPage: true });
+```
+
+Screenshot path convention: `.deepflow/screenshots/{spec-name}/{timestamp}.png`
+
+### 7. Report Results
+
+Emit a structured result for each assertion:
+
+```
+[PASS] button "Submit" — visible ✓
+[PASS] checkbox "Accept terms" — state: checked ✓
+[FAIL] heading "Dashboard" — expected visible, not found in snapshot
+[PASS] textbox "Email" — value: user@example.com ✓
+
+Results: 3 passed, 1 failed
+Screenshot: .deepflow/screenshots/login-form/2026-03-14T12-00-00-000Z.png
+```
+
+Exit with code 0 if all assertions pass, 1 if any fail.
+
+### 8. Tear Down
+
+```javascript
+await browser.close();
+```
+
+Always close the browser, even on error (use try/finally).
+
+## Full Script Template
+
+```javascript
+#!/usr/bin/env node
+const { chromium } = require('playwright');
+const fs = require('fs/promises');
+const path = require('path');
+
+async function main({ targetUrl, specName, assertions }) {
+  // Auto-install chromium if needed
+  // (handled by: npx playwright install chromium)
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+
+  try {
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+
+    const snapshot = await page.locator('body').ariaSnapshot();
+
+    const results = assertions.map(assertion => ({
+      assertion,
+      passed: evaluateAssertion(snapshot, assertion),
+    }));
+
+    // Screenshot
+    const screenshotDir = path.join('.deepflow', 'screenshots', specName);
+    await fs.mkdir(screenshotDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const screenshotPath = path.join(screenshotDir, `${timestamp}.png`);
+    await page.screenshot({ path: screenshotPath, fullPage: true });
+
+    // Report
+    const passed = results.filter(r => r.passed).length;
+    const failed = results.filter(r => !r.passed).length;
+
+    for (const { assertion, passed: ok } of results) {
+      const status = ok ? '[PASS]' : '[FAIL]';
+      console.log(`${status} ${assertion.role} "${assertion.name}" — ${assertion.check}${assertion.value ? ': ' + assertion.value : ''}`);
+    }
+
+    console.log(`\nResults: ${passed} passed, ${failed} failed`);
+    console.log(`Screenshot: ${screenshotPath}`);
+
+    process.exit(failed > 0 ? 1 : 0);
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+## Rules
+
+- Never call an LLM during the verify phase — all assertion evaluation is deterministic
+- Always use `locator.ariaSnapshot()`, never `page.accessibility.snapshot()` (removed)
+- Always close the browser in a `finally` block
+- Screenshot every run regardless of pass/fail outcome
+- If Playwright is not installed, emit a clear error and instructions — don't silently skip
+- Partial name matching is the default; use exact matching only when the assertion specifies it
+- Report results to stdout in the structured format above for downstream parsing

package/templates/config-template.yaml

@@ -75,3 +75,17 @@ quality:
 
   # Retry flaky tests once before failing (default: true)
   test_retry_on_fail: true
+
+  # Enable L5 browser verification after tests pass (default: false)
+  # When true, deepflow will start the dev server and run visual checks
+  browser_verify: false
+
+  # Override the dev server start command for browser verification
+  # If empty, deepflow will attempt to auto-detect (e.g., "npm run dev", "yarn dev")
+  dev_command: ""
+
+  # Port that the dev server listens on (default: 3000)
+  dev_port: 3000
+
+  # Timeout in seconds to wait for the dev server to become ready (default: 30)
+  browser_timeout: 30

package/src/skills/context-hub/SKILL.md

@@ -1,87 +0,0 @@
----
-name: context-hub
-description: Fetches curated API docs for external libraries before coding. Use when implementing code that uses external APIs/SDKs (Stripe, OpenAI, MongoDB, etc.) to avoid hallucinating APIs and reduce token usage.
----
-
-# Context Hub
-
-Fetch curated, versioned docs for external libraries instead of guessing APIs.
-
-## When to Use
-
-Before writing code that calls an external API or SDK:
-- New library integration (e.g., Stripe payments, AWS S3)
-- Unfamiliar API version or method
-- Complex API with many options (e.g., MongoDB aggregation)
-
-**Skip when:** Working with internal code (use LSP instead) or well-known stdlib APIs.
-
-## Prerequisites
-
-Requires `chub` CLI: `npm install -g @aisuite/chub`
-
-If `chub` is not installed, tell the user and skip — don't block implementation.
-
-## Workflow
-
-### 1. Search for docs
-
-```bash
-chub search "<library or API>" --json
-```
-
-Example:
-```bash
-chub search "stripe payments" --json
-chub search "mongodb aggregation" --json
-```
-
-### 2. Fetch relevant docs
-
-```bash
-chub get <id> --lang <py|js|ts>
-```
-
-Use `--lang` matching the project language. Use `--full` only if the summary lacks what you need.
-
-### 3. Write code using fetched docs
-
-Use the retrieved documentation as ground truth for API signatures, parameter names, and patterns.
-
-### 4. Annotate discoveries
-
-When you find something the docs missed or got wrong:
-
-```bash
-chub annotate <id> "Note: method X requires param Y since v2.0"
-```
-
-This persists locally and appears on future `chub get` calls — the agent learns across sessions.
-
-### 5. Rate docs (optional)
-
-```bash
-chub feedback <id> up --label accurate
-chub feedback <id> down --label outdated
-```
-
-Labels: `accurate`, `outdated`, `incomplete`, `wrong-version`, `helpful`
-
-## Integration with LSP
-
-| Need | Tool |
-|------|------|
-| Internal code navigation | LSP (`goToDefinition`, `findReferences`) |
-| External API signatures | Context Hub (`chub get`) |
-| Symbol search in project | LSP (`workspaceSymbol`) |
-| Library usage patterns | Context Hub (`chub search`) |
-
-**Combined approach:** Use LSP to understand how the project currently uses a library, then use Context Hub to verify correct API usage and discover better patterns.
-
-## Rules
-
-- Always search before implementing external API calls
-- Trust chub docs over training data for API specifics
-- Annotate gaps so future sessions benefit
-- Don't block on chub failures — fall back to best knowledge
-- Prefer `--json` flag for programmatic parsing in automated workflows