docs: align README, CLAUDE.md, and AGENTS.md with the code#24
Merged
Conversation
README's main config example taught the deprecated on_up/on_down hook names — and on_up maps to pre_up, which runs before any env exists, so the 'npx prisma migrate deploy' example could never see DATABASE_URL. The example now uses post_up/pre_down and documents the five-hook lifecycle; the deprecated aliases are mentioned as such. CLAUDE.md's project structure was missing five modules (process, sync, validate, log, whose_pid), described hooks.rs by its pre-rename hook names, and the command list omitted status/sync/whose-pid/flush. AGENTS.md listed a postgres.rs that does not exist, declared a 2500-line LoC budget against an ~11.8k-line tree (dropped — a violated budget only misleads the agents this file targets), and stated the state-lock mechanism in terms an upcoming change (#1) invalidates; the invariant is now phrased by intent (mutations only under StateGuard). Fixes #15 https://claude.ai/code/session_017UcuvzMKHVfyBCcq8ipAko
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
2 participants
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.
Fixes #15
Doc-only PR aligning the three prose surfaces with the code.
README.md
on_up/on_downnames. Worse,on_upaliases topre_up, which runs before any env exists — so the exampleon_up = "npx prisma migrate deploy"could never seeDATABASE_URL. The example now usespost_up/pre_down, documents the five-hook order (pre_up → pre_spawn → post_up → pre_down → post_down), and notes the deprecated aliases explicitly.CLAUDE.md
process.rs,sync.rs,validate.rs,whose_pid.rs,log.rshooks.rsdescription updated from "on_up/on_down" to the current five hooksstatus,sync,whose-pid,flush(all shipped, none listed)AGENTS.md
postgres.rsfrom the layout — the file does not existsrc/**/*.rsis ~11,850 lines (4.7× over). A violated budget presented as an invariant only misleads the agents this file is written for; if a budget is wanted, it should be re-added at a realistic number (maintainer's call)StateGuard— which stays true both today and after Exclusive state lock is held through all of provisioning — parallelupserializes and everything else hits LockTimeout #1/fix(state): pending sessions — stop holding the exclusive lock through provisioning #20 landNo code changes;
cargo testunaffected (370 + 18 green).https://claude.ai/code/session_017UcuvzMKHVfyBCcq8ipAko
Generated by Claude Code