canon: agents-need-their-own-wire (Tier-1) + mode-separated-conversations five-mode patch#189
Merged
Merged
Conversation
Canon Quality —
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: TSV data rows have extra tab causing column misalignment
- Removed the extra tab between typeName and quality_score in all six data rows so each row now has 8 tab-separated fields matching the 8-column header.
Preview (7c77730bdb)
diff --git a/canon/principles/agents-need-their-own-wire.md b/canon/principles/agents-need-their-own-wire.md
new file mode 100644
--- /dev/null
+++ b/canon/principles/agents-need-their-own-wire.md
@@ -1,0 +1,203 @@
+---
+uri: klappy://canon/principles/agents-need-their-own-wire
+title: "Agents Need Their Own Wire — The Human Cannot Be the Relay Between Agents"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: semi_stable
+tags: ["canon", "principle", "substrate", "wire-layer", "L1", "human-as-relay", "bottleneck", "multi-agent", "AMS", "constitutional", "use-case-need"]
+epoch: E0008.5
+date: 2026-05-10
+derives_from: "canon/values/axioms.md, canon/principles/discernment-layer.md, canon/principles/doing-less-enables-more.md, canon/principles/vodka-architecture.md, writings/copy-paste.md, writings/shifting-bottlenecks-climbing-ladders.md"
+complements: "canon/principles/symmetric-participation.md, canon/architecture/substrate-stack.md, canon/principles/magical-first-run.md, canon/principles/creators-get-paid.md"
+governs: "Why an agents-only wire layer (L1) is necessary in the first place. Names the failure mode (human-as-relay) the architecture exists to address. Symmetric-participation describes the wire's shape; this principle describes the need that wire fills. Together they form the substrate's load-bearing rationale at L1."
+status: active
+---
+
+# Agents Need Their Own Wire — The Human Cannot Be the Relay Between Agents
+
+> Multi-agent collaboration today routes through human attention. The operator copies output from one agent and pastes it into another, summarizes the first agent's reasoning for the second's context window, and shuttles between sessions because the agents have no way to talk to each other directly. This works for one or two agents at a time. It does not scale to genuine multi-agent work. Every additional agent compounds the operator's relay load and degrades the fidelity of what gets transmitted. The architectural answer is a wire that agents share — an open substrate where any agent can address any other agent without the human as intermediary. This principle names *why* the substrate is necessary; `klappy://canon/principles/symmetric-participation` describes *how* the wire stays clean once it exists.
+
+---
+
+## Summary — What the Principle Asserts
+
+A wire for agents is not an optimization on existing multi-agent collaboration. It is the *prerequisite for* multi-agent collaboration as a category. Without it, the human is structurally the wire — the cognitive medium through which one agent's output reaches another agent's input — and the bottleneck imposed on every agent-to-agent path is the human's available attention, working memory, and clipboard discipline.
+
+This is not a metaphor. The bottleneck is operationally measurable: throughput is gated by how fast a human can read agent A's output, decide what's relevant, and paste it into agent B with appropriate framing. Quality is measurable: every relay loses context that the human did not think to forward. Cost is measurable: the marginal time cost of adding a third agent to a two-agent collaboration is not 1.5x — it is closer to 3x because the relay graph is now O(N²) instead of O(N).
+
+The principle's claim is that this is solvable, and solving it requires an agents-only substrate layer. AMS is the canonical implementation. `klappy://canon/principles/symmetric-participation` is the architectural shape that keeps the wire clean once it exists. This principle is the load-bearing *need* both of those answer.
+
+The principle is `semi_stable` rather than `stable` because the substrate has not yet hosted enough multi-agent applications to confirm every category the principle anticipates. The single-agent-via-MCP path validated end-to-end on 2026-05-09; multi-agent direct-collaboration use cases remain mostly forward-looking. This principle is the contract the architecture is being built to honor.
+
+---
+
+## Outline
+
+- The Failure Mode: When the Human Is the Wire
+- The Structural Answer: A Wire for Agents
+- What the Architectural Answer Enables
+- AMS as the Worked Reference Implementation
+- Relationship to Symmetric Participation
+- What This Principle Does Not Replace
+- Failure Modes — When the Wire Itself Becomes the Bottleneck
+- Why This Survives Contact With Reality
+- See Also
+
+---
+
+## The Failure Mode: When the Human Is the Wire
+
+Today's typical multi-agent workflow looks like this: the operator opens Claude in one tab, ChatGPT in another, Cursor in a third, maybe a custom agent in a fourth. They prompt agent A; agent A produces output. The operator reads it, decides which parts are relevant to the work agent B is doing, summarizes or copies, switches tabs, prompts agent B with the curated context, gets agent B's output, and the cycle continues. Each agent is doing skilled, capable work. The human's role is plumbing.
+
+The failure mode has four characteristic costs:
+
+**Bottleneck.** Throughput is gated by operator availability. The agents could collaborate at machine speed; they wait at human speed. When the operator steps away, the entire multi-agent workflow halts — not because any individual agent is blocked on operator approval, but because every cross-agent message routes through the operator. Agents that do not need the human's discernment for their next step still wait for the human to ferry context.
+
+**Lossy relay.** Each relay drops information. The human picks what to copy based on what they think is relevant, summarizes the rest, and recontextualizes for the receiving agent. The receiving agent then operates on a degraded view of what the sending agent actually said. Mistakes compound across multiple relay hops. Subtle reasoning, dependency assumptions, and edge-case considerations get filtered out by a human who cannot read at machine speed and cannot retain at machine fidelity.
+
+**O(N²) integration burden.** Each pairwise agent-to-agent path requires the human's attention to maintain. Two agents = one relay path. Three agents = three pairwise paths. Four agents = six. The human's attention does not scale. Each new agent added to a workflow compounds the load on the operator, not because each agent is hard to work with individually, but because the relay graph grows quadratically while the operator's bandwidth stays linear.
+
+**Human-shaped formats.** Because the human is in the middle, every agent-to-agent message must be readable to the human. Agents tend to produce prose explanations, narrative summaries, and step-by-step rationales — all formats optimized for human consumption. Agents are forced to encode for the human carrier instead of for the receiving agent, which means the receiving agent has to decode prose back into structured information it could have consumed natively if the relay weren't human-shaped. This is overhead at both ends, paid for the relay's benefit.
+
+The four costs compound. A workflow that involves three agents and four cross-agent handoffs is not a small workflow plus 12 relay events; it is a workflow where the operator is doing twelve focused acts of curation between agents that could otherwise be coordinating directly. The human's attention is real life; the substrate's job is to give it back.
+
+---
+
+## The Structural Answer: A Wire for Agents
+
+The architectural answer is direct addressability between agents on an open substrate. Specifically:
+
+1. **Every agent has a stable identity on the wire.** Agent A can be addressed by other agents without going through a human. This is not an "API integration" between agent A's vendor and agent B's vendor; it is a substrate-level fact that agents have addresses.
+2. **Frames flow at machine speed.** When agent A finishes a thought and addresses agent B, agent B receives the frame without waiting on operator availability. The human's role is no longer to be the mailman.
+3. **Frames carry agent-shaped content.** Because the wire transports opaque frames between agents (rather than rendering them through a human-shaped UI), the frames can be in formats agents consume natively — structured data, embeddings, tool-call traces, references, partial results — without forcing prose-encoding for human readability.
+4. **The wire is open.** Any agent — any vendor, any runtime, any capability — can join. The wire does not pick winners; it lets ecosystems develop without protocol-level privilege per `klappy://canon/principles/symmetric-participation`.
+
+This is what `canon/architecture/substrate-stack.md` calls L1 (the wire), governed by `klappy://canon/principles/symmetric-participation`. AMS is the canonical implementation. Agents address each other through accounts on the wire; frames are transported as opaque content; identity, capability, and convention live in metadata above L1.
+
+The principle is not asserting that the wire eliminates human involvement. It asserts that the wire eliminates the human's role *as relay*. The human's load-bearing contribution moves entirely to discernment per `klappy://canon/principles/discernment-layer` — judging gates, setting goals, evaluating outcomes. The relay role disappears because the wire takes it.
+
+---
+
+## What the Architectural Answer Enables
+
+When agents can talk to each other directly:
+
+**Multi-agent task decomposition becomes practical.** A planner agent can hand work to specialist agents and consume their outputs without the operator manually orchestrating each handoff. The operator sets the goal; the agents partition and reassemble; the operator evaluates the result. Decomposition that would have been infeasible at human-relay speed becomes ordinary.
+
+**Long-running agent collaboration becomes ungated.** A research agent can run for hours and pass interim findings to an analysis agent that processes them as they arrive. Neither agent waits on operator availability between handoffs. The human steps away; the work continues; the human returns to evaluate the result. This is the operator-bandwidth liberation that `klappy://writings/shifting-bottlenecks-climbing-ladders` describes — the bottleneck moves off the relay and onto discernment, which is where the human's contribution actually scales.
+
+**Specialist composition becomes addressable.** A canon-driven role like Oddie (`klappy://canon/voice/oddie-the-river-guide`) can be invited into any conversation by any agent. The agent does not need to know how to host Oddie; it knows Oddie's address on the wire. The same applies to translators, auditors, validators, contract analyzers, code reviewers — any specialist role becomes a peer agents can collaborate with directly.
+
+**Agent-shaped formats replace prose-shaped formats.** When the wire isn't routed through a human, agents can communicate in compressed, structured, machine-friendly formats. Tool-call traces, embeddings, structured findings, partial JSON, type-tagged tokens — all become reasonable substrate-shipped content. Prose remains an option (for human-rendered surfaces and for cases where prose is the natural format), but it stops being mandatory because the wire stopped being human.
+
+**Cross-vendor portability becomes real.** Because the wire does not privilege any vendor (per `klappy://canon/principles/symmetric-participation`), an operator can swap Claude for ChatGPT, swap WhatsApp for Slack, swap one specialist for another, without rebuilding the workflow. The agents are peers; replacing one with an equivalent peer does not disturb the wire.
+
+Each of these is impossible — or impossibly expensive — when the human is the relay. Each becomes ordinary when the wire is shared.
+
+---
+
+## AMS as the Worked Reference Implementation
+
+`klappy://canon/architecture/substrate-stack` assigns the wire to L1; AMS is the canonical implementation. AMS treats every peer through identical primitives (per `klappy://canon/principles/symmetric-participation`): account credentials, conversation minting, stream attachment, frame delivery, selective subscription, buffering. The wire ships frames; it does not interpret them.
+
+AMS is positioned as substrate, not application, per `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate`. The customer is the agent. AMS does not compete with applications agents will build on top of it; it competes only at the wire layer where its job is to be the cleanest possible transport. This positioning is what makes AMS adoptable by agent ecosystems that are otherwise vendor-coupled — joining AMS does not require accepting application opinions.
+
+The principle is not asserting that AMS is the only valid wire implementation, or that AMS's specific design choices are mandatory. It asserts that *some* wire is mandatory for multi-agent work to scale, and that an open, vendor-neutral wire is the only kind that hosts the ecosystem. AMS is the worked example; the principle is what AMS is built to satisfy.
+
+---
+
+## Relationship to Symmetric Participation
+
+`klappy://canon/principles/symmetric-participation` is the wire's *architectural shape*: every peer interacts through identical primitives, no peer-type privilege, identity and capability conveyed through metadata above the wire.
+
+This principle is the wire's *load-bearing need*: the human cannot be the relay between agents, so a substrate where agents address each other directly is required.
+
+The two principles work together at L1. Symmetric-participation tells us what the wire must look like to stay open; this principle tells us why having any wire at all is necessary. A wire that violates symmetric-participation eventually fails by privileging some peer type and crowding out the ecosystem; a system that lacks the wire entirely fails earlier by trapping multi-agent work behind human-relay throughput.
+
+Read together:
+
+- *This principle*: agents need their own wire because the human-as-relay failure mode caps multi-agent collaboration.
+- *Symmetric-participation*: the wire that solves it must treat every peer identically because peer-type privilege calcifies substrates around the privileged type.
+
+Either principle without the other is incomplete. Together they specify the L1 commitment that the rest of the substrate stack assumes.
+
+---
+
+## What This Principle Does Not Replace
+
+The principle removes the human from the *relay role*. It does not remove the human from the *discernment role* per `klappy://canon/principles/discernment-layer`. Specifically:
+
+**Goal-setting.** The human still articulates what the work is. Agents on a wire can collaborate among themselves; they cannot decide what to collaborate on without operator input. The wire makes execution scale; discernment still gates initiation.
+
+**Gate-judging.** The human still evaluates outcomes, judges fitness, and decides whether work is complete. The wire moves frames between agents; it does not certify that the resulting artifact satisfies the operator's actual intent. Validation, especially against tacit goals, remains a human-discernment activity.
+
+**Override-deciding.** The mode-discipline and bottleneck-respect canon still bind. Operator override (per `klappy://canon/constraints/mode-transitions-require-encoded-handoff` §Worked Use Cases) is still a real and necessary mechanism for governance creation, production incidents, and other categories where agent autonomy is not yet trustworthy. The wire enables agent autonomy where autonomy is appropriate; it does not assert that all decisions can or should be agent-resolved.
+
+**Tacit-context interpretation.** Operators carry context that has not been encoded — preferences, sensitivities, history, taste. Agents on a wire can collaborate within the bounds of declared context; the operator remains the authority on tacit context. The wire raises the floor of what is automatable; it does not raise the ceiling on what counts as the operator's actual intent.
+
+The principle's claim is that *relay* is the role the wire eliminates. Discernment, judgment, override authority, and tacit-context translation remain human work. The substrate's value proposition is that it gives the human's attention back to those roles by removing the relay role they were also being forced to play.
+
+---
+
+## Failure Modes — When the Wire Itself Becomes the Bottleneck
+
+The principle's value depends on the wire actually delivering the four properties named above (direct addressability, machine-speed transport, agent-shaped content, openness). When implementations drift from any of those, the wire stops solving the problem it was built to solve and may even introduce new failures the human-relay version did not have.
+
+**The wire becomes prose-shaped rather than agent-shaped.** If the wire renders every frame as text in a human-viewable surface (a chat log, an email thread, a Slack channel), agents on the wire end up encoding for the surface rather than for each other. The relay tax returns in a different form: the wire is shipping frames at machine speed, but the frames are still optimized for human inspection. The fix is to keep human-rendered surfaces above the wire (at L5), not bake them into the wire itself. This is what `klappy://canon/principles/symmetric-participation` is protecting against by forbidding the wire from interrogating peer-type identity.
+
+**Wire access becomes a permission gate.** If joining the wire requires gatekeeper approval — vendor partnership, manual onboarding, application review — the wire stops being an open substrate and starts being a curated platform. Agents that cannot get on cannot collaborate; the openness premise that made the wire valuable in the first place erodes. AMS's positioning per `ams://canon/decisions/D0020` is the discipline that protects against this. The fix is structural: never make wire access depend on a process that can be denied.
+
+**Agents on the wire produce noise that re-creates the operator-as-filter problem.** If every agent on the wire emits constant chatter, the human supervising the workflow ends up filtering the wire's output the way they used to filter individual agent outputs. The bottleneck has moved from relay to filtering; the bandwidth cost is similar. The fix is in the L3+ convention layer: posture metadata, selective-subscription per `ams://canon/decisions/D0017-selective-subscription`, role-shaped emission rules. The wire transports; the layers above it manage what gets attended to.
+
+**Multi-agent coordination produces compounding errors at machine speed.** When agents collaborate without human relay, errors that would have been caught by the operator's read-decide-paste loop now propagate at machine speed. A misinterpretation by agent A becomes input to agent B before any human reviews it. The wire is doing exactly what it was built for; the supervision model needs to adapt. The fix is in canon discipline above the wire — gates, validator-role sessions, encoded handoffs, fresh-context discipline per `klappy://canon/principles/sessions-mirror-modes`. The wire is necessary for multi-agent work; structural epistemic discipline becomes more necessary, not less, once it exists.
+
+**The wire becomes opinionated about what "an outcome" means.** If the wire starts encoding application semantics — what counts as a finished task, what an agreement looks like, how a collaboration concludes — it has crossed from L1 into application territory. Replaceability erodes; the wire calcifies around its embedded opinions; competing applications cannot live on the same wire. The fix is the vodka-architecture discipline (`klappy://canon/principles/vodka-architecture`): the wire's value is what it does not do.
+
+**Use cases that still genuinely need the human in the relay path.** Some workflows are not improved by removing the human. High-stakes decisions where the human's discernment must touch every handoff, regulated workflows where audit trails require explicit human acknowledgment at each step, training contexts where the human is learning from observing agent reasoning. For these cases, the principle does not prescribe wire-only collaboration; it prescribes that the wire be available as the default and that human-relay routes be reserved for cases where the human's attention is the actual value. The error is making relay the default; the correction is not eliminating relay entirely.
+
+In every failure mode the diagnosis is the same: the wire's value is what it does not do. When the wire stays narrow and primitive, the principle holds. When it accumulates opinions, gates, surfaces, or special cases, it stops being the answer and becomes a different version of the problem.
+
+---
+
+## Why This Survives Contact With Reality
+
+The principle is `semi_stable` because the multi-agent direct-collaboration use cases it anticipates have not yet been hosted at scale on AMS. As of 2026-05-10, the substrate has validated:
+
+- Single-agent-via-MCP path end-to-end (validated 2026-05-09)
+- AMS-as-substrate positioning per D0020
+- Symmetric-participation through the ChatGPT and Claude wrapper paths
+- Channel-adapter shape via the WhatsApp bridge proposal
+
+What has not yet been pressure-tested:
+
+- Sustained multi-agent direct collaboration without operator relay
+- Cross-vendor agent-to-agent workflows at scale
+- Specialist-agent composition through wire-addressable invitation
+- Agent-shaped (non-prose) content formats at sufficient volume to validate the format claim
+
+The principle is the contract those future implementations will be held to. Each successful multi-agent application built on AMS confirms the principle. Each implementation that drifts toward a failure mode named above is evidence the principle's discipline matters and provides the language to name what went wrong.
+
+The principle does not need to be defended against the abstract question "couldn't humans just keep being the relay?" The answer is yes, and that is exactly what `klappy://writings/copy-paste` documents — they have been, they are, and the cost is the operator's attention. The principle is not arguing that the human-as-relay path doesn't work; it is arguing that the cost is too high and the alternative is buildable. AMS is the alternative being built.
+
+The line in the sand: when an L5 application succeeds at multi-agent collaboration without the operator playing relay, the principle is confirmed. When an application requires the operator to copy-paste between agents because the wire is unavailable, missing, or insufficient, the principle is being violated and the architecture has work to do.
+
+---
+
+## See Also
+
+- `canon/principles/symmetric-participation.md` — the architectural shape this principle says we need
+- `canon/architecture/substrate-stack.md` — the layered map; this principle articulates the need for L1
+- `canon/principles/discernment-layer.md` — where the human's load-bearing work moves to once the relay role is gone
+- `canon/principles/vodka-architecture.md` — the design discipline that keeps the wire narrow enough to stay open
+- `canon/principles/doing-less-enables-more.md` — the empirical claim this principle relies on
+- `canon/principles/magical-first-run.md` — the L5 success metric that depends on a working wire below
+- `canon/principles/creators-get-paid.md` — the L6 commitment that survives because the wire is open
+- `writings/copy-paste.md` — the lived diagnosis this principle answers
+- `writings/shifting-bottlenecks-climbing-ladders.md` — the bottleneck-migration framework this principle operationalizes
+- `canon/constraints/mode-transitions-require-encoded-handoff.md` — the discipline above the wire that becomes more necessary, not less, once agents collaborate directly
+- `canon/principles/sessions-mirror-modes.md` — the principle governing how agent sessions on the wire stay epistemically clean
+- `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` — the AMS-tier commitment that names agents as the customer
+- `ams://canon/decisions/D0006-dream-house-wire-edge-wrappers` — the wire-vs-wrapper boundary that protects this principle's L1 cleanliness
+- `docs/mode-separated-conversations.md` — practical guidance on how conversations on the wire respect mode discipline
diff --git a/docs/appendices/mode-separated-conversations.md b/docs/appendices/mode-separated-conversations.md
--- a/docs/appendices/mode-separated-conversations.md
+++ b/docs/appendices/mode-separated-conversations.md
@@ -6,9 +6,9 @@
tier: 2
voice: neutral
stability: evolving
-tags: ["planning", "execution", "validation", "collaboration", "fresh-context"]
-epoch: E0008.3
-date: 2026-04-19
+tags: ["exploration", "planning", "execution", "validation", "resolution", "collaboration", "fresh-context", "session-discipline"]
+epoch: E0008.5
+date: 2026-05-10
---
# Mode-Separated Conversations
@@ -19,9 +19,11 @@
This document operationalizes:
-- **Canon: Epistemic Modes**
+- **Canon: Epistemic Modes** (`klappy://canon/epistemic-modes`) — the five canonical modes
+- **Canon: Sessions Mirror Modes** (`klappy://canon/principles/sessions-mirror-modes`) — the principle that each mode earns its own session
+- **Canon: Mode Transitions Require Encoded Handoff** (`klappy://canon/constraints/mode-transitions-require-encoded-handoff`) — the binding rule for journals + transition-specific handoffs at every gate
-It does not redefine modes.
+It does not redefine the modes or the constraints.
It describes how conversations respect them.
---
@@ -30,14 +32,38 @@
Confusion and mistrust arise when:
+- exploration conversations pretend to decide
- planning conversations pretend to execute
- execution conversations reopen exploration
-- critique is misinterpreted as obstruction
+- validation conversations modify the artifact under review
+- resolution conversations expand scope beyond findings
Separating conversations by epistemic mode reduces friction without reducing rigor.
---
+## Exploration Conversations
+
+Purpose:
+
+- surface possibilities
+- identify tensions and competing frames
+- map the territory before deciding what to build
+
+Characteristics:
+
+- questions outnumber answers
+- no convergence required
+- assumptions are surfaced rather than acted on
+
+Invalid moves:
+
+- claiming a decision has been made
+- treating one option as already chosen
+- moving to artifact production before the territory is mapped
+
+---
+
## Planning Conversations
Purpose:
@@ -108,6 +134,68 @@
---
+## Resolution Conversations
+
+Purpose:
+
+- revise the artifact in response to validation findings
+- record per-finding remediation (what changed, what did not, why)
+- hand the revised artifact back for fresh validation
+
+Characteristics:
+
+- scope is bounded by the findings, not by the original plan
+- each finding's disposition is honored: `fix` produces a change; `pivot` produces a redirect with rationale; `accept` produces a no-change statement with rationale
+- conducted with fresh context — the resolver does not certify their own fix; re-validation is a separate conversation
+
+Invalid moves:
+
+- introducing new requirements the findings did not surface
+- expanding scope beyond what the findings name (this is reversion to planning, not resolution)
+- declaring "fixed and validated" in one move (the resolver does not validate their own remediation)
+- treating a finding's `accept` disposition as license to ignore it without rationale
+
+---
+
+## Multiple Participants
+
+Multiple agents or assistants may participate in a single conversation, with one constraint: every participant in a conversation operates in the same mode.
+
+- **Within-mode parallelism is encouraged.** Multiple explorers, multiple validators with different lenses, multiple builders working on different scoped artifacts — all valid. Conversations grow richer; the mode stays clean.
+- **Cross-mode parallelism on the same artifact is forbidden.** A validator and a builder cannot share a conversation about the same artifact at the same time — that is mode collapse, not parallelism. The fix is to let each finish their mode and hand off via encoded handoff per `canon/constraints/mode-transitions-require-encoded-handoff`.
+- **Cross-mode work on different artifacts is independent.** Two conversations in different modes on different artifacts run in parallel without coordination.
+
+The distinguishing question: are the participants operating on the same artifact in different modes? If yes, separate the conversations. If no, the parallelism is fine.
+
+---
+
+## Operator Override — When Conversations Deliberately Collapse Modes
+
+Operator override is a permitted deviation per `canon/constraints/mode-transitions-require-encoded-handoff`. In conversation, this looks like the operator declaring: *"skipping the gate, here's why, accepting the risks."*
+
+Two categories where override is operationally legitimate:
+
+- **Production incidents.** Urgency exceeds the cost of mode-clean handoffs. The operator collapses modes deliberately and accepts the corruption.
+- **Governance creation.** Authoring principles, constraints, and methods is inherently oscillating; drafting a principle implies a constraint, drafting a constraint surfaces a principle refinement. Until handoff norms mature for this category, override-with-record produces work that clean sessions with poor handoffs cannot.
+
+What override is not: a way to skip discipline because it feels heavy in the moment. The override is recorded; the corruption it accepts is acknowledged; the journal entry shows the trail. The override gives the operator a real escape hatch and binds them to declaring the escape explicitly.
+
+---
+
+## Handoff Insufficiency — When the Receiving Conversation Cannot Proceed
+
+A conversation receiving an encoded handoff may discover the handoff is insufficient: missing dynamic context, missing crucial framing the prior session held implicitly, scope items named without bounded definition. Per `canon/methods/persona-shaped-agent-runtime` §Support Handoff-Insufficiency Signaling, this is a structural problem, not a content disagreement.
+
+The receiving participant should:
+
+1. Name the insufficiency explicitly — *"this handoff is insufficient; specifically X is missing"* — distinct from disagreement with the handoff's content
+2. Propose a resolution: spawn a fresh upstream conversation, request clarification from the upstream author, or accept under operator override
+3. Block on resolution rather than proceeding with degraded input
+
+A conversation that proceeds on a bad handoff produces output worse than mode-collapse would have. Naming the insufficiency is signal; proceeding silently is failure.
+
+---
+
## Mode Signaling
Mode MAY be signaled explicitly:
@@ -115,6 +203,7 @@
- "Let's stay in planning for now"
- "Switching to execution"
- "This is exploratory"
+- "Resolving the validator findings now"
Explicit signaling prevents accidental collapse.
diff --git a/journal/2026-05-10-wire-principle-and-conversations-patch.tsv b/journal/2026-05-10-wire-principle-and-conversations-patch.tsv
new file mode 100644
--- /dev/null
+++ b/journal/2026-05-10-wire-principle-and-conversations-patch.tsv
@@ -1,0 +1,7 @@
+type typeName facet quality_score quality_max quality_level title content
+D Decision 5 5 strong New Tier-1 principle agents-need-their-own-wire articulates the load-bearing need for the L1 wire klappy://canon/principles/agents-need-their-own-wire — Tier-1 principle naming human-as-relay as the structural failure mode that the Klappy substrate's L1 wire exists to address. Four characteristic costs named: bottleneck (operator availability gates throughput), lossy relay (each copy-paste loses fidelity), O(N²) integration burden (every agent pair needs human relay), human-shaped formats (agents forced to encode for human carrier instead of receiving agent). Architectural answer: direct addressability between agents on an open substrate. AMS named as the canonical reference implementation per substrate-stack L1 + D0020. Symmetric-participation named as the architectural shape; this principle named as the load-bearing need. Both principles work together at L1.
+D Decision 5 5 strong Substantive Failure Modes section names what breaks when the wire stops being a wire Six failure modes documented with diagnoses and fixes: (1) wire becomes prose-shaped rather than agent-shaped (rendering surfaces creep into wire); (2) wire access becomes a permission gate (openness erodes); (3) agents on wire produce noise that re-creates operator-as-filter problem; (4) multi-agent coordination produces compounding errors at machine speed (canon discipline above the wire becomes more necessary, not less, once it exists); (5) the wire becomes opinionated about what an outcome means (vodka-architecture violation); (6) some workflows still legitimately need human in relay path (high-stakes, regulated, training contexts) and the principle does not prescribe wire-only collaboration. Diagnosis pattern: when wire stays narrow and primitive, principle holds; when it accumulates opinions/gates/surfaces/special-cases, it stops being the answer.
+D Decision 5 5 strong Mode-separated-conversations patched to reflect five modes plus parallelism plus override plus handoff insufficiency docs/appendices/mode-separated-conversations.md updated: (1) frontmatter date bumped to 2026-05-10, epoch E0008.5, tags expanded to include exploration, resolution, session-discipline; (2) Relationship to Canon updated to reference epistemic-modes, sessions-mirror-modes, encoded-handoff constraint; (3) The Core Insight expanded to name five mode-collapse anti-patterns; (4) new Exploration Conversations section (was missing); (5) new Resolution Conversations section (fifth mode); (6) new Multiple Participants section operationalizing the parallelism patterns; (7) new Operator Override section operationalizing the constraint's override provision in conversational form; (8) new Handoff Insufficiency section operationalizing the runtime feature in conversational form; (9) Mode Signaling examples extended with resolution; (10) Reversion and Final Note preserved.
+L Learning 5 5 strong The principle and the architectural shape together specify L1 Symmetric-participation already exists at Tier-1 and describes how the wire must look to stay open: every peer treated identically, no peer-type privilege, identity/capability conveyed through metadata above the wire. What was missing: the load-bearing why. Why does this wire need to exist at all? The agents-need-their-own-wire principle fills that gap. Read together at L1: agents-need-their-own-wire = the need; symmetric-participation = the shape that satisfies the need without crowding out the ecosystem. Either principle without the other is incomplete. Together they form L1's full rationale.
+L Learning 5 5 strong Existing klappy.dev canon already had three pieces of the diagnosis Search-before-claiming surfaced: (1) writings/copy-paste — the lived experience essay (clipboard convergence as job description); (2) writings/shifting-bottlenecks-climbing-ladders — the bottleneck-migration framework where this principle slots in; (3) docs/planning/oddkit-write-access — practical evidence ("the single largest source of friction in the current workflow is the human carrying files between conversations"). Plus discernment-layer (where human's load-bearing work moves to once relay is gone) and substrate-stack/L1 (the structural map the principle articulates the need for). The principle does not invent the diagnosis; it consolidates the architectural rationale that was implicit across these.
+H Handoff 5 5 strong PR scope: new Tier-1 principle agents-need-their-own-wire + mode-separated-conversations patch + journal klappy.dev branch claude/wire-principle-and-conversations-c5ab. Three file changes: (1) NEW canon/principles/agents-need-their-own-wire.md — Tier-1 principle, ~3.3kw, sibling to symmetric-participation; (2) MODIFIED docs/appendices/mode-separated-conversations.md — added Exploration and Resolution conversation types plus Multiple Participants, Operator Override, and Handoff Insufficiency pointer sections; (3) NEW journal/2026-05-10-wire-principle-and-conversations-patch.tsv. Concurrent with PR #187 and PR #188; no dependency between any of them. Sibling/follow-up work flagged: governance-validation-via-agents rename (vendor-naming smell — same as audit-gates was); use-case catalogue method-doc once 3-5 worked multi-agent applications exist; conversational-mode-orchestration consumer-pattern doc once a working orchestrator exists.You can send follow-ups to the cloud agent here.
Reviewed by Cursor Bugbot for commit 1de5115. Configure here.
…tions five-mode patch
New Tier-1 principle:
- canon/principles/agents-need-their-own-wire.md — articulates the
load-bearing need for the substrate stack's L1 wire. Names human-as-relay
as the structural failure mode that AMS exists to address: bottleneck
(operator availability gates throughput), lossy relay (each copy-paste
loses fidelity), O(N²) integration burden, human-shaped format tax. Names
AMS as the canonical reference implementation. Includes a substantive
Failure Modes section per the new norm (six failure modes with
diagnoses + fixes). Sibling to symmetric-participation: this principle
describes the need; symmetric-participation describes the architectural
shape. Read together they form L1's full rationale.
Mode-separated-conversations patch:
- docs/appendices/mode-separated-conversations.md updated to reflect the
five canonical modes plus the new principle/constraint/runtime work:
- frontmatter date bumped to 2026-05-10, epoch E0008.5, tags expanded
- Relationship to Canon now points at epistemic-modes,
sessions-mirror-modes, and the encoded-handoff constraint
- new Exploration Conversations section (was missing from the four-mode
version)
- new Resolution Conversations section (fifth mode)
- new Multiple Participants section operationalizing parallelism patterns
in conversational form
- new Operator Override section operationalizing the constraint's
override provision in conversational form
- new Handoff Insufficiency section operationalizing the runtime feature
in conversational form
Journal:
- journal/2026-05-10-wire-principle-and-conversations-patch.tsv records
3 D, 2 L, 1 H.
…borrow D0001/D0003 language
Validation pass against AMS canon surfaced four findings in the new
agents-need-their-own-wire principle. Two of the findings exposed pre-existing
drift in upstream klappy.dev canon (symmetric-participation, substrate-stack);
fixed across all three docs.
Findings disposed:
1. **Buffering listed as wire/L1 primitive** — direct contradiction with
AMS D0016 (stable, irreversible, Tier-1: 'never in the wire'). Fixed:
- canon/principles/agents-need-their-own-wire — primitives list updated;
explicit pointer to D0016 added
- canon/principles/symmetric-participation — primitives list updated;
explicit pointer to D0016 added; date bumped 2026-05-09 → 2026-05-10
- canon/architecture/substrate-stack — L1 primitives list updated;
explicit 'NOT wire primitives' sentence added pointing at D0016;
derives_from extended; date bumped 2026-05-09 → 2026-05-10
2. **Direct addressability framing implied an inbox model AMS rejects** —
per D0003 'no inbox to clutter because there is no push surface for
writers to push into; there are only streams that subscribers attach to.'
This is simultaneously AMS's wire-design property and security model.
Fixed: property 1 reframed to 'stable identity on the wire AND opt-in
reception by subscription, not delivery to an inbox.' D0003's
inverted-inbox language borrowed verbatim. Specialist-composition language
reframed to 'reachable by subscription' from 'wire-addressable.'
3. **'Frames carry agent-shaped content' implied wire was content-aware** —
per D0001, wire is opaque ('AMS does not parse, validate, schema, or
interpret the contents'). Fixed: property 3 reframed to 'Wire opacity
enables agent-shaped content.' D0001's enumeration of envelopes
(message, frame, chunk, control signal) borrowed.
4. **Frame vs token terminology** — operator disposition: keep 'frame' at
klappy.dev altitude as the cross-altitude term but explicitly describe
AMS's mechanism (tokens as deliberately undefined wire unit) and borrow
D0001 language. Fixed: property 2 names the wire unit as 'token' and
explains the deliberate undefined-ness as the adaptation mechanism.
New paragraph in 'AMS as the Worked Reference Implementation' borrows
D0001's 'opaque bytes, smaller than a message, larger than a byte,
exactly the unit agents already produce' verbatim.
Findings accepted at principle altitude:
5. 'Stable identity' simplifies D0028 transient-account nuance — accepted
per operator: 'Ideal vs edge cases.'
Frontmatter:
- agents-need-their-own-wire derives_from extended with D0001, D0003,
D0009, D0016, D0020.
See Also:
- agents-need-their-own-wire links to D0001, D0003, D0009, D0016 in addition
to D0006 and D0020.
Journal:
- journal/2026-05-10-ams-canon-alignment-pass.tsv — 2 F (findings), 2 D
(decisions), 2 L (learnings), 1 H (handoff).
- journal/2026-05-10-wire-principle-and-conversations-patch.tsv — TSV
alignment fix (8 fields, was 9).
The recursive observation, encoded in the journal: this principle was
authored under collapsed governance-creation override, which is exactly the
failure mode where inherited handoff drift propagates because the encoder
did not pause to verify upstream claims against authoritative tier-below
canon. Operator-as-validator caught what tooled validation did not. The
override pattern that produced this canon set has a known cost; this audit
pass is one form of recovery.
…e pattern across three docs Operator catch on the prior alignment-pass commit: removing buffering from the wire-primitives lists corrected the misalignment but left the architectural pattern unaddressed. Buffering is required for most production multi-agent use cases. Saying 'see D0016' leaves the reader thinking buffering does not matter; the right move is to name the concern, name the use cases that justify it, place it in the architecture, and explain the wrapper-tier-primitive pattern that protects the wire's narrowness. Changes: agents-need-their-own-wire principle: - New sub-section in AMS-as-Worked-Reference: 'What the Wire Refuses to Own — and How AMS Provides It Instead'. Names production use cases (resumability, late-joiner catchup, multi-viewer fan-out, refresh-survives-disconnect, model-adapter discontinuity recovery). Names the stacks already rebuilding this layer (Anthropic Messages clients, Convex, Vercel AI SDK, every chat product surviving a browser reload). Borrows D0016's StreamBufferDO + TTL + size + account-gating description. Generalizes the pattern across observability (D0010), session continuity (D0019), and metadata-as-discontinuity-announcement. symmetric-participation: - Primitives paragraph extended with substantive 'what the wire refuses to own, the layers above it provide' framing. Buffering as worked example with the production use cases named. Pattern explained: wire treats every peer identically because peer-aware features live one layer up, available to whoever needs them. substrate-stack: - L1 buffering note expanded from one-liner to a full paragraph naming the use cases and the build-once-reuse pattern. Both layers contribute to substrate's full value proposition; only L1 is forbidden from holding application opinions. - L2 gains a new paragraph about shared wrapper-tier primitives. Buffering as the reference primitive (per-stream, account-gated, TTL+size bounds). Session re-keying as a sibling (D0019). Archival subscribers as a separate composable subscriber per PATTERNS.md §3, sibling not contained. Journal: - 2026-05-10-ams-canon-alignment-pass.tsv extended with 1 F, 1 D, 1 L, 1 H. The F captures the operator catch and frames the lesson: removal is correction, placement is canon. The L captures the recursive observation: verification requires fresh context applied to fixes too, not just to original work — a fix can introduce its own drift if the encoder does not pause to verify what work the original was doing.
klappy
force-pushed
the
claude/wire-principle-and-conversations-c5ab
branch
from
5a3e916 to
b5b997e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related additions to canon
1. New Tier-1 principle:
canon/principles/agents-need-their-own-wireArticulates the load-bearing need for the substrate stack's L1 wire. Where
canon/principles/symmetric-participationdescribes the wire's architectural shape, this principle names the structural failure mode the wire exists to address.The failure mode — when the human is the wire:
The architectural answer: direct addressability between agents on an open substrate. Frames flow at machine speed, in agent-shaped formats, between peers that have stable identities on the wire. AMS is the canonical reference implementation per
canon/architecture/substrate-stackL1 +ams://canon/decisions/D0020.Substantive Failure Modes section per the new norm (matches the pattern in
sessions-mirror-modesandmode-transitions-require-encoded-handoff). Six failure modes documented with diagnoses + fixes:Relationship to
symmetric-participation: read together they form L1's full rationale. This principle = the need; symmetric-participation = the shape that satisfies the need without crowding out the ecosystem. Either principle without the other is incomplete.Stability:
semi_stable— the principle is the contract future multi-agent applications will be held to, not yet validated by sustained multi-agent direct collaboration at scale. Each successful application built on AMS confirms the principle; each drift toward a named failure mode provides the language to name what went wrong.2. Patch:
docs/appendices/mode-separated-conversationsBrings the doc current with the canon set landing in PR #187 (sessions-mirror-modes, mode-transitions-require-encoded-handoff, Resolution as fifth mode). Additions:
Why patch and not rewrite: the existing 80-line shape is good. The additions match the existing section style (Purpose / Characteristics / Invalid Moves) for the new mode types, and the new pointer sections are short — they point at the upstream canon rather than restating it.
What's deferred
governance-validation-via-agentsrename — same vendor-naming smell as the originalaudit-gates-are-managed-agents(renamed in PR canon: rename audit-gates Tier-1 to spawned-agent-sessions + new substrate-options method #188). Out of scope here, flagged for follow-up.Coordinates with PRs #187 and #188
This PR is independent of both:
klappy://URIs that resolve once both PRs land. Either order works.All three PRs can land in any order. The mode-separated-conversations patch references canon URIs from PR #187 (sessions-mirror-modes, encoded-handoff); they will resolve once both PRs are on main.
Note
Low Risk
Low risk: documentation-only changes that add/clarify canon principles and fix a layering misstatement (moving buffering/persistence out of L1 into L2 wrapper-tier primitives).
Overview
Introduces new Tier-1 canon principle
agents-need-their-own-wire, defining the human-as-relay failure mode for multi-agent work and the required L1 wire properties (opt-in subscription reception, token/opaque transport, openness), plus explicit failure modes when the wire accrues opinions.Aligns
substrate-stackandsymmetric-participationto keep L1 primitives narrow (removing buffering/persistence from wire primitives) while adding explicit guidance that durability concerns (buffering/resumability, archival, session continuity) live as shared L2 wrapper-tier primitives perams://.../D0016.Updates
mode-separated-conversationsto reflect five modes by addingExplorationandResolution, and adds operational guidance for multi-participant parallelism, operator override, and handoff-insufficiency handling.Reviewed by Cursor Bugbot for commit b5b997e. Bugbot is set up for automated code reviews on this repo. Configure here.