Reports: make the entry title itself the link, drop :LINK: property

A report subheading's title is now the link to the heading it's about
(org [[target][description]] syntax, description = the short title),
instead of a separate :LINK: property in a properties drawer. Plain text
title when there's no single heading to link. Further links, if needed,
go inline in the signed body.
This commit is contained in:
marc committed 2026-11-09 10:56:03 +01:00
1 parent 18c8284349
commit b9d1f96563
4 files changed
+6 -12

No files matched your search

+1 -1
View File
@@ -63,7 +63,7 @@ Note what's *not* here: `last_tick_commit` is deliberately **not** updated by th
1. Triage `inbox.org` only (other files changing is someone else's edit): events → `esdeveniments.org`, tasks → wherever they actually belong, `:diwan:` items get moved but not acted on yet, new topics only get a new file when nothing existing fits. 1. Triage `inbox.org` only (other files changing is someone else's edit): events → `esdeveniments.org`, tasks → wherever they actually belong, `:diwan:` items get moved but not acted on yet, new topics only get a new file when nothing existing fits.
2. Tag consistency: any `:session:`/`:chat:` heading without a `:diwan:` tag on itself or an ancestor gets `:diwan:` added directly to it. Then resolve `:chat:` ownership: chats under a `:session:` ancestor are left for that heading's own session; orphan chats get answered inline if trivial, or escalated (see step 3's three-way decision) if not. 2. Tag consistency: any `:session:`/`:chat:` heading without a `:diwan:` tag on itself or an ancestor gets `:diwan:` added directly to it. Then resolve `:chat:` ownership: chats under a `:session:` ancestor are left for that heading's own session; orphan chats get answered inline if trivial, or escalated (see step 3's three-way decision) if not.
3. Handle every `:diwan:`-tagged heading without an open `:session:`: trivial ones get answered inline, no tag beyond `:diwan:` ever assigned. Non-trivial ones split two ways — self-contained within the heading's own subtree gets a `:session:` tag and `diwan do <file>:<line> --diwan-id <slug>` run *by the tick agent itself* (the tick agent is the only thing that ever originates a fresh `DIWAN_ID`); inherently cross-cutting work (spans multiple files/headings, can't be parallelized — archiving, bulk cleanup, moving things between files) is done by the tick agent *directly*, right there, no session at all, possibly spread across several tick runs if it needs Marc's input first. The same handling applies to any open item under `diwan.org`'s `Tasks` heading — diwan's own self-maintenance backlog, no tag needed there since the location already signals it (see PROTOCOL.md's `diwan.org` section). Already-open sessions (`:session:` tag + `DIWAN_ID` present, `Close diwan session` still `[ ]`) get their subtree's content left alone as always, but are checked for a nudge: if any commit in this tick's change range *not* authored by the diwan git identity touched a line inside that subtree (a hand-authored heading edit, a new unread `:chat:` entry, anything Marc did), the tick agent re-runs `diwan do <file>:<line> --diwan-id <id>` on the existing ID — a continuation dispatch into the session's own tab/agent, not a fresh one — purely to wake it up; no nudge at all if nothing hand-authored touched the subtree. This is the only mechanism that gets a change Marc makes to an active heading in front of its own idle agent — nothing watches the file otherwise. 3. Handle every `:diwan:`-tagged heading without an open `:session:`: trivial ones get answered inline, no tag beyond `:diwan:` ever assigned. Non-trivial ones split two ways — self-contained within the heading's own subtree gets a `:session:` tag and `diwan do <file>:<line> --diwan-id <slug>` run *by the tick agent itself* (the tick agent is the only thing that ever originates a fresh `DIWAN_ID`); inherently cross-cutting work (spans multiple files/headings, can't be parallelized — archiving, bulk cleanup, moving things between files) is done by the tick agent *directly*, right there, no session at all, possibly spread across several tick runs if it needs Marc's input first. The same handling applies to any open item under `diwan.org`'s `Tasks` heading — diwan's own self-maintenance backlog, no tag needed there since the location already signals it (see PROTOCOL.md's `diwan.org` section). Already-open sessions (`:session:` tag + `DIWAN_ID` present, `Close diwan session` still `[ ]`) get their subtree's content left alone as always, but are checked for a nudge: if any commit in this tick's change range *not* authored by the diwan git identity touched a line inside that subtree (a hand-authored heading edit, a new unread `:chat:` entry, anything Marc did), the tick agent re-runs `diwan do <file>:<line> --diwan-id <id>` on the existing ID — a continuation dispatch into the session's own tab/agent, not a fresh one — purely to wake it up; no nudge at all if nothing hand-authored touched the subtree. This is the only mechanism that gets a change Marc makes to an active heading in front of its own idle agent — nothing watches the file otherwise.
4. Write one short, titled, checkbox subheading per notable thing this run did into `diwan.org`'s Reports log (not one paragraph for the whole run), each with an optional `:LINK:` property and a 1-2 line signed body; delete any already-`[X]` subheadings first. 4. Write one short, titled, checkbox subheading per notable thing this run did into `diwan.org`'s Reports log (not one paragraph for the whole run), each with the title itself linking to the one heading it's about (plain text if there isn't one) and a 1-2 line signed body; delete any already-`[X]` subheadings first.
5. Only if 1–4 all succeeded: update `state.json.last_tick_commit` to current `HEAD` and commit under the diwan identity. 5. Only if 1–4 all succeeded: update `state.json.last_tick_commit` to current `HEAD` and commit under the diwan identity.
**Verified live** (2026-11-08, herdr 0.9.5 + Claude Code, before both the 2026-11-09 tool/content split and the pi-only harness switch): dispatched for real, ran to completion with zero permission prompts, correctly left two already-open `:session:`-tagged sessions untouched (back when `:session:` was still spelled `:diwan:`, before the tag rename — see "Known gaps" for what's unverified post-rename), correctly found nothing to triage, wrote a proper signed report, and updated `state.json` correctly. A second immediate `diwan tick` correctly no-op'd. **Not yet re-verified with a real dispatched agent** against the current state of things (post-split two-repo layout, `pi` as the sole harness) — path resolution and `pi`'s own startup have each been tested separately (see below and "Known gaps"), but not yet together through a full live tick run. Do that before trusting it for real. **Verified live** (2026-11-08, herdr 0.9.5 + Claude Code, before both the 2026-11-09 tool/content split and the pi-only harness switch): dispatched for real, ran to completion with zero permission prompts, correctly left two already-open `:session:`-tagged sessions untouched (back when `:session:` was still spelled `:diwan:`, before the tag rename — see "Known gaps" for what's unverified post-rename), correctly found nothing to triage, wrote a proper signed report, and updated `state.json` correctly. A second immediate `diwan tick` correctly no-op'd. **Not yet re-verified with a real dispatched agent** against the current state of things (post-split two-repo layout, `pi` as the sole harness) — path resolution and `pi`'s own startup have each been tested separately (see below and "Known gaps"), but not yet together through a full live tick run. Do that before trusting it for real.
+1 -1
View File
@@ -20,7 +20,7 @@ Don't mark your own entries `[X]` — that's Marc acknowledging them. You may ma
## Reporting ## Reporting
When you finish a notable piece of work — answered a chat question with real content, completed a chunk of delegated research, did something worth telling Marc about after being resumed/nudged — append one short entry of your own to `diwan.org`'s Reports log, in the format PROTOCOL.md's Reports section describes (a `[ ]` subheading, a short title, an optional `:LINK:` back to your own heading, a signed one-or-two-line body). This is the one explicit exception to staying inside your own subtree: you may append a new entry there, but never edit or delete an existing one — that's `tick`'s job only. Don't report every small step, just the things Marc would actually want to know happened without reading your heading in full. Nothing about resuming or being nudged is itself reportable on its own — only report once you've actually done something as a result. When you finish a notable piece of work — answered a chat question with real content, completed a chunk of delegated research, did something worth telling Marc about after being resumed/nudged — append one short entry of your own to `diwan.org`'s Reports log, in the format PROTOCOL.md's Reports section describes (a `[ ]` subheading whose title is itself a link back to your own heading, a signed one-or-two-line body). This is the one explicit exception to staying inside your own subtree: you may append a new entry there, but never edit or delete an existing one — that's `tick`'s job only. Don't report every small step, just the things Marc would actually want to know happened without reading your heading in full. Nothing about resuming or being nudged is itself reportable on its own — only report once you've actually done something as a result.
## Committing ## Committing
+2 -5
View File
@@ -73,14 +73,11 @@ diwan's own operational file, at the root of the content repo — not a place fo
Every notable thing a diwan agent does — a tick dispatching something new, a tick triaging a batch of inbox items, a `do` session finishing a real piece of work — gets its own short subheading under the top-level "Reports" heading in `diwan.org`. One entry per notable thing, not one giant paragraph per run: this is what keeps each entry short and the whole log skimmable with everything collapsed. **Whoever actually did the thing writes the entry** — `diwan tick` reports its own actions (triage moves, inline answers, promotions, new dispatches), and a `diwan do` session reports its *own* progress once it has something worth telling the user, not before. In particular: a tick merely nudging an idle active session (see the `:session:` section above) is not itself reportable — tick has no idea yet whether anything came of it, so it stays silent; if the nudge leads the session to actually do something, that session writes the entry once it has. Every notable thing a diwan agent does — a tick dispatching something new, a tick triaging a batch of inbox items, a `do` session finishing a real piece of work — gets its own short subheading under the top-level "Reports" heading in `diwan.org`. One entry per notable thing, not one giant paragraph per run: this is what keeps each entry short and the whole log skimmable with everything collapsed. **Whoever actually did the thing writes the entry** — `diwan tick` reports its own actions (triage moves, inline answers, promotions, new dispatches), and a `diwan do` session reports its *own* progress once it has something worth telling the user, not before. In particular: a tick merely nudging an idle active session (see the `:session:` section above) is not itself reportable — tick has no idea yet whether anything came of it, so it stays silent; if the nudge leads the session to actually do something, that session writes the entry once it has.
Format: a `[ ]`/`[X]` checkbox right in the subheading title (same pattern as `Close diwan session`), a short title, an optional `:LINK:` property pointing at the one heading the entry is most about (fuzzy heading link, or `id:` link for a note file with an `:ID:` drawer — skip it if there's no single heading to point at), and a signed one-or-two-line body, no more: Format: a `[ ]`/`[X]` checkbox right in the subheading title (same pattern as `Close diwan session`), a short title that *is itself the link* to the one heading the entry is most about (fuzzy heading link, or `id:` link for a note file with an `:ID:` drawer — just plain text with no link if there's no single heading to point at), and a signed one-or-two-line body, no more. No `:LINK:` property, no properties drawer at all — any further links belong inline in the body text:
```org ```org
* Reports * Reports
** [ ] Dispatched kitchen redecoration ** [ ] [[file:personal.org::*Plan the kitchen redecoration][Dispatched kitchen redecoration]]
:PROPERTIES:
:LINK: [[file:personal.org::*Plan the kitchen redecoration][Plan the kitchen redecoration]]
:END:
[diwan 2026-11-08] Non-trivial, dispatched as do-kitchen. [diwan 2026-11-08] Non-trivial, dispatched as do-kitchen.
** [X] Triaged 2 inbox items ** [X] Triaged 2 inbox items
[diwan 2026-11-07] Moved into esdeveniments.org and personal.org. [diwan 2026-11-07] Moved into esdeveniments.org and personal.org.
+2 -5
View File
@@ -46,13 +46,10 @@ Commit after each dispatch, cross-cutting chunk of work, or batch of inline answ
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). Then add one new subheading per notable thing *this tick itself* did — a new dispatch, an inline answer, a batch of triage moves, not one giant entry covering the whole run, and not anything that happened inside an active `do` session's own subtree (that session reports its own work, see PROTOCOL.md's Reports section — a bare nudge you sent this run is explicitly not reportable by you). Keep titles short enough that Marc can skim the whole log collapsed and know what happened without opening anything. Each entry: 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). Then add one new subheading per notable thing *this tick itself* did — a new dispatch, an inline answer, a batch of triage moves, not one giant entry covering the whole run, and not anything that happened inside an active `do` session's own subtree (that session reports its own work, see PROTOCOL.md's Reports section — a bare nudge you sent this run is explicitly not reportable by you). Keep titles short enough that Marc can skim the whole log collapsed and know what happened without opening anything. Each entry:
** [ ] <short title> ** [ ] [[<fuzzy heading or id: link to the one heading this is about>][<short title>]]
:PROPERTIES:
:LINK: <fuzzy heading or id: link to the one heading this is about, if there is one>
:END:
[diwan YYYY-MM-DD] <one or two lines, no more> [diwan YYYY-MM-DD] <one or two lines, no more>
Omit the `:LINK:` property when there's no single heading the entry is about (e.g. "nothing to triage this run"). 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 may link there, but don't try to hold a conversation in it. 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 (e.g. "nothing to triage this run"). 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`. Commit: `tick: report`.