Submission polish: verification-doc accuracy and final hardening

[batbrainy]

Closes #39

What this is

The final pre-submission polish pass: documentation accuracy against the assignment text, one defensive fix in the verification script, and a CI job for the already-declared static-analysis gates. No runtime behavior changes — the only non-doc, non-CI change is the EXIT-trap arming in script/verify_recovery.sh.

Changes

README

• "How long before results appear" now opens the How to verify it's working section, where the assignment asks for it (fixture: immediate; live: first poll within ~a minute, 5-minute cadence, 30s–6h upstream feed latency), linking the existing Known-limitations detail.
• The two script/verify_recovery.sh --phase=cleanup invocations (and the --phase=rate-limit mention) now carry --confirm; without it the script prints usage and exits 2, so the documented command previously failed on first paste.
• Known limitation 8 now names what the submission ships, not just what it declines: Extensions A, B, and D are implemented and linked to the sections that describe them; C remains the declared non-goal.
• New known limitation 9: business tables are append-only by design — retention, pruning, and archival deliberately not built, with the growth arithmetic at the 60-request ceiling.
• New troubleshooting row for a host port-3000 collision, a plausible first-run failure the symptom table did not map.

script/verify_recovery.sh

• phase_scenarios stops the worker but never armed the worker-restore EXIT trap that phase_test_isolation uses, so a mid-phase failure under set -euo pipefail could leave a reviewer's worker stopped. The stop now arms TEST_WORKER_RESTART_PENDING and the verified start clears it, mirroring the existing pattern; the trap's message is rephrased since two phases now share it.

CI

• New analysis job running the three gates config/ci.rb already declares for bin/ci — RuboCop, bundler-audit, Brakeman (same flags). Until now the declared tooling had no execution record anywhere. All three verified green in the project container before this PR: RuboCop 231 files no offenses, Brakeman 0 warnings, bundler-audit no vulnerabilities against the 2026-07-31 advisory database.

Consistency

• Appendix E's "Every P0 story and extension shipped" contradicted the same document's "Extension C — deliberately not attempted"; it now reads "every attempted extension (A, B, D)".
• Two comments (page_writer.rb, end_to_end_spec.rb) still cited "reviewer verification step 7", a numbering the Phase A/B/C restructure removed; both now reference the Phase B replay check that exists.
• .gitignore now covers /.claude/, so the exclusion travels with the repository instead of relying on one machine's global git config.

Tradeoffs

• The port-3000 collision is handled with a troubleshooting row rather than a ${WEB_PORT:-3000} interpolation: every curl in the README targets localhost:3000, and a configurable port would make those examples conditionally wrong for one rare failure mode.
• The analysis job is a separate CI job, not steps appended to the RSpec job: none of the three tools needs the Postgres service, and a parallel job keeps the suite's wall-clock unchanged.

Verification

• Full suite green in the project container (db:test:prepare && rspec && rspec spec/stress), including spec/docker_compose_spec.rb, which pins verify_recovery.sh source properties the script edit had to preserve.
• RuboCop, Brakeman, and bundler-audit green in the same container (see above).
• README anchors in the new Extension A/B/D links verified against the section headings they target.