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 |