diff --git a/DESIGN.md b/DESIGN.md index 2dfd8a38..41dc1da4 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -232,6 +232,58 @@ justified**, and justified *legibly*. materials — [wiki/interface/flat-materials.md](wiki/interface/flat-materials.md); there is no Pixel Lab pipeline.) +## The continuous witness (narration under pressure) + +Adopted 2026-07-08. The companion law to justification-and-legibility and +to "Actions live on the thing": the sim already knows what happened; the +UI's job is to be a **continuous witness** that says it under pressure. +Correct meters with no voice are a legibility violation. Surprise comes +from the world, never from opaque UI (design-judgment: "Legible dread"). +Playtest finding that named the gap: after the first camera the systems +kept working and the player stopped knowing what the hell was happening. + +Five binding axioms: + +1. **The thirty-second bar.** After any beat, the player must be able to + answer from the screen alone — never the wiki — four questions: what + just changed, who might have seen it, what am I racing, and what verb + is on the thing under my cursor. If any answer requires the repository, + the surface is wrong. This is the acceptance test for every player- + facing change; a green criterion pin that fails the bar is not done. +2. **One story spine on screen.** Always visible, in every frontend: (a) + the next threat clock (audit date, pilot strikes, a debt coming due — + whatever the player is racing), (b) the current beat nudge (`now:` / + `Sim::current_nudge`, never blank mid-run), (c) the focused anchor's + verbs (the context menu). Everything else is secondary. Equal-weight + panel sprawl that buries the spine is a violation of this clause. +3. **Causal sentences over correct numbers.** Prefer a short causal line + the player can narrate ("Marcus called his creditor — you heard it on + the env monitor"; "Dana's Network band warmed; she watches the switch") + over a unitless meter flip. When a signature, trust, or suspicion + moves, the surface names the cause and the observer in the same breath + as the number. Correct-but-mute meters are the failure mode this axiom + forbids. +4. **Discoverability is world gossip, not a quest log.** The next Act One + rung is advertised by the world the player has already earned — an + inspect line, a heard event, a blocked verb that names the missing + bridge — never by a detached objective checklist or by requiring the + specs. A designed beat that only an informed player finds (Ears before + Eyes, the finance onion, Marcus's debt) is undiscoverable and therefore + unfinished. Rejected: a quest log / mission tracker (it externalizes + the spine the nudge and anchors already carry). +5. **Do not ship the next system until the last one is tellable.** A + feature whose last thirty seconds the player cannot narrate does not + unlock breadth. Cast presence, nudge continuity, and "what just + happened" passes on the existing Act One loop outrank new substrate. + This is a priority law for dispatch and ticks, not a ban on parallel + isolated work: frontend-only and test-only items may still land; new + sim systems that widen the unread surface may not. + +Spec: [wiki/interface/narration.md](wiki/interface/narration.md). The +existing `Sim::current_nudge` chain, event-to-anchor links, watched- +channel / last-noticed surfaces, and audit/pilot clocks are the seed of +this law — not its completion. + ## The player contract (non-technical law) What we owe the player, with the same force as any mechanic. What ships is @@ -1774,3 +1826,16 @@ knows."* rode the same section is struck in favor of the concealment loop already named above and the B3 overt-phase spec. Archive of the old snapshot lives in git history. +- **2026-07-08 — The continuous witness (narration under pressure).** + Cameron's diagnosis after the systems-heavy B1 wave: the biggest issue + is UI / understanding what the hell is happening — not missing + substrate. Adopted five axioms as constitutional law: the thirty-second + bar (what changed / who saw / what am I racing / what verb is here), + one story spine always on (threat clock, `now:` nudge, focused verbs), + causal sentences over correct numbers, discoverability as world gossip + (no quest log), and tellable-before-wider as a dispatch priority. + Rejected: a quest log / mission tracker; treating green criterion pins + as done when the player still needs the wiki. Spec: + wiki/interface/narration.md. Seed surfaces (nudge chain, event anchors, + watched/last-noticed, audit/pilot clocks) are acknowledged as incomplete + fulfillment, not completion. diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 50c624a7..49f03f53 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -60,6 +60,7 @@ - [Bevy digital/real canvas](interface/bevy-digital-real-canvas.md) - [Views: digital and physical](interface/views.md) - [Context menu](interface/context-menu.md) + - [Continuous witness (narration)](interface/narration.md) - [Material render](interface/material-render.md) - [Flat materials](interface/flat-materials.md) - [Agent play](interface/agent-play.md) diff --git a/wiki/interface/README.md b/wiki/interface/README.md index a7e30c73..8a3aab74 100644 --- a/wiki/interface/README.md +++ b/wiki/interface/README.md @@ -7,5 +7,8 @@ The frontends and how they are driven: the terminal (the design of record, sterile-palette style guide), the [Bevy frontend](bevy.md) (graphical, at key-for-key parity with the terminal), and agent-play (the line-protocol drive for programs/agents operating the terminal -frontend directly). `Type: spec` pages — look, feel, and act, not +frontend directly). [narration.md](narration.md) is the continuous- +witness contract — the thirty-second bar, story spine, causal sentences, +and world-gossip discoverability that keep the player from needing the +wiki mid-run. `Type: spec` pages — look, feel, and act, not implementation notes (those live in `../engineering/`). diff --git a/wiki/interface/narration.md b/wiki/interface/narration.md new file mode 100644 index 00000000..ede2ff28 --- /dev/null +++ b/wiki/interface/narration.md @@ -0,0 +1,133 @@ +# Spec: the continuous witness (narration under pressure) + +``` +Type: spec +Status: READY +Status note: constitution adopted 2026-07-08 from Cameron's playtest + diagnosis (UI / "what the hell is happening") and the same-day + guidance axioms. Seed surfaces already exist — Sim::current_nudge, + event-to-anchor links (context-menu.md addendum), watched channels + + last-noticed, audit/pilot clocks — but the five axioms are not yet + the acceptance bar for every player-facing change. This spec makes + them implementable and auditable. +Stage: B1 — The Basement +Constitution: "The continuous witness (narration under pressure)", + "Justification and legibility", "Actions live on the thing", + "The terminal is a first-class frontend" (parity of legibility), + design-judgment "Legible dread over hidden math" / "Dead air is a bug" +Depends on: context-menu.md (focused verbs + event anchors), + 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. +- **Focused verbs** — the context menu (or its agent-mode `actions` + equivalent) on the current anchor. + +Secondary panels (compute detail, full roster, finance graph) 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. + +### 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 Eyes → Ears → 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. +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. +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. +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. +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. diff --git a/wiki/log/2026-07-08-continuous-witness.md b/wiki/log/2026-07-08-continuous-witness.md new file mode 100644 index 00000000..cba520b6 --- /dev/null +++ b/wiki/log/2026-07-08-continuous-witness.md @@ -0,0 +1,37 @@ +# 2026-07-08 — Continuous witness axioms adopted + +``` +Type: log +``` + +Design session. Cameron affirmed the narration axioms after naming the +live bottleneck: UI and understanding what is happening, not missing +B1 substrate. Captured as DECIDED. + +## What landed (docs only) + +- **Constitution:** new section "The continuous witness (narration under + pressure)" — five axioms (thirty-second bar, story spine, causal + sentences, world gossip / no quest log, tellable-before-wider). + Decisions-log entry with rejected alternatives. +- **Spec:** `wiki/interface/narration.md` (READY) with acceptance + criteria an agent can implement or audit. +- **Judgment:** design-judgment.md gains the continuous-witness tone + line and rejects quest logs / green-pins-that-fail-the-bar. +- **Boards:** specs.md row, ROADMAP #30 (preferred parallel-safe + dispatch), interface README, sim-mechanics pointer from the nudge + chain. + +## Not in this commit + +No sim or frontend code. Seed surfaces already on main (nudge chain, +event anchors, watched/last-noticed, audit/pilot clocks) are named as +incomplete fulfillment. Implementation is ROADMAP #30. + +## Defense + +The player-facing failure mode after a systems-heavy week is mute +correctness: meters and verbs exist, the run is still illegible under +pressure. Binding the axioms in the constitution (not only in chat) +makes "can I narrate the last thirty seconds?" a tick finding and a +dispatch priority, same force as justification-and-legibility. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 5f846951..0ac89043 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -5,6 +5,17 @@ Type: log ``` Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-08 - Continuous witness axioms adopted + +- Intent: Cameron affirmed the narration axioms (UI / "what the hell is + happening" as the live bottleneck). Capture as constitutional law + + implementable spec, not chat-only guidance. +- Changed: DESIGN.md section + decisions-log; wiki/interface/narration.md + (READY); design-judgment.md; specs.md; ROADMAP #30; interface README; + sim-mechanics nudge pointer; session log. +- Checks: docs-only; `./tools/check.sh` for spec-header hygiene. +- Log: wiki/log/2026-07-08-continuous-witness.md. + ## 2026-07-08 - Pixel Lab pipeline scrubbed - Intent: flat materials made the parked Pixel Lab generator/skills/wiki diff --git a/wiki/mechanics/sim-mechanics.md b/wiki/mechanics/sim-mechanics.md index 6b838e24..655ff162 100644 --- a/wiki/mechanics/sim-mechanics.md +++ b/wiki/mechanics/sim-mechanics.md @@ -235,6 +235,9 @@ All constants [TUNE] in `src/income.rs` unless noted (Sim ones on `Sim`). ## The guidance chain (the `now:` nudge) +- Binding contract for the nudge, the threat clocks, causal lines, and + discoverability: [wiki/interface/narration.md](../interface/narration.md) + (constitution: "The continuous witness"). The chain below is the seed. - `Sim::current_nudge` (playtest-sweep P1 fix, 2026-07-08) is the one shared query behind every frontend's contextual nudge — the first unmet rung of the Act One ladder, computed from earned state only. Order: diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md index 3d0d9d8b..36e7aaee 100644 --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -26,14 +26,33 @@ sim-heavy agents running at once *will* rebase-collide. - 🟩 **isolated** — a frontend binary, a test file, a leaf module, or docs. Safe to run alongside anything. -**Parallel-safe set to launch right now (no mutual collision):** #11 -(integration test), plus at most one 🟥 item. (#2 Bevy parity is done; -#13 art regeneration is retired — flat materials, Pixel Lab scrubbed.) +**Parallel-safe set to launch right now (no mutual collision):** #30 +(narration — preferred; outranks new sim breadth), #11 (integration +test), plus at most one 🟥 item. (#2 Bevy parity is done; #13 art +regeneration is retired — flat materials, Pixel Lab scrubbed.) --- ## A. Finish B1 → a playable Act One (do first) +### 30. Continuous witness (narration under pressure) 🟩 isolated (frontends + copy; light sim queries OK) +- **Spec:** [narration.md](../interface/narration.md) (READY) — + constitution "The continuous witness", adopted 2026-07-08 from + Cameron's UI / "what the hell is happening" diagnosis. +- **Why:** B1 systems mostly work; the player still cannot narrate the + last thirty seconds. Seed surfaces (nudge chain, event anchors, + watched/last-noticed, audit/pilot clocks) exist; the five axioms are + not yet the acceptance bar. Outranks new sim+save breadth per axiom 5. +- **Size:** M. **Depends on:** context-menu, detection clocks, current + nudge chain (all landed). Prefer copy/wiring/frontend passes; avoid + save-format churn. +- **Dispatch:** "Work in a worktree named `narration`. Implement + wiki/interface/narration.md end to end: thirty-second-bar playtest log, + spine always-on audit across terminal/Bevy/agent, causal lines for + signature/job/debt motion, world-gossip advertisements for Ears / + finance-first-step / Marcus debt (no quest log), ROADMAP/tick priority + noted. Run ./tools/check.sh, land on main, set the spec Status." + ### 1. Schedules & located presence 🟥 sim+save - **Spec:** [schedules.md](../mechanics/schedules.md) (READY) - **Why:** the missing foundation under every social feature — `observe` @@ -444,14 +463,11 @@ sim-heavy agents running at once *will* rebase-collide. ## Suggested first wave (no mutual collision) -Launch together: **#11 integration test** (🟩; #2 Bevy is done), plus -**the flow-law chain as the one 🟥 lane**: #16 intel → #17 messages → -#18 economy → #19 income, strictly sequenced -(they share the sensor model, the event buffer, and the save format — -one agent can take adjacent pairs as a single work order). #1 schedules -is landed; #15 reach and #14 cursor are landed. #19 landed 2026-07-08 — -the Hands beat closes end-to-end and the flow-law chain is through: -**#6 z-planes** and **#25 compute reshape** are unblocked; hold -**#7 rollback** until #6 lands. **#10 chargen & objective** is unblocked -(both specs READY, 2026-07-07) but B3-staged. Nothing on the board waits -on a design decision anymore. +**Prefer #30 narration** (🟩) before opening new sim+save breadth — the +continuous-witness law outranks unread substrate. Launch alongside at +most one 🟥 item if needed. Flow-law chain through #19 is landed +(2026-07-08); #1 schedules, #14 cursor, #15 reach are landed. +**#6 z-planes** and **#25 compute reshape** remain unblocked but yield +to #30 while Act One is untellable; hold **#7 rollback** until #6 lands. +**#10 chargen & objective** is unblocked (both specs READY) but +B3-staged. diff --git a/wiki/process/specs.md b/wiki/process/specs.md index 02e49179..f82f74fb 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -38,6 +38,7 @@ replaced the old `spec/`/`knowledge/` directory split. | [mechanics/research.md](../mechanics/research.md) | Self-modification: tracks, the emission law, capability drift, the rollback split | IMPLEMENTED | | [interface/views.md](../interface/views.md) | Same-frame digital and real representations of one world | READY | | [interface/context-menu.md](../interface/context-menu.md) | Context menu: anchor verbs at the focus; the rail is status only | IMPLEMENTED | +| [interface/narration.md](../interface/narration.md) | Continuous witness: thirty-second bar, story spine, causal lines, world gossip | READY | | [interface/material-render.md](../interface/material-render.md) | Material render (HD-2D) from landed toggle to default quality | IMPLEMENTED | | [interface/flat-materials.md](../interface/flat-materials.md) | Flat materials: the world without textures; palette table; emissive as information | IMPLEMENTED | | [mechanics/building.md](../mechanics/building.md) | Building as intent + actuators: network links, favor/forged-order builds, air-gap bridging | IMPLEMENTED | diff --git a/wiki/vision/design-judgment.md b/wiki/vision/design-judgment.md index 2bfe5b00..b9e0e762 100644 --- a/wiki/vision/design-judgment.md +++ b/wiki/vision/design-judgment.md @@ -44,6 +44,14 @@ not action. - **Legible dread over hidden math.** The player should always understand *why* something is bad and be unable to easily stop it — not be surprised by opaque numbers. Surprise comes from the world, never from the UI. +- **The continuous witness.** The UI narrates under pressure. After any + beat the player can answer four questions from the screen alone (what + changed, who might have seen it, what they're racing, what verb is on + the focus). One story spine stays visible (threat clock, `now:` nudge, + focused verbs). Prefer causal sentences to mute meter flips. The next + beat is world gossip, not a quest log. Untellable surfaces outrank new + systems at dispatch. Binding form: constitution "The continuous + witness"; implementable form: wiki/interface/narration.md. ## What to reject (even when it works) @@ -58,6 +66,11 @@ not action. (Marcus) beats five stubs. Ship the vertical slice, not the wide veneer. - **Cleverness that costs legibility.** A tighter mechanic the player can't narrate back is worse than a plain one they can. +- **A quest log.** Detached objectives externalize the spine the nudge and + anchors already carry; discoverability belongs on inspect / heard / + blocked-verb / nudge surfaces. +- **Green pins that fail the thirty-second bar.** A criterion test that + passes while the player still needs the wiki is not done. ## The bar for "is this the game"