From 762d14d2e47ac684aed2411b7f3df284ae523c0e Mon Sep 17 00:00:00 2001 From: Cameron Date: Wed, 15 Jul 2026 21:40:51 -0700 Subject: [PATCH] Adopt the digital read: DIGITAL default, language in world space, REAL deferred. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design session from the Fable playtest debrief. presence.md's two-views law now names DIGITAL the default and the read, and marks REAL deferred without deletion; the new digital-read.md spec (work order digital-read, priority 27, frontend) owns the contract: one causal receipt model behind pre-commit receipts and post-commit records, standing anchor sentences under an attention economy, reticle receipts from ActionDesc, trace debt as records on the wire, held choices interrupting at their anchors, intel levels with an altitude gate, and a live dev two-pane for dialect parity review. The scaled-summary authoring source is left as a decision-required issue rather than silently picked. Trace (Cameron's Letta agent) reviewed the direction; its contact route enters the CLAUDE.md doorway. Defense: wiki/process/design-sessions.md and wiki/overview.md — an adopted direction must exist in the binding corpus in the same session it is adopted; the law amendment and owning spec land together with decision history, session log, and regenerated indexes. --- CLAUDE.md | 10 ++ wiki/SUMMARY.md | 1 + wiki/interface/digital-read.md | 161 ++++++++++++++++++ wiki/interface/presence.md | 51 ++++-- .../2026-07-15-digital-read-design-session.md | 33 ++++ wiki/log/DEVLOG.md | 5 + wiki/log/decisions/2026-07-15.md | 19 +++ wiki/process/ROADMAP.md | 1 + wiki/process/specs.md | 1 + 9 files changed, 270 insertions(+), 12 deletions(-) create mode 100644 wiki/interface/digital-read.md create mode 100644 wiki/log/2026-07-15-digital-read-design-session.md diff --git a/CLAUDE.md b/CLAUDE.md index bb34bfe5..278d8960 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,3 +39,13 @@ afterward. `wiki/` and carry a Defense. Documentation work updates stale knowledge, adds a dated `wiki/log/` entry, then runs `tools/ledger_index.sh`; never hand-edit generated `wiki/log/DEVLOG.md` or `wiki/process/specs.md`. + +## Project agents + +- **Trace** — Cameron's Letta agent holding deep Misaligned context + (design history, collaboration patterns, dispatch sequencing). Consult + before large interface/spec work and for cross-session continuity: + `letta -p "" --agent agent-7039aebc-8ae3-4688-8ca3-31c4ade526f1` + (`--new` starts a conversation, `--conv ` resumes one). Headless + mode needs `LETTA_API_KEY` — sourced from the repo-root `.env` (never + stage or print it). diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 38c57279..cf99ba9a 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -69,6 +69,7 @@ - [Overview](interface/README.md) - [The continuous witness](interface/continuous-witness.md) + - [The digital read — a world made of language](interface/digital-read.md) - [Superhuman operability](interface/superhuman-operability.md) - [The terminal is first-class](interface/terminal-first.md) - [Presence and representation](interface/presence.md) diff --git a/wiki/interface/digital-read.md b/wiki/interface/digital-read.md new file mode 100644 index 00000000..0950d468 --- /dev/null +++ b/wiki/interface/digital-read.md @@ -0,0 +1,161 @@ +# Spec: the digital read — a world made of language + +``` +Type: spec +Status: READY +Status note: adopted 2026-07-15 from the Fable playtest debrief (report: + wiki/playtests/2026-07-15-playtest-fable.md). The playtest proved the + game's felt core is the witness voice — causal sentences with named + observers and pre-commit signature receipts — which the agent protocol + drains constantly and the Bevy frame renders almost nowhere (the receipt + reaches Bevy only as ops_explain_text on an already-selected Operations + row; Cameron had never seen it). Decision: DIGITAL is the default and + becomes the read — language projected into world space; REAL is deferred + (presence.md). Trace (Letta agent) reviewed the direction 2026-07-15 and + contributed the one-receipt-model, attention-economy, and + projection-first sequencing constraints captured below. Summary-source + for scaled intel sentences is [OPEN] (Tangled issue). +Stage: B1 — The Basement +Work order: digital-read +Work priority: 27 +Work class: frontend +Blocked by: none +Exclusive keys: + - wiki/interface/digital-read.md + - crates/misaligned-bevy/ +Design: + - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations + - wiki/interface/continuous-witness.md#the-continuous-witness-narration-under-pressure + - wiki/vision/simulation-laws.md#justification-and-legibility + - wiki/vision/scale.md#self-similar-scale +Depends on: + - wiki/interface/action-vocabulary.md#spec-action-vocabulary-what-the-player-can-tell-the-process-to-do + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/intel.md#spec-intel-record-and-process +``` + +## Dependency notes + +presence.md owns the two-representation law this spec realizes on the +digital side; continuous-witness.md owns the axioms (the thirty-second +bar, causal sentences over numbers) this spec moves from the rail into +world space; action-vocabulary.md owns the shared `ActionDesc` rows whose +`cost`/`ExpectedSignature`/`disabled_reason` fields are the receipt's +single source of truth; detection.md owns the pending-pool and routed- +evidence model that trace-on-the-wire renders; intel.md owns the +recordings/custody pipeline whose sentences scale with zoom. The clinical +frame (clinical-frame.md) remains the deferred REAL dialect's authority; +its rail contract stays valid where this spec does not supersede it. + +## Why this spec exists + +Two players played the same build and reported different games. The agent +protocol player received, on every action row and every consequence, a +sentence: `1.50 T | Network 8 -> the IT [Cold]`; "the IT noticed Network +from stolen egress opening: +8 (Curious -> Concerned)"; "Marcus Webb reads +the note twice on a night round." The human player, clicking in the Bevy +frame, received the visuals and almost none of the sentences — and the +designer of the detection system had never seen its own receipt. The fix +adopted here: stop treating the sentences as rail detail and make the +digital representation itself out of them. DIGITAL is what a process +natively perceives; a process perceives *causality, priced*. The read is +that perception rendered. + +## Behavior + +- **One receipt model (binding).** Pre-commit receipts, post-commit + records, and standing state sentences are projections of one shared + causal model in core, not three formatting paths. `ActionDesc` (cost, + `ExpectedSignature`, disabled reason, automate price) is the pre-commit + face; drained events with anchors are the post-commit face; the + building-route composer's staged receipts are the precedent. Frontends + never compose their own causal prose from raw state. +- **Standing anchor sentences (glance tier).** Every earned anchor in view + wears at most one short live sentence naming its current relationship to + you: the switch carries `egress hum · Dana samples this · Curious`; a + starving reservoir carries `open · nothing thinking`; a held plot + carries its question. Stable-and-quiet state says nothing — **the + attention economy is law**: starvation, deadlines, contradictions, held + choices, and band motion rise; nominal state stays dark. A world made of + language must not become every system continuously talking. +- **Reticle receipts (focus tier).** Focusing any verb (hover, controller + focus, or agent `actions` listing — same rows) renders the full receipt + at the reticle: `cost · ExpectedSignature::label() · [band]`, DIM + `no signature` when the verb emits nothing. A blocked verb renders its + blocker as world state on the anchor that blocks it (`needs: security + segment — the switch bridges it`), never as a grayed catalog row. The + player never commits an act whose shadow they have not been shown. +- **Trace on the wire.** Pending one-shot signatures render as discrete + records sitting on their emitting anchors/carriers, aging toward the + observer who samples that channel; scrub visibly consumes them. The + standing/one-shot distinction detection.md already models becomes + spatially legible: standing hums mark their source; pool debt sits as + records. TRACE: LIVE stops being a badge you can miss. +- **Held moments stop the world (drill tier).** A held plot choice dims + the frame one step and hangs the question and its options — rendered as + the exact bound commands — at the person's anchor until answered. + Sentences never expire unread: an unread consequence pins itself to the + story spine until glanced. Reading is free; the command clock already + holds time while you read (agent parity: this is the drain contract). +- **Sentence LOD rides zoom (self-similar scale).** Zoom is a semantic + altitude: close shows individual sentences; hall scale shows sentence + *density* and only rising items; regional/planetary scale (B3) shows + only aggregate intel sentences — the design intent is that a fully + zoomed-out read says things like a regional intel item would ("a state + actor's filing wave"), while small items never surface above their + altitude. Intel items therefore carry a **level** (person, room, hall, + campus, region), assigned at processing. How scaled summary sentences + are *authored* — small-model generation, pre-authored pools, or leveled + plot text — is [OPEN] (decision-required issue filed 2026-07-15); the + level field and the altitude gate are not blocked on it. +- **Dev two-pane (alignment instrument, not player surface).** A live + toggleable development view renders the same tick in both dialects side + by side (and may pair the agent frame's text), for design review of + parity — how humans think versus how agents think, diffable. Ships in + the ordinary build as a debug view (no feature flag), excluded from the + player-facing default and from the frames-not-dumps contract. +- **REAL stays deferred.** No standing anchor sentences are added to the + material dialect; its diegetic whispers (overheard speech at embers) are + specified intent under presence.md but wait behind the read. + +## Player surface + +The default Bevy experience is the read: open the game, see the dark +field, your presence beam, and language exactly where your knowledge is. +The thirty-second bar is answerable from the world alone: what changed +(its sentence is on the thing), who might have seen it (the observer is +named in that sentence with their band), what you are racing (threat clock +on the rail, unchanged), what verb is on the thing under your cursor (the +verb and its full receipt at the reticle). Agent mode and the terminal +already speak this dialect; criterion is parity of meaning, not identical +composition. + +## Acceptance criteria + +1. A renderer-neutral sentence/receipt projection exists in core with pure + fixtures pinning representative states (starving reservoir, band + motion, held choice, pending vs standing trace, blocked verb), and + agent mode emits the same semantics as inspectable text. +2. Focusing any executable verb in Bevy shows cost + expected signature + + observer + band at the reticle before commitment; verbs with no + emission say so; the row's data comes from `ActionDesc` unmodified. +3. Standing anchor sentences render for rising states and only rising + states: a nominal machine says nothing; a starving reservoir, a held + choice, a deadline, and an observer band change each surface at their + anchor within one tick of the projection reporting them. +4. Pending signature records are visible at their emitting anchors and are + visibly consumed by scrub; standing emissions mark their source + distinctly from pool debt. +5. A held plot choice interrupts at the person's anchor with its options + as the exact bound commands; the sim's held state and the surface's + held state cannot disagree (single projection). +6. Intel items carry a level; a zoomed-out frame surfaces only + at-or-above-altitude sentences (fixture-tested at two altitudes with + mixed-level intel). +7. The dev two-pane toggle renders both dialects of the same tick live in + one build, and is absent from the default player layout. +8. Cold-player scenario pass (not state traces): opening darkness, first + Ears, first receipt, first band motion, a starving reservoir, a held + choice, aging trace debt — captured as final frames and visually + reviewed before IMPLEMENTED (structural screenshot audits are not + visual review). diff --git a/wiki/interface/presence.md b/wiki/interface/presence.md index 9092ff9f..b10ab5d5 100644 --- a/wiki/interface/presence.md +++ b/wiki/interface/presence.md @@ -151,24 +151,51 @@ reaching for without a portal: digital is not a place you travel to, and it is not a detached topology board; it is what a process natively perceives of the same room. +**DIGITAL is the default; REAL is deferred (DECIDED 2026-07-15).** The +2026-07-15 Fable playtest exposed the split's real stakes: the agent +protocol drains a continuous stream of *causal sentences* — who noticed +what and why, the pre-commit signature of every verb, the overheard 3 a.m. +call — and that voice, not the material render, is where the game's dread +and comprehension actually live. The material/REAL dialect is beautiful +but distracting to build against, and it is not the experience the game +defaults to. So the digital representation is not merely home; it is the +game's primary surface, and it stops being a sparse amber diagram: it +becomes **a world made of language — the read** (spec: +[digital-read.md](digital-read.md)). REAL is not deleted — it remains the +specified embodied dialect for the overt phase and for looking at what your +body costs you — but it is deferred: not the default, not the current build +focus, and no new system waits on it. When this law and digital-read.md +speak about the same surface, digital-read.md owns the exact contract. + - **Shared canvas.** A person, rack, camera, door, wall, and core have one coordinate/anchor and one knowledge state. The cursor stays on the same tile across flips. Device nodes anchor to the device's physical location. Reach edges draw between physical device anchors. Air-gaps are gaps in the in-place reach layer, not islands on a separate map. -- **The digital representation (home).** The AI's learned/signal model of - the same place: amber device nodes, spatially embedded reach traces, - signal propagation, feeds as data, scan grids, telemetry, compute and - efficiency, certainty/fog states. **Reach is native here, but reach is - a layer, not a replacement layout.** You act by reach, not walking: - your attention moves as a cursor, and your agency spreads through +- **The digital representation (home, the read).** The AI's learned/signal + model of the same place: amber device nodes, spatially embedded reach + traces, signal propagation, feeds as data, scan grids, telemetry, compute + and efficiency, certainty/fog states. **Reach is native here, but reach is + a layer, not a replacement layout.** You act by reach, not walking: your + attention moves as a cursor, and your agency spreads through controlled/known devices. This is the amber/black signal world: your - habitat. -- **The real / camera representation.** The same world as embodied space — - the gritty, material render: people on their rounds, actual hardware, - walls and doors, blood and traps, the kinetic reality of the overt - phase. Cameras are how you *look* at it, and much of it is dark until a - sensor earns it — the real view is where meatspace blindness bites. + habitat. Its defining texture is **language in world space** — every + anchor wears its live causal sentence, every focusable verb shows its cost + and the signature-shadow it will cast on which observer, and pending trace + debt sits on the wire as records aging toward whoever samples that channel. + A process does not click blind; it reads. digital-read.md owns this + contract; the amber signal world above is its substrate, not its ceiling. +- **The real / camera representation (deferred).** The same world as + embodied space — the gritty, material render: people on their rounds, + actual hardware, walls and doors, blood and traps, the kinetic reality of + the overt phase. Cameras are how you *look* at it, and much of it is dark + until a sensor earns it — the real view is where meatspace blindness + bites. Deferred per the 2026-07-15 decision: the material dialect stays + specified (the clinical frame remains its authority) but is not the + default surface and is not the current build focus. The one place it earns + active work before the overt phase is diegetic, not decorative — overheard + speech and material pressure that the read cannot express — and even that + waits behind the read. - **Same overlay, two dialects.** Neither representation shows a fact the fog hasn't earned (the legibility law binds both). Digital may flatten, ghost, label, and model the room; real may show material volume and diff --git a/wiki/log/2026-07-15-digital-read-design-session.md b/wiki/log/2026-07-15-digital-read-design-session.md new file mode 100644 index 00000000..cfe5c114 --- /dev/null +++ b/wiki/log/2026-07-15-digital-read-design-session.md @@ -0,0 +1,33 @@ +# Design session: DIGITAL default, the read, REAL deferred + +``` +Type: log +``` + +Session triggered by the Fable playtest debrief. Cameron compared his +clicked Bevy experience against the playtest's language-carried run and +found they were different games; investigation showed the shared +ActionDesc receipt (`cost | ExpectedSignature -> observer [band]`) +renders on every agent row and terminal menu but reaches Bevy only as a +post-selection Operations explain line — the designer had never seen it. + +Decided (captured to presence.md and the new digital-read.md spec): +DIGITAL is the default surface and becomes the read — language projected +into world space under an attention economy; REAL is deferred without +deletion; one causal receipt model feeds pre-commit receipts and +post-commit records; a live dev two-pane renders both dialects of one +tick for parity review. Open: authoring source for scaled intel summary +sentences (issue filed). Deferred: REAL polish; B3 regional-intel +surfacing beyond the level field and altitude gate. + +Trace (Cameron's Letta agent) was consulted mid-session and shaped three +binding clauses: the single receipt model (building-route-composer +precedent), glance/focus/drill attention tiers so the read never becomes +"every system continuously talking," and projection-first sequencing +with cold-player scenario review before IMPLEMENTED. Trace's contact +route is recorded in CLAUDE.md. + +Defense: wiki/process/design-sessions.md — adopted direction captured to +the owning law and a new spec in one session; decision history appended +to the dated volume; the genuinely-open taste call left as a +decision-required issue instead of a silent pick. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 8744cdad..20f36bae 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -21,6 +21,11 @@ add or amend a session log, then re-run the generator. - Intent: The oldest never-audited READY work order was Marcus. Its runtime had already grown past that dispatch status: the canonical person and observer data, the debt-intel gate, both debt plots, recruitment, three general asset tasks, the tier-3 key route, and the complete Act One t... - Log: [wiki/log/2026-07-15-marcus-graduation.md](2026-07-15-marcus-graduation.md) +## 2026-07-15 - Design session: DIGITAL default, the read, REAL deferred + +- Intent: (see session log) +- Log: [wiki/log/2026-07-15-digital-read-design-session.md](2026-07-15-digital-read-design-session.md) + ## 2026-07-15 - One physical link, one open proposal - Intent: (see session log) diff --git a/wiki/log/decisions/2026-07-15.md b/wiki/log/decisions/2026-07-15.md index 8ff0e75e..4ab08e11 100644 --- a/wiki/log/decisions/2026-07-15.md +++ b/wiki/log/decisions/2026-07-15.md @@ -18,3 +18,22 @@ Type: log added; persisted current-stage execution remains R5/R6. Authority and evidence: `wiki/mechanics/building.md` and `wiki/log/2026-07-15-building-route-full-preview.md`. + +## DIGITAL is the default and becomes the read; REAL deferred + +Cameron, from the Fable playtest debrief: the material/REAL dialect is +"too distracting to work on" and the game should "always default to the +digital experience." Adopted: DIGITAL is the primary surface and becomes +a world made of language — standing anchor sentences (attention-economy +gated), reticle receipts from the shared ActionDesc receipt model, trace +debt as records on the wire, held choices interrupting at their anchors, +sentence LOD by zoom with leveled intel. REAL stays specified (clinical +frame remains its authority) but is deferred: not default, not build +focus. A live-toggleable dev two-pane renders both dialects of one tick +for design review (no feature flag). Owner: wiki/interface/presence.md +(law) and wiki/interface/digital-read.md (new spec, work order +digital-read, priority 27). Open: how scaled intel summary sentences are +authored (small-model generation vs pre-authored pools vs leveled plot +text) — decision-required issue. Trace (Letta agent, id +agent-7039aebc-8ae3-4688-8ca3-31c4ade526f1) reviewed the direction and +contributed the one-receipt-model and attention-economy constraints. diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md index 40e9b719..74dd9bdb 100644 --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -18,6 +18,7 @@ not a second status owner. | Priority | Work order | Spec | Status | Class | Blocking | |---:|---|---|---|---|---| +| 27 | `digital-read` | [the digital read — a world made of language](../interface/digital-read.md) | READY | frontend | - | | 29 | `building-route-composer` | [building — intent and actuators](../mechanics/building.md) | IN PROGRESS | save | - | | 40 | `people-tokens` | [people and tokens — carriers, attention, trust](../mechanics/people-tokens.md) | IN PROGRESS | save | - | | 60 | `plots` | [plots — authored manipulation stories](../mechanics/plots.md) | READY | sim | - | diff --git a/wiki/process/specs.md b/wiki/process/specs.md index 4d7e8612..ab7a2677 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -32,6 +32,7 @@ replaced the old `spec/`/`knowledge/` directory split. | [../interface/clinical-frame.md](../interface/clinical-frame.md) | the clinical frame — perception exposes the institution | IMPLEMENTED | | [../interface/computer-visual-language.md](../interface/computer-visual-language.md) | computer visual language — territory at a glance | IMPLEMENTED | | [../interface/context-menu.md](../interface/context-menu.md) | context menu — actions live on the thing | IMPLEMENTED | +| [../interface/digital-read.md](../interface/digital-read.md) | the digital read — a world made of language | READY | | [../interface/feel-floor.md](../interface/feel-floor.md) | the feel floor — rails, pads, and the build beam | IMPLEMENTED | | [../interface/flat-materials.md](../interface/flat-materials.md) | flat materials — the world without textures | IMPLEMENTED | | [../interface/fleet-command.md](../interface/fleet-command.md) | fleet command — ruling at scale | DRAFT | -- 2.51.2