{"content": "fact 28 \u2014 The designer agent type exists, so design work goes to a subagent \u2014 Since 2026-10-01 .claude/agents/designer.md (Dieter, Opus, Claude Design tools, read-only on the repository) is an agent type; rule 56 says design is a subagent's job, never a helper's.; rule 45 \u2014 No prose words as names in code - said, says, heard, spoke, told\u2026 \u2014 Messages 1360 and 1698. The user has said more than once that code must not read like prose: a variable, attribute, property or function is named for what it holds or does (text, command, labels, lines), never with a verb from a story. 'says' on the Design type (1360) and 'said = call.said.lower()' in features/recital.py (1698) are the examples. Rule 27 states the naming rule; this one carries the words, so writing one of them whispers it. Before writing a name, ask whether a reader who has never seen the code would know what it holds.; rule 58 \u2014 A design runs three critique rounds, then is built on a branch \u2014 Messages 17276 and 17281 (2026-10-06): the norm is a three-round cycle. Round by round, the designer designs (or revises), separate critic agents review the design through their lenses (the critic agent type, .claude/agents/critic.md: read-only, with a browser; one per lens, such as first-time, native, words and parity), and the designer adjusts it to their findings; three rounds in all. The three rounds stand in for the user's approval of the design: the user does not approve it. After the third round the design is built on a branch of its own, which ends in a pull request that waits for the user's approval (rule 61). Replaces message 15725's prototype approval.; rule 63 \u2014 A small design is drawn once and the user approves it, with no\u2026 \u2014 The user, messages 17628 and 17629 (2026-10-07), about the tooltip and waiting-status designs: 'This design round doesn't really need multiple rounds... I just want the designer agent to design it, and I will approve it.' Rule 58's three critique rounds are for large designs such as the phone app; a small one (a tooltip, a status word, one control) is drawn once by the designer, the link goes to the user, and it is built once the user approves it.; rule 68 \u2014 The orchestrator approves the designer's designs itself \u2014 Message 19718 (and 18972): whenever a designer subagent is sent out, here or on a remote, the orchestrator makes the final call on whether the design is right and approves it; it never waits for the user to. This replaces the user-approval step in rule 63, which only the user can strike.; rule 72 \u2014 Ship fixes as patches at once; batch features into a minor version \u2014 The user, messages 23885 and 23886 (2026-10-10): a bug fix, and any hotfix for an agent's bug, is released at once as a patch version. A new feature waits on its branch and goes out together with others in the next minor version, when enough has gathered to make one; installing every feature right away costs too much time. The orchestrator decides what is a patch and what is a minor.; 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 <noun> <method>. A helper added to the base class therefore becomes a command on every type \u2014 which is how journal <type> handled and journal <type> 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.; fact 34 \u2014 A hooks list in a checkout's .claude/settings.json stops every\u2026 \u2014 Seen 2026-10-08: since commit 707a82915 the committed .claude/settings.json held {\"hooks\": []}; current Claude Code answers a hooks value that is not an object with a SettingsWarning dialog, which a headless helper cannot answer, so helpers 183 and 184 exited before doing anything (their launch logs in .journal/runtime/launches/ show it). This repository's journal hooks live in settings.local.json; the committed settings.json stays {}.; rule 35 \u2014 Write clean code - one funnel per kind of operation, never the same\u2026 \u2014 Every kind of operation has one funnel: one method that creates, one that saves, one that refuses, one that formats. A second method that does the same thing under another name splits the behaviour, and the two drift apart. Before writing a method, search for the one that already does it and extend that. scripts/checks/funnels.py finds bodies written twice.; rule 55 \u2014 Always dispatch Codex helpers on gpt-6-sol \u2014 The user's word, message 13431: switch the codex agents to GPT-6-Sol and make it their default. ~/.codex/config.toml names it as the default model too.; rule 56 \u2014 Helpers are for work that writes; subagents read, research and design \u2014 The user, message 13464: there must be a clear distinction. A subagent can be dispatched for anything read-only: research, review, design. A helper is for actual work that writes, best in its own worktree when the work is separate. Dieter designing in Claude Design should have been a subagent, not a helper.; rule 71 \u2014 Always reuse a helper's or subagent's whole session, never only its\u2026 \u2014 The user, messages 23609 and 23614 (2026-10-10): workers are reused by their whole session, so they keep their context. A helper whose agent ended resumes its own session (to-do 3872); a fresh start under the same name wastes the user's tokens. It belongs in the journal application itself, not only this project.; fact 25 \u2014 A designer's install packs the whole tree, half-done server edits\u2026 \u2014 2026-09-25: Eames and Saul run python3 src/journal.py --root .journal upgrade after their viewer builds; it packs every file in src, so a server handler I was halfway through writing went live and raised on every PostToolUse hook. While designers work in parallel, keep server edits whole between tool calls (write and test in the scratchpad first), and reinstall after reverting anything.; rule 74 \u2014 Run the whole suite only for a minor; a patch runs its affected tests \u2014 Message 24581 (2026-10-10): the user forbade running the full suite except for a minor version; a patch release runs only the tests beside what changed. Replaces rule 65's whole suite before every merge to main for patches.", "meta": {"from": "journal"}}
{"content": "the log tag does this in one step \u2014 [!log:N] makes the turn itself the log entry; it runs only when it opens the last text of your turn; work 1 is still open, with nothing logged \u2014 journal work log 1 \"<what was decided or done, and why>\" \u2014 then journal work end 1 --how \"<what landed>\", or journal work park 1 \"<why it waits>\"; main moved since your worktree was cut \u2014 It gained 5 commits (51b3518a4 A hook that cannot reach the server keeps its event quietly, with no notice in the agent's transcript; 74c4cb42e Version 2.269.1; 87dcc496c The mascot imports the blink it uses; 358211c47 A plan under review says on its card and in its inspector how many reviewers are still reviewing; e8db5a1b9 A plugin service whose when-check exits 126 or 127, or cannot run or answer, is listed as failing with the command's own words, and the watcher tells it once, never as not needed). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; main moved since your worktree was cut \u2014 It gained 6 commits (f88874fea Version 2.269.2; 51b3518a4 A hook that cannot reach the server keeps its event quietly, with no notice in the agent's transcript; 74c4cb42e Version 2.269.1; 87dcc496c The mascot imports the blink it uses; 358211c47 A plan under review says on its card and in its inspector how many reviewers are still reviewing; and 1 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; that Write call returned 148,437 characters, the largest this session \u2014 It stays in the context for good. If you were looking for one thing in it, the next read can be narrower: grep for the line, sed a range, head the file.; main moved since your worktree was cut \u2014 It gained 7 commits (6691d6e71 A session start asks for the untagged files in one line when there are many instead of writing a row for each, and finds them again only when the rows of a type changed, so the work left after a hook answers is a fifth of what it was; f88874fea Version 2.269.2; 51b3518a4 A hook that cannot reach the server keeps its event quietly, with no notice in the agent's transcript; 74c4cb42e Version 2.269.1; 87dcc496c The mascot imports the blink it uses; and 2 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; main moved since your worktree was cut \u2014 It gained 8 commits (4b9615ed1 Version 2.269.3; 6691d6e71 A session start asks for the untagged files in one line when there are many instead of writing a row for each, and finds them again only when the rows of a type changed, so the work left after a hook answers is a fifth of what it was; f88874fea Version 2.269.2; 51b3518a4 A hook that cannot reach the server keeps its event quietly, with no notice in the agent's transcript; 74c4cb42e Version 2.269.1; and 3 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; 14 facts standing, read them \u2014 9. Every public method on a controller becomes a journal command; 13. This live session runs the installed copy in .journal/journal.pyz; 18. cProfile inflates the slow-request profiles about tenfold; 20. A slim supervisor holds the agent and a worker reloads on every build; 23. Every upgrade brings system sequences and their triggers in line with the code; 24. An answer followed by tool calls can be missing from Claude's transcript; 25. A designer's install packs the whole tree, half-done server edits included; 26. Claude Code reads agent profiles when a session starts; 27. Running src/journal.py against the live .journal root starts a second server; 28. The designer agent type exists, so design work goes to a subagent; 29. Codex's transcript records the end of every exec session, polled or not; 30. The tunler server refuses TLS for any subdomain without a tunnel; 34. A hooks list in a checkout's .claude/settings.json stops every helper at start; 36. Announcement artwork is flat vector on near-black with one indigo accent; 47 rules in force, read them \u2014 7. journal disable must only ever be run because the user explicitly asked for it,; 9. Research dispatched to a subagent ends in a REPORT for the user, compiled by the; 13. A title names the thing in at most 80 characters and never explains it with a co; 14. A small journal capability is a feature under features, with at most one test; 17. Do not restart the viewer for frontend-only changes; 18. Provider-specific code belongs in providers, never features; 19. Providers report facts; features decide behavior; 22. File distinct user work requests immediately; 27. Name a declaration with the word a reader already knows; 30. The viewer has one API client, and every piece of it does one job; 31. Every finding a reviewing agent reports becomes its own to-do; 35. Write clean code - one funnel per kind of operation, never the same method twice; 36. Clean, DRY, idiomatic before it is committed, never after it is complained about; 37. Close every to-do explicitly with todo done or a Journal commit trailer; 38. Never change the git branch until the user says so, by name; 39. Use only registered exclamation response tags; 40. A feature is named for what it is, never for its machinery; 41. Keep moving, run the whole suite before every commit, never wait; 42. Every user-facing text passes the formatters before it leaves the server; 43. A request or hook over its budget is fixed before the next release; 45. No prose words as names in code - said, says, heard, spoke, told, shown, became; 46. Only commit and push once the whole journal is proven to boot; 47. The journal sets itself up once, when the server starts, never per command; 48. The viewer is built from its component library, and pages only compose it; 49. A dialog whose content grows keeps one fixed height, and its content scrolls; 50. Everything the user does is doable in the viewer; 51. Every finished feature is committed, pushed and released with a new version tag; 52. A chat mark for something the user did sits on the user's side; 54. Settings and feature switches are read at boot and on change, never per call; 55. Always dispatch Codex helpers on gpt-6-sol; 56. Helpers are for work that writes; subagents read, research and design; 57. Never merge the overnight refactor into main before its pull request is approved; 58. A design runs three critique rounds, then is built on a branch; 59. Every viewer heading and label says plainly what it is about; 60. A hotfix is done by a dispatched agent in a worktree of main; 61. Features wait as pull requests until approved; only hotfixes merge at once; 62. The voice profile shapes only the agent's chat speech, never code or text; 63. A small design is drawn once and the user approves it, with no critique rounds; 64. A finished feature is merged into main without waiting for approval; 65. Run only new and affected tests while working; the whole suite only before main; 66. The journal never slows the agent down; 68. The orchestrator approves the designer's designs itself; 70. Release fixes for transportklok-workspace reports at once, without the suite; 71. Always reuse a helper's or subagent's whole session, never only its name; 72. Ship fixes as patches at once; batch features into a minor version; 74. Run the whole suite only for a minor; a patch runs its affected tests; 76. An environment has one live session; a second asks the user to take over; main moved since your worktree was cut \u2014 It gained 10 commits (70d2e77c6 A resume asked for an agent that is not paused is taken and not said, so the update's resume line is typed once, and a pause left on a row for longer than any update takes no longer keeps the agents being asked to resume every second; dcaec1d74 A session that starts on an environment where another is live waits in an environment of its own and the user is asked whether to take the busy one over, which unbinds the session that was there, so an environment has one live session; 4b9615ed1 Version 2.269.3; 6691d6e71 A session start asks for the untagged files in one line when there are many instead of writing a row for each, and finds them again only when the rows of a type changed, so the work left after a hook answers is a fifth of what it was; f88874fea Version 2.269.2; and 5 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; main moved since your worktree was cut \u2014 It gained 11 commits (47752a984 Version 2.269.4; 70d2e77c6 A resume asked for an agent that is not paused is taken and not said, so the update's resume line is typed once, and a pause left on a row for longer than any update takes no longer keeps the agents being asked to resume every second; dcaec1d74 A session that starts on an environment where another is live waits in an environment of its own and the user is asked whether to take the busy one over, which unbinds the session that was there, so an environment has one live session; 4b9615ed1 Version 2.269.3; 6691d6e71 A session start asks for the untagged files in one line when there are many instead of writing a row for each, and finds them again only when the rows of a type changed, so the work left after a hook answers is a fifth of what it was; and 6 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; main moved since your worktree was cut \u2014 It gained 12 commits (0794b725b The two tests of a session that starts beside a live one are one test, so the file holds ten; 47752a984 Version 2.269.4; 70d2e77c6 A resume asked for an agent that is not paused is taken and not said, so the update's resume line is typed once, and a pause left on a row for longer than any update takes no longer keeps the agents being asked to resume every second; dcaec1d74 A session that starts on an environment where another is live waits in an environment of its own and the user is asked whether to take the busy one over, which unbinds the session that was there, so an environment has one live session; 4b9615ed1 Version 2.269.3; and 7 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; main moved since your worktree was cut \u2014 It gained 15 commits (76be31797 The menu change keeps class members before methods and holds no nullable lookup; fd72be623 The asked-agent command is built once per menu; c4414f915 An unknown terminal menu is answered by a dispatched agent, and the choice is remembered; 0794b725b The two tests of a session that starts beside a live one are one test, so the file holds ten; 47752a984 Version 2.269.4; and 10 more). Rebase onto main in /Users/jessegall/projects/agent-journal/.claude/worktrees/main-signor-bernini before you report.; work 1 is still open \u2014 end it or park it before you stop: journal work end 1 --how \"<what landed>\", or journal work park 1 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "rule 36 \u2014 Clean, DRY, idiomatic before it is committed, never after it is\u2026 \u2014 The user should never be the one who finds duplication, dead code, a clumsy name or a pattern the codebase does not use. Read the diff before every commit as a reviewer would, and fix what is not clean then, not in a follow-up after a complaint.; 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 76 \u2014 An environment has one live session; a second asks the user to take\u2026 \u2014 The user's ruling, 2026-10-11, refined in his own words: 'we shouldn't be able to have multiple sessions on an environment. The journal should tell the user, Hey, there's a session already here. What do you want to do? Do you want to take over? That means that the other session is unbound to that environment.' So a session starting on an environment that already has a live one does not take it silently and does not stop the other by itself: the journal asks the user what to do. On take over, the session that was there is unbound from the environment and the new one holds it; otherwise the new session does not get the environment. It came after his messages 25226, 25229 and 25230 reached a session he was not watching, while environment main held three live sessions at once.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you commit \u2014 you've changed 5 judged files since the\u2026 \u2014 Code Commandments \u2014 before you commit: you've changed 5 judged files 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": "Code Commandments \u2014 before you commit \u2014 you've changed 3 judged files since the\u2026 \u2014 Code Commandments \u2014 before you commit: you've changed 3 judged files 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"}}