Add dev Makefile; format all markdown with prettier

Adds a minimal Makefile wrapping the toolchain the way sneak's other
repos expose it:

- fmt        gofmt -w plus prettier (4-space tabs, proseWrap: always)
- fmt-check  fail if any Go or Markdown file is unformatted
- lint       golangci-lint run ./...
- test       go test ./...
- check      fmt-check + lint + test (the local pre-commit gate)

Running make fmt normalizes the four existing Markdown docs to the
shared prettier style (80-column proseWrap: always, aligned tables) —
a one-time reflow with no content change. The repo remains exempt from
the rest of the policy scaffold (no Dockerfile, CI, or REPO_POLICIES).
This commit is contained in:
2026-07-22 22:20:34 +07:00
parent 88f18fc635
commit 35b538e888
5 changed files with 939 additions and 773 deletions

View File

@@ -1,44 +1,41 @@
# Project Memory
Working notes for agents on this repo. Read this alongside TODO.md
(which holds the step queue and workflow) before starting work.
Working notes for agents on this repo. Read this alongside TODO.md (which holds
the step queue and workflow) before starting work.
## Error handling
Panicking on bad/unexpected errors is allowed and preferred over
threading unlikely error returns through game code — e.g. write-side
Close/encode failures where continuing would mean corrupt state. The
game already unwinds C's exit() calls via a gameEnd panic recovered in
Run. Return errors where a caller genuinely handles them (save-file
prompts, restore validation). Reserve deliberate `_ =` discards for
true best-effort paths (scorefile writes, signal-time autosave), always
with a comment saying why.
Panicking on bad/unexpected errors is allowed and preferred over threading
unlikely error returns through game code — e.g. write-side Close/encode failures
where continuing would mean corrupt state. The game already unwinds C's exit()
calls via a gameEnd panic recovered in Run. Return errors where a caller
genuinely handles them (save-file prompts, restore validation). Reserve
deliberate `_ =` discards for true best-effort paths (scorefile writes,
signal-time autosave), always with a comment saying why.
## Linting
The .golangci.yml is the house standard and may only be modified with
sneak's explicit permission. To disable a linter, ask, explaining what
the linter does; he approves specific exceptions, which are recorded
in the config's "Repo-specific exceptions" block with the approval
date. Approved so far: paralleltest (2026-07-06); testpackage,
exhaustive, and mnd (2026-07-07). The complexity linters (cyclop,
gocognit, nestif) are enabled and clean as of refactor step 7
(2026-07-07): the whole golangci-lint run is 0 issues, so keep it that
way — decompose new hot spots rather than reaching for a nolint.
Line-level //nolint with a reason is used sparingly for C-faithfulness
(e.g. the authentic "missle" message spellings) and provably-safe gosec
conversions; each needs a justifying comment.
The .golangci.yml is the house standard and may only be modified with sneak's
explicit permission. To disable a linter, ask, explaining what the linter does;
he approves specific exceptions, which are recorded in the config's
"Repo-specific exceptions" block with the approval date. Approved so far:
paralleltest (2026-07-06); testpackage, exhaustive, and mnd (2026-07-07). The
complexity linters (cyclop, gocognit, nestif) are enabled and clean as of
refactor step 7 (2026-07-07): the whole golangci-lint run is 0 issues, so keep
it that way — decompose new hot spots rather than reaching for a nolint.
Line-level //nolint with a reason is used sparingly for C-faithfulness (e.g. the
authentic "missle" message spellings) and provably-safe gosec conversions; each
needs a justifying comment.
## Faithfulness
Behavior must not change during the idiomatic-Go refactor unless a
TODO step says so. The 80x24 seed-compatible gameplay, message text
(including original typos), RNG call order, and C quirks (documented
in tests like TestHoldScrollGreedyMonsterQuirk) are contract. Doc
comments keep their "(file.c func_name)" breadcrumbs.
Behavior must not change during the idiomatic-Go refactor unless a TODO step
says so. The 80x24 seed-compatible gameplay, message text (including original
typos), RNG call order, and C quirks (documented in tests like
TestHoldScrollGreedyMonsterQuirk) are contract. Doc comments keep their "(file.c
func_name)" breadcrumbs.
## Debugging
Write real, committed test files with t.Logf output and run plain
`go test -v`; no throwaway scratch scripts. Successful debug probes
become regression tests.
Write real, committed test files with t.Logf output and run plain `go test -v`;
no throwaway scratch scripts. Successful debug probes become regression tests.