PR 12 — Reviewer documentation and final hardening

[batbrainy]

Linked issue

Closes #22 — IMPLEMENTATION_PLAN.md §13's final PR.

Problem

The code was done; the documentation was not. docs/DESIGN_BRIEF.md did not exist though
§14 calls it the reviewer's primary architecture document. README.md:13 still announced
"Background processing and recovery stage (PR 8)" — four PRs stale, and the first line a
reviewer reads. The data model was absent entirely (S2.7), there was not one sample JSON log
line anywhere (S4.9), processing guarantees had no home (B10), and a ## Planned contents
table still deferred three items to this PR. Two of §14's eight named ADR topics — "Why Kafka
was not selected" and the pinned API version — had zero coverage in the repository. §16
forbids stale documentation, and PR 12 is the last chance to close any of it.

Scope

New: docs/DESIGN_BRIEF.md (two pages, mermaid request-path and data-model figures);
docs/SUBMISSION_CHECKLIST.md (§16's four gate lists as checkboxes, the forbidden-claim
scan, the post-merge email template); ADR 0011 (pinned API version 2022-11-28) and ADR 0012
(Solid Queue over Kafka); docs/evidence/2026-07-31-clean-checkout-verification.md.

README restructured to a 20-heading spine with a table of contents. Mostly moves —
nine existing blocks relocate into new containers (Rate limits and the request budget,
Inspecting the data, Troubleshooting and reset, Logs), which is what keeps this affordable.
Genuinely new: the data model, sample log lines, processing guarantees, known limitations,
the §15 eleven-step verification walk, the SSRF boundary with a worked example, a three-level
reset ladder, and a symptom table.

IMPLEMENTATION_PLAN.md gains ## Appendix E only. §1–§17 and Appendices A–D are
byte-identical — the freeze governs changing direction mid-build without stating the
tradeoff, not recording afterward what changed.

Important technical decisions

Sample log lines are captured from a real fixture run, not hand-authored.
ingestion.run_completed alone is splat-merged across ~20 to_log methods; hand-authoring
gets a key or a nesting level wrong eventually, and a wrong sample in the section whose
entire purpose is trustworthiness is exactly the stale documentation §16 forbids. The capture
command sits beside the samples so they are self-verifying.

Two duplications are deliberate: the allowance formula (§14 requires it in the README
and the brief) and §8's at-least-once equation (§14 requires the durability boundary in the
brief; B10 requires processing guarantees where a reviewer will look). Both are short fences
kept byte-identical to the plan.

The two ADRs ship here rather than with their code because neither records a decision made
during a PR — both were made before PR 1 and never written down.

A defect found by this PR's own clean-checkout verification

docker compose up --build failed from a cold image and started zero containers:

target worker: failed to solve: image "github-push-ingestor-app:latest": already exists

Compose Bake — on by default in Docker Desktop — makes every service with a build: its own
bake target, and six services declared build: . against the same image: tag, so the
targets raced to export it. It reproduces only when the image is absent — a reviewer's
first command and no other run — which is why a spec-guarded design property had been
silently broken for a reviewer the whole time.

Fixed: setup is the only service on the up path that builds; web and worker reference
the tag and already wait on it; the tools one-shots keep their own build (each invoked alone
by docker compose run, a single target) plus pull_policy: build.
spec/docker_compose_spec.rb now asserts that invariant instead of the one that broke.

Other non-documentation changes

• CI's foundation job asserts docs/DESIGN_BRIEF.md exists.
• spec/requests/health_spec.rb asserts the health endpoints spend no budget — the one §16
  gate that was structurally true but untested.
• Deleted config/initializers/cors.rb, commented-out scaffolding for a gem the plan
  excludes ("no dead or speculative infrastructure").
• README's test command gains --build: the code is baked into the image rather than
  mounted, so running the suite against a stale image tests what the image was built from.

Testing performed

1728 examples, 0 failures plus 10 examples, 0 failures (spec/stress), against a rebuilt
image, repeated with --seed 4242.

Clean-checkout verification from a fresh clone into an empty directory on a host with no
image, both halves:

• Live: one unauthenticated poll persisted 96 push events from a page of 100, ledger
  bootstrapped from GitHub's own headers, both entity classes enriched. 3 requests of 60.
• Fixture, empty volume: 4 / 3 / 3 / 3, complete 2 / permanent_failure 1 per class,
  replay absorbing 4 duplicates with occurrences 3 → 6 and no reactivation.
• script/verify_recovery.sh --confirm: 19 checks, absolute count mode for the first
  time (the committed kill transcript had to run in delta).
• Test isolation measured rather than asserted: both development databases unchanged across a
  full test run, poller stopped so the counts could not drift.

Docker verification

Covered above and transcribed in docs/evidence/2026-07-31-clean-checkout-verification.md.

Documentation updates

This PR is the documentation update.

Known limitations

• The clean-checkout transcript is one host, one date, one Docker version. The Bake collision
  is specific to Compose Bake plus the containerd image store.
• The live half is one poll from one shared-budget IP. It shows the API is reachable without a
  token; it shows nothing about sustained behaviour or authenticated requests.
• The authoritative clean-checkout run is post-merge, against the default branch.

Deferred, out of issue #22's scope — noted, not fixed: bin/dev execs rails server
(host-only scaffolding; removing it means editing bin/setup too); config/ci.rb runs
bin/setup --skip-server → db:prepare on development databases, though no workflow
invokes it; config/credentials.yml.enc is committed with no key and nothing reads it;
config/bundler-audit.yml's CVE-THAT-DOES-NOT-APPLY placeholder; and §11's optional
/api/actors/:id, /api/repositories/:id, /api/ingestion_runs endpoints, correctly unbuilt.

🤖 Generated with Claude Code