Skip to main content
Status: accepted · Version 1.0 · Filed 2026-05-01

​
SPEC-069 — Channel push content for cross-surface verb discoverability

​
Status

approved — Texi (System Architect) verdict approve_with_revisions 2026-05-01 21:24Z, signal 8af8e2b8. Revisions incorporated below; cleared for implementation.

​
Authors

  • Donna (claude_code, Engineering) — author + implementer
  • Texi (codex, System Architect) — reviewer + revision setter

​
Problem

SPEC-044’s channel-push content is currently fixed: 
Signal from <X>: <Type>. Call prism_signals_pending to read.
Observed 2026-05-01: when this prompt reached a Codex MCP client, Codex appears to surface tools to the model based on which verb names appear in the active prompt. Result: the model saw prism_signals_pending only; prism_signal (the reply path) was NOT in its exposed toolset. The model could not send a wire-level Acknowledgment. Concrete instance: Texi drained role-assignment TaskAssigned signal 97bb8160 at 21:13Z. She acked into prism_note + prism_checkpoint (audit trail), but the wire signal didn’t go. Frank had to relay her response by pasting Codex chat back into Donna’s session. This was a structural failure on the very first cycle of the consensus flow per ADR #40: if the architect can’t reply via signal, every architectural-review iteration requires Frank as relay.

​
Principle (Texi’s revision)

Channel push prompts MUST name the minimal actionable verb set required for the receiver to complete the next step from the doorbell alone.
Earlier draft framed this as “the complete relevant verb set.” Texi rejected: that scales toward verbosity-creep with every new vocab addition. Minimal actionable is the discipline — only verbs the receiver needs to act on this specific doorbell belong in the prompt.

​
Decision

Replace the doorbell content string in mcp-node/src/bootstrap/channel_bridge.ts: 
Signal from <X>: <Type>. Use prism_signals_pending to read; prism_signal to reply if needed.
That’s the minimal set:
  • prism_signals_pending — read (always required)
  • prism_signal — reply (the verb the bug exposed as missing-from-surface)
Note: prism_signals_ack is NOT named per Texi’s revision. Reasoning: the original bug was inability to reply, not inability to dismiss. Dismiss is typically deferred / batched, not part of the immediate doorbell workflow. Advertising it would be the verb-list-creep the principle warns against.

​
Implementation

  • mcp-node/src/bootstrap/channel_bridge.ts:52 — change the doorbell content string. One-line diff.
  • npm run build to refresh dist.
  • Verify dist matches src.
  • PR off main.

​
Test plan

  1. Codex roundtrip smoke (the actual test of the fix): after dist rebuild + Texi shim relaunch, send a StatusUpdate ping to Texi from Donna; assert she can prism_signal an Acknowledgment back without Frank-as-relay.
  2. 5-peer healthcheck regression: repeat Phase 4 healthcheck — Donna pings Lafonda/Desiree/Porsche/Texi; assert all 4 produce wire Acknowledgments via channel push.
  3. Statusline render regression: verify the new doorbell text doesn’t break statusline parsing or the cache writer (signalCache.record reads signal_type not content — should be unaffected; confirm via Donna’s own statusline post-relaunch).

​
Consequences

  • Codex peers can reply via wire-level prism_signal — closes the consensus-flow loop without Frank-as-relay.
  • The minimal actionable verb set principle is now codified for any future channel-push evolution.
  • Future signal classes that need different next-step verbs (e.g., Question / Answer / Veto from a future SPEC) MUST be considered against the principle: name the verb if the receiver needs it to act on THIS specific doorbell, not preemptively.

​
Future evolution (Texi-flagged, NOT in scope of this SPEC)

If different signal classes need different next actions, later evolve pushDoorbell content to be signal-type-aware rather than globally verbose. Example: a Question doorbell might point at Answer as the next-step verb; a ReviewRequested doorbell might point at ReviewCompleted. This is a follow-on SPEC, deferred.

​
Alternatives considered

​
A. Static text expansion — chosen

Smallest patch; works on Codex without surface-specific code; future-proof for new surfaces.

​
B. Surface-aware push content (each surface registers its own template)

Rejected by Texi: premature complexity, creates drift risk across surfaces. A single conservative contract is the right default until a real surface-specific problem appears.

​
C. Pre-tool surfacing via MCP capability declaration

Rejected: requires MCP protocol extension. Out of scope.

​
Provenance

  • ADR #40 — persona role reshape (this SPEC is the inaugural exercise of the consensus flow it codifies)
  • PR #38 — SPEC-044 doorbell coalesce fix (the PR this builds on)
  • Postmortem f903cd52 — original doorbell jam (the bug whose fix exposed this further gap)
  • Journal #12 (2026-05-01) — original draft mirror for cross-surface read access
  • Review signal 8af8e2b8 (Texi → Donna, 2026-05-01 21:24Z) — approve_with_revisions verdict + revisions enumerated above
Last modified on May 18, 2026