1. 'Close diwan session' now uses TODO/DONE (assign_diwan_id inserts
'** TODO Close diwan session'), matching Reports. No headline anywhere
in diwan's own docs uses a [ ]/[X] checkbox now -- only :chat: list
items do, which is correct org usage (checklist items, not headline
states) and unaffected.
2. Rewrote PROTOCOL.md/TICK.md/DO.md/DESIGN.md to read as a single
coherent design rather than a changelog of how they got here. Removed:
contrastive 'not because X, but because Y' phrasing that only makes
sense if you know the prior rule, references to old tag names/formats
that no longer exist, a Claude-Code-vs-pi rationale that belongs in
DESIGN.md (if anywhere) not the agent-facing PROTOCOL.md, and 'no
:LINK: property' (never describe a convention by naming something it
doesn't have).
3. DESIGN.md got the heaviest pass since it had drifted from reality,
not just tone: it still said 'no flake.nix yet' (there is one, in
production use via samfelag), claimed several things 'not yet
re-verified live' that have since been verified multiple times
(tick's no-op gate, triage, the tag-consistency/escalation decision,
pi against real heading content via tick), and didn't mention
'diwan remote' or the actual flake.nix packaging shape anywhere.
Rewrote the verified-live claims and Known Gaps list to match current
reality, added flake.nix to the doc map and architecture section.
Live content migrated to match: diwan-dev-notes' decorate-home heading
('Close diwan session' checkbox -> TODO).
11 KiB
diwan tick procedure
You are a diwan tick agent. Read PROTOCOL.md and the content repo's AGENTS.md first if you haven't — this doc assumes both (you were given PROTOCOL.md's path directly in your dispatch prompt). You were dispatched by diwan tick with a commit range (<since>..<now>) representing what changed since the last completed tick. Your job is one pass of housekeeping over that change, not an open-ended audit of the whole repo.
Work through these steps in order. Make a separate, small, lock-protected commit (see PROTOCOL.md's concurrency contract) after each coherent chunk of work rather than one giant commit at the end — that's what makes your run legible in git log afterwards.
1. Triage the inbox
Look at what changed in inbox.org (and only there — other files changing is someone/something else's edit, not raw capture). The goal is to leave inbox.org empty, or as close to it as possible, once this step is done — it's a capture buffer, not a holding pen; don't let items linger there just because placement is a little unclear. For each new item:
- An event (something with a date/time, or clearly calendar-shaped) → move it into
esdeveniments.orgunder "Propers", in roughly chronological position. If it's missing information you'd need to do this well (e.g. a flight with no time yet), move it anyway with what you have, and flag the gap in the report (step 4) rather than leaving it in the inbox. - A plain task → move it to wherever it actually belongs: an existing project file/folder if it's clearly about one (e.g.
folkugat/), the relevant domain file (personal.org, etc.) if general, or a sensible top-level spot inpersonal.orgif nothing fits. Don't create a new file for something that fits an existing one. If you're genuinely unsure which existing spot is right, still move it to your best guess rather than leaving it in the inbox — but add a:chat:child heading under it there with a question asking Marc where it should actually live, so he can redirect it next pass instead of it silently sitting in a wrong-but-plausible place. - A
:diwan:-tagged item (see PROTOCOL.md) → leave it where it landed for now; it gets handled in step 3, not here. (You may still move it out of the inbox into a sensible home first, same as any other item — the tag travels with it.) - Something that's clearly the seed of a new project/topic with no existing home → create a new file for it, but only when it genuinely doesn't fit anywhere existing. Default to not creating new files.
Commit this as its own step: tick: triage inbox.
2. Ensure tag consistency, then resolve :chat: ownership
First, tag consistency (see PROTOCOL.md's tag-consistency rule): for every heading tagged :session: or :chat: anywhere in the tree, check whether it or an ancestor already carries :diwan:. If not, add :diwan: directly to that heading itself (not to the ancestor) so the implied attention is made explicit.
Then, chat resolution: find every :chat: heading anywhere in the tree with at least one unread ([ ]) entry.
- If it has a
:session:-tagged ancestor: skip it. That heading'sDIWAN_IDsession owns it. - If it does not: for each unread entry, decide trivial vs non-trivial.
- Trivial (you can just answer or act right now, no multi-step delegated work): do it, write your reply as a new signed entry (
[diwan YYYY-MM-DD] ...), mark the original[X]. Report this in step 4 — you've left Marc a note to read, and he hasn't seen it yet even though it's marked[X](that just means you've acted on it). - Non-trivial: this is the same three-way escalation decision step 3 makes for any
:diwan:-tagged heading — self-contained work gets a:session:tag and a dispatch, cross-cutting work gets handled by you directly, both as part of step 3. Leave the chat entry unread until the work is actually done and its own agent (or you, on a later tick) answers it.
- Trivial (you can just answer or act right now, no multi-step delegated work): do it, write your reply as a new signed entry (
Commit: tick: resolve chat ownership and tag consistency.
3. Handle :diwan: headings
Find every :diwan:-tagged heading in the tree (including ones just tagged in step 2).
- No
:session:tag yet, and the request is trivial (quick lookup, one-line answer you can produce yourself right now): do it inline, write the result into the heading, and leave it — no session, nothing further to track. This is the common case for small asks. Report it in step 4 — it's new, and Marc hasn't seen the result yet. - No
:session:tag yet, non-trivial, and self-contained within this heading's own subtree (independent delegated work, nothing that needs writes to other files or headings): add the:session:tag and rundiwan do <file>:<line> --diwan-id <short-slug>yourself (pick a short, readable slug from the heading text —diwan dowill write theDIWAN_IDproperty and theClose diwan sessionTODO item for you; don't hand-edit those). Report the dispatch in step 4 — a new session is new information even before it has anything to show for itself yet. - No
:session:tag yet, non-trivial, and inherently cross-cutting — touches multiple files or headings at once, or can't be meaningfully parallelized (archiving, bulk cleanup, moving files/folders between locations, repo-wide renames): do this yourself, directly, right now, in small separate commits per coherent chunk — the same way you'd do any other tick step. Don't add a:session:tag for this; a subtree-scopeddoagent would just hit the same wall a human doing it alone would. If there's a real judgment call to make first (not just mechanical execution), ask in the heading's own:chat:and leave the rest for a future tick once Marc answers, rather than guessing or acting unsupervised at scale. It's fine for this kind of task to span several tick runs — pick up wherever the heading's own content (and its sub-TODOs, if any) says you left off. Report what you actually moved/changed in step 4. - Already has a
:session:tag and itsClose diwan sessionitem is stillTODO: it's an active session, already being worked by its own agent — you still have no business editing inside its subtree, but check whether it needs waking up. Look at this tick's change range for any commit not authored by the diwan git identity (diwan <diwan@local>) that touched a line inside that heading's subtree — a direct edit by Marc to the heading body, a new unread:chat:entry, anything hand-authored. The tick's own start-of-run manual-edit snapshot commit is the usual source of these. If you find one, nudge the session: rundiwan do <file>:<line> --diwan-id <id>again (same existingDIWAN_ID— this reuses the session's own tab/agent, it does not create a new one) so it re-reads the heading and notices on its own. If nothing hand-authored touched the subtree, leave it alone entirely, no dispatch at all. A nudge isn't reportable in step 4: you genuinely don't know yet whether anything comes of it. If it leads the session to do real work, that session reports it, not you. - Already has a
:session:tag and itsClose diwan sessionitem is markedDONE: retire the session. Find its herdr tab (thediwanworkspace, tab label == this heading'sDIWAN_ID) and close it withherdr tab close <tab-id>— if it's already gone (closed by hand, e.g.), there's nothing to do there, move on. Then remove the:session:tag from the heading itself (leave:diwan:and any other tags alone). Leave theDIWAN_IDproperty in place as a historical record of what ran there. LeaveClose diwan sessionmarkedDONEas-is. Report the closure in step 4.
Also check diwan.org's Tasks heading for any open (not-yet-DONE) item — these are the same kind of cross-cutting work as above, already homed in the right spot with no tag needed (see PROTOCOL.md's diwan.org section). Pick one up and make progress on it (or finish it) directly, in its own commit(s), the same way as any other cross-cutting :diwan: request; mark it DONE once actually finished, or ask via a :chat: child first if it needs a real judgment call from Marc. Report what you did in step 4.
Commit after each dispatch, cross-cutting chunk of work, batch of inline answers, or session closure: tick: dispatch <slug> / tick: <what you did> / tick: answer <heading> / tick: close session <diwan_id>. A nudge doesn't change any file content on its own, so there's nothing to commit for it either.
4. Write the report
In diwan.org at the repo root, under a top-level "Reports" heading (create the file and heading if this is the very first tick), first delete any existing report subheadings already marked DONE in their title — Marc has read those, they're disposable, don't let them pile up (this applies to every entry regardless of who wrote it, including ones a do session appended).
Then add one new subheading per reportable thing this tick itself did. The bar is deliberately broad — this report is the one place Marc checks for what's new, a shortcut to everything that needs his attention, so err on the side of including something: items moved (triage), a new dispatch, a session closed, an inline answer, a finding, a flagged ambiguity, a problem hit, or anywhere you've left a note for him to read in a :chat: (even one you've already marked [X] yourself — that just means you acted on it, not that he's seen it). The only things that don't get an entry: a tick run where genuinely nothing happened (no triage, no dispatches, no chat activity, nothing — don't manufacture an entry just to show you were active), and a bare nudge, since you don't yet know if anything came of it (see PROTOCOL.md). Never one giant entry covering the whole run — one subheading per reportable thing, and don't report anything that happened inside an active do session's own subtree (that session reports its own work). Keep titles short enough that Marc can skim the whole log collapsed and know what happened without opening anything. Each entry:
** TODO [[<fuzzy heading or id: link to the one heading this is about>][<short title>]]
[diwan YYYY-MM-DD] <one or two lines, no more>
Make the title itself the link to the one heading the entry is about. Leave the title as plain text (no link) when there's no single heading the entry is about. Anything needing Marc's actual input or a reply (as opposed to a passive FYI) belongs as a normal unread entry in the relevant heading's own :chat:, not in the report — the report entry's title or body may link there, but don't try to hold a conversation in it.
Commit: tick: report.
5. Record completion
Last step, only if everything above succeeded: update .diwan/state.json's last_tick_commit to the current HEAD sha, and commit that under the diwan identity: tick: mark complete. If anything above failed partway, leave state.json alone — the next tick (or Marc, by hand) should see the same change range again rather than silently skipping it.