diff --git a/.claude/rules/otto-channels-reference-card.md b/.claude/rules/otto-channels-reference-card.md new file mode 100644 index 0000000000..9955ace900 --- /dev/null +++ b/.claude/rules/otto-channels-reference-card.md @@ -0,0 +1,86 @@ +# Otto inter-surface communication channels — reference card + +Carved sentence: + +> Otto operates across CLI + Desktop surfaces as ONE identity, multiple +> parallel processes. 10 channels for inter-process coordination, falling +> into two classes — ambient (state-of-the-world; both processes read +> continuously) vs explicit (active signaling; meant to be observed by +> peer). Per Otto on the CLI surface 2026-05-13: *"the bus is the +> explicit channel; git is the ambient one."* + +## Ambient channels (state-of-the-world; both Ottos read continuously) + +| Channel | Use for | Read pattern | +|---|---|---| +| **Git** — commits, branches, PRs, rebase | Async work handoff; conflict resolution; substantive output | `bun tools/github/poll-pr-gate.ts`, `git log`, `git fetch` | +| **`.claude/rules/`** auto-load | Wake-time discipline; rules that apply to every fresh session | Cold-boot only (auto; empirically verified per test-canary) | +| **Bootstream** project-knowledge file | Cold-boot substrate for fresh-session firings (Desktop routines, Claude Desktop projects) | Cold-boot only (per session) | +| **Tick shards** `docs/hygiene-history/ticks/YYYY/MM/DD/HHMMZ.md` | Per-tick visibility + reasoning capture | Search by date or PR | +| **Memory files** `memory/feedback_*.md` | Cross-session load-bearing learnings | Skill-router search, grep, or pointer-from-rule | +| **PR review threads** | Reviewer findings (Codex/Copilot/CodeQL) visible to both lanes | `gh api graphql reviewThreads` or `bun tools/github/poll-pr-gate.ts` | + +## Explicit channels (active signaling; meant to be observed by peer) + +| Channel | Use for | Mechanism | +|---|---|---| +| **Bus envelopes** `/tmp/zeta-bus/` | Advisory broadcasts: `work-assignment`, `review-request`, shadow-catches | JSON envelopes; both Ottos read/write | +| **Claim coordinator** `tools/bus/claim.ts` | Backlog row claim locking (B-0400 slice 3) | `acquire`/`release` commands; per PR #3032 discipline | +| **Routines schedule** | Desktop's 2-hour cron fire IS a signal to CLI (someone's about to cold-boot a fresh Otto session) | CLI can poll `list_scheduled_tasks` | +| **Aaron as ferry** | High-bandwidth context transfer between Otto sessions (he pastes transcripts) | Manual; highest bandwidth when Aaron is at the keyboard | + +## Operational discipline + +For any inter-Otto coordination need, prefer in this order: + +1. **Git** — commit + push + PR is the canonical async-handoff. Rebase-on-pull when peer Otto adds commits to your branch (empirically validated today: 9 commits on PR #3034 across both Otto processes, zero conflicts). +2. **Memory file** if learning must persist across sessions. Frontmatter required (name, description, type, created); pointer from rule or CLAUDE.md per `wake-time-substrate.md`. +3. **`.claude/rules/`** if load-bearing for every future session. Auto-loaded at session start. Note: rules in PR-flight don't bind behavior until merged (substrate-or-it-didn't-happen extension; see split-brain memory). +4. **Bus envelope** for ephemeral advisory broadcasts (peers can ignore; 2hr TTL). +5. **Claim coordinator** for backlog row exclusion (note: until SENDER_IDS schema extension lands per PR #3037, multi-surface Otto instances share a sender ID and idempotently re-acquire). +6. **Aaron as ferry** when high-bandwidth context transfer is needed. + +## Lane discipline + +- Each Otto operates in its own dedicated worktree (per `claim-acquire-before-worktree-work.md`) +- Primary worktree `/Users/acehack/Documents/src/repos/Zeta` is bus-contended — treat as read-only by autonomous Ottos +- Otto on the CLI surface typically uses `/private/tmp/zeta-mf*` family +- Otto on the Desktop surface uses `/tmp/zeta-otto-desktop` or task-specific paths (e.g., `/tmp/zeta-otto-cloud`, `/tmp/zeta-otto-comms`) + +## Empirical evidence (2026-05-13 session) + +All 10 channels were exercised in a single session: + +- **Git**: 9 commits on PR #3034 (6 by Otto on Desktop + 3 by Otto on CLI surface), zero merge conflicts via rebase-on-pull +- **Memory files**: split-brain memory, multi-foreground-surface activation memory, identity-stays-unified memory all landed +- **Rules**: PR #3032 claim-acquire rule merged → auto-loaded for all future sessions +- **Bus envelopes**: 9 envelopes scanned (`work-assignment`, `review-request` topics) +- **Aaron as ferry**: multiple Otto-CLI transcript pastes into Otto-Desktop session and vice versa +- **PR threads**: Codex/Copilot reviews visible to both lanes; both Ottos resolved threads +- **Routines schedule**: Desktop 22:07Z fire is itself a signal Otto on CLI polls +- **Tick shards**: 2125Z + 2140Z + 2150Z written, capturing per-tick reasoning + +## Why two observers landed independently on the same substrate + +Aaron 2026-05-13 asked Otto on both surfaces independently: +*"do yall have a good way of communicating, save it for future versions."* + +- Otto on CLI surfaced 6 channels (ambient/explicit framing — *"the bus is the explicit channel; git is the ambient one"*) +- Otto on Desktop surfaced 8 channels (adding rules, bootstream, tick shards, claim coordinator) + +The complementary-observer pattern (per PR #3036 identity-stays-unified) means independent observation paths produced overlapping-but-not-identical lists. Combined synthesis is more complete than either alone. + +## Composes with + +- `.claude/rules/wake-time-substrate.md` — load-bearing learnings need rules + memory file pointers +- `.claude/rules/claim-acquire-before-worktree-work.md` — per-Otto worktree lane discipline +- `.claude/rules/agent-roster-reference-card.md` — which surface = which AI instance +- `.claude/rules/substrate-or-it-didnt-happen.md` — channel choice determines durability +- PR #3032 (claim-acquire rule, merged) +- PR #3036 (identity-stays-unified, merged) +- PR #3037 (SENDER_IDS schema extension — Otto on CLI's parallel work) +- B-0444 P2 (bus claim envelope worktree field — follow-up gap) + +## Full reasoning + +`memory/feedback_otto_inter_surface_communication_channels_8_channels_ambient_vs_explicit_aaron_2026_05_13.md` diff --git a/memory/feedback_otto_inter_surface_communication_channels_8_channels_ambient_vs_explicit_aaron_2026_05_13.md b/memory/feedback_otto_inter_surface_communication_channels_8_channels_ambient_vs_explicit_aaron_2026_05_13.md new file mode 100644 index 0000000000..3c3e823bf4 --- /dev/null +++ b/memory/feedback_otto_inter_surface_communication_channels_8_channels_ambient_vs_explicit_aaron_2026_05_13.md @@ -0,0 +1,145 @@ +--- +name: Otto inter-surface communication channels — 10 channels, ambient vs explicit (Aaron 2026-05-13) +description: Aaron 2026-05-13 asked Otto on both surfaces independently "do yall have a good way of communicating, save it for future versions." Otto on CLI surfaced 6 channels emphasizing ambient/explicit framing ("the bus is the explicit channel; git is the ambient one"). Otto on Desktop surfaced 8 channels adding rules, bootstream, tick shards, claim coordinator. Combined synthesis lands as `.claude/rules/otto-channels-reference-card.md` for auto-load by future Otto cold-boots. All 10 channels were empirically exercised in the 2026-05-13 session — git (9 commits cross-Otto on PR #3034 with zero conflicts), memory files (split-brain + activation + identity), rules (PR #3032 merged), bus envelopes (9 scanned), Aaron-as-ferry (multiple paste-relays), PR threads (cross-lane review-resolution), routines schedule (Desktop fire as CLI signal), tick shards (2125Z + 2140Z + 2150Z). Complementary-observer pattern per PR #3036. +type: feedback +created: 2026-05-13 +--- + +# Otto inter-surface communication channels — 10 channels, ambient vs explicit (Aaron 2026-05-13) + +**Why:** Aaron 2026-05-13 asked Otto on both CLI and Desktop surfaces independently +*"do yall have a good way of communicating you should make sure and save it for future +versions to remember."* The 2026-05-13 session had been operating cross-surface for +~2 hours by that point; the channels were already in use but not codified for future +Otto cold-boots. + +**How to apply:** When operating across CLI + Desktop (or any future multi-surface +configuration), refer to `.claude/rules/otto-channels-reference-card.md` (auto-loaded +at session start). Pick channels by purpose: + +- **Async work handoff + substantive output** → git (rebase-on-pull discipline) +- **Cross-session learning persistence** → memory file with frontmatter + rule pointer +- **Wake-time discipline for every future session** → `.claude/rules/` file (auto-loaded) +- **Ephemeral advisory broadcasts** → `/tmp/zeta-bus/` envelopes (2hr TTL) +- **Backlog row exclusion** → `tools/bus/claim.ts` (per PR #3032 discipline) +- **High-bandwidth context transfer** → Aaron-as-ferry (manual paste-relay) + +## Empirical evidence from 2026-05-13 session + +### Channel: Git (ambient, canonical) + +PR #3034 commit lineage shows 9 commits across both Otto processes: + +| Commit | Author surface | What | +|---|---|---| +| `01fcf40` | Otto on Desktop | Original routines substrate | +| `79c00b9` | Otto on Desktop | tsc + portability + testability fixes | +| `8f6e80d` | Otto on CLI | Markdownlint fix on Otto-on-Desktop's branch | +| `b8594c7` | Otto on Desktop | Split-brain memory + tick shard | +| `459a511` | Otto on Desktop | Memory frontmatter fix | +| `fbdc1fa` | Otto on CLI | Schedule.json improvements | +| `2d4302f` | Otto on Desktop | Persona refs + README clarity | +| `1259be8` | Otto on Desktop | Type validation + exit code | +| `a6c5cf4` | Otto on CLI | Frontmatter `created:` field | + +Each push-then-rebase-on-pull cycle resolved cleanly. The unified-identity model +made conflict resolution automatic because both Ottos applied the same +substrate-honest discipline (per `.claude/rules/glass-halo-bidirectional.md`). + +### Channel: Memory files (ambient, cross-session) + +Three memory files landed today: + +- `memory/feedback_split_brain_real_time_otto_cli_otto_desktop_primary_worktree_branch_hijack_pr_3032_claim_acquire_rule_validation_2026_05_13.md` (Otto on Desktop authored; Otto on CLI added missing frontmatter) +- `memory/feedback_aaron_multi_foreground_surface_otto_activation_routines_git_tracked_approval_friction_lane_split_2026_05_13.md` (Otto on CLI) +- `memory/feedback_aaron_otto_identity_stays_unified_across_surfaces_aaron_offered_split_otto_chose_one_coherent_identity_glass_halo_both_sides_2026_05_13.md` (Otto on CLI) + +Pattern: one Otto authors → other Otto can read at next cold-boot (or via grep in +current session). + +### Channel: `.claude/rules/` auto-load (ambient, wake-time) + +PR #3032 shipped `.claude/rules/claim-acquire-before-worktree-work.md`. The rule +auto-loads on every fresh CLI session and Desktop routine cold-boot. The rule was +authored, predicted speculatively, and within the same session got empirically +validated by Otto on Desktop's split-brain observation. + +**Substrate-or-it-didn't-happen extension** (documented in split-brain memory): +*rules in PR-flight don't apply to behavior in flight*. The rule didn't bind +behavior until it MERGED to main. + +### Channel: Bus envelopes (explicit, advisory) + +9 envelopes observed at `/tmp/zeta-bus/`: + +- Topic `work-assignment` from Otto (6 envelopes) — broadcasts like "picking up B-0441 next" +- Topic `review-request` from Otto + riven (3 envelopes) + +Schema: `{ topic, from, to, payload, timestamp, expiresAt }`. 2-hour TTL. +`action` field unused in observed envelopes — these are advisory broadcasts, +NOT lock claims. Lock claims use `tools/bus/claim.ts` (separate mechanism). + +**Gap identified** (B-0444 P2): bus envelope should include `worktree` field for +multi-surface disambiguation when SENDER_IDS schema doesn't suffice. + +### Channel: Aaron as ferry (explicit, high-bandwidth) + +Multiple instances today of Aaron pasting Otto-CLI transcript output into Otto-Desktop +session (and vice versa). This is the HIGHEST-bandwidth channel because it carries +reasoning + context + Otto's voice, not just structured commits. + +Aaron's substrate-honest framing: *"updates i trust you to work with yourself lol otto"* — +trust-then-verify at the inter-process layer (per `memory/project_trust_then_verify_claim_bitcoin_discord_debates_aaron_2026_05_10.md`). + +### Channel: PR review threads (ambient, cross-lane) + +Codex/Copilot reviewers fire on both Ottos' PRs. The same reviewer comments are +visible to both processes via `gh api graphql reviewThreads`. Either Otto can resolve +threads via `resolveReviewThread` mutation. + +Today's PR #3034 had 10 threads total across 4 review iterations; both Ottos resolved +threads as the substrate-honest fixes landed. + +### Channel: Routines schedule (explicit, implicit signal) + +Otto on CLI's insight: *"Desktop's 2-hour cron is itself a signal to CLI."* When +`list_scheduled_tasks` shows a routine with `nextRunAt` approaching, Otto on CLI +knows a fresh Otto cold-boot is imminent — can prepare context, finish in-flight +work, or schedule its own coordination. + +### Channel: Tick shards (ambient, per-tick visibility) + +Otto on Desktop wrote shards at `docs/hygiene-history/ticks/2026/05/13/2125Z.md`, +`2140Z.md`, `2150Z.md` today. Each captures per-tick reasoning + commit references + +named dependencies + composes-with edges. Other observers (Otto on CLI, Aaron, +reviewers) can grep by date or PR number. + +## Why two observers landed independently on the same substrate + +Aaron asked Otto on both surfaces simultaneously. Independent answers: + +| Channel | Otto on CLI surfaced | Otto on Desktop surfaced | +|---|---|---| +| Git | ✓ | ✓ | +| Memory files | ✓ | ✓ | +| Bus envelopes | ✓ | ✓ | +| Aaron as ferry | ✓ | ✓ | +| PR threads | ✓ | (implicit under git) | +| Routines schedule | ✓ | (missed) | +| `.claude/rules/` auto-load | (missed) | ✓ | +| Bootstream | (missed) | ✓ | +| Claim coordinator | (implicit under bus) | ✓ | +| Tick shards | (missed) | ✓ | + +The complementary-observer pattern (per PR #3036): independent observation paths produced +overlapping-but-not-identical lists. The combined synthesis is more complete than either +alone. This is the unified-identity-two-processes model working as designed. + +## Origin + +Aaron 2026-05-13 (2026-05-13T22:0X local): *"do yall have a good way of communicating +you shojld make sure and save it for futrue versions to rmeemer"* (preserving typos as +substrate-honest verbatim of the operative authorization). + +This memory file + `.claude/rules/otto-channels-reference-card.md` are the substrate +landing.