A new contributor could not have known the engine cannot import from lib/ - #234
Merged
Conversation
…lib/ Every convention in this repo that matters is written down somewhere, and no two of them are in the same place. The engine boundary is explained in the header of lib/constants/game-config.ts. The invariants are §10 of a 67KB design doc. The reason CI does not run lint is a comment in a workflow file. The reason wagmi mounts as a sibling rather than a wrapper is thirty lines of Web3Providers.tsx — and the note explaining it exists because somebody had already undone it once. That is fine for the owner, who wrote all of it. It is not fine for an assistant opening the repo cold, which is exactly who keeps being handed these tasks: it reads the file it was pointed at, does not read the four other files that explain why the file is shaped that way, and helpfully simplifies something back into the bug it was written to fix. CLAUDE.md collects the parts that are load-bearing and cheap to violate: THE BOUNDARY, first, because everything else follows from it. Fourteen plain <script> files under public/ that next build never touches, cannot import from lib/, and whose syntax errors ship. The duplicated marketplace list is a consequence, not an oversight, and the engine's copy wins. THE INVARIANTS from GAME-DESIGN.md §10 verbatim, plus the two the tooling already enforces but nobody would guess: one owner for the RPC endpoint and one for the origin, and an attribution tag that CANNOT be backfilled — an untagged transaction is unattributed forever, including the four the backend signs. WHAT THE CHECK SCRIPTS ARE. They are not a test suite. Each one is a bug that already shipped, wearing a filename. check:cssvars exists because a primary button rendered as near-black text on a dark modal; check:copy exists because "Add Cash" reached four files and a "Connect wallet" line sat permanently on /profile. Listing them next to what they guard is what stops the next person from deleting the noisy one. THE MINIPAY RULES that live in copy and in .npmrc, which look like style preferences and are listing-review rejections. THE COMMIT STYLE, described from the log rather than prescribed: the subject names the problem in the player's words, the body carries symptom, mechanism, fix and a Verified: line with real numbers. Verified against the source, not the README: the env section names FIREBASE_SERVICE_ACCOUNT, which is what firebase-config.ts actually reads — the README says FIREBASE_SERVICE_ACCOUNT_JSON, which nothing does. Route count (44), engine script count and load order, gitignored min/ output, and the audit's one-place-allowed rules for celoRpc.ts and siteUrl.ts were each read off the files. npm run audit clean; no source file changed.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Two reasons, and the second is the one that needed doing. The branch was cut before #235 landed, so it was describing a repo that has since gained lib/server/vaultChain.ts and a vault payout path that no longer does two on-chain writes in one request. A documentation branch that is behind main is documentation that is already wrong. It also retriggers the preview deployment. The one for d8297cf errored with a build log that stops dead after 'Cloning completed: 50.039s' — no install, no next build, no error, nothing. Zero build output on a diff that adds one markdown file, while the GitHub checks workflow passed on the same SHA and every other deployment that day went green. That is a stall on Vercel's side, not something in the change, and it never retried on its own.
The branch was cut before #235, so the file described a repo that no longer exists: 44 routes (now 45), a lib/server/ list with no vaultChain or vaultSweep, a cron that only closes seasons, and no mention of test:vaultpay. Three conventions added to §6, because they are exactly the kind this file is for — each one is a bug that already shipped and would have been avoided by a sentence: - two on-chain writes in one player request is how a solved vault paid nothing; the second write was rejected at the RPC boundary before it was a transaction, and only the first winner of each week ever took that path - anything that can leave a reward unpaid needs a server-side sweep, because the vault's only recovery was re-clearing Bunker 5 to reach the door - never name a cause you did not check: the payout blamed an empty pool it had never read A documentation branch that is behind main is documentation that is already wrong, which is the failure invariant #2 in this same file exists to name.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
CLAUDE.md. One new file, no source changed.The problem
Every convention in this repo that matters is written down somewhere, and no two of them are in the same place. The engine boundary is explained in the header of
lib/constants/game-config.ts. The invariants are §10 of a 67KB design doc. The reason CI does not run lint is a comment in a workflow file. The reason wagmi mounts as a sibling rather than a wrapper is thirty lines ofWeb3Providers.tsx— and that note exists because somebody had already undone it once.That is fine for the owner, who wrote all of it. It is not fine for an assistant opening the repo cold, which is exactly who keeps being handed these tasks: it reads the file it was pointed at, does not read the four other files explaining why that file is shaped the way it is, and helpfully simplifies something back into the bug it was written to fix.
What it collects
<script>files underpublic/thatnext buildnever touches, cannot import fromlib/, and whose syntax errors ship. The duplicated marketplace list is a consequence, not an oversight, and the engine's copy wins.docs/GAME-DESIGN.md§10 verbatim, plus the two the tooling already enforces but nobody would guess: one owner for the RPC endpoint and one for the origin, and an attribution tag that cannot be backfilled — an untagged transaction is unattributed forever, including the four the backend signs.check:cssvarsexists because a primary button rendered as near-black text on a dark modal;check:copyexists because "Add Cash" reached four files and a "Connect wallet" line sat permanently on/profile. Listing them next to what they guard is what stops the next person from deleting the noisy one..npmrc, which look like style preferences and are listing-review rejections.Verified:line with real numbers.Also covered: the three identity tiers in
useWallet()and the note that none of them is a credential, the read-before-write rule on Firestore transactions that once discarded every kill for a month, the server-side replay protection pattern inmarketplace/verify, and the docs map.Verified
Against the source, not the README. The env section names
FIREBASE_SERVICE_ACCOUNT, which is whatfirebase-config.tsactually reads — the README saysFIREBASE_SERVICE_ACCOUNT_JSON, which nothing does. Route count (44), engine script count and load order, gitignoredmin/output, and the audit's one-place-allowed rules forceloRpc.tsandsiteUrl.tswere each read off the files.npm run auditclean. No source file changed, so nothing else can regress.Generated by Claude Code