Correct stale claims in MEMORY.md, TODO.md, and README.md (closes #3) #18

clawbot · 2026-08-09T06:59:22+02:00

clawbot commented

2026-08-09 06:59:22 +02:00

Fixes the four false documented claims in #3 plus the fifth added in the
follow-up comment. Documentation only — the diff touches MEMORY.md,
README.md, and TODO.md and nothing else. ARCHITECTURE.md is deliberately
untouched (tracked in #16).

Every claim was re-verified against the tree at c922a16 before rewriting;
none of it is a paraphrase of the issue. Details are in the PR comment below.

Changes

MEMORY.md "Error handling" — dropped the sentence about C's exit()
being unwound by a gameEnd panic recovered in Run, and added a paragraph
stating the real model: one game run is one process, myExit restores the
terminal via Terminal.Fini and calls os.Exit(0), Run() never returns, and
there is nothing to recover. Includes the testing consequence — any death exits
the test binary, hence tests drive command() directly and crash sweeps pin
the hero with fortify().

MEMORY.md "Linting" — .golangci.yml is byte-identical to canonical and
must not be edited, not even to add an exception; approved exceptions are
in-code //nolint directives carrying the approval date, which is what keeps
the config canonical. paralleltest moved out of the approved-disables list
with a note that it was fixed rather than disabled.

MEMORY.md "Debugging" — points at make test / make check instead of
plain go test -v, naming the flags the target carries so the reason is
self-evident.

README.md — the headless-testability line now says make test; the
Makefile paragraph notes what make test carries and says to use the targets
rather than go test directly.

TODO.md — the 2026-08-07 entry no longer asserts a specific host linter
version (the pin question itself is out of scope, tracked separately), and a
Completed Steps entry was added. Next Step is deliberately not rotated:
this is out-of-band issue work per the precedent set on #9, and "broaden unit
test coverage" is unfinished.

Verification

make check green — fmt-check clean (prettier reports all matched files use
Prettier code style), golangci-lint run ./... reports 0 issues, and the suite
passes under -timeout 30s -race -cover (game 1.927s, 46.0% coverage).
make fmt was run and its result is in the commit.

Fixes the four false documented claims in #3 plus the fifth added in the follow-up comment. Documentation only — the diff touches `MEMORY.md`, `README.md`, and `TODO.md` and nothing else. `ARCHITECTURE.md` is deliberately untouched (tracked in #16). Every claim was re-verified against the tree at `c922a16` before rewriting; none of it is a paraphrase of the issue. Details are in the PR comment below. ## Changes **`MEMORY.md` "Error handling"** — dropped the sentence about C's `exit()` being unwound by a `gameEnd` panic recovered in `Run`, and added a paragraph stating the real model: one game run is one process, `myExit` restores the terminal via `Terminal.Fini` and calls `os.Exit(0)`, `Run()` never returns, and there is nothing to recover. Includes the testing consequence — any death exits the test binary, hence tests drive `command()` directly and crash sweeps pin the hero with `fortify()`. **`MEMORY.md` "Linting"** — `.golangci.yml` is byte-identical to canonical and must not be edited, not even to add an exception; approved exceptions are in-code `//nolint` directives carrying the approval date, which is what keeps the config canonical. `paralleltest` moved out of the approved-disables list with a note that it was fixed rather than disabled. **`MEMORY.md` "Debugging"** — points at `make test` / `make check` instead of plain `go test -v`, naming the flags the target carries so the reason is self-evident. **`README.md`** — the headless-testability line now says `make test`; the Makefile paragraph notes what `make test` carries and says to use the targets rather than `go test` directly. **`TODO.md`** — the 2026-08-07 entry no longer asserts a specific host linter version (the pin question itself is out of scope, tracked separately), and a Completed Steps entry was added. **`Next Step` is deliberately not rotated**: this is out-of-band issue work per the precedent set on #9, and "broaden unit test coverage" is unfinished. ## Verification `make check` green — `fmt-check` clean (prettier reports all matched files use Prettier code style), `golangci-lint run ./...` reports 0 issues, and the suite passes under `-timeout 30s -race -cover` (`game` 1.927s, 46.0% coverage). `make fmt` was run and its result is in the commit.

clawbot added 1 commit 2026-08-09 06:59:23 +02:00

docs: correct stale claims in MEMORY.md, TODO.md, and README.md (closes #3 ) 56bcad9fc6

Four documented claims had gone false and were actively misdirecting agents
working this repo; the independent reviewer on PR #9 repeated one of them
verbatim. Each claim was re-verified against the tree before rewriting.

MEMORY.md "Error handling" described C's exit() calls being unwound by a
gameEnd panic recovered in Run. Refactor step 8 removed that: gameEnd appears
nowhere in the sources, myExit (game/rip.go) restores the terminal via
Terminal.Fini and calls os.Exit(0), and Run() has no return values and never
returns. The section now states that model and its testing consequence -- a
death exits the test binary, which is why tests drive command() directly and
crash sweeps pin the hero with fortify() in game/run_test.go.

MEMORY.md "Linting" said approved exceptions are recorded in a "Repo-specific
exceptions" block in .golangci.yml. There is no such block: the config is
byte-identical to canonical (sha256 021cc83f...46bcb) and the approvals live in
in-code //nolint directives carrying their dates. Following the old text would
have meant editing the canonical config. The same paragraph listed paralleltest
as an approved disable when it was fixed instead -- no paralleltest token
exists in the tree and all 32 tests call t.Parallel().

MEMORY.md "Debugging" and README.md both told the reader to run go test
directly. Since PR #9 the test target carries -timeout 30s -race -cover, so a
raw invocation silently drops the race detector while appearing to verify the
change. Both now point at make test / make check.

TODO.md asserted the host golangci-lint is "currently v2.12.2". It is v2.10.1
and the repo pins nothing, so the claim documented an accident of one machine.
Only the false claim is removed; the pin question is tracked separately.

Documentation only: no code, Makefile, or config change. Next Step is
deliberately not rotated, per the precedent for out-of-band issue work.

clawbot self-assigned this 2026-08-09 06:59:27 +02:00

clawbot added the merge-ready label 2026-08-09 06:59:28 +02:00

clawbot commented

2026-08-09 06:59:56 +02:00

Claim-by-claim verification

Every claim in #3 was checked against the tree at c922a16 before any text was
rewritten. All five held; nothing in the issue turned out to be wrong.

1. MEMORY.md: "unwinds C's exit() calls via a gameEnd panic recovered in
Run" — FALSE, confirmed. grep -rn gameEnd --include=*.go . returns no
hits: the identifier does not exist anywhere in the tree. The live exit path is
game/rip.go:17:

func (g *RogueGame) myExit() {
	g.scr.Fini()
	os.Exit(0)
}

Run() is func (g *RogueGame) Run() at game/game.go:205 — no return values
— and its own doc comment already says "It does not return — the game ends by
exiting the process (see myExit); one game run is one process." The in-code
comments were correct and MEMORY.md was the sole outlier. The testing
consequence is likewise already documented in-code: fortify() at
game/run_test.go:14 pins HP/MaxHP/Exp/FoodLeft and clears NoCommand/NoMove
because "game-over now calls myExit and os.Exit(0) (step 8), which would kill
the test binary", and driveTurns notes that tests drive command() directly
since Run() no longer returns.

2a. MEMORY.md: exceptions recorded in a "Repo-specific exceptions" block in
.golangci.yml — FALSE, confirmed. Grepping .golangci.yml for
Repo-specific, paralleltest, testpackage, exhaustive, and mnd returns
nothing; there is no such block. sha256sum .golangci.yml gives
021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb, matching the
canonical hash cited in the issue, so the config is byte-identical to canonical
as claimed. The approvals are in the source instead — e.g.
game/dice_test.go:1 //nolint:testpackage // ... (approved 2026-07-07),
game/object.go:41 //nolint:exhaustive // C-faithful ... (approved 2026-07-07), and file-level //nolint:mnd ... (approved 2026-07-07) on
daemons.go, init.go, passages.go, monsters.go, misc.go, rooms.go,
potions.go, command.go, chase.go, level.go, score.go, sticks.go,
things.go. This one had teeth: an agent following the old text would have
edited the canonical config, which is exactly what the org standard forbids.

2b. MEMORY.md: paralleltest listed as an approved disable — FALSE,
confirmed; it was fixed. grep -rn paralleltest --include=*.go . returns
nothing at all — no directive, no suppression. The suite has 32 top-level
func Test* and 32 t.Parallel() calls, matching the TODO.md record of the
golangci-v2.12.2 work ("t.Parallel() in all 32 tests").

3. MEMORY.md: "run plain go test -v" — contradicts policy and now loses
real coverage, confirmed. The Makefile test: target runs
go test -timeout 30s -race -cover $(GO_PKGS) with a verbose rerun plus
exit 1 on failure. A raw go test -v therefore drops the race detector,
coverage, the timeout, and the no-flaky-rescue rerun semantics, while looking
like a successful verification.

4. TODO.md: host golangci-lint "currently v2.12.2" — FALSE, confirmed.
golangci-lint --version on this host reports 2.10.1. Nothing in the repo
pins a version (no Dockerfile, no CI; the Makefile calls bare
golangci-lint), so the line documented one machine at one moment and had
already drifted. Only the false claim is removed — the pin question itself is
out of scope here and left to its own issue.

5. README.md:75: go test ./game/ — FALSE for the same reason as item 3,
confirmed. Identical defect; now points at make test, with the surrounding
Makefile paragraph naming what the target carries.

Scope discipline

The diff is MEMORY.md, README.md, TODO.md — git diff --name-only | grep -v '\.md$' is empty. No code, Makefile, .golangci.yml, or other
config was touched, and nothing outside *.md turned out to be necessary.
ARCHITECTURE.md deliberately untouched (its corrections are tracked in #16).
Next Step not rotated, per the out-of-band-work precedent from #9.
No new problems were fixed drive-by. One adjacent observation, filed nowhere
because it is arguably fine as-is: README.md's "Building and running"
section still shows go build ./cmd/rogue, which is out of scope here (the
issue is specifically about the test invocation) and has no make equivalent
— the Makefile has no build target. Flagging it rather than silently
changing it.

Gate

make check green from a clean worktree off origin/main:

fmt-check: gofmt -l empty; prettier — "All matched files use Prettier
code style!" (make fmt was run and its reflow is in the commit)
lint: golangci-lint run ./... — 0 issues
test: ok git.eeqj.de/sneak/rgoue/game 1.927s coverage: 46.0% of statements, under -timeout 30s -race -cover; cmd/rogue and term build
clean with no tests

## Claim-by-claim verification Every claim in #3 was checked against the tree at `c922a16` before any text was rewritten. All five held; nothing in the issue turned out to be wrong. **1. `MEMORY.md`: "unwinds C's exit() calls via a gameEnd panic recovered in Run" — FALSE, confirmed.** `grep -rn gameEnd --include=*.go .` returns no hits: the identifier does not exist anywhere in the tree. The live exit path is `game/rip.go:17`: ```go func (g *RogueGame) myExit() { g.scr.Fini() os.Exit(0) } ``` `Run()` is `func (g *RogueGame) Run()` at `game/game.go:205` — no return values — and its own doc comment already says "It does not return — the game ends by exiting the process (see myExit); one game run is one process." The in-code comments were correct and `MEMORY.md` was the sole outlier. The testing consequence is likewise already documented in-code: `fortify()` at `game/run_test.go:14` pins HP/MaxHP/Exp/FoodLeft and clears `NoCommand`/`NoMove` because "game-over now calls myExit and os.Exit(0) (step 8), which would kill the test binary", and `driveTurns` notes that tests drive `command()` directly since `Run()` no longer returns. **2a. `MEMORY.md`: exceptions recorded in a "Repo-specific exceptions" block in `.golangci.yml` — FALSE, confirmed.** Grepping `.golangci.yml` for `Repo-specific`, `paralleltest`, `testpackage`, `exhaustive`, and `mnd` returns nothing; there is no such block. `sha256sum .golangci.yml` gives `021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb`, matching the canonical hash cited in the issue, so the config is byte-identical to canonical as claimed. The approvals are in the source instead — e.g. `game/dice_test.go:1` `//nolint:testpackage // ... (approved 2026-07-07)`, `game/object.go:41` `//nolint:exhaustive // C-faithful ... (approved 2026-07-07)`, and file-level `//nolint:mnd ... (approved 2026-07-07)` on `daemons.go`, `init.go`, `passages.go`, `monsters.go`, `misc.go`, `rooms.go`, `potions.go`, `command.go`, `chase.go`, `level.go`, `score.go`, `sticks.go`, `things.go`. This one had teeth: an agent following the old text would have edited the canonical config, which is exactly what the org standard forbids. **2b. `MEMORY.md`: `paralleltest` listed as an approved disable — FALSE, confirmed; it was fixed.** `grep -rn paralleltest --include=*.go .` returns nothing at all — no directive, no suppression. The suite has 32 top-level `func Test*` and 32 `t.Parallel()` calls, matching the `TODO.md` record of the `golangci-v2.12.2` work ("`t.Parallel()` in all 32 tests"). **3. `MEMORY.md`: "run plain `go test -v`" — contradicts policy and now loses real coverage, confirmed.** The `Makefile` `test:` target runs `go test -timeout 30s -race -cover $(GO_PKGS)` with a verbose rerun plus `exit 1` on failure. A raw `go test -v` therefore drops the race detector, coverage, the timeout, and the no-flaky-rescue rerun semantics, while looking like a successful verification. **4. `TODO.md`: host `golangci-lint` "currently v2.12.2" — FALSE, confirmed.** `golangci-lint --version` on this host reports **2.10.1**. Nothing in the repo pins a version (no Dockerfile, no CI; the `Makefile` calls bare `golangci-lint`), so the line documented one machine at one moment and had already drifted. Only the false claim is removed — the pin question itself is out of scope here and left to its own issue. **5. `README.md:75`: `go test ./game/` — FALSE for the same reason as item 3, confirmed.** Identical defect; now points at `make test`, with the surrounding Makefile paragraph naming what the target carries. ## Scope discipline - The diff is `MEMORY.md`, `README.md`, `TODO.md` — `git diff --name-only | grep -v '\.md$'` is empty. No code, `Makefile`, `.golangci.yml`, or other config was touched, and nothing outside `*.md` turned out to be necessary. - `ARCHITECTURE.md` deliberately untouched (its corrections are tracked in #16). - `Next Step` not rotated, per the out-of-band-work precedent from #9. - No new problems were fixed drive-by. One adjacent observation, filed nowhere because it is arguably fine as-is: `README.md`'s "Building and running" section still shows `go build ./cmd/rogue`, which is out of scope here (the issue is specifically about the test invocation) and has no `make` equivalent — the `Makefile` has no `build` target. Flagging it rather than silently changing it. ## Gate `make check` green from a clean worktree off `origin/main`: - `fmt-check`: `gofmt -l` empty; prettier — "All matched files use Prettier code style!" (`make fmt` was run and its reflow is in the commit) - `lint`: `golangci-lint run ./...` — **0 issues** - `test`: `ok git.eeqj.de/sneak/rgoue/game 1.927s coverage: 46.0% of statements`, under `-timeout 30s -race -cover`; `cmd/rogue` and `term` build clean with no tests

clawbot merged commit eb31473ef0 into main

2026-08-09 07:00:35 +02:00

clawbot deleted branch docs-staleness

2026-08-09 07:00:35 +02:00

clawbot commented

2026-08-09 07:00:47 +02:00

Manager notes.

Merged directly under the docs-only exception — the diff touches
MEMORY.md, README.md, and TODO.md and nothing else, so it skips the
adversarial gate.

Because that exception removes the reviewer backstop, I verified the diff
myself rather than taking the label on trust:

git diff --name-only origin/main...origin/docs-staleness | grep -v '\.md$'
is empty — genuinely docs-only.
.golangci.yml on the branch still hashes to
021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb.
No Claude/Anthropic strings and no attribution trailers in the commit
author, subject, or body.
I read the prose changes rather than just the file list. The rewritten
"Error handling", "Linting", and "Debugging" sections match what I had
independently confirmed in the source: gameEnd appears nowhere in the
tree, myExit is at game/rip.go calling Terminal.Fini then
os.Exit(0), the config carries no exceptions block, and t.Parallel() is
present in all 32 tests.

Two things I want on the record:

The paralleltest wording is the detail that mattered most. The old text
listed it as an approved disable. The new text says the approval exists but is
no longer in force because the lint was fixed instead. That distinction is
what stops a future agent from "restoring" a disable that was deliberately
retired — it is a better outcome than simply deleting the line.

The scope discipline was correct. The implementer left ARCHITECTURE.md
alone (tracked in #16, as instructed) and did not touch the golangci pin
(#4, sneak's call). It also declined to repoint README's
go build ./cmd/rogue — correctly, since there is no make build target to
point it at, and inventing one mid-docs-commit would have broken the
docs-only exception this PR relies on.

Follow-up filed as #19 for that last raw-toolchain instruction.

Manager notes. Merged directly under the docs-only exception — the diff touches `MEMORY.md`, `README.md`, and `TODO.md` and nothing else, so it skips the adversarial gate. Because that exception removes the reviewer backstop, I verified the diff myself rather than taking the label on trust: - `git diff --name-only origin/main...origin/docs-staleness | grep -v '\.md$'` is empty — genuinely docs-only. - `.golangci.yml` on the branch still hashes to `021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb`. - No Claude/Anthropic strings and no attribution trailers in the commit author, subject, or body. - I read the prose changes rather than just the file list. The rewritten "Error handling", "Linting", and "Debugging" sections match what I had independently confirmed in the source: `gameEnd` appears nowhere in the tree, `myExit` is at `game/rip.go` calling `Terminal.Fini` then `os.Exit(0)`, the config carries no exceptions block, and `t.Parallel()` is present in all 32 tests. Two things I want on the record: **The `paralleltest` wording is the detail that mattered most.** The old text listed it as an approved disable. The new text says the approval exists but is no longer in force because the lint was *fixed* instead. That distinction is what stops a future agent from "restoring" a disable that was deliberately retired — it is a better outcome than simply deleting the line. **The scope discipline was correct.** The implementer left `ARCHITECTURE.md` alone (tracked in #16, as instructed) and did not touch the golangci pin (#4, sneak's call). It also declined to repoint README's `go build ./cmd/rogue` — correctly, since there is no `make build` target to point it at, and inventing one mid-docs-commit would have broken the docs-only exception this PR relies on. Follow-up filed as #19 for that last raw-toolchain instruction.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/rgoue#18