docs(lanes): document proof gallery (C)

docs/LANES.md

@@ -877,6 +877,53 @@ curl -X POST http://localhost:4820/api/lanes/5/remove \
 
 **Actions gated behind confirmation:** `remove` requires the `confirm` flag to prevent accidental deletion.
 
+## Proof gallery
+
+A lane's proof gallery is a collection of QC screenshots captured during active work, grouped by feature (the same slug from **Per-feature state and archive** above) and phase (e.g. desktop, mobile, e2e, visual). A QC agent running an MCP server like `playwright-mcp` captures screenshots to disk at `<lane.cwd>/.playwright-mcp/proof/<slug>/<phase-group>/` and generates an optional ticket report at `<slug>/ticket/REPORT.html`. The Workspace gallery panel displays these files grouped by feature, using the same feature picker as the per-feature state section.
+
+### Storage
+
+Proof files live inside the lane's own `cwd`, not under `LANES_ROOT`:
+
+```
+<lane.cwd>/.playwright-mcp/proof/
+├── auth-redesign/
+│   ├── desktop/
+│   │   ├── 01-login.png
+│   │   └── 02-signup.png
+│   ├── mobile/
+│   │   ├── 01-login.png
+│   │   └── 02-signup.png
+│   └── ticket/
+│       └── REPORT.html
+├── another-feature/
+│   ├── e2e/
+│   │   └── 01-user-flow.png
+│   └── ticket/
+│       └── REPORT.html
+└── …
+```
+
+### Linking proof directories (the `ensure_proof_link` primitive)
+
+An MCP server's `--output-dir` flag may point to different locations across runs. To converge all proof onto one canonical path regardless, CCAM provides the `ensure_proof_link` operation, exposed only as the explicit `ccam lanes proof-link` CLI command — it is **never automatic**. This matches the "CCAM does not orchestrate" rule: a session decides when to link, not the dashboard.
+
+`ensure_proof_link` works as follows:
+
+1. If a stray `proof/` directory exists at `<lane.cwd>/proof`, merge its contents into the canonical `.playwright-mcp/proof` (no-clobber — existing files are never overwritten) and replace it with a symlink.
+2. If a `proof/` symlink already points to `.playwright-mcp/proof`, the operation is a no-op.
+3. If a file named `proof` exists (neither directory nor symlink), it is left untouched to avoid clobbering a user's file.
+
+The operation is idempotent and always safe — running it multiple times on the same lane has no side effects.
+
+### Security
+
+Every path the proof module touches — reading, serving, or deleting files — is resolved, realpath'd, and checked to be inside the lane's proof root before any filesystem operation. Symlink escapes, path traversal (`../`), and bad characters (`/`, `\`, `..` in segment names) are all rejected with `EBADPATH` errors. `deleteProof` never removes the `ticket/` directory, only the phase-group subdirectories and their images, so a lane's ticket report persists even when phase proofs are pruned.
+
+### Gallery panel and feature selection
+
+The Workspace page's gallery panel reuses the feature picker from **Per-feature state and archive** — there is only one selector, not a separate one for proofs. Selecting a feature displays that feature's saved pipeline (from per-feature state) and its proof gallery (if any proofs exist for that feature).
+
 ## Cross-lane named locks
 
 Cross-lane named locks serialize work that thrashes a shared machine — builds, e2e runs, database migrations — across all lanes, not just within one lane. This is a separate axis from `withLaneLock`, the in-process per-lane lock in `server/lib/lane-lock.js`: `lane-lock` is about _when_ a lane runs internal operations; `named-lock` is about which _other lanes_ must wait.