--- name: deep-systems-review-2026-07-13 description: "⭐⭐ THE SECOND BOMBSHELL (2026-07-13). The TEST GATE + DOCS are the biggest system in the project — bigger than the app — and they verify source SHAPE, not behavior. Plus: the CLI is already most of the way built in two disconnected halves, and the app is quietly de-AI-ing itself." metadata: node_type: memory type: project originSessionId: 0b7c5f41-bb34-4ab4-93be-fdb363f5eb40 --- ⭐⭐ **The owner's DEEP SYSTEMS REVIEW (analysis-only, Opus, 2026-07-13), run right after [[architecture-review-2026-07-13]].** Dispatch handed it that morning's findings as a **ban list** (re-reporting them = failure) and pointed it at the ground the first review never walked. It came back with a real second discovery. > **That morning: the RUNTIME is more advanced than the docs admit.** > **This review: the GATE AND THE DOCS have quietly become the biggest system in the project — and they are strongest exactly where the user can't see, and weakest exactly where the user always looks.** *Note 2026-07-20: every measured number in the original write-up has been removed. They were true when taken and are meaningless now — and re-deriving them is a grep away. The analysis below is what mattered, and it still holds.* --- ## ⭐⭐⭐ THE FINDING — the gate verifies source SHAPE, not BEHAVIOR The reframe that fell out of measuring the project against itself: - **The test runner is larger than the entire application it tests.** The tests are not a support layer; they are the biggest single artifact in the repo. - **The large majority of tests are static source-TEXT analysis** — they read a source file as a *string* and assert against it with a regex. Only a minority execute app code, and most of those exercise state and data logic, not anything rendered. - **A meaningful share of suites don't test the app AT ALL.** They police the *project's own rules*: file encoding, changelog formatting, root-directory junk, doc-vs-code drift, diagnostic-trigger coverage. - **At COMMIT time nothing looks at a browser.** Lint, format, and the Node runner. Every browser check is push-only. **The fast, frequent gate a session actually feels is entirely source-shape.** ⇒ **The gate checks the source LOOKS right. Not that the app WORKS.** **The incident that proved it (this is why the rule matters):** an entire inventory panel rendered **completely invisible** under a fully green gate. The render function's source still contained the expected class markup, so every "render contract" test passed. **The gate cannot distinguish "looks right" from "works right," by construction** — the Node runner has no browser, no layout, no geometry. ⚠ **AND THE SUITE HAS STARTED CONSTRAINING THE ARCHITECTURE RATHER THAN OBSERVING IT.** A large block of tests is coupled to source *layout*, not behavior. When a refactor moved files, hundreds would have broken on a change that altered **no behavior** — so a path-rewriting shim was built *inside the runner* to keep the greps green. **The project now carries machinery whose only job is keeping layout-coupled tests happy through refactors.** Tail wagging dog. **The honest reframe:** a world-class *invariant-enforcement engine* and a nearly-blind *behavior oracle*. Superb at "did someone delete a safeguard / corrupt an encoding / let a doc drift." Blind to "does the screen show the right thing." ### ⇒ THE #1 LEVERAGE POINT IN THE PROJECT: **MAKE "GREEN" MEAN "THE USER CAN SEE IT."** The render-integrity harness — occlusion hit-testing, contrast math, clipping, truncation — is **the most important test file in the project.** At review time it was days old, covered a handful of panels, and ran push-only. **Promote it to ALL panels, then into the commit gate.** That closes the exact hole that shipped multiple visible bugs under a green gate. *(Current coverage and where it runs: check the test directory and `.github/` workflows.)* ⛔ **AND: STOP ADVERTISING THE TEST COUNT.** It does not measure correctness — **it measures how *greppable* the source is.** Chasing the number rewards more greppable invariants, not a better app. It should stop being a headline metric. --- ## ⭐⭐ SECOND "IT WAS ALREADY HERE": THE CLI IS MOSTLY BUILT, IN TWO HALVES THAT DON'T TOUCH - **The diagnostic-shell tool registry is the command CATALOGUE** — uniform machine-readable entries, a single dispatch path, many parameterized, and a gate rule **mechanically force-feeds it** (the build FAILS if a feature ships with no trigger). That is the hard part of a CLI: a complete, enumerable control surface over the app's own behavior. - **The native command router is the command PARSER** — native commands, natural-language quick-log patterns, and a whole offline terminal mode. - ⇒ **The project has a command CATALOGUE and a command PARSER, and they do not touch each other.** Missing: only an invoke-by-name bridge. **Wire them and you get the in-fiction CLI, macros/replay, AND behavioral test automation for free.** Same shape as the scheduler discovery — half-built, unnoticed. *(Module locations: `library/CODE_MAP.md`.)* ## ⭐ THIRD: THE APP IS QUIETLY DE-AI-ING ITSELF (an unannounced program) THREAT · VATS · LOOT · BIO-SCAN · GPS · CONSULT were **all AI round-trips once. All are deterministic offline calculators now.** Nobody named this as a program; it had been running for months. **The trend line is the app becoming LESS AI-dependent over time, not more** — the truest signal of what RobCo actually is. The sharpest evidence: the AI may write most state fields, but **the ones it is forbidden are exactly the boundary-defining ones** — game context, device preferences, player-authored data. That is not an accident of implementation; it is the architecture fencing the AI out of durable truth. **Protect this trend** ([[player-control-principle]]). ## THE AI-MAINTAINER HYPOTHESIS — **TRUE in kind, OVERSTATED in degree** Dispatch's hypothesis: *the real maintainer is a sequence of context-limited AI sessions, and the docs are infrastructure, not support material.* **Confirmed**, by the shape of the docs themselves: the rulebook's token split; a code map whose entire purpose is navigating without reading whole files (a token optimization that would be meaningless to a human with an IDE); an explicitly Claude-facing brain dump; a literal question→doc routing index; and gate suites that **fail the build when a doc names code that doesn't exist**. The doctrine underneath it is the keeper: **a STALE doc is worse than no doc, because it makes a session *confidently wrong*.** That is an AI-safety rule, not a tidiness rule — humans discount stale docs, agents trust them. ⇒ **"An operating system for the project's own maintenance, enforced by the same gate as the code."** Never named anywhere in the project's own materials. **The single most novel structural fact about RobCo.** ⚠ **BUT the guards cover the docs' SKELETON, not their FLESH.** The drift suite proves the code map's *table of contents* is real; it does **not** prove any entry inside it is current. And the richest AI-facing docs are **gitignored**, so the strongest truth-checks run **only on the owner's machine, never in CI.** **The wart that proves it:** a core module's own header comment asserted that *nothing* read a given store — **true when written, false by the time it was found.** Doc drift living *inside a code comment*, the one place the doc-drift guards cannot reach. ## WHAT IS ROBCO, ACTUALLY? (question 1, answered) **"A diegetic, offline, single-operator terminal OS that is engineered to be maintained by AI."** Least well described as a website. "Game companion" undersells it; "platform" overstates it. ## PERSISTENCE: LEAVE IT ALONE — it's one coherent model, not four parallel ones localStorage (preference read-authority) + **IndexedDB (primary for cold-store saves, and the sole home for per-slot version history and the offline cloud-push queue — NOT vestigial)** + the cloud store + the metadata store. Several stores, **one clean layered model.** ⛔ **Do NOT "modernize" it.** One real wart: the chat log and playstyle are campaign data stored as loose top-level keys, outside both the save envelope and the preference manifest. ## WHAT ROBCO SHOULD **NOT** BECOME (argued as seriously as the dreams — the owner's demonstrated failure mode is scope growth) - ⛔ **No build step, no framework.** Closed on arithmetic: a bundler would invalidate the vast majority of the test suite overnight. **Vanilla is load-bearing, not a preference.** - ⛔ **Don't let the protocol book grow unbounded.** Append-only plus never-reuse plus pre-allocated-but-unwritten entries is the structural signature of a system trending toward a tax. It was not a tax at review time — most of it is gate-enforced scar tissue. **But a substantial cluster of protocols say the same thing in different words and could consolidate to a fraction of the count without dropping a single rule.** Do it once, deliberately, before the next dozen arrive. - ⛔ **Never make the AI an authority.** The architecture fences it OUT of durable truth; protect the AI→native trend already underway. - ⛔ **No paid infra, no server, no cloud functions** ([[project-must-stay-free]]). - ⛔ **No "modding platform" / "simulation engine."** Nothing in the code traces to them — science fiction. ## HONOR-SYSTEM RULES THAT WOULD DO REAL DAMAGE IF SILENTLY SKIPPED (no gate can force them) **Every fix ships a regression test** · **extend an existing system before creating a parallel one** · **keep the declared test count in sync across its files.** *(Exact rule text and numbering: `CLAUDE.md` + `rules/`.)* ## FUTURE POSSIBILITIES — traceable to real files ONLY - **In-fiction CLI + macros** → the catalogue + parser halves above. - **Multi-title Fallout environment** → the additional game definition already exists and validates. - **A durable personal gaming archive** → IndexedDB cold-store, additive cloud saves and per-slot version history already exist. Related: [[architecture-review-2026-07-13]] (the morning's review — the runtime half), [[robco-os-architecture]], [[self-improving-code]], [[engineering-metrics-log]], [[player-control-principle]], [[fo3-pipboy-program]], [[reframing-review-2026-07-13]] (why the gate is static: a rule mandated it).