Doc reconciliation: Shitbox_Architecture.md is factually out of date (11 corrections)

[wpinrui]

Shitbox_Architecture.md has drifted badly from the code. These are factual errors — the doc describes types, files, and phases that do not exist as written. Every row below is a doc-side correction; none of them require code changes.

Sequencing: the PM has deliberately scheduled this pass after PR #62 lands, so it also captures #62's rule changes (the "one shot per car" listing removal, and NPC pricing re-anchored to listing.askingPrice). Don't start before #62 merges.

Corrections

• §6 — Phase tracker. Doc says Phase 4 "← CURRENT" with all 10 boxes unchecked. Phase 4 is actually 7/10 done and merged (PR feat: negotiation system #61). Tick the completed boxes and move the marker. Phases 0–3 also need their boxes ticked — with one asterisk: Phase 0's "Create data validator tool" is partial (tools/data-validator.ts validates only economy.json; cars, traits, activities, and map are unvalidated — the file says so itself).
• §3.1 — economy.json spec is substantially wrong. The real file has a completely different statEffects tree. It lacks the doc's skillGrowth, conditionAssessment, lemonChance, investmentFund, and roadTripEngagement blocks, and adds carDegradation and rest.crashOutEnergyPerHour. The doc also says shitboxEnergyPerHour: 4; the actual value is 6.
• §3.5 — data/stunts.json. Specced, but the file does not exist (Phase 7, not started). Mark aspirational.
• §4.1 — GameState.npcs.activeNegotiations. Removed. Negotiation now lives in store UI state. (See Negotiation state is not persisted across saves #74 — it isn't persisted, which is a real bug.)
• §4.1 — player.domainSkills.cinematography. Does not exist in types.ts. Needed for Phase 7.
• §4.3 — Offer type. Doc gives it extras + paymentTerms, and lists reject / thinking response types. The actual NegotiationOffer is { price } only, and NpcResponse is counter / accept / walk_away.
• §4.4 — Road trip system reference implementation. Not built. src/engine/systems/roadtrip.ts does not exist.
• §5.1 — Store interface. Missing the real store's sleep/chill, toasts, audio, tabs, takeGig, and walkTo/driveTo. Lists road-trip actions that don't exist.
• §5.2 — src/store/selectors.ts. Still does not exist. The doc already flags this as aspirational, so this row is accurate as written — listed only for completeness.
• §7 — Testing strategy, with example unit and integration tests. Zero tests exist in the repo. Either build them or mark the section aspirational.
• §2 — Directory structure. Missing src/engine/systems/negotiation.ts and sleep.ts, the hud/ component folder, SleepModal / ChillModal / NegotiationModal / TravelConfirmModal, and data/traits.json.

Also worth fixing while in here

Architecture §1 principle #1 is "All tunable values live in JSON. Code never contains magic numbers." The code violates this in at least three places — tracked separately in #81, #77, and #76. The principle is right; the code doesn't follow it. Don't weaken the doc to match the code.

---

From the 2026-07-13 code audit (Researcher). Verified against main @ b8e0d70.