CH-002: Launchers default to the published GHCR image

[flemming-n-larsen]

Acceptance brief

• Plan item and whether it remains wanted: plan-less; serves G-001 (contributors obtain a ready-to-run image without building it), which remains wanted.
• The vision this change proceeds under: VIS-001 — Enable community-run ranked Tank Royale battles (status: draft, inferred).
• Added or changed criteria: AC-004 (new, Test-type: Human) — this line is its proof:

  @AC-004
  Scenario: The launchers run the published image unless told otherwise
    Test-type: Human
    Given a contributor has not built or tagged any image locally
    When they run "docker/rumble.sh runtimes" or "docker/rumble.ps1 runtimes" without an image argument
    Then the launcher runs ghcr.io/robocode-dev/rumble-client:latest, pulling it if it is not present
    And passing an explicit image argument, such as a locally built "rumble-client:dev", runs that image instead

  Supporting observation: with a stub docker that echoes its arguments, both launchers passed ghcr.io/robocode-dev/rumble-client:latest with no image argument and rumble-client:dev when given; latest pulls anonymously from GHCR. No real container run was done locally (Docker daemon not running).
• What becomes binding on merge: CAP-001's revised scope — the launchers default to the mutable ghcr.io/robocode-dev/rumble-client:latest tag rather than a local build. No decision records added or superseded; no unaccepted base.

A green build, complete form, or confident agent is not evidence that this outcome is wanted or that the criteria reflect reality. Keep this brief to one screen; split a change rather than hiding material meaning.

Summary

docker/rumble.sh and docker/rumble.ps1 default to ghcr.io/robocode-dev/rumble-client:latest instead of the local-only rumble-client:dev. The README makes pulling the published image the default path (no docker tag step); building the container image or the Java code moves under "Building rumble-client itself", and running a local build means passing its name as the image argument. CAP-001 README, criteria, and design, the architecture overview, and CHANGELOG.md are updated.

Documentation impact: README.md, docs/architecture/README.md, and CAP-001's README/criteria/design changed; docs/design/README.md needed no change (no cross-cutting behaviour changed).

Verification

• clue validate --forbid-changes: OK
• git diff --check origin/main HEAD: clean
• sh -n docker/rumble.sh: OK; stub-engine argument checks for both launchers as above
• CI does not use the launchers (verify-container.sh builds and tags its own image), so it is unaffected by the default

Cliewen proposal

• Change ID: CH-002
• Plan item served: plan-less (G-001)
• Proposal location: /changes/CH-002-launchers-default-ghcr-image/proposal.md (in commit db55b7a; deleted in digest)
• Agentic review mode, reviewed commit, and pass count: context-isolated; 00549c0; 2 passes (3d2448b clean; 00549c0, scoped to the README fix separating Docker/Podman commands, clean)
• Outstanding advisory findings:
  • The published image is linux/amd64 only; ARM hosts get emulation (Docker Desktop on Apple Silicon) or exec format error (ARM Linux without qemu). Consider a README note or multi-arch publishing later.
  • The external guide (robocode.dev/rumble/client-guide, in robocode-dev/tank-royale) still builds rumble-client:dev and runs runtimes without an image argument, which now checks the GHCR image instead of the local build; it also says no published image exists. Needs a follow-up there.
  • latest is mutable and not digest-verified, and an already-present latest is not refreshed automatically (documented). Consider --pull=newer or pinning later.
• Hosted head reviewed before this update: 3d2448b
• Outstanding actionable findings: none

Traceability and Decisions

• Acceptance criteria or capability meaning changed: CAP-001 (scope statement), AC-004 (added)
• Decision records added or changed: none
• Constraints assessed: C-001 (no hard-wrapped Markdown) — satisfied

🤖 Generated with Claude Code

https://claude.ai/code/session_01KwJVGH7ftyX2ThQ2wMCLQK