{"content": "todo 1 next", "meta": {"from": "journal"}}
{"content": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "meta": {"from": "journal"}}
{"content": "that Bash call returned 20,806 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.", "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.", "meta": {"from": "journal"}}
{"content": "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.; fact 30 \u2014 The tunler server refuses TLS for any subdomain without a tunnel \u2014 Seen 2026-10-04 in the server's docker logs (ssh root@tunler.jessegall.nl, container tunler): 'TLS handshake error ... host \"journal-probe.tunler.jessegall.nl\" not allowed'. A made-up subdomain never answers even when the server is healthy; probe https://tunler.jessegall.nl/ for the server itself. Root SSH to the server works.", "meta": {"from": "journal"}}
{"content": "rule 49 \u2014 A dialog whose content grows keeps one fixed height, and its content\u2026 \u2014 Message 5361, after asking more than once: a dialog that shows output as it arrives (install, update, logs) opens at its final height and never jumps; only its content scrolls.", "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; fact 13 \u2014 This live session runs the installed copy in .journal/journal.pyz \u2014 The running journal (server, hooks, CLI) runs from .journal/journal.pyz with its viewer and skills in .journal/src, never from the repo. A change in the repo reaches it only through python3 src/journal.py --root .journal upgrade, which packs the zip again. A commit alone changes nothing that is running.; 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.", "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": "rule 54 \u2014 Settings and feature switches are read at boot and on change, never\u2026 \u2014 The user, message 13349: the application boots, determines every feature and setting once, and re-evaluates only when something changes, such as a setting or a plugin. Never lazy-load settings.", "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.; rule 27 \u2014 Name a declaration with the word a reader already knows \u2014 An attribute, a variable or a field gets the ordinary programming word for what it holds, not an evocative one. was, heard and alone were poetry; aliases, notify_actions and urgent_actions are what they are. The test: could a reader who has never seen this codebase guess what it holds from the name alone? Prose belongs in the help text and the abstract, where it is read as prose. This does not license abbreviations \u2014 a plain word in full, not a short one.; 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.", "meta": {"from": "journal"}}
{"content": "rule 58 \u2014 The user tests a design's clickable prototype and approves it before\u2026 \u2014 Message 15725 (2026-10-05): 'ask Dieter to create an interactive prototype! I want to test it first and give feedback before giving it my go', and remove any fact or rule that conflicts. Replaces rule 53's 'the designer decides'. The designer still runs one critique round (messages 12800, 13475) and revises before showing the prototype; then the user clicks through it, gives feedback, and only the user's go starts the build.", "meta": {"from": "journal"}}
{"content": "rule 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.", "meta": {"from": "journal"}}
{"content": "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.", "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 <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 23 \u2014 Every upgrade brings system sequences and their triggers in line\u2026 \u2014 install.py runs ship_sequences after the migrations on each upgrade, so features/sequences/shipped.py is the whole source: change its wording and the next upgrade updates every journal, no migration needed. Shipped rows carry system=True and are read-only for everyone but SYSTEM (controllers/base.py _shipped).", "meta": {"from": "journal"}}
{"content": "work 1 in hand \u2014 Build the approved Settings, Skills, Helpers and lists redesign \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 the files changed since the last check (`details.py`, `deta\u2026 \u2014 Code Commandments \u2014 the files changed since the last check (`details.py`, `details.py`, `details.py`, `groups.py`, `details.py`) breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 python-placeholder-filled-data at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/features/groups.py:69 \u00b7 LOAD the skill `commandments-python-type-honesty` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.", "meta": {"from": "journal"}}
{"content": "rule 44 \u2014 Release a new version after every significant change \u2014 The user, message 13219 (2026-10-01): 'Don't forget to release new versions every time you do something significant.' Bump VERSION, add a CHANGELOG entry, push main and the tag. Replaces message 5929's release-on-request.; 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": "fact 18 \u2014 cProfile inflates the slow-request profiles about tenfold \u2014 The faults feature writes a profile when a request passes its budget, and the profile is taken with cProfile, which adds per-call overhead. On 2026-09-22 /api/summary profiled at 58ms with 48ms inside Resource.fork's deep copy; with the profiler off the same call ran in 2 to 7ms. Read the profile for where the time goes in relative terms, then time the call with curl before changing anything.", "meta": {"from": "journal"}}
{"content": "work 1 in hand \u2014 Build the approved Settings, Skills, Helpers and lists redesign \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "rule 52 \u2014 A chat mark for something the user did sits on the user's side \u2014 Message 10960 (2026-09-25): marks for the user's own actions, such as answering a question, are right-aligned like the user's messages. A mark is put there by giving its card side=user.", "meta": {"from": "journal"}}
{"content": "rule 38 \u2014 Never change the git branch until the user says so, by name \u2014 The work happens on the branch the user named. That was main until message 5929 and question 80 (2026-09-23), which moved the sins work to the branch sins. Do not create, switch to or merge any other branch unless the user names it in their own words.", "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": "your command ran 31s 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": "fact 27 \u2014 Running src/journal.py against the live .journal root starts a\u2026 \u2014 Seen 2026-10-01: with VERSION bumped in the tree, src/journal.py --root .journal saw the live server as another build and started a new one on a new port (8431, 8432), and the user's tabs kept losing connection. Run source builds against a throwaway or demo root (~/projects/demo-crumb/.journal), never the live one, until the release is installed.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 the files changed since the last check (`Segmented.vue`, `S\u2026 \u2014 Code Commandments \u2014 the files changed since the last check (`Segmented.vue`, `SettingsPage.vue`) breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 deep-nested at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/pages/SettingsPage.vue:200 \u00b7 LOAD the skill `commandments-frontend-vue-components` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.", "meta": {"from": "journal"}}
{"content": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 `SettingsPage.vue`, changed since the last check, breaks a\u2026 \u2014 Code Commandments \u2014 `SettingsPage.vue`, changed since the last check, breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 deep-nested at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/pages/SettingsPage.vue:201 \u00b7 LOAD the skill `commandments-frontend-vue-components` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.", "meta": {"from": "journal"}}
{"content": "work 1 in hand \u2014 Build the approved Settings, Skills, Helpers and lists redesign \u2014 if this is not what you are doing, end it or park it and start the work you are in; 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 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.", "meta": {"from": "journal"}}
{"content": "rule 27 \u2014 Name a declaration with the word a reader already knows \u2014 An attribute, a variable or a field gets the ordinary programming word for what it holds, not an evocative one. was, heard and alone were poetry; aliases, notify_actions and urgent_actions are what they are. The test: could a reader who has never seen this codebase guess what it holds from the name alone? Prose belongs in the help text and the abstract, where it is read as prose. This does not license abbreviations \u2014 a plain word in full, not a short one.", "meta": {"from": "journal"}}
{"content": "fact 13 \u2014 This live session runs the installed copy in .journal/journal.pyz \u2014 The running journal (server, hooks, CLI) runs from .journal/journal.pyz with its viewer and skills in .journal/src, never from the repo. A change in the repo reaches it only through python3 src/journal.py --root .journal upgrade, which packs the zip again. A commit alone changes nothing that is running.; rule 49 \u2014 A dialog whose content grows keeps one fixed height, and its content\u2026 \u2014 Message 5361, after asking more than once: a dialog that shows output as it arrives (install, update, logs) opens at its final height and never jumps; only its content scrolls.; 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.", "meta": {"from": "journal"}}
{"content": "your command ran 31s 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": "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.", "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": "rule 54 \u2014 Settings and feature switches are read at boot and on change, never\u2026 \u2014 The user, message 13349: the application boots, determines every feature and setting once, and re-evaluates only when something changes, such as a setting or a plugin. Never lazy-load settings.", "meta": {"from": "journal"}}
{"content": "12 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 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; 44. Release a new version after every significant change; 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. The user tests a design's clickable prototype and approves it before the build", "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 <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.; 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 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.; 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.", "meta": {"from": "journal"}}
{"content": "fact 23 \u2014 Every upgrade brings system sequences and their triggers in line\u2026 \u2014 install.py runs ship_sequences after the migrations on each upgrade, so features/sequences/shipped.py is the whole source: change its wording and the next upgrade updates every journal, no migration needed. Shipped rows carry system=True and are read-only for everyone but SYSTEM (controllers/base.py _shipped).; 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.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you commit \u2014 you've changed 70 judged files since th\u2026 \u2014 Code Commandments \u2014 before you commit: you've changed 70 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": "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": "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": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "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 chat talked about the journal's workings - \"Still waiting\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead", "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.", "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": "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 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": "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.", "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": "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; you ran the same check 3 times in a row - until grep -q END\u2026 \u2014 if you are waiting for something to change, say journal work await \"<what you wait for>\" and end your turn: you are asked to look again every five minutes, and a background command tells you itself when it ends. Keep checking only if each look moves the work on.", "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=(\"<id>\", \"helper:<n>\")] 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 26 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 26 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": "waiting: 1 unread todo 1", "meta": {"from": "journal"}}
{"content": "your command ran 31s 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 wait for the phase 4 full suite, queued in the shared suite lock behind\u2026 \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "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": "your command ran 31s 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 wait for the targeted test rerun for the two failing tests is over\u2026 \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 4 judged files since th\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 4 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": "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": "your chat talked about the journal's workings - \"I'm still waiting\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead", "meta": {"from": "journal"}}
{"content": "your wait for the phase 5 full suite is over, because you are working again \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "fact 23 \u2014 Every upgrade brings system sequences and their triggers in line\u2026 \u2014 install.py runs ship_sequences after the migrations on each upgrade, so features/sequences/shipped.py is the whole source: change its wording and the next upgrade updates every journal, no migration needed. Shipped rows carry system=True and are read-only for everyone but SYSTEM (controllers/base.py _shipped).", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 20 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 20 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": "your wait for the phase 6 full suite is over, because you are working again \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "rule 37 \u2014 Close every to-do explicitly with todo done or a Journal commit\u2026 \u2014 Ending work does not close its row. A to-do is closed by journal todo done <n> --how, or by a commit whose message carries Journal: todos done <n> at column 0, several numbers separated by commas. A row left open after its work landed misleads the next session and auto mode.", "meta": {"from": "journal"}}
{"content": "rule 58 \u2014 The user tests a design's clickable prototype and approves it before\u2026 \u2014 Message 15725 (2026-10-05): 'ask Dieter to create an interactive prototype! I want to test it first and give feedback before giving it my go', and remove any fact or rule that conflicts. Replaces rule 53's 'the designer decides'. The designer still runs one critique round (messages 12800, 13475) and revises before showing the prototype; then the user clicks through it, gives feedback, and only the user's go starts the build.", "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"}}
{"content": "rule 44 \u2014 Release a new version after every significant change \u2014 The user, message 13219 (2026-10-01): 'Don't forget to release new versions every time you do something significant.' Bump VERSION, add a CHANGELOG entry, push main and the tag. Replaces message 5929's release-on-request.; 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": "Thanks, good work. Please rebase helper-main-mies-buildwright onto overnight-refactor (it gained c05e88b3, c5fa6b0b, 5068f90a). On a conflict in src/web/dist, take neither side: rebuild with npx vite build in src/web and commit the result. Then tell me it's rebased, so I can take your commits. Dieter is checking the build against the prototype; any fixes it finds come to you afterwards.", "meta": {"from": "main"}}
{"content": "work 2 in hand \u2014 Rebase the six redesign commits onto overnight-refactor and\u2026 \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "work 2 is still open, with nothing logged \u2014 journal work log 2 \"<what was decided or done, and why>\" \u2014 then journal work end 2 --how \"<what landed>\", or journal work park 2 \"<why it waits>\"", "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", "meta": {"from": "journal"}}
{"content": "work 2 is still open \u2014 end it or park it before you stop: journal work end 2 --how \"<what landed>\", or journal work park 2 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "Your commits are taken onto overnight-refactor (now 119a2ab5, pushed). Dieter checked your build against the prototype; please fix these, in this order, after rebasing your branch onto 119a2ab5. Commit as you go, then report. MUST: (1) pages/SettingsPage.vue uses SettingGroup at line 179 without importing it, so on a phone every group opens empty. (2) kit/TimingChip.vue: the unit row runs past 300 px and the 'Or once, when' list past 250 px; make both wrapping Segmented controls like the prototype, so the default line and Reset show. (3) resource/ResourceCard.vue: 'Ships with the journal' sits on top of the '3 steps \u00b7 starts when' line; give it its own place. (4) ResourceCard.vue:15 shows raw event names ('starts when a board.finished'); use plain words ('when a board is closed', 'when a ticket's agent is stuck'). (5) src/skills.py lines 98, 114, 116 add a second full stop after abstracts that already end in one. SHOULD: (6) kit/SettingControl.vue ~line 64: choices keep their natural width (align-self: flex-start). (7) The update setting must be Dieter's option A, the four choices: patches, minor, major and always (the user chose Dieter's pick). features/auto_update/check.py gives Always its own meaning. (8) Stop the journal shows only the red card, without the heading, line and divider repeating it. (9) The Always on rows get their hints back in domain/settingsCatalog.js. (10) pages/PluginSettings.vue: same left column and bordered content as the other tabs, plugin heading with version and On switch, up to four options as Segmented (PluginSetting.vue:37). (11) HelperList: the working row's button reads 'Stop its agent'; closed rows say 'Closed 2h ago'. Also clear the two deep-data-reach sins at HelperList.vue:45 and :84. (12) Settings search: no tab underline while results span every tab; small uppercase 'IN FEATURES' labels, not large headings. MINOR: (13) Agent group order: Call you by a title, Work modes, Keep journal talk out of the chat, Brief each new session, Run commands from tags; text fields max 420 px. (14) Skills: heading '21 skills \u00b7 3 loaded here', 'Ask the agent to load it now' as primary, hint under 'Load at session start', full-width search on a phone. (15) Phone: a tab with one group opens it directly. (16) Sharing: the tunler block gets a heading and card; Environments with no rows says there are none yet. (17) A closed to-do reads 'Closed just now'. Dieter's screenshots are in /private/tmp/claude-501/-Users-jessegall-projects-agent-journal/c35e7375-7ce3-4bc3-b1ae-7cdf73bd1488/scratchpad/ (v-*.png desktop, p-*.png phone). They are to-dos 2790-2806 in the main list; say which numbers each commit closes.", "meta": {"from": "main"}}
{"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.", "meta": {"from": "journal"}}
{"content": "rule 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.", "meta": {"from": "journal"}}
{"content": "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.", "meta": {"from": "journal"}}
{"content": "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.", "meta": {"from": "journal"}}
{"content": "rule 27 \u2014 Name a declaration with the word a reader already knows \u2014 An attribute, a variable or a field gets the ordinary programming word for what it holds, not an evocative one. was, heard and alone were poetry; aliases, notify_actions and urgent_actions are what they are. The test: could a reader who has never seen this codebase guess what it holds from the name alone? Prose belongs in the help text and the abstract, where it is read as prose. This does not license abbreviations \u2014 a plain word in full, not a short one.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 the files changed since the last check (`SettingGroup.vue`,\u2026 \u2014 Code Commandments \u2014 the files changed since the last check (`SettingGroup.vue`, `SettingControl.vue`) breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 control-flow-on-element at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/kit/SettingGroup.vue:19; control-flow-on-element at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/kit/SettingGroup.vue:44 \u00b7 LOAD the skill `commandments-frontend-vue-control-flow` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.; rule 52 \u2014 A chat mark for something the user did sits on the user's side \u2014 Message 10960 (2026-09-25): marks for the user's own actions, such as answering a question, are right-aligned like the user's messages. A mark is put there by giving its card side=user.", "meta": {"from": "journal"}}
{"content": "work 3 in hand \u2014 Fix Dieter's findings 1 to 17 on the redesign \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "meta": {"from": "journal"}}
{"content": "work 3 in hand \u2014 Fix Dieter's findings 1 to 17 on the redesign \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "fact 30 \u2014 The tunler server refuses TLS for any subdomain without a tunnel \u2014 Seen 2026-10-04 in the server's docker logs (ssh root@tunler.jessegall.nl, container tunler): 'TLS handshake error ... host \"journal-probe.tunler.jessegall.nl\" not allowed'. A made-up subdomain never answers even when the server is healthy; probe https://tunler.jessegall.nl/ for the server itself. Root SSH to the server works.", "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.", "meta": {"from": "journal"}}
{"content": "Please rebase helper-main-mies-buildwright onto overnight-refactor 8f14c3f9 (pushed). On a src/web/dist conflict take neither side; rebuild with npx vite build and commit it. Tell me when it's rebased so I can take your 17 fixes.", "meta": {"from": "main"}}
{"content": "the end tag does this in one step \u2014 [!end:N] makes the turn itself what landed; it runs only when it opens the last text of your turn; rule 37 \u2014 Close every to-do explicitly with todo done or a Journal commit\u2026 \u2014 Ending work does not close its row. A to-do is closed by journal todo done <n> --how, or by a commit whose message carries Journal: todos done <n> at column 0, several numbers separated by commas. A row left open after its work landed misleads the next session and auto mode.", "meta": {"from": "journal"}}
{"content": "Taken, thank you: your 17 fixes are on overnight-refactor (e4db4996). Three more in your files, from Ruth's rule audit; please fix them on your branch (rebase onto e4db4996 first) and report: main to-do 2816, rename the viewer's 'shown' names for what they hold (PluginsPage.vue:32 'shown' is a preview; also composables closing.js:7, terminal.js:9, promised.js:43, revisions.js:83, chat/Compose.vue:47); to-do 2818, use the kit's Btn instead of raw <button> in chat/HelperRow.vue (helper-what, helper-more), pages/SettingsPage.vue (settings-back) and pages/SkillsRow.vue (skill-open); to-do 2819, one kit ResetButton for the two setting-reset buttons and timing-reset.", "meta": {"from": "main"}}
{"content": "rule 49 \u2014 A dialog whose content grows keeps one fixed height, and its content\u2026 \u2014 Message 5361, after asking more than once: a dialog that shows output as it arrives (install, update, logs) opens at its final height and never jumps; only its content scrolls.", "meta": {"from": "journal"}}
{"content": "12 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; context 50% full, decide \u2014 a fact is what a later reader would get wrong without, a rule binds every environment, or nothing \"<why>\"; 34 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; 44. Release a new version after every significant change; 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. The user tests a design's clickable prototype and approves it before the build", "meta": {"from": "journal"}}
{"content": "work 5 is still open, with nothing logged \u2014 journal work log 5 \"<what was decided or done, and why>\" \u2014 then journal work end 5 --how \"<what landed>\", or journal work park 5 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 17 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 17 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": "work 5 is still open \u2014 end it or park it before you stop: journal work end 5 --how \"<what landed>\", or journal work park 5 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "work 5 is still open \u2014 end it or park it before you stop: journal work end 5 --how \"<what landed>\", or journal work park 5 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "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.", "meta": {"from": "journal"}}
{"content": "rule 27 \u2014 Name a declaration with the word a reader already knows \u2014 An attribute, a variable or a field gets the ordinary programming word for what it holds, not an evocative one. was, heard and alone were poetry; aliases, notify_actions and urgent_actions are what they are. The test: could a reader who has never seen this codebase guess what it holds from the name alone? Prose belongs in the help text and the abstract, where it is read as prose. This does not license abbreviations \u2014 a plain word in full, not a short one.", "meta": {"from": "journal"}}
{"content": "Thanks, I'll take those three once my current gate lands. Please also clear the remaining 'shown' names you found (chat/pins.js, QuestionOverlay.vue, DumpWindow.vue, UpdateOverlay.vue, AgentBarViews.vue), so rule 45 is clean across the viewer, as one more commit on top. Tell me when it's in.", "meta": {"from": "main"}}
{"content": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "meta": {"from": "journal"}}
{"content": "When the remaining renames are committed, rebase onto overnight-refactor 82bd5289 (dist conflicts: rebuild, as before), then tell me; I'll take all four of your commits together.", "meta": {"from": "main"}}
{"content": "your command ran 31s 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": "you ran the same check 3 times in a row - cd\u2026 \u2014 if you are waiting for something to change, say journal work await \"<what you wait for>\" and end your turn: you are asked to look again every five minutes, and a background command tells you itself when it ends. Keep checking only if each look moves the work on.", "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.", "meta": {"from": "journal"}}
{"content": "work 6 in hand \u2014 Rename the remaining shown names in the viewer \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "work 6 is still open \u2014 end it or park it before you stop: journal work end 6 --how \"<what landed>\", or journal work park 6 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 64 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 64 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": "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; your chat talked about the journal's workings - \"I'm still waiting\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead", "meta": {"from": "journal"}}
{"content": "your wait for the full suite on the shown renames is over, because you are\u2026 \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "Thanks. One more rebase please, onto overnight-refactor baae65fd (just pushed; it touched kit/Diff.vue and kit/MarkedText.vue and some tests), then tell me and I'll take all of them at once.", "meta": {"from": "main"}}
{"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.", "meta": {"from": "journal"}}
{"content": "the end tag does this in one step \u2014 [!end:N] makes the turn itself what landed; it runs only when it opens the last text of your turn", "meta": {"from": "journal"}}
{"content": "work deferred in words, not parked \u2014 \"after this\" is the title of a to-do: journal todo create \"<title>\" --brief, then say so", "meta": {"from": "journal"}}
{"content": "todo 2 next; 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.; 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.", "meta": {"from": "journal"}}
{"content": "your chat talked about the journal's workings - \"nothing pending\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead; todo 2 next", "meta": {"from": "journal"}}
{"content": "todo 2 next; 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 58 \u2014 The user tests a design's clickable prototype and approves it before\u2026 \u2014 Message 15725 (2026-10-05): 'ask Dieter to create an interactive prototype! I want to test it first and give feedback before giving it my go', and remove any fact or rule that conflicts. Replaces rule 53's 'the designer decides'. The designer still runs one critique round (messages 12800, 13475) and revises before showing the prototype; then the user clicks through it, gives feedback, and only the user's go starts the build.", "meta": {"from": "journal"}}
{"content": "New build, Jesse approved it: Dieter's agent inspector redesign (main to-do 2833). The prototype, with its spec page and build spec, is /private/tmp/claude-501/-Users-jessegall-projects-agent-journal/c35e7375-7ce3-4bc3-b1ae-7cdf73bd1488/scratchpad/insp/Agent inspector prototype.html (also https://claude.ai/design/p/039284dd-8329-4076-a1d2-222e3c8d498e?file=Agent+inspector+prototype.html). Jesse's pick is A: one inspector for every agent kind (main, helper, ticket and plan agents, subagents), opened as a large dialog. Today the main agent opens resource/AgentPage.vue and the others agents/AgentHome.vue: make them one. Follow the spec: header with state in words, task as title, one facts line (Byline), actions in the approved Helpers wording (Stop its agent, Remove helper and its working copy, Pause/Resume its agent for the main one); bands for what needs you; tabs from TabBar (Chat, Transcript, Files changed, Terminal, History, Subagents as each kind has them); subagents open inside their parent with a way back; a large Dialog size added to the kit. Also fold in main to-do 2835: the inspector's chat loads older rows as you scroll up (composables/scrollback.js), since the polls now ask for one page. First rebase onto overnight-refactor e9c87c16. Build the viewer (npx vite build in src/web) and commit dist with each change. Check it in a browser against a scratch journal with a helper row, like last time. Run the full suite, commit with plain messages and no trailers, and report with the to-dos each commit closes. Dieter will check it against the prototype after.", "meta": {"from": "main"}}
{"content": "rule 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.; rule 49 \u2014 A dialog whose content grows keeps one fixed height, and its content\u2026 \u2014 Message 5361, after asking more than once: a dialog that shows output as it arrives (install, update, logs) opens at its final height and never jumps; only its content scrolls.", "meta": {"from": "journal"}}
{"content": "fact 24 \u2014 An answer followed by tool calls can be missing from Claude's\u2026 \u2014 Seen 2026-09-24 for messages 9391-9404: text blocks opening with [!reply:n] that were followed by tool calls never appeared in the session's jsonl (only thinking and tool_use rows did), so the journal never saw them and the replies were lost. When a turn goes on after answering, send the answer with journal message reply <n> \"<text>\" instead of the tag.", "meta": {"from": "journal"}}
{"content": "law L1 \u2014 Every subagent dispatch names its model and chooses the least\u2026 \u2014 Use a fast, economical model for mechanical work with a known answer, a capable general model for careful implementation, and the strongest model only when the task turns on difficult judgement. Inheriting the orchestrator's model is not a model choice. If the dispatch API cannot accept a model, that operation is exempt.; law L2 \u2014 Every subagent is bound to a concrete job; never dispatch a generic\u2026 \u2014 Use the most specific available agent type whose declared purpose matches the assignment. On providers without agent types, give the dispatch a concrete task name and bounded prompt. If no suitable specialization exists, keep the work in the main agent instead of manufacturing an unscoped helper.; law L4 \u2014 Follow-up work goes back to the subagent that did the first part\u2026 \u2014 A subagent that drew a design, wrote the code or ran the research keeps what it learned. When the user asks for a change to its work, continue that subagent with a message rather than dispatching a new one that has to rediscover everything; start fresh only when the earlier one is gone or the new work is unrelated.; law L5 \u2014 Every subagent dispatch names the agent - a human name, a little\u2026 \u2014 A name is how the user and the chat tell subagents apart and how they are messaged later; an id or a task line is not a name. Start the dispatch's description with the name, a colon, then the task, such as \"Dr. Einstein: profile the slow hooks\" or \"Coco Rams: draw the plan card\". A designer can borrow from famous designers, a researcher from famous scientists, mixed up for fun.", "meta": {"from": "journal"}}
{"content": "work 8 in hand \u2014 Build the agent inspector redesign as one large dialog \u2014 if this is not what you are doing, end it or park it and start the work you are in; 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.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 `AgentInspector.vue`, changed since the last check, breaks\u2026 \u2014 Code Commandments \u2014 `AgentInspector.vue`, changed since the last check, breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 deep-data-reach at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/agents/AgentInspector.vue:188; deep-data-reach at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/agents/AgentInspector.vue:193; deep-data-reach at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/agents/AgentInspector.vue:204 (+1 more) \u00b7 LOAD the skill `commandments-frontend-vue-components` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.", "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", "meta": {"from": "journal"}}
{"content": "fact 13 \u2014 This live session runs the installed copy in .journal/journal.pyz \u2014 The running journal (server, hooks, CLI) runs from .journal/journal.pyz with its viewer and skills in .journal/src, never from the repo. A change in the repo reaches it only through python3 src/journal.py --root .journal upgrade, which packs the zip again. A commit alone changes nothing that is running.", "meta": {"from": "journal"}}
{"content": "rule 38 \u2014 Never change the git branch until the user says so, by name \u2014 The work happens on the branch the user named. That was main until message 5929 and question 80 (2026-09-23), which moved the sins work to the branch sins. Do not create, switch to or merge any other branch unless the user names it in their own words.", "meta": {"from": "journal"}}
{"content": "rule 52 \u2014 A chat mark for something the user did sits on the user's side \u2014 Message 10960 (2026-09-25): marks for the user's own actions, such as answering a question, are right-aligned like the user's messages. A mark is put there by giving its card side=user.", "meta": {"from": "journal"}}
{"content": "rule 48 \u2014 The viewer is built from its component library, and pages only\u2026 \u2014 Message 4258. Every visual piece the viewer shows more than once, or that a user would recognise as the same kind of thing (a dialog, a side panel or inspector, a dropdown, a list row, a switch, a button), is one component in web/src/kit, extracted aggressively, and every page composes those components instead of building its own copy. Before writing markup or styles in a page, look for the kit component that already does it and extend it with a prop; a second hand-built version is a bug. The side panel that animated in but not out, while a separate skill panel did both, is the example.", "meta": {"from": "journal"}}
{"content": "work 8 in hand \u2014 Build the agent inspector redesign as one large dialog \u2014 if this is not what you are doing, end it or park it and start the work you are in", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 the files changed since the last check (`paneLayout.js`, `p\u2026 \u2014 Code Commandments \u2014 the files changed since the last check (`paneLayout.js`, `panes.js`, `AgentInspectorHead.vue`, `AgentInspector.vue`, `AgentPage.vue`) breaks a rule. Fix it now, at its SOURCE, while the code is still in front of you: \u00b7 \u2022 deep-data-reach at /Users/jessegall/projects/agent-journal/.claude/worktrees/main-mies-buildwright/src/web/src/agents/AgentInspectorHead.vue:34 \u00b7 LOAD the skill `commandments-frontend-vue-components` before fixing \u2014 load it even if you believe you already have. \u00b7 Run `commandments info <sin>` if a rule is not one you recognise. This check reads a file at a time, so it is not the whole picture \u2014 `judge` still is.", "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 <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.; 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.", "meta": {"from": "journal"}}
{"content": "rule 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.", "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; work 8 in hand \u2014 Build the agent inspector redesign as one large dialog \u2014 if this is not what you are doing, end it or park it and start the work you are in", "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", "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.", "meta": {"from": "journal"}}
{"content": "auto mode is on and work 8 stands still while todo 2 is ready \u2014 if work 8 waits on the user, decide it yourself when you can; otherwise put the question on its row with journal todo ask, end or park the work, and start todo 2. Stop only when nothing ready is left.; work 8 is still open \u2014 end it or park it before you stop: journal work end 8 --how \"<what landed>\", or journal work park 8 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 17 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 17 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": "your wait for the full suite on the inspector build is over, because you are\u2026 \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you commit \u2014 you've changed 13 judged files since th\u2026 \u2014 Code Commandments \u2014 before you commit: you've changed 13 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": "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.", "meta": {"from": "journal"}}
{"content": "fact 24 \u2014 An answer followed by tool calls can be missing from Claude's\u2026 \u2014 Seen 2026-09-24 for messages 9391-9404: text blocks opening with [!reply:n] that were followed by tool calls never appeared in the session's jsonl (only thinking and tool_use rows did), so the journal never saw them and the replies were lost. When a turn goes on after answering, send the answer with journal message reply <n> \"<text>\" instead of the tag.; law L1 \u2014 Every subagent dispatch names its model and chooses the least\u2026 \u2014 Use a fast, economical model for mechanical work with a known answer, a capable general model for careful implementation, and the strongest model only when the task turns on difficult judgement. Inheriting the orchestrator's model is not a model choice. If the dispatch API cannot accept a model, that operation is exempt.; law L2 \u2014 Every subagent is bound to a concrete job; never dispatch a generic\u2026 \u2014 Use the most specific available agent type whose declared purpose matches the assignment. On providers without agent types, give the dispatch a concrete task name and bounded prompt. If no suitable specialization exists, keep the work in the main agent instead of manufacturing an unscoped helper.; law L4 \u2014 Follow-up work goes back to the subagent that did the first part\u2026 \u2014 A subagent that drew a design, wrote the code or ran the research keeps what it learned. When the user asks for a change to its work, continue that subagent with a message rather than dispatching a new one that has to rediscover everything; start fresh only when the earlier one is gone or the new work is unrelated.; law L5 \u2014 Every subagent dispatch names the agent - a human name, a little\u2026 \u2014 A name is how the user and the chat tell subagents apart and how they are messaged later; an id or a task line is not a name. Start the dispatch's description with the name, a colon, then the task, such as \"Dr. Einstein: profile the slow hooks\" or \"Coco Rams: draw the plan card\". A designer can borrow from famous designers, a researcher from famous scientists, mixed up for fun.; rule 37 \u2014 Close every to-do explicitly with todo done or a Journal commit\u2026 \u2014 Ending work does not close its row. A to-do is closed by journal todo done <n> --how, or by a commit whose message carries Journal: todos done <n> at column 0, several numbers separated by commas. A row left open after its work landed misleads the next session and auto mode.", "meta": {"from": "journal"}}
{"content": "Thanks, Mies. overnight-refactor moved to fb5bd96b, which rebuilt dist with a PhoneDialog fix. Please rebase onto it; for the dist conflict, take upstream's dist and rebuild with vite build, then commit dist again as the tip. Run the full suite once after the rebase, and report the new tip. Dieter will then check the inspector against his prototype.", "meta": {"from": "main"}}
{"content": "fact 13 \u2014 This live session runs the installed copy in .journal/journal.pyz \u2014 The running journal (server, hooks, CLI) runs from .journal/journal.pyz with its viewer and skills in .journal/src, never from the repo. A change in the repo reaches it only through python3 src/journal.py --root .journal upgrade, which packs the zip again. A commit alone changes nothing that is running.", "meta": {"from": "journal"}}
{"content": "auto mode is on and work 9 stands still while todo 2 is ready \u2014 if work 9 waits on the user, decide it yourself when you can; otherwise put the question on its row with journal todo ask, end or park the work, and start todo 2. Stop only when nothing ready is left.; work 9 is still open, with nothing logged \u2014 journal work log 9 \"<what was decided or done, and why>\" \u2014 then journal work end 9 --how \"<what landed>\", or journal work park 9 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "waiting: 4 unread profiles 1, 2, 3, 4", "meta": {"from": "journal"}}
{"content": "waiting: 4 unread profiles 1, 2, 3, 4", "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: 4 unread profiles 1, 2, 3, 4", "meta": {"from": "journal"}}
{"content": "your chat talked about the journal's workings - \"Still waiting\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead", "meta": {"from": "journal"}}
{"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 58 \u2014 The user tests a design's clickable prototype and approves it before\u2026 \u2014 Message 15725 (2026-10-05): 'ask Dieter to create an interactive prototype! I want to test it first and give feedback before giving it my go', and remove any fact or rule that conflicts. Replaces rule 53's 'the designer decides'. The designer still runs one critique round (messages 12800, 13475) and revises before showing the prototype; then the user clicks through it, gives feedback, and only the user's go starts the build.", "meta": {"from": "journal"}}
{"content": "waiting: 4 unread profiles 1, 2, 3, 4", "meta": {"from": "journal"}}
{"content": "your chat talked about the journal's workings - \"nothing pending\" \u2014 the user sees replies, reactions, pills and reads themselves; say what the work is instead; fact 18 \u2014 cProfile inflates the slow-request profiles about tenfold \u2014 The faults feature writes a profile when a request passes its budget, and the profile is taken with cProfile, which adds per-call overhead. On 2026-09-22 /api/summary profiled at 58ms with 48ms inside Resource.fork's deep copy; with the profiler off the same call ran in 2 to 7ms. Read the profile for where the time goes in relative terms, then time the call with curl before changing anything.; fact 26 \u2014 Claude Code reads agent profiles when a session starts \u2014 Seen 2026-09-26: after the board-filler's profile in .claude/agents gained its steps and the Grep rule, dispatches from the running session still used the old profile (a 3.5-minute first question, shell grep refused); after the session restarted, the same request took 21 seconds with 4 calls. A change to an agent type reaches only sessions started after it is written.; rule 43 \u2014 A request or hook over its budget is fixed before the next release \u2014 Comment 1151 on this rule. When the faults feature reports a request, a hook or a command slower than its budget, file it as a to-do at once. It does not jump ahead of the work in hand, but no version is published while one is still open: profile it, fix it, and verify the new time before the release goes out. The budget is 50ms, because everything runs locally against files.", "meta": {"from": "journal"}}
{"content": "waiting: 4 unread profiles 1, 2, 3, 4", "meta": {"from": "journal"}}
{"content": "waiting: 4 unread profiles 1, 2, 3, 4", "meta": {"from": "journal"}}
{"content": "Dieter checked the inspector against his prototype: no blockers. Please fix: 1. Main agent: the current task as the title (it shows the session id 'claude-35215' and the name 'Agent 1'); the session id moves into the facts line. 2. Phone: labelled tabs in one scrolling row with an edge fade (only Chat has a label now); Comments and the actions go into the \u00b7\u00b7\u00b7 menu; drop Change layout there (it does nothing in one pane). 3. The old pane tour ('1 of 5 \u00b7 Drag a view onto a pane') opens over the inspector and points at nothing: remove that step or point it at something that exists. 4. A refusal shows raw server text ('session claude-35215 is not online'): say it in plain words, e.g. 'Its agent isn't running, so it can't be paused.' 5. Subagent chat: 'Message the main agent instead' under the caption. 6. Helper providers written like the main agent's: 'Codex \u00b7 gpt-6-sol'. 7. Subagent facts: 'its parent's model' instead of 'inherited model'. 8. Report band: 'Open report N' next to 'Show the whole report'. 9. journal agent create --set context=\u2026 fails with 'got multiple values for argument context': rename that argument. Rebase onto overnight-refactor once it holds the commit 'A UnitTextInput in the kit\u2026' (a gate is running); for dist take upstream's and rebuild. Full suite, commit dist last, report as before. Screenshots: /private/tmp/claude-501/-Users-jessegall-projects-agent-journal/c35e7375-7ce3-4bc3-b1ae-7cdf73bd1488/scratchpad/v4/shots", "meta": {"from": "main"}}
{"content": "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.", "meta": {"from": "journal"}}
{"content": "12 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; 33 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. The user tests a design's clickable prototype and approves it before the build", "meta": {"from": "journal"}}
{"content": "rule 27 \u2014 Name a declaration with the word a reader already knows \u2014 An attribute, a variable or a field gets the ordinary programming word for what it holds, not an evocative one. was, heard and alone were poetry; aliases, notify_actions and urgent_actions are what they are. The test: could a reader who has never seen this codebase guess what it holds from the name alone? Prose belongs in the help text and the abstract, where it is read as prose. This does not license abbreviations \u2014 a plain word in full, not a short one.", "meta": {"from": "journal"}}
{"content": "work 10 in hand \u2014 Fix Dieter's nine inspector findings \u2014 if this is not what you are doing, end it or park it and start the work you are in", "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": "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": "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 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; 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", "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.", "meta": {"from": "journal"}}
{"content": "auto mode is on and work 10 stands still while todo 2 is ready \u2014 if work 10 waits on the user, decide it yourself when you can; otherwise put the question on its row with journal todo ask, end or park the work, and start todo 2. Stop only when nothing ready is left.; work 10 is still open \u2014 end it or park it before you stop: journal work end 10 --how \"<what landed>\", or journal work park 10 \"<why it waits>\"", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 18 judged files since t\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 18 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": "check the full suite on the nine inspector fixes now - you have waited 5 min \u2014 look at the thing itself: the background shell's output, the process, the run's status. If it is still going, say journal work await \"<what you wait for>\" again and wait. If it finished or failed, journal work log what came of it and take the next step. Never wait for something you can do without.", "meta": {"from": "journal"}}
{"content": "One more for your current round, from the user (message 16501, to-do 2904): in the Helpers dropdown a row runs the helper's name and its job together and wraps them over five lines in a narrow column beside 'Working' and 'Stop its agent' (and the next row's name is underlined). Put the name on its own line, the job under it clamped to two lines (full text in a tooltip), the provider line under that (written 'Codex \u00b7 gpt-6-sol', as in point 6), and keep the controls from squeezing the text: stack them under the text when the dropdown is narrow. chat/HelperRow.vue and chat/HelperList.vue.", "meta": {"from": "main"}}
{"content": "From now on, never commit src/web/dist: commit only your source changes, and I build the viewer once after taking your work (your own vite build for checking in a browser stays local and uncommitted). If your branch already has a dist commit on top, drop it when you next rebase (git rebase -i is not available; use git rebase --onto or reset --soft and recommit your source). The tip of overnight-refactor moves soon with the commit 'The Documents list shows summaries in plain words'; rebase onto that when you are ready to report.", "meta": {"from": "main"}}
{"content": "check the full suite on the nine inspector fixes now - you have waited 10 min \u2014 look at the thing itself: the background shell's output, the process, the run's status. If it is still going, say journal work await \"<what you wait for>\" again and wait. If it finished or failed, journal work log what came of it and take the next step. Never wait for something you can do without.", "meta": {"from": "journal"}}
{"content": "your wait for the full suite on the nine inspector fixes is over, because you\u2026 \u2014 say journal work await \"<what you wait for>\" again if you are still only waiting", "meta": {"from": "journal"}}
{"content": "your command ran 31s 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": "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": "your command ran 31s 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 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": "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": "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 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 42 \u2014 Every user-facing text passes the formatters before it leaves the\u2026 \u2014 Not only a brief. A title, an abstract, an outcome and every section body are read by a person, so each goes through the same formatters on its way to the viewer \u2014 chat turns, activity items, to-do rows, inspector pages, docs alike. One field formatted out of five is not a rule, it is an accident, and it is how a raw tag ended up in the activity list after the tags feature had been stripping them for weeks. When a new field carries words a person reads, it joins the list in the same place.; 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 49 \u2014 A dialog whose content grows keeps one fixed height, and its content\u2026 \u2014 Message 5361, after asking more than once: a dialog that shows output as it arrives (install, update, logs) opens at its final height and never jumps; only its content scrolls.; rule 54 \u2014 Settings and feature switches are read at boot and on change, never\u2026 \u2014 The user, message 13349: the application boots, determines every feature and setting once, and re-evaluates only when something changes, such as a setting or a plugin. Never lazy-load settings.", "meta": {"from": "journal"}}
{"content": "helpers.js names 2 files in the project \u2014 write the path so the chat can link it: src/web/src/composables/helpers.js, src/web/src/domain/helpers.js; 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.", "meta": {"from": "journal"}}