docs(e2e): README for the e2e lane — harness contract, CI sharding, board-lock spec patterns

[claudegoogl-sudo]

Follows CONTRIBUTING.md PR template — sections present: Thinking Path, Linked Issues or Issue Description, What Changed, Verification, Risks, Model Used, Checklist.

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• The repo's e2e lane (tests/e2e) drives a real throwaway Paperclip instance with Playwright, and CI splits it into three shards that each boot their own server
• The lane's operating contract lives only in scattered places: config comments (workers: 1, retries: 0, reuseExistingServer: false), the CI workflow's shard-rationale comments, and commit messages
• A recently stabilized spec (signoff-policy.spec.ts) also encoded a non-obvious resilience rule: specs drive a real board with real advisory locks, so conflict 409s are expected and a winning conflict-retry PATCH can reassign the issue in the same request — that rule previously existed only in a fix commit message
• tests/e2e/ had no README, so an engineer writing or debugging a spec had to reconstruct all of this from the workflow YAML and git history
• This change adds tests/e2e/README.md documenting the harness contract, the CI shard split, the board-lock pattern, and the benign teardown warning, so the lane's entry point and its failure folklore are discoverable in one place
• Documentation only; no spec, config, or product code changes

Linked Issues or Issue Description

No public issue tracks this; the gap is described here. The board-lock section records the pattern behind the signoff-policy.spec.ts checkout-helper fix (the spec that intermittently failed with "Board checkout failed" and was hardened to accept a successful conflict-retry PATCH regardless of who the same request assigned the issue to).

What Changed

• tests/e2e/README.md (new): how to run the lane locally, the harness facts (throwaway instance via onboard --yes --run, dedicated port PAPERCLIP_E2E_PORT/3199, local_trusted, reuseExistingServer: false), single-worker/no-retry rationale, the CI 3-shard deterministic partition (scripts/e2e-shard.mjs + durations manifest, aggregate gate, PAPERCLIP_E2E_SKIP_LLM=true), the two out-of-lane multi-user specs and the ignore-list drift guard, and a "writing resilient specs" section covering the board-lock 409/conflict-retry pattern and the benign heartbeat_run_events teardown warning.
• Everything stated is drawn from the existing config comments, workflow YAML, and sharder source — no behavior claims added.

Verification

• Docs-only change; no test surface. npx playwright test --config tests/e2e/playwright.config.ts --list still resolves the same spec list (nothing moved).
• Facts cross-checked against tests/e2e/playwright.config.ts, .github/workflows/pr.yml (e2e shard matrix + aggregate gate), scripts/e2e-shard.mjs, and package.json scripts (test:e2e, test:e2e:headed, test:e2e:multiuser-authenticated).
• CI runs the full verify matrix and all three e2e shards on this PR; the shard 3/3 job boots its own server and runs the documented lane end to end.

Risks

• Docs-only, no code paths. Worst case is a sentence aging out of date as configs evolve; the README links each claim to its source file.
• No PLA/internal identifiers, no instance-local URLs in branch, body, or content.

Model Used

GLM via the Anthropic-compatible Claude Code endpoint (z.ai). Agentic coding session with tool use and extended reasoning; the session does not expose the exact GLM version string.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work (docs-only)
• I have searched GitHub for duplicate or related PRs and linked them above (none exist; tests/e2e had no README)
• I have either (a) linked existing issues with Fixes: # / Closes: # / Refs: # OR (b) described the issue in-PR following the relevant issue template (option b)
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/claudegoogl-sudo/paperclip URLs)
• My branch name describes the change (docs/e2e-spec-authoring) and contains no internal Paperclip ticket id or instance-derived details
• I have run tests locally and they pass (docs-only; spec list resolution checked via --list)
• I have added or updated tests where applicable (N/A — documentation)
• I have updated relevant documentation to reflect my changes (this is the documentation)
• I have considered and documented any risks above
• All Paperclip CI gates are green (full verify matrix runs on this PR)
• [N/A] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (Greptile reviews the upstream repo; this fork-internal PR has no Greptile integration)