{"content": "1 thing in the record have evidence against them \u2014 fact:34 names settings.json, which is gone \u2014 journal fact 34 strike \"\"", "meta": {"from": "journal"}} {"content": "fact 9 \u2014 Every public method on a controller becomes a journal command \u2014 The CLI is generated from the controllers: each public method of Controller, or of a typed controller, turns into journal . A helper added to the base class therefore becomes a command on every type \u2014 which is how journal handled and journal refuse came to exist, from the CRUD funnel and the refusal funnel. An internal helper on a controller is named with a leading underscore, as _shaped and _status already are, or it ships as a command nobody meant.; rule 50 \u2014 Everything the user does is doable in the viewer \u2014 Message 6710 (2026-09-23): the user never uses the CLI, only the UI; everything should be doable from the viewer. The journal commands are for agents; any action meant for the user (making boards, confirming, accepting, hosting, watching an agent) needs its place in the viewer.", "meta": {"from": "journal"}} {"content": "law L3 \u2014 Read narrowly - grep for the line, sed a range, head the file; never\u2026 \u2014 Everything a tool returns stays in the context for good and is paid for on every turn after it. Search before you read, read the range you need, and cap output with grep, head or tail. Read a whole file only when you need all of it.; rule 40 \u2014 A feature is named for what it is, never for its machinery \u2014 Messages 599, 600 and 703. A feature is a capability the user would name and would think of switching off. File tracking, a write gate, a phrase bank, a tree diff are services used inside a feature, not features of their own: they live in the feature they serve. Before adding a directory under features/, say what the user would call it; if the answer names a mechanism, it belongs inside something else. Report 16 holds the grouping this implies.; rule 46 \u2014 Only commit and push once the whole journal is proven to boot \u2014 Messages 2178 and 2179. A release that has not been started for real can crash every project that installs it, as 2.78.3 did for Codex and 2.84.0 did to project records. Before every commit and push: the full suite passes, including tests/test_it_boots.py, which installs a packed copy into a fresh project, launches Claude and Codex from it, writes a project record, upgrades again and checks the record survives. When a change touches launching, installing or upgrading, also start a real journal in a scratch project and close it properly afterwards, leaving no process behind.; rule 51 \u2014 Every finished feature is committed, pushed and released with a new\u2026 \u2014 Message 9207 (2026-09-24): when a new feature is ready, commit, push and publish a new tag. This is the user's standing word for releasing, so rule 44's only-when-the-user-says is met by it for finished features; fixes in between wait for the next feature or a patch the user asks for.", "meta": {"from": "journal"}} {"content": "rule 57 \u2014 Never merge the overnight refactor into main before its pull request\u2026 \u2014 Messages 15005, 15006, 15109, 15110 (2026-10-04): all refactor work goes on branch overnight-refactor and reaches the user as one pull request, which they read in the morning; nothing of it is merged into main until they say so. Hotfixes the user explicitly asks for go to main at once and are merged into the branch.; rule 61 \u2014 Features wait as pull requests until approved; only hotfixes merge\u2026 \u2014 Message 17118 (2026-10-06), after the overnight refactor merged as 2.252.0: start new work in a new branch, do not merge, write the pull request. Every pull request or new feature is parked until the user approves it. Hotfixes can be merged into main immediately (by a dispatched agent in a worktree of main, rule 60).; rule 64 \u2014 A finished feature is merged into main without waiting for approval \u2014 The user, message 17815 (2026-10-07): 'make sure that no pull requests are lingering on the repository. You may merge them into main... You are allowed to merge everything into main once the feature is completed.' This replaces rule 61's wait for approval: a feature still goes on its own branch, and once it is complete, tested and its whole suite passes, it is merged into main and released, and no pull request is left open.", "meta": {"from": "journal"}} {"content": "rule 41 \u2014 Keep moving, run the whole suite before every commit, never wait \u2014 The full suite runs in about seven seconds: .venv/bin/python -m pytest -q --timeout=300 -n auto. Run it before every commit instead of picking tests by name. Group rows that sit in the same code into one sitting: write them all, test once, commit once. And never wait, not for a subagent, a build, or an answer you can carry on without. Dispatch it and keep working. If you truly are waiting on something, say so in the work log.; rule 65 \u2014 Run only new and affected tests while working; the whole suite only\u2026 \u2014 The user, messages 17914 to 17917 (2026-10-07): 'stop running the whole test suite and wasting my time... please only run the new or affected tests, and then, whenever you are merging to main or publishing to main, you can run the full test suite.' Replaces rule 41's whole suite before every commit: on a feature branch, run the tests beside what changed (journal check touched, or the feature's test.py and the browser scenarios it touches); the whole suite runs once, before a merge into main and its release.; rule 66 \u2014 The journal never slows the agent down \u2014 The user, message 18990, after hooks timed out and waited on locks under load: the journal must never, ever decrease the performance of an agent. A hook answers at once with what decides the tool call; everything else runs after, in the background, and reaches the agent as a message. No hook waits on a lock it does not need.", "meta": {"from": "journal"}} {"content": "your command ran 33s in the foreground and was moved to the background \u2014 carry on with other work; you are told when it ends. Start a command you expect to take long in the background yourself", "meta": {"from": "journal"}} {"content": "your command ran 30s in the foreground and was moved to the background \u2014 carry on with other work; you are told when it ends. Start a command you expect to take long in the background yourself", "meta": {"from": "journal"}} {"content": "the await tag does this in one step \u2014 [!await] makes the rest of the turn what you wait for; [!await on=(\"\", \"helper:\")] waits on those; it runs only when it opens the last text of your turn", "meta": {"from": "journal"}} {"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 1 judged file since the\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 1 judged file since the last commit. Consider running `commandments judge --changes` to confirm they conform, and fix any sin at its SOURCE (don't launder a finding with a default/cast/null-check). This is a one-time nudge for this batch \u2014 if you've already judged, or these changes aren't worth a scan, just say so and carry on.", "meta": {"from": "journal"}} {"content": "your command ran 34s in the foreground and was moved to the background \u2014 carry on with other work; you are told when it ends. Start a command you expect to take long in the background yourself", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "your wait for Waiting for the test run to finish. is over, because you are\u2026 \u2014 say journal work await \"\" again if you are still only waiting", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "your command ran 32s in the foreground and was moved to the background \u2014 carry on with other work; you are told when it ends. Start a command you expect to take long in the background yourself", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "chat etiquette - a line from the journal is an instruction, not a message\u2026 \u2014 a turn that only handles a journal line needs no words: act on it, or say once in the chat what you wait on, then carry on; what the user needs to know still goes to the chat", "meta": {"from": "journal"}} {"content": "waiting: 2 unread todos 1, 2", "meta": {"from": "journal"}} {"content": "rule 60 \u2014 A hotfix is done by a dispatched agent in a worktree of main \u2014 Message 16836 (2026-10-06): the orchestrator cut a worktree under .claude/worktrees for a Codex hotfix, its session moved to a new environment and the user's messages stopped reaching it. The user: when working on a branch and a hotfix comes in, create a worktree of main and dispatch an agent to do that work. The orchestrator stays on its branch and in its environment, and never cds into another checkout.", "meta": {"from": "journal"}} {"content": "your chat talked about the journal's workings - \"to-do 1 is closed\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead", "meta": {"from": "journal"}}