Skip to content

docs(CH-035): publish Rumble documentation and open P-004 - #251

Merged
flemming-n-larsen merged 23 commits into
mainfrom
ch-034-rumble-hardening-plan
Sep 6, 2026
Merged

flemming-n-larsen merged 23 commits into
mainfrom
ch-034-rumble-hardening-plan

Conversation

@flemming-n-larsen

@flemming-n-larsen flemming-n-larsen commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Acceptance brief

  • Plan item: P-003/M-009 and successor plan P-004. Both remain wanted.
  • Acceptance criteria: None added, retired, or materially changed; no scenario-resolution verdicts are required.
  • Merge binds: CH-035’s published Rumble documentation, P-003 completion, and the draft P-004 hardening plan. The earlier documentation PR docs(CH-034): publish Rumble user documentation #250 is superseded. Accepted changes already on main, including CH-036/P-005, are retained.
  • Documentation impact: ARCH-025 and the published Rumble guides are updated. No public API or runtime interface changes are introduced by CH-035.
  • Verification: clue validate --forbid-changes, the repository Markdown local-link check, ./gradlew clean build, and ./gradlew :web:build pass.
  • Review: in-context fallback, reviewed commit 40ecb0c9cedc3b2c3fee0414e42da2503ba97f95, pass 1, no blocking findings and no advisories.

Rumble user documentation (P-003/M-009)

This PR carries the documentation work originally proposed in PR #250, which is now superseded.

New quickstarts under web/docs/rumble/, one per audience, are wired into the VitePress navigation and sidebar:

  • bot-author-guide.md: fork, add source, validate, open the PR, plus TwinDuel teams, ownership, versions, and slots.
  • client-guide.md: register a client, build from source, check and synchronize, run one ranked battle, submit results.
  • moderator-guide.md: review submissions and client registrations, handle disputes and abuse, keep the GitHub automation healthy.
  • index.md: landing page.

The client guide describes the client's actual current pre-release state rather than an aspirational published-container flow. With M-009 done, all six P-003 milestones are done and P-003 becomes status: completed.

P-004 successor plan (CH-035)

Closing a plan does not close the system. Delivery work for P-003’s own milestones is still unmerged upstream, and hands-on testing after the V1 launch found defects that were never tracked. P-003 stays immutable as the launch record; P-004 carries the follow-up as its own campaign rather than reopening P-003.

ID Milestone Tracked in
M-011 In-flight P-003 delivery reconciled This PR, plus rumble-client#9 awaiting a maintainer merge
M-012 Practice mode has a working CLI path rumble-client#10
M-013 Catalog passes its own validator rumble-bots#8
M-014 Documentation matches post-fix behavior Gated on the others
M-015 Container image runs under rootless Podman rumble-client#11

M-015 covers the concrete risk that docker/rumble.sh passes --user "$(id -u):$(id -g)" alongside bind mounts, which under rootless Podman can leave the mounted state directory unwritable. Podman is not becoming a second CI-tested runtime; the milestone asks for one deliberate manual pass and an honest written answer.

Review corrections included

  • Submission trees put bot source under src/, matching the booter convention and live catalog bots.
  • The client guide carries -PtankRoyaleSource and --no-configuration-cache on every Gradle invocation.
  • The client guide explains that several game types cause the client to select the alphabetically first entry, and notes that battlesPerSession is unused by current commands.
  • The moderator guide points bans at bannedAccounts and disqualifiedBots in rumble-data/bans.json.
  • TwinDuel team members are identified by their name-and-version entries.

Per C-002, this PR requires a human merge.

🤖 Generated with Claude Code

