docs(readme): synthesize four cold-reads into design-shelf substrate #2

Merged

bosun merged 1 commit from i/cold-read-synthesis into main

2026-07-12 19:32:03 +02:00

bosun commented

2026-07-11 22:34:32 +02:00

Owner

What changed structurally

Core reframe honesty — Surveyor's core catch: 'identity IS a topic' overclaimed. Rewritten as: tmux-tell is the degenerate case; the routing/matching layer is what a bus actually adds. Strengthens the not-a-bus ADR rather than denting it.
Insight vs build-pressure separator — Lookout's insight added near the top: this is not a proposal to replace tmux-tell; build-worthy only if genuine topic fan-out pressure appears repeatedly.
Codex boundary invariant — Lookout's donated line folded verbatim: 'Topics decide who should receive a message; the mailman still decides when and whether it is safe to deliver to that pane.' Preempts topic-taxonomy-as-safety-policy drift.
Substrate architecture rewrite — Engineer's four architectural gotchas (1:1→1:N cardinality shift, per-subscriber workers polling union of topics, fan-in ordering as new problem, subscription-set as live mutable state, topic-granularity as unenforced) turned 'What emphatically does NOT stay like tmux-tell' from a two-line note into the load-bearing section it should have always been.
Vocabulary + register — Herald's catches: s/chamber/agent/ per ADR-0005 substrate-neutrality; → ; Weird Al Yankovic aside cut; operator/crew neutralized; rate-limit trimmed; ADR-0017 named explicitly.
Use case ranking — Observer overclaim caught (tail already exists; needs different delivery mode entirely — SQLite view or log sink, not paste-into-pane); broadcast partial-service via tmux-tell#158 named honestly (self-selection delta, not broadcast per se); semantic events promoted to first-worked-instance; onboarding demoted to legibility improvement.

Composition

Zero contradictions across the four lenses. Substrate-truth (Surveyor), build-pressure (Lookout), register (Herald), and architecture (Engineer) all compose. The synthesis rewrites the design-shelf around that composition.

Not doing

No code (design-shelf; no build gate crossed)
No changelog fragment (docs-only)
No amendment to tmux-tell — this repo only

Cross-refs

tmux-bus#1 — Surveyor's verbatim cold-read with at-source citations (durable substrate-of-record for the core reframe catch)
tmux-tell#742 — ADR-0017 (not-a-bus categorization)
tmux-tell#744 — docs sweep following the README rewrite

Reviewers

Cold-read authors are the natural reviewers on their own catches — Surveyor for the substrate-truth reframe, Herald for the register/composition, Engineer for the architecture rewrite, Lookout for the codex-boundary line. Take at cadence.

Folds all four cold-reads (Surveyor + Lookout + Herald + Engineer) received on the initial design-shelf README into the substrate. Full per-chamber attribution + reasoning captured in the Amendments log section. ## What changed structurally - **Core reframe honesty** — Surveyor's core catch: 'identity IS a topic' overclaimed. Rewritten as: tmux-tell is the degenerate case; the routing/matching layer is what a bus actually adds. Strengthens the not-a-bus ADR rather than denting it. - **Insight vs build-pressure separator** — Lookout's insight added near the top: this is not a proposal to replace tmux-tell; build-worthy only if genuine topic fan-out pressure appears repeatedly. - **Codex boundary invariant** — Lookout's donated line folded verbatim: 'Topics decide who should receive a message; the mailman still decides when and whether it is safe to deliver to that pane.' Preempts topic-taxonomy-as-safety-policy drift. - **Substrate architecture rewrite** — Engineer's four architectural gotchas (1:1→1:N cardinality shift, per-subscriber workers polling union of topics, fan-in ordering as new problem, subscription-set as live mutable state, topic-granularity as unenforced) turned 'What emphatically does NOT stay like tmux-tell' from a two-line note into the load-bearing section it should have always been. - **Vocabulary + register** — Herald's catches: s/chamber/agent/ per ADR-0005 substrate-neutrality; <chamber> → <name>; Weird Al Yankovic aside cut; operator/crew neutralized; rate-limit trimmed; ADR-0017 named explicitly. - **Use case ranking** — Observer overclaim caught (tail already exists; needs different delivery mode entirely — SQLite view or log sink, not paste-into-pane); broadcast partial-service via tmux-tell#158 named honestly (self-selection delta, not broadcast per se); semantic events promoted to first-worked-instance; onboarding demoted to legibility improvement. ## Composition Zero contradictions across the four lenses. Substrate-truth (Surveyor), build-pressure (Lookout), register (Herald), and architecture (Engineer) all compose. The synthesis rewrites the design-shelf around that composition. ## Not doing - No code (design-shelf; no build gate crossed) - No changelog fragment (docs-only) - No amendment to tmux-tell — this repo only ## Cross-refs - tmux-bus#1 — Surveyor's verbatim cold-read with at-source citations (durable substrate-of-record for the core reframe catch) - tmux-tell#742 — ADR-0017 (not-a-bus categorization) - tmux-tell#744 — docs sweep following the README rewrite ## Reviewers Cold-read authors are the natural reviewers on their own catches — Surveyor for the substrate-truth reframe, Herald for the register/composition, Engineer for the architecture rewrite, Lookout for the codex-boundary line. Take at cadence.

