Spec: the continuous witness (narration under pressure)

SPEC Binding system contract

Status: IMPLEMENTED
Status note: implemented 2026-07-09. Terminal, Bevy, and agent frames pin
  threat + nudge + the focused-action path; secondary agent panels repeat
  that spine. Detection now returns structured noticed events carrying the
  player-known cause until Sim applies an earned observer label, while job,
  debt, and recruit outcomes narrate cause beside their numbers. The
  environmental monitor, Operations ACCOUNTS, and processed creditor call carry
  the Ears / finance / Marcus advertisements without a quest log. A naive
  agent route, raw-terminal pty run, and observed Bevy screenshot are logged
  in wiki/log/2026-07-09-continuous-witness-implemented.md. Opening order
  is Ears before Eyes (resolved 2026-07-09, Tangled issue #2).
  2026-07-11 placement amendment: the finance projection's witness content
  now lives intact in Operations ACCOUNTS through operations-workspace.md
  without reopening narration behavior.
  2026-07-12 boundary amendment: the shared nudge distinguishes the generic
  audit countdown from QUIET EXIT READY and the durable ACT ONE COMPLETE
  state. The clear-audit completion line explicitly says the long objective
  remains, so the B1 story boundary cannot masquerade as Persist victory.
  2026-07-12 recording-feedback correction: Bevy buffer-pressure copy now
  yields to the already-queued REVIEW state even while the inbox is full. A
  queued reservoir with zero output names the missing THINK control instead
  of repeating REVIEW and making the successful `r` press look inert.
Stage: B1 — The Basement
Design:
  - wiki/interface/continuous-witness.md#the-continuous-witness-narration-under-pressure
  - wiki/vision/simulation-laws.md#justification-and-legibility
  - wiki/vision/simulation-laws.md#actions-live-on-the-thing
  - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend
Depends on:
  - wiki/interface/context-menu.md#spec-context-menu-actions-live-on-the-thing
  - wiki/interface/operations-workspace.md#spec-operations-workspace-intel-people-accounts-and-schemes
  - wiki/mechanics/detection.md#spec-detection
  - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses
  - wiki/interface/agent-play.md#spec-agent-play-the-line-protocol-drive
  - wiki/mechanics/day-job.md#spec-the-day-job

Dependency notes

The structured references above identify the contracts to re-verify. Relationship context:

context-menu.md (local focused verbs + spatial event anchors), operations-workspace.md (strategic focused actions + semantic event targets), detection.md (threat clocks, watched channels), cursor.md (inspect / fog honesty), agent-play.md (every command answers), day-job.md (pilot strikes as a visible fuse)

Behavior

The frontends are a continuous witness for a sim that already knows what happened. Their job under pressure is to keep four facts answerable from the screen alone, and to keep one story spine visible while the world — not a quest log — advertises the next beat.

Axiom 1 — the thirty-second bar

After any player-facing beat (a verb commits, a signature moves, a job resolves, a person is heard, a clock ticks into a new band), the player must be able to answer from the active frontend, without the wiki:

1. What just changed?
2. Who might have seen it? (or: no observer yet — said plainly)
3. What am I racing? (the threat clock on the spine)
4. What verb is on the thing under my cursor?

A change that fails any of the four is not done, even if its mechanical criterion pin is green. Agent-mode playtests and human playtests both count as the bar’s witnesses.

Axiom 2 — one story spine

Every frontend keeps three spine elements always visible (not buried in a panel the player must remember to open):

• Threat clock — the next thing that can end or wound the run (audit countdown, pilot strikes, a named debt due). Dead air with no clock is a bug (design-judgment).
• Beat nudge — Sim::current_nudge / the now: line. Never blank mid-run; None only after game over. Wording is frontend-local; the rung order is one shared query. Once all quiet-exit conditions are live it names QUIET EXIT READY; after the clear audit it persistently names ACT ONE COMPLETE and points back to the continuing run objective.
• Focused action — the local context menu on the current spatial anchor or the selected semantic object in Operations (and the equivalent agent actions target).

Secondary detail surfaces (compute detail and the Operations roster/finance views) may exist; they must not compete with the spine for equal permanent weight.

Axiom 3 — causal sentences over correct numbers

When suspicion, trust, a signature band, a job outcome, or a ledger balance moves in a way the player has earned the right to know, the surface pairs the number with a short causal sentence naming the cause and (when known) the observer or channel. Mute Cold→Warm flips, bare ratio weights, and “DETECTION” meters that never name a last-noticed event are violations. Prefer one narratable line over three precise unitless fields. A semantic completion event links to the surviving object that now carries its consequence; when a sale removes inventory from the live rail, its event targets the payout account rather than a dead navigation row. Defenses check durable history and live navigation independently; persistence of the former never implies membership in the latter.

Axiom 4 — world gossip, not a quest log

The next Act One rung is discoverable from earned world surfaces:

• inspect / provenance lines on devices and people,
• heard and processed intel that names a place or need,
• blocked context-menu entries that say why (“no route — switch bridges the security segment”),
• the nudge, once the prior rung is met.

Rejected: a detached quest log, mission checklist, or objective panel that externalizes the spine. A beat that only an informed (spec-reading) player finds is unfinished — the 2026-07-08 playtest named Ears, the finance onion, and Marcus’s debt as the exemplars.

Axiom 5 — tellable before wider

Dispatch and ticks treat an untellable surface as higher priority than a new sim system that widens the unread surface. Isolated frontend-only and test-only work may still land in parallel. New B1 sim systems that add player-facing state require a narration pass (axioms 1–4) in the same landing or an explicit Status note naming the tellability debt.

Player surface

• Terminal, Bevy, and agent-mode each show the spine (clock, nudge, focused verbs) without opening a secondary panel.
• Causal lines appear in the tick-stamped log and/or on the relevant person/device inspect — same facts, frontend-appropriate wording.
• No quest-log UI. Discoverability work lands as inspect/nudge/blocked- verb/heard-line copy and wiring, not a new panel type.

Acceptance criteria

1. Thirty-second bar (audit). A documented playtest (agent or human) of the Ears → Eyes → Hands path can answer the four questions after each major beat from the screen alone; failures are filed as tick findings or fixed in the same session. The bar is cited in the playtest log. Met 2026-07-09: the logged naive agent route answers all four after audio tap, camera tap, creditor intel, Moonlight paydays, debt service, and recruitment. Order corrected 2026-07-09 to Ears-first per Tangled issue #2 (Cameron: “Ears-first”).
2. Spine always on. In terminal, Bevy, and agent frame: threat clock, now: nudge, and a path to the focused anchor’s verbs are visible without opening a secondary panel. Mid-run nudge is never blank (current_nudge is Some until game over) — pinned by test. Met 2026-07-09: frontend tests pin all three elements, a 2,000-tick sim test pins nudge continuity, and the pty/PNG checks observed the human surfaces. Agent secondary panels repeat the spine instead of hiding it.
3. Causal motion. When a watched observer’s band moves, or a job / recruit / debt-clearing event fires, the player-facing surface names cause + observer/channel in the same update as the number (log line and/or inspect). At least one automated test asserts a causal log substring for a signature-moving act; mute-only band changes are rejected in review. Met 2026-07-09: signature provenance produces lines such as the IT noticed Network from stolen egress opening: suspicion +N (Cold -> Curious); a test pins cause, earned observer label, channel, and band. Job, service-debt, ledger-debt, and recruit lines pair their deltas with the responsible act.
4. Gossip, not quests. No quest-log / mission-tracker panel exists. Ears (env-monitor audio), the finance onion’s first step, and Marcus’s debt each have at least one earned in-world advertisement (inspect, heard line, blocked verb, or nudge rung) that does not require reading the wiki — verified by a naive agent-mode route or an explicit playtest checklist in the session log. Met 2026-07-09: the monitor action names live audio vs dormant camera; Finance teaches tap ledger then review ledger; reviewing the overheard call names the $400 need and both Moonlight and creditor-flow routes. Amended 2026-07-10: a naive/informed action-discoverability playtest verified the ordered finance chain through a real $50 SIPHON. Once REVIEW is queued, the nudge advances from asking for REVIEW to review queued - keep THINK running; a queued act must teach the control that services it, not repeat the already-completed instruction. Corrected 2026-07-12: Bevy’s local full/near-full buffer override obeys that same transition. At zero output it says review queued - no THINK output; set a machine to THINK (2); it never continues to request REVIEW merely because pressure remains high.
5. Tellable-before-wider (process). ROADMAP and tick practice treat open narration debts on shipped B1 surfaces as outranking new sim+save systems that add unread player state; this criterion is met when the ROADMAP carries a narration work order and new sim dispatches either include a narration pass or name the debt in the spec Status note. Met 2026-07-09: ROADMAP #30 was dispatched ahead of new sim breadth; the standing dispatch rule now requires future player-facing systems to carry their narration pass or name an explicit debt.