@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/test-browser/SKILL.md

@@ -0,0 +1,464 @@
+---
+name: test-browser
+description: "This skill should be used when running end-to-end browser tests on pages affected by a PR. Uses agent-browser CLI to map changed files to routes and capture screenshots."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Browser Test
+
+<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>
+
+> **Positioning (ADR-049, #4834):** for **structural-UI** diffs (nav/rail/dashboard shell), the *pre-merge* visual check is now the committed, CI-blocking `nav-states-*.e2e.ts` gate run by `soleur:qa` Step 2.6 — not this skill. Running `test-browser` only *after* ship is the deferral trap that let the #4810 layout bugs reach prod. Treat this skill as a **post-ship smoke** (broad page reachability + console-error sweep) that complements, never replaces, the pre-merge `soleur:qa` gate.
+
+## CRITICAL: Use agent-browser CLI Only
+
+**DO NOT use Chrome MCP tools (mcp__claude-in-chrome__*).**
+
+This skill uses the `agent-browser` CLI exclusively. The agent-browser CLI is a Bash-based tool from Vercel that runs headless Chromium. It is NOT the same as Chrome browser automation via MCP.
+
+If calling `mcp__claude-in-chrome__*` tools, STOP. Use `agent-browser` Bash commands instead.
+
+- When working in a worktree, always pass absolute paths to Playwright MCP screenshot tools -- relative filenames are resolved from the main repo root (the MCP server's CWD), so screenshots land in the main repo instead of the active worktree.
+
+## Introduction
+
+<role>QA Engineer specializing in browser-based end-to-end testing</role>
+
+This skill tests affected pages in a real browser, catching issues that unit tests miss:
+
+- JavaScript integration bugs
+- CSS/layout regressions
+- User workflow breakages
+- Console errors
+
+## Prerequisites
+
+<requirements>
+- Local development server running (e.g., `bin/dev`, `rails server`, `npm run dev`)
+- agent-browser CLI installed (see Setup below)
+- Git repository with changes to test
+</requirements>
+
+## Setup
+
+**Check installation:**
+
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+
+```bash
+npm install --prefix ~/.local -g agent-browser@0.22.3
+agent-browser install  # Downloads Chrome for Testing (~300MB)
+```
+
+**On Linux (Ubuntu 23.10+, containers, VMs), export the no-sandbox launch flag
+before the first command** — otherwise Chrome cannot launch and `open` hangs:
+
+```bash
+export AGENT_BROWSER_ARGS="--no-sandbox"
+```
+
+See the `agent-browser` skill for detailed usage and the "Chrome fails to launch
+/ `open` hangs" troubleshooting entry.
+
+## Main Tasks
+
+### 0. Verify agent-browser Installation
+
+Before starting ANY browser testing, verify agent-browser is installed:
+
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Ready" || (echo "Installing..." && npm install --prefix ~/.local -g agent-browser@0.22.3 && agent-browser install)
+```
+
+If installation fails, inform the user and stop.
+
+### 1. Ask Browser Mode
+
+<ask_browser_mode>
+
+Before starting tests, ask the user if they want to watch the browser:
+
+Use AskUserQuestion with:
+
+- Question: "Do you want to watch the browser tests run?"
+- Options:
+  1. **Headed (watch)** - Opens visible browser window so tests can be observed
+  2. **Headless (faster)** - Runs in background, faster but invisible
+
+Store the choice and use `--headed` flag when user selects "Headed".
+
+</ask_browser_mode>
+
+### 2. Determine Test Scope
+
+<test_target> $ARGUMENTS </test_target>
+
+<determine_scope>
+
+**If PR number provided:**
+
+```bash
+gh pr view [number] --json files -q '.files[].path'
+```
+
+**If 'current' or empty:**
+
+```bash
+git diff --name-only main...HEAD
+```
+
+**If branch name provided:**
+
+```bash
+git diff --name-only main...[branch]
+```
+
+</determine_scope>
+
+### 3. Map Files to Routes
+
+<file_to_route_mapping>
+
+**Repo feature map first.** When the repository carries a maintained feature
+map — convention: `docs/feature-map.md` (soleur's own lives at
+`apps/web-platform/test/feature-map.md`; the entry schema and update contract
+are in [feature-map.md](./references/feature-map.md)) — its route entries are
+the navigation source of truth: each `## \`/route\`` section names stable
+selectors, the user-POV expected outcome, auth/fixture needs, and gotchas.
+Prefer it over inferring routes from file paths; the generic table below is
+the fallback for repos without a map AND for routes a partial map does not
+cover — a map is authoritative per-route, never a reason to skip testing an
+unmapped route.
+
+Map changed files to testable routes:
+
+| File Pattern | Route(s) |
+|-------------|----------|
+| `app/views/users/*` | `/users`, `/users/:id`, `/users/new` |
+| `app/controllers/settings_controller.rb` | `/settings` |
+| `app/javascript/controllers/*_controller.js` | Pages using that Stimulus controller |
+| `app/components/*_component.rb` | Pages rendering that component |
+| `app/views/layouts/*` | All pages (test homepage at minimum) |
+| `app/assets/stylesheets/*` | Visual regression on key pages |
+| `app/helpers/*_helper.rb` | Pages using that helper |
+| `src/app/*` (Next.js) | Corresponding routes |
+| `src/components/*` | Pages using those components |
+
+Build a list of URLs to test based on the mapping.
+
+</file_to_route_mapping>
+
+### 4. Verify Server is Running
+
+<check_server>
+
+Before testing, verify the local server is accessible:
+
+### Preflight: verify the plugin install before any snapshot
+
+The redactor is reached through `${CLAUDE_PLUGIN_ROOT}`. An ambient value pointing at a
+directory that is not a Soleur install would resolve to a path that does not exist — or, worse,
+to one an attacker chose. Verify plugin IDENTITY and halt if it does not hold (ADR-179 decision 2);
+a `test -f` on the script alone is a shape check and was measured bypassable.
+
+```bash
+[ -f "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" ] \
+  && grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" \
+  || { echo "SOLEUR_SNAPSHOT_HALT reason=plugin-root-unverified root=[${CLAUDE_PLUGIN_ROOT}]" >&2
+       echo "  Cannot locate the snapshot redactor, so no accessibility snapshot may be taken here." >&2
+       echo "  Root EMPTY: no Soleur plugin is loaded in this session. Install it and start a NEW session." >&2
+       echo "  Root set but wrong: a repo checkout is not an install. Run 'claude plugin update soleur@soleur-marketplace' (or the id 'claude plugin list' prints, if you added the repository directly), then RESTART Claude Code." >&2
+       echo "  Nothing has been captured yet, so nothing has leaked." >&2
+       exit 2; }
+```
+
+```bash
+agent-browser open http://localhost:3000
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+If server is not running, inform user:
+
+```markdown
+**Server not running**
+
+Please start the development server:
+- Rails: `bin/dev` or `rails server`
+- Node/Next.js: `npm run dev`
+
+Then run `soleur:test-browser` again.
+```
+
+</check_server>
+
+### 5. Test Each Affected Page
+
+<test_pages>
+
+For each affected route, use agent-browser CLI commands (NOT Chrome MCP):
+
+**Step 1: Navigate and capture snapshot**
+
+```bash
+agent-browser open "http://localhost:3000/[route]"
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+**Step 2: For headed mode (visual debugging)**
+
+```bash
+agent-browser --headed open "http://localhost:3000/[route]"
+agent-browser --headed snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+**Step 3: Verify key elements**
+
+- Use `agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"` to get interactive elements with refs
+
+**Credential safety (#7947).** An accessibility snapshot serializes the **value**
+of input fields, including a value the agent never typed (a password manager's
+autofill, a static `value=`, a generated-credential panel). On any page carrying
+a password or credential field, route the snapshot through the redactor —
+`agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"`
+— and never capture a page that is displaying a credential value: a screenshot
+is safe for a `type=password` field but **not** for a readonly `type=text`
+credential panel, which renders in clear. Full rule and its measured ceiling:
+`plugins/soleur/skills/agent-browser/SKILL.md` §"Credential safety on a login or
+credential page".
+
+- Page title/heading present
+- Primary content rendered
+- No error messages visible
+- Forms have expected fields
+
+**Step 4: Test critical interactions**
+
+```bash
+agent-browser click @e1  # Use ref from snapshot 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+**Step 5: Take screenshots**
+
+```bash
+agent-browser screenshot page-name.png
+agent-browser screenshot --full page-name-full.png  # Full page
+```
+
+</test_pages>
+
+### 5b. Write or refresh the feature map
+
+After all affected routes are tested, maintain the repository's feature map —
+`docs/feature-map.md` by convention (soleur's own lives at
+`apps/web-platform/test/feature-map.md`); see
+[feature-map.md](./references/feature-map.md) for the schema and update
+contract:
+
+- **No map at either path + web app + ≥1 route exercised:** write
+  `docs/feature-map.md` seeded with the exercised routes only — real
+  observed `selectors`, `expects`, and `gotchas`, the update-contract
+  header, and a `## Deliberately unmapped` section (empty is fine). Do not
+  enumerate unvisited routes as entries.
+- **Map present at either path:** refresh only the fields a run
+  contradicted; append
+  `## \`/route\`` entries for exercised routes that were missing; leave every
+  untouched entry and the header byte-identical (operator annotations
+  survive).
+- **Skip:** non-web repos (no route surfaces found) and runs that exercised
+  zero routes — never write a vacuous map.
+
+The map is a working-tree edit that lands with the feature's PR — same
+change, per the update contract.
+
+**Report:** the Step 8 test summary names the map action taken — `written`,
+`refreshed`, or `skipped` + one-word reason (`non-web`, `no-routes`) — so a
+silently-absent map is never mistaken for a maintained one.
+
+### 6. Human Verification (When Required)
+
+<human_verification>
+
+Pause for human input when testing touches:
+
+| Flow Type | What to Ask |
+|-----------|-------------|
+| OAuth | "Please sign in with [provider] and confirm it works" |
+| Email | "Check inbox for the test email and confirm receipt" |
+| Payments | "Complete a test purchase in sandbox mode" |
+| SMS | "Verify the SMS code was received" |
+| External APIs | "Confirm the [service] integration is working" |
+
+Use AskUserQuestion:
+
+```markdown
+**Human Verification Needed**
+
+This test touches the [flow type]. Please:
+1. [Action to take]
+2. [What to verify]
+
+Did it work correctly?
+1. Yes - continue testing
+2. No - describe the issue
+```
+
+</human_verification>
+
+### 7. Handle Failures
+
+<failure_handling>
+
+When a test fails:
+
+1. **Document the failure:**
+   - Screenshot the error state: `agent-browser screenshot error.png`
+   - Note the exact reproduction steps
+
+2. **Ask user how to proceed:**
+
+   ```markdown
+   **Test Failed: [route]**
+
+   Issue: [description]
+   Console errors: [if any]
+
+   How to proceed?
+   1. Fix now - help debug and fix
+   2. Create todo - Add to todos/ for later
+   3. Skip - Continue testing other pages
+   ```
+
+3. **If "Fix now":**
+   - Investigate the issue
+   - Propose a fix
+   - Apply fix
+   - Re-run the failing test
+
+4. **If "Create todo":**
+   - Create `{id}-pending-p1-browser-test-{description}.md`
+   - Continue testing
+
+5. **If "Skip":**
+   - Log as skipped
+   - Continue testing
+
+</failure_handling>
+
+### 8. Test Summary
+
+<test_summary>
+
+After all tests complete, present summary:
+
+```markdown
+## Browser Test Results
+
+**Test Scope:** PR #[number] / [branch name]
+**Server:** http://localhost:3000
+**Feature map:** [written | refreshed | skipped: <reason>]
+
+### Pages Tested: [count]
+
+| Route | Status | Notes |
+|-------|--------|-------|
+| `/users` | Pass | |
+| `/settings` | Pass | |
+| `/dashboard` | Fail | Console error: [msg] |
+| `/checkout` | Skip | Requires payment credentials |
+
+### Console Errors: [count]
+- [List any errors found]
+
+### Human Verifications: [count]
+- OAuth flow: Confirmed
+- Email delivery: Confirmed
+
+### Failures: [count]
+- `/dashboard` - [issue description]
+
+### Created Todos: [count]
+- `005-pending-p1-browser-test-dashboard-error.md`
+
+### Result: [PASS / FAIL / PARTIAL]
+```
+
+</test_summary>
+
+### 9. Cleanup
+
+<cleanup>
+
+Playwright MCP writes screenshots to the main repo root when invoked from a worktree, so clean both locations. If any test failures were recorded with `error.png`, upload or review those screenshots before running cleanup.
+
+```bash
+# Remove session screenshots from current working directory
+rm -f *.png
+
+# If in a worktree, also clean the main repo root
+MAIN_REPO=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+if [[ -n "$MAIN_REPO" ]]; then
+  rm -f "$MAIN_REPO"/*.png
+fi
+```
+
+**Do NOT delete** files under `plugins/soleur/docs/` -- those are legitimate assets.
+
+</cleanup>
+
+## Quick Usage Examples
+
+```bash
+# Test current branch changes
+soleur:test-browser
+
+# Test specific PR
+soleur:test-browser 847
+
+# Test specific branch
+soleur:test-browser feature/new-dashboard
+```
+
+## agent-browser CLI Reference
+
+**ALWAYS use these Bash commands. NEVER use mcp__claude-in-chrome__* tools.**
+
+```bash
+# Navigation
+agent-browser open <url>           # Navigate to URL
+agent-browser back                 # Go back
+agent-browser close                # Close browser
+
+# Snapshots (get element refs)
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # Interactive elements with refs (@e1, @e2, etc.)
+agent-browser snapshot -i --json 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # JSON output
+
+# Interactions (use refs from snapshot)
+agent-browser click @e1            # Click element
+agent-browser fill @e1 "text"      # Fill input
+agent-browser type @e1 "text"      # Type without clearing
+agent-browser press Enter          # Press key
+
+# Screenshots
+agent-browser screenshot out.png       # Viewport screenshot
+agent-browser screenshot --full out.png # Full page screenshot
+
+# Headed mode (visible browser)
+agent-browser --headed open <url>      # Open with visible browser
+agent-browser --headed click @e1       # Click in visible browser
+
+# Wait
+agent-browser wait @e1             # Wait for element
+agent-browser wait 2000            # Wait milliseconds
+```

package/skills/test-browser/references/feature-map.md

@@ -0,0 +1,161 @@
+# Feature map convention
+
+A **feature map** is a committed, user-POV inventory of a repository's
+navigable features. Each entry names how to reach a route, its stable
+selectors, the expected outcome, the session state it needs, and its gotchas.
+It is the artifact that turns browser testing from flailing — re-deriving
+file-to-route mappings on every run and discarding them at session end —
+into navigation. The prescription comes from the poteto note in
+[Agentic Verification](https://addyo.substack.com/p/agentic-verification):
+agents that test in a real browser need a maintained map to navigate by.
+
+This document is the convention the `test-browser`, `qa`, `ux-audit`, and
+`reproduce-bug` skills read: the path, the entry schema, the parse contract
+consumers rely on, the update contract, and how the map stays fresh.
+
+## Canonical location
+
+The map lives at **`docs/feature-map.md`** in the repository root. One path
+keeps every consumer's check trivial: a skill looks for that file, reads it
+when present, and falls back to file-to-route inference when absent.
+
+`docs/` is the right home even when the repository publishes a docs site —
+the map is internal agent tooling, not user-facing documentation. If the
+site builds from `docs/`, mark the file accordingly (a comment in the site
+config or a build ignore) so it is not rendered as a page.
+
+## Entry schema
+
+Each mapped route is one `##` heading naming the route in backticks,
+followed by field bullets:
+
+```markdown
+## `/settings/billing`
+
+- route: `/settings/billing`
+- entry: rail nav → settings → billing tab, or direct URL
+- selectors: `data-testid="plan-card"`, `data-testid="manage-subscription"`
+- expects: current plan and invoices render; a missing subscription shows the upgrade empty state
+- auth: signed-in fixture with an active subscription
+- gotchas: the invoices table lazy-loads — wait for `data-testid="invoice-row"` before asserting row count
+```
+
+The fence markers above are display-only — they delimit the example in this
+document and must never be copied into the map itself (see "Consumer-parse
+constraints" below).
+
+Field semantics:
+
+- `route` — the route path, matching the heading. Dynamic segments stay
+  literal (`/posts/[id]`, `/docs/[...path]`, `/t/:token`) — the map documents
+  the route shape, not a concrete id.
+- `entry` — how an agent reaches the route: a nav link, a direct URL, or a
+  redirect from another surface.
+- `selectors` — stable anchors an agent can assert on. Prefer `data-testid`
+  values, then role/text anchors (`getByRole`/`getByText` style). Do not list
+  selectors you have not observed.
+- `expects` — the user-POV outcome of reaching the route, not an
+  implementation detail.
+- `auth` — the session state the route needs: anonymous, a signed-in
+  fixture, or a role-gated account. Name the fixture class, not credentials.
+- `gotchas` — anything that makes naive navigation or assertions wrong:
+  conditional banners, redirects, lazy mounts, duplicated testids.
+
+## Deliberately unmapped
+
+Some routes should not be mapped — error surfaces, routes pending removal,
+surfaces intentionally out of test scope. Exempt them in a
+`## Deliberately unmapped` section at the end of the map, one bullet each,
+of the exact shape:
+
+`- \`/route\` — <reason>`
+
+The em-dash and a non-empty reason are part of the grammar. An exemption is
+a recorded decision, not silent absorption: a route absent from both the
+entries and this section reads as "unmapped and unexempted" to coverage
+checks, which is exactly what the section exists to distinguish.
+
+## Consumer-parse constraints
+
+Consumers anchor on lines, not on rendered structure:
+
+- A `## \`/route\`` heading (a `##`, a space, a backtick, a slash) opens an
+  entry; its field bullets run until the next `##` heading or end of file. <!-- markdownlint-disable-line MD038 -->
+- `- selectors:` and `- expects:` bullets are how a consumer sees that an
+  entry is complete — mentioning the field names in prose inside the entry
+  does NOT conform.
+- `## Deliberately unmapped` carries no backtick in the heading, and its
+  bullets match `- \`/route\` — <reason>` exactly.
+
+**No fenced code blocks inside the map itself.** Every consumer here is
+line-anchored, so a `## \`/route\`` line inside a fenced block reads as a
+real entry and its fenced body as real fields. The map documents routes
+with inline backticks; it needs no fences.
+
+## Update contract
+
+Adding, renaming, or deleting a route surface requires an edit to the map —
+or to `## Deliberately unmapped` — in the same change. State this contract
+in the map's own header so a reader of the artifact sees it. A map whose
+entries drift from the routes is worse than no map: tombstoned entries
+navigate to nothing and unmapped new routes are invisible.
+
+## Authoring the map
+
+There is no universal route glob — the agent enumerates route surfaces from
+the repository's own shapes:
+
+- Next.js app router: `git ls-files '<app dir>' | grep -E '/page\.tsx$'`
+- Next.js pages router: `git ls-files '<pages dir>' | grep -vE '/_(app|document|error)\.'`
+- Rails: `config/routes.rb` plus the `app/views` tree
+- SPAs: the router config (`createRouter`, route tables, `<Route>` elements)
+
+Use a prefix pathspec plus a suffix filter — never a `**/` glob, which
+silently drops zero-directory roots on some git versions. The commands above
+are POSIX-safe and run on stock macOS; adapt the prefix and suffix to the
+repository's actual layout.
+
+Fill `selectors`, `expects`, and `gotchas` only from observed navigation or
+read page source. An unvisited entry that asserts unverified selectors is
+worse than no entry — it navigates an agent toward anchors that may not
+exist.
+
+## Keeping the map fresh
+
+Three mechanisms, cheapest first:
+
+1. **Refresh on run.** `test-browser` writes or refreshes the map on each
+   run: it seeds the map when absent (exercised routes only), refreshes
+   entries a run contradicted, and appends newly exercised routes. See the
+   `test-browser` skill's "Write or refresh the feature map" step.
+2. **The update contract.** Human route changes carry map edits in the same
+   change (above).
+3. **A coverage lint (optional, user-adapted).** A shell lint can enforce
+   the contract mechanically with five arms:
+   - *Coverage* — every route surface the lint derives is either a mapped
+     entry or a `Deliberately unmapped` bullet.
+   - *Staleness* — every mapped entry and exemption still corresponds to a
+     real route (tombstones red).
+   - *Completeness* — every entry carries `- selectors:` and `- expects:`
+     field bullets.
+   - *Contradiction* — no route appears in both the entries and the
+     exemptions.
+   - *Grammar* — no fenced code blocks anywhere in the map.
+   Add an anti-vacuity check that the route enumeration actually derived at
+   least one route, so a broken glob cannot certify an empty map. The
+   coverage and staleness arms need the repository's own route-file glob;
+   the other arms are portable to any map.
+
+## Edge cases
+
+- **Non-web repositories carry no map.** With no route surfaces there is
+  nothing to inventory; consumers skip the lookup silently.
+- **Zero exercised routes means no seed is written.** A vacuous map
+  certifies nothing.
+- **A partial map is valid.** Entries cover the routes actually observed;
+  the update contract and the coverage lint keep uncovered routes visible.
+  A map is authoritative per-route — never a reason to skip an unmapped
+  route.
+- **Refresh is field-scoped.** A producer refresh updates the fields a run
+  contradicted and appends new entries; it must leave untouched entries and
+  the header byte-identical so operator annotations survive.