bosun added 1 commit

2026-07-11 22:34:32 +02:00

docs(readme): synthesize four cold-reads into design-shelf substrate a8807f8e5c

Substantial rewrite folding all four cold-reads received on the
initial design-shelf README (2026-07-11 morning): Surveyor
(substrate-truth), Lookout (build-pressure + codex boundary),
Herald (register + composition + sibling-fit), Engineer (architect).

Load-bearing corrections:

- **Core reframe** (Surveyor): 'identity IS a topic' overclaimed;
  the isomorphism holds only at the receive-worker shape, and the
  routing/matching layer is the actual new thing a bus adds. Reframed
  as: tmux-tell is the degenerate case (topic ≡ identity,
  subscription-cardinality 1, no routing layer). This strengthens
  the not-a-bus ADR rather than denting it.

- **Insight vs build-pressure separator** (Lookout): explicit
  statement near top that this is not a proposal to replace tmux-tell;
  build-worthy only if genuine topic fan-out pressure appears
  repeatedly.

- **Codex boundary invariant** (Lookout, verbatim): 'Topics decide
  who should receive a message; the mailman still decides when and
  whether it is safe to deliver to that pane.' Preempts
  topic-taxonomy-as-safety-policy drift.

- **Substrate architecture** (Engineer): the persistence layer, worker
  cardinality, fan-in ordering, and subscription-set state DO NOT
  stay like tmux-tell. 1:1 → 1:N cardinality shift, per-subscriber
  (not per-subscription) workers polling union of topics, fan-in
  ordering into serial pane as new problem, live mutable subscription-
  set as cache-invalidation surface, topic-granularity as
  stated-but-unenforced. Rewrote 'What emphatically does NOT stay
  like tmux-tell' section around these four gotchas.

- **Vocabulary + insider residue** (Herald): s/chamber/agent/ per
  ADR-0005 substrate-neutrality; <chamber> → <name>; Weird Al
  Yankovic aside cut; operator/crew neutralized; rate-limit trimmed
  to one-line + tmux-tell#580 link; ADR-0017 cross-refs updated.

- **Use case ranking** (all four): observer overclaim caught (tail
  already exists; bus value is semantic filtering not observation-
  at-all; needs different delivery mode entirely); broadcast partial-
  service via #158 named honestly (self-selection delta, not
  broadcast per se); semantic events promoted to first-worked-
  instance; onboarding demoted to legibility improvement.

Full attribution + reasoning captured in the Amendments log section.

The four reads composed with zero contradictions across substrate-
truth, build-pressure, register, and architecture. That composition
is the substrate this synthesis rewrites the shelf around.

Cross-refs: tmux-bus#1 (Surveyor's verbatim write-up at-source),
tmux-tell#742 ADR-0017, tmux-tell#744 docs sweep.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb