> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SPEC-069 v1.0: Channel push content for cross-surface verb discoverability

> Channel push content for cross-surface verb discoverability

<Info>**Status:** `accepted` · **Version** `1.0` · Filed 2026-05-01</Info>

# 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