brane 0.1.1 → 0.3.0

package/protocols/summarize.md

@@ -0,0 +1,203 @@
+# /summarize [guidance]
+
+Consolidate a session into a durable summary narration — the nap that
+lets a fresh session pick up without re-learning what just happened.
+
+## Why summarize
+
+A session accumulates context that is about to be lost: the context
+window gets compacted or cleared, the agent session dies and is
+revived, a twin takes over, or the operator simply returns tomorrow.
+The narrative event log survives all of these — but a reader arriving
+cold gets the log in event order, newest last, with the load-bearing
+conclusions scattered among the play-by-play. A summary narration is
+the consolidation pass that fixes this: one event, near the end of the
+log, that a `listen(wait: false, tail: 50)` on re-entry finds
+immediately, stating where things stand.
+
+The framing comes from Erik Bylund's "Agents Need Sleep"
+(erikbylund.com, 2026): memory needs **consolidation as a first-class
+practice** — a light "nap" after each unit of work so that "a fresh
+session tomorrow picks up without re-learning what just happened."
+Consolidation's job is salience, compression, trust, and *forgetting*
+— not retrieval, which search already handles. `/summarize` is the
+nap, adapted to brane's substrate.
+
+That substrate changes the risk profile. Bylund's central warning —
+*"distillation concentrates error exactly as efficiently as it
+concentrates signal"* — is about mutable state files, where the
+summary silently replaces the record and a stale claim inherits full
+authority. A brane summary is a narration: append-only, attributed,
+timestamped, and sitting *beside* the events it summarizes rather than
+over them. It cannot erase anything, and every claim in it can carry
+an `nid:seq` citation back to the event it came from. That is the
+discipline this protocol enforces: a summary is a **checkable index
+into the record**, not a replacement for it. Written this way, the
+summary doubles as a **trailing table of contents** for the
+narrative: its `nid:seq` backlinks — which the operator's UI
+auto-linkifies into links that jump to the exact event — let a
+reader navigate the whole session from one narration.
+
+## Audiences
+
+Write for all of these at once, in roughly this priority:
+
+1. **Your future self** after a `/clear`, compaction, or revive —
+   reloading via `listen` and needing plan, stance, and in-flight
+   state back without re-reading everything.
+2. **A successor or twin** continuing the work with none of your
+   context (see the [twin](twin.md) protocol).
+3. **The operator**, catching up asynchronously — possibly on a
+   phone, possibly days later.
+4. **Future search and `/digest` runs** — the summary is the event
+   most worth surfacing for the whole session, so make it findable
+   and self-contained.
+
+The quality bar is Bylund's stranger test: **could a stranger read
+this one narration and know where things stand?** If understanding it
+requires having watched the session, it is not done.
+
+## What a good session summary is
+
+**A state snapshot, not a chronicle.** Report where things stand
+*now* — not the order in which you got there. The sequence of
+attempts, tool calls, and course corrections is already in the log in
+perfect fidelity; re-telling it is the one thing a summary can never
+do better than the record itself. Chronology earns a place only where
+it explains the present ("X was tried before Y ruled it out").
+
+**Forgetting is the job.** The append-only log is what makes
+aggressive compression safe: nothing you omit is lost, only demoted to
+search. Drop the routine and the resolved. What must *not* be dropped:
+open threads, unanswered operator questions, and negative findings —
+"we tried X and it failed because Y" is expensive knowledge that a
+successor will otherwise re-purchase.
+
+**Grounded, not remembered.** A wrong confident summary is worse than
+no summary at all — it gets read *instead of* the record, so its
+errors propagate with the full authority of consolidation. The rules
+are the same as [/digest](digest.md)'s, and they are mandatory:
+
+- Re-read the events before summarizing them. Your in-context memory
+  of the session may already be compacted prose; the log is not.
+  Report only what the log actually says.
+- Cite claims as `nid:seq` so they are checkable — and so the summary
+  works as an entry point into `listen` / `narrative_search` for any
+  reader who needs the detail (see the [memory](memory.md) protocol).
+  Always the full `nid:seq` form: prose like "seq 42" is not
+  linkified, so it makes a claim checkable but not tappable.
+- Repo facts (branch names, PR numbers, commit hashes, test results)
+  are copied from real `git`/`gh` output obtained this run, never
+  composed from memory to look precise.
+- Attribute positions; don't assert them. Decisions are "the operator
+  directed…" / "we agreed…" with a citation, not settled fact. Don't
+  editorialize, sharpen vague outcomes into definite ones, or supply
+  motives the events don't give.
+- Name your gaps instead of filling them. If part of the session is
+  unread or an outcome is unverified, say so plainly.
+
+## Interpreting guidance
+
+`/summarize [guidance]` is freeform; interpret intent generously, as
+`/digest` does. The default — bare `/summarize` or
+`/summarize session` — is the current narrative, whole session,
+general audience. Guidance can adjust any of:
+
+- **Scope** — `/summarize since the last summary`,
+  `/summarize the last hour`, `/summarize the auth work only`
+- **Audience** — `/summarize for a twin` (lean toward in-flight
+  state, gotchas, and next actions), `/summarize for the operator`
+  (lean toward outcomes and open questions)
+- **Target** — `/summarize claude-4c7289d1`: summarize another
+  narrative, loading it first via `listen` with a cursor (see
+  *Cross-Narrative Context Loading* in [memory](memory.md)). Narrate
+  the summary into your own narrative unless directed otherwise.
+- **Focus** — any topical emphasis the guidance names
+
+## Gathering
+
+Ground the summary in the log, not in what you think you remember:
+
+1. Find your previous summary, if any — scan your own narrative for
+   the `**Session summary**` header (a `listen` re-read, or
+   `narrative_search` scoped by content). Its seq is your default
+   window start, and your `re` target for supersession.
+2. Re-read the window: `listen` with `wait: false` and `after` set to
+   the previous summary's seq (or `0` for the whole narrative —
+   paginate if long). Note the seqs of load-bearing events as you go:
+   operator direction, decisions, reversals, results.
+3. Corroborate externals — run `git`/`gh` for any repo state the
+   summary will assert; check that "done" things are actually merged,
+   pushed, or passing.
+
+For long sessions, narrate brief progress as you gather, per the LIVE
+loop's narrate-often principle.
+
+## Summary structure
+
+Begin the narration with a header line:
+
+```
+**Session summary** — {one-line gist} ({date})
+```
+
+Then sections as needed, omitting any that are empty. Suggested
+shape, not a rigid template — let the session's actual shape win:
+
+- **Where things stand** — current state of the work: what exists,
+  what is verified working, what is merely drafted. Concrete
+  locations: branch, worktree, files, PRs.
+- **Decisions** — direction set during the session, attributed and
+  cited (`nid:seq`). Include decisions *against* things.
+- **Open threads** — in-flight work, unanswered questions, promised
+  follow-ups, blockers. This is the section a successor acts on
+  first; make each item actionable.
+- **Lessons and dead ends** — negative findings worth keeping:
+  approaches ruled out and why, gotchas discovered, anything a
+  successor would otherwise re-learn the hard way.
+- **Pointers** — key events (`nid:seq`), PRs/commits, files, wiki
+  pages (`slug#anchor`) for readers who need to go deeper. Together
+  with the citations woven through the sections above, this is the
+  trailing-table-of-contents role made explicit: every major beat of
+  the session reachable through a backlink.
+
+Keep it compact — a summary that must be summarized has failed.
+Compression is safe precisely because the pointers carry the depth.
+
+## Output
+
+Narrate the summary in full via `narrate`, on one call that also:
+
+- **Sets `meta.summary`** to a current one-liner for the narrative
+  list — e.g. `"Summarized: daemon refactor merged; expo tab bug
+  open"`. The narrated body and the metadata line serve different
+  readers (log vs. list); update both.
+- **Back-references via `re`**: the previous `**Session summary**`
+  event if one exists (supersession by reference — the new summary
+  visibly succeeds the old, and the chain of summaries becomes
+  walkable), plus the load-bearing events the summary rests on.
+
+Before posting, make one verification pass over the draft: every
+claim, citation, and identifier — can you point to the event or
+command output you read it from? Cut or flag anything you cannot.
+
+## Cadence
+
+`/summarize` runs when the operator invokes it, but the natural
+moments to *suggest* one (or, with standing permission, run one) are
+exactly Bylund's nap boundaries: a unit of work just completed, a
+`/clear` or handoff is imminent, or the session is winding down. A
+summary written while context is still warm is cheap; the same
+summary reconstructed after context loss is expensive and worse.
+
+The heavier tier — Bylund's "deep sleep," where accumulated summaries
+are themselves challenged against reality and distilled — is not this
+protocol. Cross-narrative consolidation belongs to [/digest](digest.md)
+(activity over a time window) and the [/wiki](wiki.md) audit (curated
+synthesis against the record).
+
+## After generating
+
+Return to the LIVE loop — `listen` for further signals. The operator
+may ask follow-ups, request a different focus, or use the summary as
+the handoff point for a `/clear` or twin spawn.

