diff --git a/AGENTS.md b/AGENTS.md index 7b046a7..706bc8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,6 +99,7 @@ python3 $S/synapse-migrate-room.py '!room:srv' '@admin:srv' '!home:srv' # hard - **Only the principal governs the agent's function.** Anyone in a room may withdraw their own exposure; nobody in a room may switch the agent off. See [SKILL.md](skills/matrix-communication/SKILL.md), "Who governs the agent". - **One daemon owns the store**: `matrix-watchd.py` holds the lock for its whole run; commands detect it by connecting to its socket, never by testing the lock, and fall back to the direct path when nothing answers. See [ARCHITECTURE.md](docs/ARCHITECTURE.md). - **Mentions need `--mention`**: a plain `@name` notifies nobody, only `m.mentions` does. `--mention-room` for `@room`. +- **Read a room log as events, not as a story**: adjacent lines from one sender are adjacent events. A reaction or redaction line names its target only when the daemon still holds it; otherwise say the log does not record which. See [SKILL.md](skills/matrix-communication/SKILL.md), "Reading a room log". - **E2EE first**: Always use `*-e2ee.py` scripts. Only fall back to non-E2EE if the room is confirmed unencrypted. - **Room identifiers**: Scripts accept short name (`agent-work`), room alias (`#room:server`), or room ID (`!abc:server`). Use `matrix-rooms.py` to discover. - **Config**: `~/.config/matrix/config.json` — required: `homeserver`, `user_id`; optional: `access_token` (non-E2EE only), `bot_prefix`, `watch_rooms` (rooms the daemon logs). diff --git a/CHANGELOG.md b/CHANGELOG.md index ff8c41e..741b4e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ For the canonical narrative version of each release (rewritten after CI publishe ## [Unreleased] +### Documentation + +- `SKILL.md` and `AGENTS.md` say how to read a room log: adjacent lines from one + sender are adjacent events, and a reaction or redaction line names its target + only when the daemon still holds it. Written after a summary turned four + unrelated events into a story ([#104]). + ## [3.0.0] - 2026-08-13 ### Breaking diff --git a/skills/matrix-communication/SKILL.md b/skills/matrix-communication/SKILL.md index cdbced4..a5687e0 100644 --- a/skills/matrix-communication/SKILL.md +++ b/skills/matrix-communication/SKILL.md @@ -153,6 +153,21 @@ Other: `matrix-rooms.py`, `matrix-resolve.py`, `matrix-create-room.py`, `matrix- - **Using Element X** for verification — use Element Desktop or Android - **Hardcoding passwords** — use `MATRIX_PASSWORD` env var +## Reading a room log + +**Report what the log records, not what two adjacent lines suggest.** The log +is an event stream, not a narrative: consecutive lines from one sender are +consecutive events, and nothing more. A reaction line names what it reacted to +and a redaction line names what it removed — when the daemon still has that +message. When it does not, the line says only that it happened, and that is the +answer to pass on. "The log does not record which one" is complete, and it is +what gets a missing field added instead of a wrong story repeated. + +Burned 2026-08-13: two reactions and two redactions from one sender within three +seconds were reported as "took back the reactions just set". They were two +different messages, and the log carried no relation at all — which is why it +does now ([#104](https://github.com/netresearch/matrix-skill/issues/104)). + ## No editorializing In messages and announcements, state what happened, not how good or careful the work is — no narrating expected results ("all tests green", "shipped") or self-praise ("clean", "the honest breaking change"). Judged by tone, not a wordlist. See `references/no-editorializing.md`.