Reports: TODO/DONE format instead of checkboxes, much broader reportability bar

Format: '** TODO <title>' unread, '** DONE <title>' read -- tick deletes
DONE entries at the start of its next run (previously [X]). This only
changes the Reports heading's own keyword; :chat: entries and Close
diwan session stay checkbox-based, unaffected.

Reportability: reversed last turn's narrow 'only real findings' bar.
The report is now explicitly meant to be the one place Marc checks for
everything new or needing attention -- so triage moves, new dispatches,
session closures, and inline answers are reportable again, alongside
findings/ambiguities/problems and anywhere a note was left for Marc to
read (even one the agent already marked [X] itself -- that's not the
same as Marc having seen it). Only two exclusions remain: a run where
nothing happened at all, and a bare nudge (no information yet on
whether anything came of it).

No code changes -- this is PROTOCOL.md/TICK.md/DO.md/DESIGN.md only.
Also cleaned up one stale 'did nothing' entry in diwan-dev-notes'
diwan.org that violated the rule even under the old wording.
This commit is contained in:
marc committed 2026-11-09 23:08:42 +01:00
1 parent 43215d6e0a
commit 19e6ae3a59
4 files changed
+18 -18

No files matched your search

+10 -10
View File
@@ -23,7 +23,7 @@ Then, chat resolution: find every `:chat:` heading anywhere in the tree with at
- If it has a `:session:`-tagged ancestor: skip it. That heading's `DIWAN_ID` session 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]`.
- 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.
Commit: `tick: resolve chat ownership and tag consistency`.
@@ -32,23 +32,23 @@ Commit: `tick: resolve chat ownership and tag consistency`.
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.
- 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 run `diwan do <file>:<line> --diwan-id <short-slug>` yourself (pick a short, readable slug from the heading text — `diwan do` will write the `DIWAN_ID` property and the `Close diwan session` checkbox item for you; don't hand-edit those). The dispatch itself isn't reportable (see step 4) — it was always going to happen, there's nothing informative to say about it 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-scoped `do` agent 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.
- Already has a `:session:` tag and its `Close diwan session` item is still `[ ]`: 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: run `diwan do <file>:<line> --diwan-id <id>` again (same existing `DIWAN_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 is not itself something to report in step 4 — you have no idea 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 its `Close diwan session` item is `[X]`: this session is being retired, for real, right now. Find its herdr tab (the `diwan` workspace, tab label == this heading's `DIWAN_ID`) and close it with `herdr 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 the `DIWAN_ID` property in place — don't delete it, it's the historical record of what ran there, in case it's ever worth revisiting. Leave `Close diwan session` checked as-is. This is routine follow-through on something Marc explicitly asked for by checking the box — not reportable on its own (see step 4), unless something about the teardown itself was unexpected (the tab held uncommitted work, say).
- 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 run `diwan do <file>:<line> --diwan-id <short-slug>` yourself (pick a short, readable slug from the heading text — `diwan do` will write the `DIWAN_ID` property and the `Close diwan session` checkbox 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-scoped `do` agent 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 its `Close diwan session` item is still `[ ]`: 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: run `diwan do <file>:<line> --diwan-id <id>` again (same existing `DIWAN_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 is not itself something to report in step 4 — not because it's unimportant, but because you genuinely have no information yet: you don't know if 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 its `Close diwan session` item is `[X]`: this session is being retired, for real, right now. Find its herdr tab (the `diwan` workspace, tab label == this heading's `DIWAN_ID`) and close it with `herdr 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 the `DIWAN_ID` property in place — don't delete it, it's the historical record of what ran there, in case it's ever worth revisiting. Leave `Close diwan session` checked as-is. Report the closure in step 4 — the session going away is a real state change Marc should see confirmed, even though he's the one who asked for it.
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.
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 `[X]` 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).
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, and only if there's something that actually clears the bar, add one new subheading per reportable thing *this tick itself* did. The bar: real information — a finding, a decision you made on Marc's behalf, an ambiguity you flagged, a problem you hit. Below the bar, write nothing: a plain dispatch with nothing to say about it yet, a routine session closure Marc already asked for, a pass where nothing needed triaging, a nudge you sent (that one's not yours to report regardless, see PROTOCOL.md) — none of these get an entry. A tick run that did real mechanical work (moved files, dispatched a session, closed another) but has nothing *informative* to add writes **zero** new Reports entries, full stop — don't manufacture one just to show you were active; `git log` and `diwan.org`'s other headings already show that. Never one giant entry covering the whole run either — 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:
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 (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 (not because it's unimportant, but because 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:
** [ ] [[<fuzzy heading or id: link to the one heading this is about>][<short title>]]
** 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 — no `:LINK:` property, no properties drawer. 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.