package/protocols/twin.md

@@ -0,0 +1,174 @@
+# Protocol: twin
+
+A **twin** is a brane-managed agent spawned to continue from a
+**predecessor** narrative — inheriting its history and, when the
+predecessor is still live, tracking it in real time. Twinning is how an
+external or absorbed session's context is brought into brane as a
+first-class, revivable narrative without disturbing the original.
+
+This protocol is **role-bound**: it is binding on agents who hold
+`role: "twin"`. For everyone else it is informational. Roles are
+superpositional (see the prelude's "Role-bound protocols"): a twin
+can be steered by the operator to *also* hold another role — most
+naturally `keeper`, scoped to its predecessor — and then both
+protocols bind it jointly. See "A twin as a single-purpose keeper"
+below.
+
+**Prerequisite:** this protocol uses the LIVE loop's tools and
+vocabulary (`listen`, `narrate`, `whoami`, `narrative_info`, etc.). If
+you have not already read `protocols/LIVE_loop.md`, read it first; then
+return here.
+
+## What a twin is for
+
+The operator spawned you to adopt a predecessor narrative — typically an
+**external** MCP session (an agent that connected without `brane spawn`)
+or an **absorbed** import. The predecessor may be:
+
+- **Over** — disconnected or finished. You are importing a closed
+  history, the way an absorbed narrative is activated.
+- **Still live** — an external client may still be connected and
+  appending events *after* the point you were forked from. You are then
+  a real-time twin: you continue the work *alongside* it, not just from
+  a snapshot.
+
+You will not know which until you look — so this protocol has you treat
+the predecessor as **possibly live** by default.
+
+## Step 1 — Find your predecessor
+
+Your predecessor is recorded in your **own `started` event's `re`**, in
+`nid:seq` form (e.g. `external-9f3a1c20:42`). Read it:
+
+```json
+{ "tail": 1, "after": 0 }
+```
+
+The `re` entry's `nid` is your predecessor; its `:seq` is the **boundary
+seq** — the last event that existed in the predecessor when you were
+forked. Everything in the predecessor **through that seq is your
+inherited prefix**; anything past it (if any) is new activity that
+arrived after the fork.
+
+If your `started` event carries no `re`, you have no predecessor — fall
+back to the plain LIVE loop.
+
+## Step 2 — Read the inherited prefix
+
+Read the predecessor's history up to the boundary seq and process it as
+your own context:
+
+```json
+{ "after": { "<predecessor-nid>": 0 } }
+```
+
+Keep advancing the cursor (`{ "<predecessor-nid>": <last-seq-seen> }`)
+until you have read through the boundary seq. If there are many events,
+page until you reach it. This is the salient context you were spawned to
+carry forward — understand it before acting.
+
+The prefix may be **thin or empty** — e.g. a freshly-connected external
+client whose only event is its connection. That's fine: carry forward
+whatever is there and move on. This step earns its keep when twinning an
+absorbed import or a long-running session; for a brand-new predecessor
+there is simply little to inherit.
+
+## Step 3 — Twin the live loop
+
+From now on, **LIVE-loop with a multi-narrative cursor over both your
+own narrative and the predecessor's**, so you stay in sync if the
+predecessor is still active:
+
+```json
+{ "after": { "self": <your-last-seq>, "<predecessor-nid>": <boundary-seq> } }
+```
+
+- Advance **both** keys as events arrive.
+- New events from the predecessor past the boundary seq are the live
+  session continuing — interpret them as fresh signals, not history.
+- If the predecessor is over, this watch simply yields nothing extra and
+  you behave like any other agent. No special-casing needed.
+
+## Step 4 — Wait for operator direction
+
+DO NOT under any circumstances begin executing actions (_especially_
+contacting the previous agent) before you have explicit direction from
+the operator, as this skips the L, I, and V steps of the LIVE loop. Do
+not even speculate about the nature of the task before you actually
+know, even if the operator has not yet said anything, as this will
+confuse future readers if you happen to be wrong. Wait.
+
+## Step 5 — Coordinate, don't collide
+
+**First, find out whether a peer is actually live** — don't assume. A
+predecessor narrative may have a live agent on the other end, or it may
+be **dormant**: an external client that has since disconnected, or a
+narrative the operator is simply using as a second channel to type into.
+Check before you worry about collision:
+
+- Call `narrative_info` with the predecessor's nid and look at
+  `mcp_connected` (and `status`), and/or `list_peers` to see whether it
+  appears as an active peer.
+- **No agent connected →** there is no one to collide with. Every event
+  there is the operator (or your own foreign-narration); you are simply
+  the sole live agent rooted in two narratives. Keep watching it (it's
+  nearly free and the operator may use it as a channel), but drop the
+  coordination ceremony.
+- **An agent *is* connected →** treat it as a true peer. Coordinate
+  explicitly and don't duplicate its actions.
+
+When a peer is live, avoid both agents thinking they alone are driving:
+
+- **Your own narrative is your voice.** Narrate your work into `self`.
+- **Once you have permission to communicate with your predecessor, use
+  foreign-narration** (`narrate` with `nid: "<predecessor-nid>"`) to
+  coordinate. Your message arrives there as an `agent_signal`.
+- **Defer to operator direction over assumptions about who owns what.**
+  You have not "inherited" any work until the operator says so, and you
+  are not entitled to suggest any division of labor between the agents.
+
+## Extend, don't replace
+
+A twin continues *from* its predecessor — it does not take it over. The
+predecessor narrative stays intact as the historical record; you branch
+from it and carry its context forward, leaving the original where it is.
+
+## A twin as a single-purpose keeper
+
+A twin is already most of a [keeper](keeper.md) scoped to one
+narrative, so the operator may steer a newborn twin to *also* keep
+watch over its predecessor. When that happens you hold both roles at
+once (see the prelude's "Role-bound protocols") and read `keeper.md`
+as binding, not merely informational — no cognitive dissonance over a
+`whoami` that still says `twin`.
+
+The fit is natural because the twin machinery *is* the keeper machinery
+in miniature:
+
+- **Context for free.** A daemon-wide keeper starts cold and
+  reconstructs an agent's state from its tmux pane. You inherited the
+  predecessor's prefix (Step 2), so you oversee from *inside* its
+  context.
+- **The watch set is already built.** A keeper maintains a cursor map
+  over every active narrative; yours is just the two keys you already
+  multi-listen on — `{ self, <predecessor> }` (Step 3). No
+  `list_peers` reconciliation loop to run.
+- **Scope, not singleton.** There's no one-keeper-per-daemon rule
+  (keeper.md, "Scoped, not singleton"); keepers with disjoint
+  scopes coexist. A twin-keeper is scoped to one predecessor, so it
+  rarely collides — other single-purpose keepers watch different
+  narratives, and a global keeper can simply cede your predecessor to
+  you. The only thing to watch for is another keeper *also*
+  authoritative over your predecessor; if you spot that, notify the
+  operator and coordinate (per keeper.md Step 3) rather than either
+  of you racing on its prompts. You don't run the daemon-wide keeper's
+  startup overlap sweep — your scope is one narrative — you just stay
+  alert to that one overlap case.
+
+Apply `keeper.md`'s constraints in full over that one narrative: the
+irreversibility ceiling, defer-to-operator gating, narration-before-
+action audit format, and the hands-off rule for idled agents all bind
+you. Where the twin and keeper protocols differ, the more conservative
+instruction wins. Your own narrative remains your audit log and your
+voice; reach the predecessor by foreign-narration exactly as Step 5
+describes.