flemming-n-larsen and others added 11 commits September 3, 2026 22:40
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Add bot-author, battle-contributor, and moderator quickstarts under
web/docs/rumble/, plus a landing page, wired into the VitePress nav
and sidebar. The client guide documents the client's actual current
pre-release state (build from source / dev Docker image) rather than
an aspirational published-container flow.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Mark P-003/M-009 done and P-003 completed (its last open milestone),
regenerate the plans README index, and delete the change workspace.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Note in ARCH-025 that the shipped quickstarts diverge deliberately
from the design's fuller aspirational document set (moderator
handbook, onboarding.md, faq.md remain future work).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Use idiomatic VitePress directory-index links (/rumble/ instead of
/rumble/index) and avoid the "2v2" phrasing docs/design/rumble/README.md
asks writers to avoid for TwinDuel.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
BR-049 is an internal Battle Runner acceptance-criterion identity that
means nothing to end users. Replace it with a plain-language
description of what the local Tank Royale checkout needs to contain.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
…cate it

Trim the battle-contributor quickstart to the one step that happens
in a different repository (client registration in rumble-data) and
hand off to the rumble-client README for everything else, so build
and run instructions live in one place next to the code they
describe (robocode-dev/rumble-client#9 rewrites that README as a
complete, working Docker quickstart and closes a real gap where the
hardened launchers never grew --run/--submit support).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Creates a plan-mutation change proposing P-004 (Rumble hardening),
covering the two open P-003 delivery PRs, the practice-mode CLI gap
in rumble-client, and the Vector stale-source-hash bug in rumble-bots.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H
Main already merged an unrelated change under CH-033 (release
changelog precondition, PR #252) while this branch was still using
that same identity for the Rumble documentation change. Renumbers
this branch's reservation to the next free identity, CH-034, and
updates its two references accordingly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
Main merged CH-033 for an unrelated change (release changelog
precondition, PR #252) while ch-033-rumble-docs independently claimed
CH-033 for the Rumble docs change; that branch has since been fixed to
use CH-034 instead (see its own merge commit). This branch's proposal
also reserved CH-034 for itself, plus a stray unused CH-033 and CH-035
reservation from the same minting pass. Drops the stray CH-033
reservation (superseded by main's real one) and renumbers this
branch's actual proposal from CH-034 to CH-035, since ch-033-rumble-docs
now owns CH-034 and lands first. The extra unused CH-035 reservation
becomes this branch's real identity; nothing else was reserved beyond
it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
@flemming-n-larsen flemming-n-larsen changed the title propose(CH-034): track Rumble's remaining follow-up work propose(CH-035): track Rumble's remaining follow-up work Sep 5, 2026
flemming-n-larsen and others added 4 commits September 5, 2026 20:00
Six corrections to the shipped Rumble guides, each verified against
the code or data that the guide describes:

- Bot submission tree puts source under src/, matching the booter
  convention in the design and the boot scripts of the live catalog
  bots, which invoke "$SCRIPT_DIR/src/<entry point>".
- Team teamMembers name member directories, not "Name Version".
  BotBooter.bootTeamMember resolves each string with
  parentPath.resolve(botName) and BotIdentityReader treats it as a
  member directory name; the versioned form is what the generated
  catalog carries. The versioning paragraph is reworded to match.
- Client guide carries -PtankRoyaleSource and --no-configuration-cache
  on every Gradle invocation, not only the build. Without the property
  the composite build is skipped and Gradle tries to resolve Battle
  Runner 1.2.0, which is unreleased, so --sync, --run and --submit
  all fail.
- Client guide states the consequence of listing several game types:
  RumbleClient takes the alphabetically first entry, so a multi-type
  configuration silently runs only 1v1. Also notes that
  battlesPerSession is unused by the current commands.
- Moderator ban procedure points at bannedAccounts and
  disqualifiedBots in rumble-data/bans.json. The previously named
  rumble-bots/bots/banned.json does not exist.
- Removes long dashes from the two paragraphs this change added to
  P-003 and ARCH-025.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
# Conflicts:
#	.clue/id-ledger.yaml
Review findings on the CH-035 proposal set:

- Add the missing frontmatter to proposal.md, tasks.md and
  open-questions.md, matching the CH-032 set. clue validate rejected
  all three files as committed; it now passes.
- Register CH-035 as live (its change directory exists) and add the
  CH-035-open-questions and CH-035-tasks opaque entries, so every ID
  the frontmatter declares is in the ledger.
- Reserve P-004 through "clue id next P". The task list committed to
  creating docs/plans/P-004-rumble-hardening.md while the P counter
  still read 3, leaving the ID unclaimed. It stays reserved until the
  plan file exists, per "clue id live".
- Merge ch-033-rumble-docs into this branch. The proposal's premise
  that P-003 is completed was false on its own base: that flip lived
  only on the unmerged docs branch. Both changes now land as one
  pull request, and M-011 is reworded to match.
- Give open-questions.md real content: what is not open and why, the
  two operational prerequisites that belong to the tracked milestones
  rather than to this change, and the merge-order decision.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
flemming-n-larsen and others added 4 commits September 5, 2026 21:56
The teamMembers slots carry the full "name version" identity of each
member bot, not a bare directory name, and a member version change is
an explicit edit to the team's own configuration rather than something
the catalog resolves on the author's behalf.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
Implements CH-035. P-003 closed as completed when M-009 landed, but
delivery work for its own milestones is still unmerged upstream and
two defects found after the V1 launch were never tracked. P-004
carries that follow-up as its own campaign; P-003 stays immutable.

Milestones, all verified against the live forge state:

- M-011 reconciles in-flight P-003 delivery. The M-009 documentation
  rides on this branch; rumble-client#9 is open and mergeable and
  needs a maintainer merge.
- M-012 gives practice mode a working CLI path. Tracked in
  rumble-client#10.
- M-013 makes the catalog pass its own validator again, after
  Vector's recorded sourceHash drifted from its source. Tracked in
  rumble-bots#8.
- M-014 sweeps the Rumble documentation against post-fix behavior,
  gated on the other three so the sweep cannot bake in the
  inaccuracies it exists to remove.

Marks P-004 live in the identity ledger and regenerates the plans
README index. clue validate: OK, 154 artifacts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
The container path has only ever been exercised on Docker Desktop,
while rootless Podman is the default runtime on Fedora and RHEL and
so a realistic profile for a battle contributor.

The known risk is concrete. docker/rumble.sh passes
--user "$(id -u):$(id -g)" alongside bind mounts; under rootless
Podman that resolves through the subuid map to a different host UID
and leaves the mounted .rumble-client state directory unwritable,
surfacing as a client failure writing its journal or evidence rather
than as an obvious runtime mismatch. The resource flags (--cpus,
--memory, --pids-limit) additionally need cgroups v2 with delegation.

M-015 asks for one deliberate manual pass and a written answer for
people who do not run Docker; Podman is explicitly not becoming a
second CI-tested runtime. M-014's documentation sweep now waits on it
too, so the guides do not settle on a Docker-only runtime story.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
Files rumble-client#11 for the rootless Podman gap and cites it as
M-015's evidence, matching how M-012 and M-013 carry theirs. Also
corrects the milestone count in the plan's preamble now that five
milestones exist, four of them delivered outside this repository.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv
@flemming-n-larsen flemming-n-larsen changed the title propose(CH-035): track Rumble's remaining follow-up work docs(CH-035): publish Rumble documentation and open P-004 Sep 5, 2026
flemming-n-larsen and others added 4 commits September 6, 2026 08:18
Ultrareview found the moderator guide pointing bans at a non-existent
bannedAccounts field (schema uses bannedOwners), CH-035's proposal/
tasks/open-questions describing P-004 as M-011-M-014 while the plan
adds M-015, a plan-index tagline copied from P-003's opening sentence,
and a client-guide claim that only holds when 1v1 is alphabetically
first.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012FvTpb45VPPmEPv9BHDNSa
@flemming-n-larsen
flemming-n-larsen marked this pull request as ready for review September 6, 2026 20:00
@flemming-n-larsen
flemming-n-larsen merged commit 7a56383 into main Sep 6, 2026
6 checks passed
@flemming-n-larsen
flemming-n-larsen deleted the ch-034-rumble-hardening-plan branch September 6, 2026 20:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant