Close diwan session: TODO/DONE instead of checkbox; purge evolutionary residue from all docs

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).
This commit is contained in:
marc committed 2026-11-09 23:17:17 +01:00
1 parent 19e6ae3a59
commit 34f1f4396e
5 files changed
+36 -37

No files matched your search

+6 -6
View File
@@ -18,17 +18,17 @@ Can be added directly by the user, or by diwan itself when it decides some other
## `:session:` tag
A heading tagged `:session:` has (or is about to get) a dedicated, persistent agent session handling it — a `DIWAN_ID` property and a `Close diwan session` checkbox item. Note the org tag syntax when it's stacked alongside `:diwan:`: one colon-delimited run, no space (`:diwan:session:`, not `:diwan: :session:`) — the latter isn't valid org tag syntax and won't parse as two tags.
A heading tagged `:session:` has (or is about to get) a dedicated, persistent agent session handling it — a `DIWAN_ID` property and a `Close diwan session` TODO item. Note the org tag syntax when it's stacked alongside `:diwan:`: one colon-delimited run, no space (`:diwan:session:`, not `:diwan: :session:`) — the latter isn't valid org tag syntax and won't parse as two tags.
```org
* Gather information about what I could do on my next trip to greece :diwan:session:
:PROPERTIES:
:DIWAN_ID: do-greece-trip
:END:
** [ ] Close diwan session
** TODO Close diwan session
```
Can be added by the user directly, when they already know a heading needs its own ongoing session, or by diwan (ordinarily `tick`) when it decides a `:diwan:`-tagged request is non-trivial and self-contained enough to delegate (see above). `DIWAN_ID` is a herdr terminal name (see "herdr", below) — not an arbitrary id. It points directly at the live/persisted agent session handling this heading, so "jump in personally" is just attaching to that terminal, no separate lookup needed. A heading keeps the same `DIWAN_ID`/`:session:` tag across multiple tick passes until its `Close diwan session` item is checked off (`[X]`) by the user, at which point the *next* tick actually retires it: closes that `DIWAN_ID`'s herdr tab for real (`herdr tab close`, not just leaving it be) and removes the `:session:` tag from the heading. The `DIWAN_ID` property itself is left in place as a historical record (in case the session's work is ever worth revisiting) — only the tag and the live terminal go away.
Can be added by the user directly, when they already know a heading needs its own ongoing session, or by diwan (ordinarily `tick`) when it decides a `:diwan:`-tagged request is non-trivial and self-contained enough to delegate (see above). `DIWAN_ID` is a herdr terminal name (see "herdr", below) — not an arbitrary id. It points directly at the live/persisted agent session handling this heading, so "jump in personally" is just attaching to that terminal, no separate lookup needed. A heading keeps the same `DIWAN_ID`/`:session:` tag across multiple tick passes until its `Close diwan session` item is marked `DONE` by the user, at which point the *next* tick retires it: closes that `DIWAN_ID`'s herdr tab (`herdr tab close`) and removes the `:session:` tag from the heading. The `DIWAN_ID` property itself is left in place as a historical record, in case the session's work is ever worth revisiting.
## `:chat:` tag
@@ -73,7 +73,7 @@ diwan's own operational file, at the root of the content repo — not a place fo
This is the one place the user checks for what's new — a shortcut to everything that needs their attention, not just a highlights reel — so the bar for getting a short subheading under the top-level "Reports" heading in `diwan.org` is deliberately broad: items moved (triage), a new session dispatched, a session closed, an inline answer, a finding, a flagged ambiguity, a problem hit, or anywhere a note was left for the user to read (even one already marked `[X]`/acted-on by whoever wrote it — that means *they've* acted on it, not that the user has seen it yet). The only things that don't get an entry: a run where genuinely nothing happened at all, and a bare nudge to an idle session (not because it's unimportant, but because whoever sent it has no idea yet whether anything came of it — see the `:session:` section above; if the nudge leads to real work, that work gets its own entry once there's something to report). Keep each entry to its own short subheading, not one giant paragraph per run: this is what keeps the whole log skimmable with everything collapsed. **Whoever actually did the thing writes the entry** — `diwan tick` reports its own actions, and a `diwan do` session reports its own progress once it has something to tell the user, not before.
Format: a `TODO`/`DONE` keyword on the subheading itself, 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:
Format: a `TODO`/`DONE` keyword on the subheading itself, 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. Any further links belong inline in the body text:
```org
* Reports
@@ -120,10 +120,10 @@ Sessions are herdr (https://herdr.dev) terminals, not a diwan-invented session s
- a `diwan tick` run is a tab labeled `tick-<UTC timestamp>`, with a `pi` agent started in its root pane and prompted with the tick instructions;
- a `diwan do` session for a given `DIWAN_ID` is a tab labeled exactly that `DIWAN_ID`, same pattern — this is *why* `DIWAN_ID` must be a valid herdr agent name (`^[a-z][a-z0-9_-]{0,31}$`), not an arbitrary string.
To resume a `DIWAN_ID`, `diwan` first checks whether its agent is still alive (`herdr agent get <id>`) and just prompts it if so; if the process has exited (normal between ticks), it finds the tab by label and starts a fresh agent in the same pane, in the same working directory — the heading's own content is what carries continuity, not agent conversation history. `diwan` shells out to the real `herdr` CLI (the `diwan` CLI has the exact calls, verified live against herdr 0.9.5; run `herdr --skill` to check this hasn't drifted on a newer version). When `herdr` isn't on PATH, every call prints what it would have run instead of failing, so the pipeline stays testable without herdr installed.
To resume a `DIWAN_ID`, `diwan` first checks whether its agent is still alive (`herdr agent get <id>`) and just prompts it if so; if the process has exited (normal between ticks), it finds the tab by label and starts a fresh agent in the same pane, in the same working directory — the heading's own content is what carries continuity, not agent conversation history. `diwan` shells out to the real `herdr` CLI, verified live against herdr 0.9.5 (run `herdr --skill` to check this hasn't drifted on a newer version). When `herdr` isn't on PATH, every call prints what it would have run instead of failing, so the pipeline stays testable without herdr installed.
Bare `diwan` (no subcommand) focuses the local `diwan` workspace and attaches you to it interactively. `diwan remote <machine>` does the same against a herdr machine saved via `herdr machine add <ssh-target>` (see herdr's own `--help`/`--skill` for setting one up) — it focuses that machine's `diwan` workspace over the scripted `--machine` API, then execs `herdr --remote <machine>` to open an interactive attach into it. This relies on `<machine>` being usable both as a saved machine label (for the focus step) and as a raw `--remote` SSH target (for the attach) — true by default, since `herdr machine add` labels a profile after its SSH target unless `--label` overrides it.
## The harness is `pi`
diwan dispatches `pi`, and only `pi` — not a pluggable choice. It's the only herdr-supported agent kind diwan has ever needed that runs real work fully unattended: it has no per-tool-call approval gate at all (unlike e.g. Claude Code, which otherwise prompts before every edit/bash call and would defeat the "act first, report passively" model), so no permission-mode flag or similar is needed to let it act freely. The one thing that can still block a dispatch is pi's one-time project-trust decision for protected `.pi/*` resources, if a content repo ever has any — `--approve` (always passed, see the `diwan` CLI) makes that a one-shot yes instead of a hang; override with `DIWAN_PI_APPROVE` if a different flag is ever needed. `TICK.md` and `DO.md` are still plain-language procedures with nothing pi-specific baked into their wording — that's just good practice, not a promise of swapping in a different harness later.
diwan dispatches `pi` exclusively, started with `--approve` so it never blocks on its one-time project-trust decision for protected `.pi/*` resources, if a content repo ever has any. Override the flag via `DIWAN_PI_APPROVE` if a different one is ever needed.