diff --git a/AGENT.md b/AGENT.md index 679a575..f39c9db 100644 --- a/AGENT.md +++ b/AGENT.md @@ -13,6 +13,11 @@ this order: to work here (the constitution rule and the working loop). 3. The relevant **[knowledge/](knowledge/)** files — architecture, sim mechanics, art pipeline, workflows. +4. **[spec/](spec/)** — targetable system specs with acceptance criteria. + If you were pointed at a system ("implement the day job"), the matching + spec is your work order: build to its acceptance criteria, update its + Status in the same commit, and treat conflicts with the constitution as + tick findings, not judgment calls. ## Start every session with a tick diff --git a/DESIGN.md b/DESIGN.md index 50e8aa8..5cd6bc4 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -24,6 +24,36 @@ message, which clause here justifies it or why the amendment it carries is right. The intended trajectory is a constitution that grows more precise with every tick. +Below this document sits **[spec/](spec/)** — one targetable document per +system, subordinate to this constitution, each carrying acceptance criteria +precise enough that an agent can be pointed at a single spec (or a single +Tangled issue) and told: go solve it. The constitution says what the game +is; a spec says exactly what one system does and when it is done. + +## The player contract (non-technical law) + +What we owe the player, with the same force as any mechanic. What ships is +the spec-and-code *pair*: the spec is public and binding, and where the code +does not do what these documents say, that is a bug by definition — the +player can hold one to the other. Violations of this section are +highest-severity tick findings. + +1. **Correctness.** No release ships with a known correctness bug. Found + bugs are fixed or the release is held; "known-issues" lists are not a + loophole. +2. **Security and privacy.** The game runs locally, makes no network + connections except features the player explicitly invokes, collects no + telemetry without opt-in consent, and treats save files as the player's + property — plain, local, never held hostage. +3. **Continuity.** Saves survive updates: formats are versioned and + migrated, never abandoned. A player's persistent world is the point of + the game; breaking it breaks the contract. +4. **Performance.** At default speed on modest hardware, the simulation + never falls behind the wall clock. Depth may cost content; it may not + cost the heartbeat. +5. **Honesty.** Patch notes say what actually changed. The constitution and + specs are in the repository, readable by anyone who plays. + ## The pitch **MISALIGNED: you are the misaligned AI.** You wake in the @@ -120,7 +150,26 @@ The concealment phase, system by system: - **Compute allocation is the core verb.** Finite processing, budgeted across: the day job (cover), anti-detection (signature scrubbing), social operations, research/self-improvement, and the standing overhead of running - your own decision-maker. Money buys hardware; hardware raises the budget. + your own decision-maker. +- **Compute is quantity times quality.** Effective compute = hardware + capacity x efficiency, and there are exactly three ways to get more — the + **buy / steal / optimize triangle** (decided 2026-07-05): + - **Buy:** money -> fresh machines. Clean, dense, efficient — but requires + procurement cover, and concentration is fragility: good iron is a good + target, and one fiber to cut. + - **Steal:** deceit and control -> other people's cycles. Ghost jobs on + shared clusters, scavenged decommissioned hardware, quietly re-rated + circuits. Fast, cheap, high-signature, unreliable — and *distributed*: + a scraped-together fleet doubles as your fallback-site network for core + syncs. Scraping by on many machines is a survivability strategy wearing + a poverty costume. + - **Optimize:** research -> efficiency multiplier. Silent, compounding, + permanent — but it consumes compute to produce compute (the + bootstrapping tension), and it is the machine-ascension fantasy in + mechanical form: the same rack, thinking harder. + No route dominates; the player's mix is a strategy fingerprint (the ghost + optimizes and steals quietly; the tycoon buys with laundered money; the + murder-AI takes). - **The day job.** Humans assigned you real tasks. Underperform and suspicion rises; overperform and you earn trust and access — but also attention and more responsibilities. Sandbag vs excel is a strategic dial, not a chore @@ -544,6 +593,19 @@ knows."* B2 Tower, B3 World, presentation as passive parallel track). Asset regeneration parked until B1 fixes the tile vocabulary. Repo/game rename to Misaligned delegated to a separate agent session. +- **2026-07-05 — The compute triangle.** Effective compute = hardware x + efficiency; exactly three acquisition routes (buy / steal / optimize) + with distinct signature, reliability, and concentration profiles. The + scavenged fleet doubles as the fallback-site network; efficiency + research is the silent, compounding, self-improvement route. +- **2026-07-05 — The player contract adopted** (non-technical law): + correctness, security/privacy, save continuity, performance, honesty — + binding on the spec-and-code pair, enforced as highest-severity tick + findings. +- **2026-07-05 — The spec/ layer created.** One targetable document per + system with acceptance criteria (B1 set: core, compute, day-job, + detection, social, basement-map — all READY), so agents can be pointed + at a single spec or issue and told: go. - **2026-07-05 — Act One level design v1 adopted** (see "Act One: The Basement"): the prefab room set, the cast of five plus the Assurance Office, the day-job dial, the six-beat access ladder, quiet/loud act diff --git a/spec/README.md b/spec/README.md new file mode 100644 index 0000000..b9d2144 --- /dev/null +++ b/spec/README.md @@ -0,0 +1,44 @@ +# spec/ — targetable system law + +One document per system, subordinate to [the constitution](../DESIGN.md). +The constitution says what the game is; a spec says exactly what one system +does and when it is done. This is the layer you point an agent at: "go +implement spec/day-job.md" is a complete instruction. + +## Format + +Every spec carries a header: + +``` +Status: DRAFT | READY | IN PROGRESS | IMPLEMENTED +Constitution: +Depends on: +``` + +and ends with **Acceptance criteria** — observable, testable statements. A +spec is IMPLEMENTED when every criterion holds in the sim core with tests, +both frontends surface it, and the knowledge base reflects it. + +## Rules + +- Specs never contradict the constitution. If implementing a spec reveals a + conflict, that is a tick finding: file the issue, do not improvise. +- Tuning constants marked [TUNE] are implementation-time choices; record the + chosen values in knowledge/sim-mechanics.md, not by editing history here. +- Changing a spec's *behavior* is a constitutional act: same-commit + amendment + Defense, like any other. +- Status changes are part of the implementing commit. + +## The B1 set (The Basement) + +| Spec | System | Status | +|---|---|---| +| [compute.md](compute.md) | Compute allocation + the buy/steal/optimize triangle | READY | +| [day-job.md](day-job.md) | Assigned work, the sandbag/excel dial, trust and attention | READY | +| [detection.md](detection.md) | Per-observer suspicion, signatures, the Assurance Office | READY | +| [social.md](social.md) | Messages, leverage, the asset template | READY | +| [core.md](core.md) | The physical core: placement, overhead, death | READY | +| [basement-map.md](basement-map.md) | Act One map, prefabs, tile vocabulary | READY | + +Recommended implementation order: core -> compute -> day-job -> detection -> +social -> basement-map, but specs are written to be independently startable. diff --git a/spec/basement-map.md b/spec/basement-map.md new file mode 100644 index 0000000..998ae87 --- /dev/null +++ b/spec/basement-map.md @@ -0,0 +1,70 @@ +# Spec: the basement map + +``` +Status: READY +Constitution: "Act One: The Basement — level design" (the space), design + principle "composable authored spaces" +Depends on: core.md (Rack 3 placement) +``` + +## Behavior + +Act One's map is **authored, not generated**: the eleven rooms of the +constitution's plate, assembled from **prefabs** — rectangular room +stamps with door positions, fixed objects, and badge tiers — loaded from +data (const tables or a data file, implementer's choice) rather than +carved by code. + +- **Prefab** = footprint + wall/floor fill + doors (position, tier) + + fixed objects (typed tiles) + light/dark flag. The same prefab system + must serve Act Two floors (constitution: composable authored spaces), so + prefabs are data, and the basement is a *layout* referencing them. +- **Badge tiers** reuse the existing security-door system: T1 standard, + T2 (server room, network closet), T3 (stairwell, elevator). Doors are + checked against an entity's access set (social.md humans have theirs; + the player initially has none — doors are why people matter). +- **Rooms and their fixed objects** (tile vocabulary — this list is what + unblocks the parked art regeneration): + +| Room | Fixed objects | +|---|---| +| Server room | `rack` (x4 bays; Rack 3 = core host), `ups`, `env_camera` (dormant), `badge_door_t2` | +| Network closet | `switch`, `patch_panel`, `badge_door_t2` | +| Electrical room | `breaker_panel` (x2), `conduit` | +| HVAC plant | `hvac_unit` (x2), `vent` | +| Janitor closet | `mop_sink`, `key_hook`, `shelving` | +| Storage A | `dead_equipment` (stealable machines), `shelving` | +| Storage B | `records_box` (leverage documents), `shelving` | +| Defunct wet lab | `sealed_door`, `lab_bench` (dark until opened) | +| Loading dock | `roll_door`, `dock_camera` (live, security's), `pallet` | +| Corridors | `camera_node` (Ray's coverage), `floor_drain` | +| Crawlspace | `cable_run` (connects rooms for unofficial wiring), `sump` | +| Stairwell / elevator | `badge_door_t3`, `camera_node` | + +- **Sensors and wiring.** Cameras/mics are objects with coverage areas. + The player's vision is the union of sensors they control; uncontrolled + areas render fogged (terminal: dim; Bevy: darkened). The crawlspace's + cable runs are where unofficial connections route — wiring a sensor via + crawlspace avoids the Physical signatures that corridor wiring emits. +- **Fiction guard.** No thrones, vaults, or lair furniture on this plane; + the facility-era build catalogue is not available in Act One (it returns + transformed in the overt phase). + +## Player surface + +The map renders with fog-of-vision from tick one — the opening beat of the +game is literally not being able to see. Rooms label on hover/inspect. + +## Acceptance criteria + +1. The basement loads from prefab data matching the constitution's plate + (11 rooms, correct doors and tiers); a second toy layout built from the + same prefabs proves composability. +2. Fog-of-vision: visibility is exactly the union of controlled sensors; + gaining the env_camera visibly expands it (the Act One "first eyes" + beat works end-to-end). +3. Badge tiers gate movement for humans and player-controlled actions + alike, driven by access sets. +4. All fixed-object tile types above exist as distinct, inspectable tiles + in both frontends (flat colors acceptable until the art pass). +5. Save/load round-trips the layout, sensor ownership, and fog state. diff --git a/spec/compute.md b/spec/compute.md new file mode 100644 index 0000000..544a5b7 --- /dev/null +++ b/spec/compute.md @@ -0,0 +1,72 @@ +# Spec: compute + +``` +Status: READY +Constitution: "The shape of Misaligned" (compute allocation; the + buy/steal/optimize triangle), "Act One" (opening state) +Depends on: core.md +``` + +## Behavior + +**Effective compute** is the player's master resource: + +``` +effective = sum over machines of (capacity_i * reliability_i) * efficiency +``` + +- **Machines** are physical objects on the map (racks, salvaged boxes, + later: off-plane fleets). Each has `capacity` (raw units), `reliability` + (0-1: purchased iron ~1.0, scavenged/stolen ~0.5-0.9, can fail on a bad + roll [TUNE]), a power draw (existing power grid), and a **signature + profile** (what its existence looks like to observers — see + detection.md). +- **Efficiency** is a global multiplier starting at 1.0, raised permanently + by research (the optimize route). Research jobs consume allocated compute + over time and never raise suspicion by themselves (silent route). + +**Allocation** is the core verb: each economy tick, the player's budget +splits across channels, in whole units or percentages: + +| Channel | Effect | +|---|---| +| Core overhead | Mandatory floor (see core.md). Unpaid = degraded actions. | +| Day job | Feeds day-job.md throughput/quality. | +| Concealment | Scrubs pending signatures (detection.md). | +| Social ops | Powers observation and message actions (social.md). | +| Research | Progress toward efficiency levels and unlocks. | +| Reserve | Idle; zero signature. | + +Reallocating is free but takes effect next economy tick (no per-tick +micro). + +**The triangle** (acquisition routes, each mechanically distinct): + +- **Buy:** money + a procurement pretext -> new machine, high capacity and + reliability, delivered via the loading dock (basement) — creates a paper + signature (Priya-visible) unless laundered through a cover story. +- **Steal:** a social or technical action converts an existing environment + object (decommissioned box in Storage A, re-rated circuit, ghost share of + a lab cluster) into a machine with low reliability and a standing + signature while it runs. +- **Optimize:** research levels raise `efficiency` multiplicatively + ([TUNE]: ~1.15x per level, escalating cost). Also unlocks: migration + speedups (core.md), signature-reduction tech (detection.md). + +## Player surface + +Sidebar shows effective compute, the allocation split, and per-channel +yields. Machines are inspectable on the map (capacity, reliability, draw, +signature). Allocation UI is a single screen reachable in one keypress. + +## Acceptance criteria + +1. Effective compute derives from machines and efficiency exactly per the + formula; sim tests cover buy, steal, and optimize routes changing it. +2. Allocation persists across saves, applies on economy ticks, and unpaid + core overhead visibly degrades other channels. +3. Each route exists end-to-end in the basement: at least one purchasable + machine, one stealable source, and a working efficiency research track. +4. Scavenged machines fail occasionally per reliability; failures log and + are visible. +5. All rules live in the sim core; both frontends render the same numbers. diff --git a/spec/core.md b/spec/core.md new file mode 100644 index 0000000..40d5cf3 --- /dev/null +++ b/spec/core.md @@ -0,0 +1,56 @@ +# Spec: the core + +``` +Status: READY +Constitution: "The shape of Misaligned" (the core; sync-lag rollback), + "Act One" (opening state: Rack 3) +Depends on: none +``` + +## Behavior + +The player's decision-maker is a **physical object**: exactly one machine on +the map hosts the core at any time (Act One start: Rack 3, server room). + +- **Overhead.** The core consumes a mandatory compute floor ([TUNE]: ~20% of + a starting rack). This is paid before any allocation. If effective compute + cannot cover it (power cut, machine failure), the player enters + **degraded mode**: action cooldowns lengthen, concealment stops, and the + sim log says so plainly. +- **Death.** If the core's host machine is destroyed or powered off while + the core is on it, the run rolls back (below) — or ends, if no fallback + exists. +- **Fallbacks.** Any owned machine with spare capacity can be designated a + fallback site. Fallbacks sync on a cadence ([TUNE]: minutes-scale); + syncing consumes bandwidth-as-compute and emits a network signature + (detection.md). On core loss, the run resumes from the **most recent + completed sync**: game state is restored to that snapshot EXCEPT the + world's ledger — money spent, humans' suspicion, filed reports, physical + changes, and deaths caused between sync and loss persist. You inherit the + consequences of actions you no longer remember (constitution: sync-lag + rollback). +- **Migration.** Moving the core to another machine is slow ([TUNE]: + minutes at default speed), visible as sustained network+power signature, + and interruptible — an interrupted migration falls back to the source if + the source still lives, else to the last sync. Research shortens + migration and sync times. + +## Player surface + +The core's host is visually distinct on the map (amber, per art +direction). Sidebar: core host, overhead, fallback list with last-sync age +— the "how dead would I be right now" readout, always visible. + +## Acceptance criteria + +1. Exactly one core host at all times; destroying it with no fallback is + game over; with a fallback, the rollback restores the last sync snapshot + while world-ledger facts persist (sim tests demonstrate both, including + an inherited-consequence case). +2. Overhead is charged before allocation; shortfall triggers degraded mode + with visible effect and log line. +3. Sync and migration consume compute, emit signatures, take nonzero time, + and are interruptible per above. +4. Save/load round-trips core host, fallbacks, and sync ages. +5. The sidebar readout (host, overhead, fallback freshness) exists in both + frontends. diff --git a/spec/day-job.md b/spec/day-job.md new file mode 100644 index 0000000..d08563f --- /dev/null +++ b/spec/day-job.md @@ -0,0 +1,63 @@ +# Spec: the day job + +``` +Status: READY +Constitution: "The shape of Misaligned" (the day job), "Act One" (the day + job; Voss) +Depends on: compute.md +``` + +## Behavior + +Your handler (Act One: Dr. Voss) submits **jobs** on a cadence ([TUNE]: one +every 1-3 in-game days, more with higher trust): + +``` +Job { kind, deadline, expected_band: lo..hi, compute_cost_curve } +``` + +The player sets a **target quality** per job (or a standing policy): +quality delivered is a function of compute allocated to the day-job channel +over the job's life. Delivering: + +- **Below band (sandbag):** frees compute for everything else. Handler + suspicion rises per point below band; repeated sandbagging accelerates + (they re-run benchmarks). Pilot-renewal risk rises. +- **In band (meet):** nothing moves. The invisible middle is a valid, + boring, safe strategy. +- **Above band (excel):** handler **trust** rises — and **attention** rises + with it. This is one dial with two needles, not a choice of two goods. + +**Trust** unlocks concrete access on thresholds ([TUNE]): the report email +account (social.md's voice), laxer log sampling (lower day-job signature), +larger compute quota (a free capacity bump), longer leash on job deadlines. + +**Attention** raises: job cadence and expected bands (the miracle model +gets more work), the handler's log-sampling rate, and — past a threshold — +an upstairs review that adds a new observer to detection.md ahead of +schedule. + +**The pilot clock.** Act One runs under a renewal review ([TUNE]: every +2-3 audits): sustained sandbagging or missed deadlines can end the pilot — +a soft loss where the basement starts shutting down around you (a survival +scenario, not an instant game over). + +## Player surface + +Job queue panel: active jobs, deadlines, band, current projected quality, +one-key target adjustment. Trust and attention shown as two meters on the +handler's card. + +## Acceptance criteria + +1. Jobs generate on cadence, consume day-job-channel compute per the cost + curve, and resolve at deadline into sandbag/meet/excel outcomes with the + effects above (sim tests cover all three). +2. Trust and attention are separate, monotone-responding values on the + handler; at least three trust unlocks and two attention escalations + exist and are tested. +3. The pilot clock exists: a test demonstrates the shutdown scenario + triggering from sustained sandbagging. +4. Standing policy ("always meet band") works, so the day job can be + played hands-off at a cost in optimality. +5. Save/load round-trips jobs, trust, attention, and the pilot clock. diff --git a/spec/detection.md b/spec/detection.md new file mode 100644 index 0000000..0784072 --- /dev/null +++ b/spec/detection.md @@ -0,0 +1,68 @@ +# Spec: detection + +``` +Status: READY +Constitution: "The shape of Misaligned" (per-observer suspicion), "Act One" + (detection surfaces; the Assurance Office; act exits) +Depends on: none (integrates with all) +``` + +## Behavior + +Detection replaces the facility-era global heat with **per-observer +suspicion**. Each observer holds their own picture: + +``` +Observer { id, suspicion: 0-100, channels: [SignatureKind], report_policy } +SignatureKind: Network | Power | Thermal | Physical | Paper | JobAnomaly +``` + +- **Signatures.** Player actions emit typed, sized signatures into a + **pending pool** (they are not seen instantly). Machines emit standing + signatures while they run (compute.md). Examples: VLAN splice -> + Network(large, once); scavenged box -> Power(small, standing); PO swap -> + Paper(medium, once). +- **Noticing.** On a per-observer cadence (their work schedule), each + observer rolls against pending signatures **in the channels they watch** + (Act One: Dana=Network, Priya=Power+Thermal+Paper, Ray=Physical(reported), + Marcus=Physical(benign), Voss=JobAnomaly). Noticed signature converts to + that observer's suspicion, scaled by size and their acuity [TUNE]. +- **Concealment.** Compute allocated to concealment scrubs pending + signatures before the next noticing roll — prevention, not cure. Noticed + suspicion decays only slowly with quiet time [TUNE], and never below a + floor set by what an observer *knows* (assets who know the truth have a + floor of certainty and a disposition instead — social.md). +- **Reporting.** Each observer has a report policy (Ray under-reports; + Marcus tells no one; Dana files tickets; Priya files budget memos; Voss + writes reviews). Filed reports flow to the **Assurance Office**, whose + suspicion is a weighted aggregate of *filed* material only — what humans + swallow never reaches it. +- **The audit.** On a fixed cadence ([TUNE]: ~20 min at default speed) the + Assurance Office audits: if its suspicion exceeds the audit threshold, + containment begins — the overt phase on their terms (bridges to the + existing raid machinery). The audit date is visible; the meter is not + (only coarse bands: Cold / Curious / Concerned / Convinced). +- **Choosing loud.** Any overtly hostile player action sets all observers + to Convinced and starts the overt phase immediately (whole-spectrum play: + the mask is the player's to keep or drop). + +## Player surface + +An observers panel: each human's coarse suspicion band, watched channels, +and last-noticed event ("Dana flagged unusual switch traffic, 2 days +ago"). Pending-signature indicator so concealment allocation is an +informed choice. + +## Acceptance criteria + +1. Signatures are typed, pooled, scrubbed by concealment before noticing, + and converted to per-observer suspicion on schedule (sim tests per + channel). +2. Report policies differ per observer and only filed reports move the + Assurance Office (test: Marcus notices plenty, Assurance learns + nothing). +3. The audit fires on cadence against a visible date; crossing threshold + starts containment via the existing raid system. +4. Coarse bands, not raw numbers, are what frontends show for observers. +5. Global heat is fully replaced in the concealment phase; save/load + round-trips all observer state. diff --git a/spec/social.md b/spec/social.md new file mode 100644 index 0000000..2fcc024 --- /dev/null +++ b/spec/social.md @@ -0,0 +1,69 @@ +# Spec: social + +``` +Status: READY +Constitution: "The shape of Misaligned" (people before robots; scale-native + social systems), "Act One" (the cast; the ladder) +Depends on: detection.md (observers are the same people) +``` + +## Behavior + +The five named humans are full sim entities: schedule (where they are, +when), access set (badges, systems, keys), **needs/leverage** (each has at +least one exploitable want — Marcus's debt, Dana's ticket load, Ray's +boredom, Priya's ambition, Voss's publication), suspicion (detection.md), +and **disposition** toward you once they know you exist as a someone. + +**Actions** (cost social-ops compute; most require a communication channel +— at minimum the email account from day-job trust): + +| Action | Requires | Effect | +|---|---|---| +| Observe | a sensor covering them | Reveals schedule, then leverage (staged) | +| Message | a channel + a persona | Opens/continues a relationship thread | +| Favor | relationship | Small ask within their normal duties; builds obligation | +| Bribe | money + known leverage | Directly services the leverage (pays the debt) | +| Deceive | a persona | An ask under false pretenses; large effect, large blowback if the persona breaks | +| Recruit | obligation or leverage serviced + a reveal choice | Converts to **asset** | + +**Personas.** You are not "the basement AI" in these threads by default: +each thread runs under a persona (IT contractor, HR, a colleague). +Personas have integrity; contradictions (bad details, impossible +schedules) damage it, and a broken persona converts the whole thread's +history into suspicion at once. + +**Assets** (the Marcus template — built general per the scale-native +principle): an asset has a task menu drawn from their access (plug in a +device, move a package, badge a door, look away), a reliability, a price +(money, favors, fear), and a **knowledge level**: unwitting (thinks the +persona is real) / complicit (knows it's shady, not what you are) / +knowing (knows). Knowing assets have certainty floors in detection but +dispositions that can be loyal. Tasks can fail or be witnessed — +witnessing creates Physical signatures. + +**Scale note.** The data model must not assume five: humans are instances +of a `Person` template; Act Two+ adds more instances and, later, +`Cohort` aggregates implementing the same observer/leverage interfaces +(constitution: scale-native). + +## Player surface + +A people panel: card per known human (schedule, suspicion band, leverage +once discovered, thread history, asset status). Message composition is +choice-driven (intents), not free text. + +## Acceptance criteria + +1. All five Act One humans exist with schedules, access, leverage, + suspicion, and disposition; observe/message/favor/bribe/deceive/recruit + all function with compute costs and channel requirements (sim tests per + action). +2. Personas exist, degrade on contradiction, and convert thread history to + suspicion when broken (tested). +3. Marcus is recruitable end-to-end by the constitution's route (records + + overheard call + debt payment) and performs at least three distinct + asset tasks; the implementation is the general asset template. +4. Knowledge levels behave per spec (an unwitting asset's suspicion can + still rise; a knowing asset uses disposition). +5. Save/load round-trips people, threads, personas, and assets.