{"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.; rule 62 \u2014 The voice profile shapes only the agent's chat speech, never code or\u2026 \u2014 The user, message 17620 (2026-10-07): the profile (butler, homie, coach, colleague) must not leak into the code the agent writes or into user-facing text of any application it works on: names, labels, comments, commit messages, docs and briefs written into a project use plain words (helper, subagent). Speaking in the chat in the profile's voice is fine.", "meta": {"from": "journal"}}
{"content": "fact 39 \u2014 Measure a process's CPU by its cputime over a window, never by a\u2026 \u2014 2026-10-11: I read ps -o pcpu= four times two seconds apart on transportklok's engines, got 0.0 every time, and told the user the idle-CPU gap was closed. Ada Funnelace contradicted it with ps cputime deltas over 30 and 40 second windows: 7.7 to 8.0 percent on the same two engines. I checked her way over 14 seconds and got 8.1, 7.4 and 0.5 percent. An instant reading can land between bursts and show nothing; a CPU-time delta over a window cannot. Use ps -p <pid> -o cputime= twice, seconds apart, and divide.", "meta": {"from": "journal"}}
{"content": "your answer to a journal line was kept out of the chat \u2014 a journal line is an instruction, not a message: act on it and write nothing, unless the user needs to know something such as a failure, finished work or a decision that waits on them", "meta": {"from": "journal"}}
{"content": "the hook hit an error \u2014 journal: the hook hit an error and kept going; the last of it is below and the whole of it is in .journal/runtime/engine.log. Fix it, then say so. the hook got no answer from the server 5 times (codes 000, machine load 85.66 on 10 cores)", "meta": {"from": "journal"}}
{"content": "law L7 \u2014 Write the least code that solves the whole problem - find what\u2026 \u2014 Before writing, search the code for what already does the job or most of it, and extend that instead of adding a second way. Every read or write of one kind of thing (a file, a record, a setting, a provider) goes through the one funnel that owns it, which is where caching and checks live. A fix lands where the fault is born, not where it shows. When you finish, say in a line what you skipped or did not check.", "meta": {"from": "journal"}}
{"content": "the hook hit an error \u2014 journal: the hook hit an error and kept going; the last of it is below and the whole of it is in .journal/runtime/engine.log. Fix it, then say so. the hook got no answer from the server 8 times (codes 000, machine load 77.38 on 10 cores)", "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", "meta": {"from": "journal"}}
{"content": "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 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": "sequence 30, Filing a document that is already written, step 1 of 4 - Add the\u2026 \u2014 Finishing this sequence comes before anything else you do; everything else waits until it is finished or abandoned. Take it up first with journal sequence follow 30 --about doc:78. If a collection the user keeps fits what you wrote, add it: journal collection add <collection n> doc:78. Look with journal collection all first. When none fits but other documents or reports on the same subject sit in no collection, make one named for the subject with journal collection create \"<subject>\", add this and them, and say so in one line. A row with nothing related gets no collection of its own. Then journal sequence next 30 --about doc:78.", "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": "sequence 30, Filing a document that is already written, step 2 of 4 - Link the\u2026 \u2014 Finishing this sequence comes before anything else you do; everything else waits until it is finished or abandoned. Take it up first with journal sequence follow 30 --about doc:78. Link the rows it answers or was built on, such as the to-dos, plans, documents, reports or messages it is about, with journal doc link 78 \"<row>\" for each. Leave out rows it only mentions in passing. Then journal sequence next 30 --about doc:78.", "meta": {"from": "journal"}}
{"content": "sequence 30, Filing a document that is already written, step 3 of 4 - Offer\u2026 \u2014 Finishing this sequence comes before anything else you do; everything else waits until it is finished or abandoned. Take it up first with journal sequence follow 30 --about doc:78. If it asks the user to decide or approve something, give it buttons: journal doc update 78 --set buttons='[{\"label\": \"Accept this proposal\", \"say\": \"I accept this proposal\", \"choice\": \"answer\"}, {\"label\": \"Change it first\", \"say\": \"I want changes first\", \"choice\": \"answer\"}]'. A button with say sends those words to you as the user's message; one naming a type, n and action runs that command. Buttons of one decision share a choice, so the others go once one is pressed. Skip this when nothing waits on the user. Then journal sequence next 30 --about doc:78.", "meta": {"from": "journal"}}
{"content": "sequence 30, Filing a document that is already written, step 4 of 4 - Tell the\u2026 \u2014 Finishing this sequence comes before anything else you do; everything else waits until it is finished or abandoned. Take it up first with journal sequence follow 30 --about doc:78. Say in one or two plain lines what it concludes, then its reference on a line of its own, like doc 41 or report 98, never in backticks. Finish with journal sequence next 30 --about doc:78.", "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": "fact 9 \u2014 Every public method on a controller becomes a journal command \u2014 The CLI is generated from the controllers: each public method of Controller, or of a typed controller, turns into journal <noun> <method>. A helper added to the base class therefore becomes a command on every type \u2014 which is how journal <type> handled and journal <type> refuse came to exist, from the CRUD funnel and the refusal funnel. An internal helper on a controller is named with a leading underscore, as _shaped and _status already are, or it ships as a command nobody meant.; fact 34 \u2014 A hooks list in a checkout's .claude/settings.json stops every\u2026 \u2014 Seen 2026-10-08: since commit 707a82915 the committed .claude/settings.json held {\"hooks\": []}; current Claude Code answers a hooks value that is not an object with a SettingsWarning dialog, which a headless helper cannot answer, so helpers 183 and 184 exited before doing anything (their launch logs in .journal/runtime/launches/ show it). This repository's journal hooks live in settings.local.json; the committed settings.json stays {}.; fact 38 \u2014 A helper reported as gone can still be reached with journal helper say \u2014 Seen repeatedly on 2026-10-11 with helper 239, Signor Bernini. The journal announced 'its agent is gone, so journal helper say cannot reach it' again and again while the helper was alive and working; journal helper say 239 answered 'sent to Signor Bernini' every time and he acted on each message. The notice tracks the agent id the journal itself dispatched, so a helper whose session was resumed by hand keeps being reported as gone. Check with pgrep and its worktree's git log before believing the notice, and never dispatch a second helper on its word alone.; 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 55 \u2014 Always dispatch Codex helpers on gpt-6-sol \u2014 The user's word, message 13431: switch the codex agents to GPT-6-Sol and make it their default. ~/.codex/config.toml names it as the default model too.; rule 56 \u2014 Helpers are for work that writes; subagents read, research and design \u2014 The user, message 13464: there must be a clear distinction. A subagent can be dispatched for anything read-only: research, review, design. A helper is for actual work that writes, best in its own worktree when the work is separate. Dieter designing in Claude Design should have been a subagent, not a helper.; rule 60 \u2014 A hotfix is done by a dispatched agent in a worktree of main \u2014 Message 16836 (2026-10-06): the orchestrator cut a worktree under .claude/worktrees for a Codex hotfix, its session moved to a new environment and the user's messages stopped reaching it. The user: when working on a branch and a hotfix comes in, create a worktree of main and dispatch an agent to do that work. The orchestrator stays on its branch and in its environment, and never cds into another checkout.; rule 71 \u2014 Always reuse a helper's or subagent's whole session, never only its\u2026 \u2014 The user, messages 23609 and 23614 (2026-10-10): workers are reused by their whole session, so they keep their context. A helper whose agent ended resumes its own session (to-do 3872); a fresh start under the same name wastes the user's tokens. It belongs in the journal application itself, not only this project.", "meta": {"from": "journal"}}
{"content": "Code Commandments \u2014 before you wrap up \u2014 you've changed 9 judged files since th\u2026 \u2014 Code Commandments \u2014 before you wrap up: you've changed 9 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": "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 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": "todo 2 next", "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"}}