Urbs Vitruvian Roman Mechanical Semiotics & Universal Codebase Simulator Specification (2026)

This document defines the Vitruvian Roman mechanical architecture for Milestone v4.7 (Phases 259–264, 24 requirements). It preserves 100% Classical Roman styling and materials (dressed travertine stone, oak timber, wrought iron, hammered bronze, terracotta, parchment scrolls, mosaic tiles, waterwheels, and oil braziers—zero modern sci-fi lasers or holograms) while shaping and animating every structure as a self-evident Roman engineering mechanism (Vitruvius, De Architectura) whose physical form and moving parts immediately communicate its software and LLM harness operation at a glance.

1. Core Design Law: Vitruvian Roman Engineering Where Form + Motion = Software Function

1. Zero Modern Sci-Fi: No lasers, no glowing neon cubes, no glass tubes, no holographic tablet screens, and no modern factory hydraulics. Every material is authentically Roman: dressed travertine and basalt ashlar, heavy oak timber, hammered bronze, wrought iron, terracotta tiles, wax tablets, parchment scrolls, mosaic tesserae, flowing aqueduct water, and warm oil braziers.
2. Zero Opaque Temple Boxes: Instead of generic enclosed temples that require reading a text label or knowing Roman history, every module and harness subsystem is built as a recognizable Vitruvian Roman machine (machina) whose physical action directly mirrors what the code and LLM agents are doing:
   • Adding & Deleting Lines of Code (+LoC / -LoC Git Diff) = A Roman Timber Treadwheel Crane (Polyspastos) hoisting fresh green-banded ashlar stone blocks onto the wall while masons slide chiseled red-ochre rubble down a wooden chute into an ox-cart.
   • Routing Tokens & Judging Multi-Model Consensus = A Roman Aqueduct Distribution Basin (Castellum Divisorium) with pivoting Bronze Sluice-Paddles splitting flow between a fast Roman Waterwheel Mill (Local Model) and Parallel Aqueduct Channels (Cloud Models) pouring into a monumental Bronze Balance Scale (Libra).
   • Reading Files into the Prompt Context Window = An open-walled Roman Scriptorium Scroll-Rack (Armarium) where scribes under warm brass oil-lamps pull parchment scrolls from wooden pigeonholes and load them into a graduated Bronze Clepsydra (Water-Clock / Scroll Vessel, 68% Full).
   • Compiling & Typechecking Code = A Waterwheel-Driven Bronze Trip-Hammer & Carved Stone Caliper Arch (Moneta Forge) stamping stone tablets—or cracking a flawed block with forge embers and dropping an Iron & Timber Aqueduct Sluice-Dam (Cataracta) that leaves downstream channels dry (BLAST RADIUS BLOCKED).

---

2. The 8 Universal Vitruvian Roman Mechanisms (Works on Any Repo)

#	Vitruvian Roman Mechanism	Software / LLM Operation (Any Repo)	Authentic Roman Physical Geometry (No Sci-Fi, No Labels Needed)	Live Mechanical Animation & 1-Click Control
1	Masonry Scaffold & Timber Treadwheel Crane (Polyspastos)	Source code modules & files (src/*, crates/*, packages/*) and uncommitted Git diffs (+LoC / -LoC)	Roman stone building wrapped in oak timber scaffolding topped by a wooden treadwheel pulley crane and a side timber rubble chute.	Dormant: Completed, calm moonlit stone structure. Active Edit / Diff: The wooden treadwheel rotates, hoisting fresh emerald-banded ashlar blocks (+added LoC) onto the wall course while chiseled red-ochre rubble (-removed LoC) tumbles down the timber chute. Click to inspect diff or open file.
2	Aqueduct Splitter (Castellum Divisorium) & Bronze Libra Scale	LLM Router (Local Fast Model vs. Cloud Consensus) & token dispatch	Carved stone aqueduct splitter basin with pivoting bronze sluice-valves feeding either a Roman waterwheel mill or parallel stone channels into a monumental bronze balance scale (Libra).	Flowing aqueduct water & floating golden seal-tokens divert through the active bronze sluice; during multi-model consensus, parallel channels fill the Libra pans and tip toward the winning response.
3	Open Scroll Armarium & Graduated Bronze Clepsydra	Agent file reads (read_file, rg, @pinned context) & Context Window (% full)	Open-fronted wooden scroll pigeonholes (Armaria) lit by a brass oil-lamp, connected to a graduated bronze & stone Clepsydra vessel with a floating brass level rod (Context 68%).	When an agent reads a file, parchment scrolls unroll under the warm brass lamp and stack into the Clepsydra basin, raising the brass fill-level indicator.
4	Waterwheel Trip-Hammer Forge & Aqueduct Sluice-Dam (Cataracta)	Compiler, Typechecker, Linter, or Bundler (rustc, tsc, pytest, go build)	Waterwheel-driven bronze trip-hammer and carved stone caliper gauge arch straddling a timber roller-way, paired with a heavy iron-and-oak aqueduct sluice-dam.	Pass: Stone tablets pass smoothly through the caliper arch and receive a clean emerald laurel seal. Fail (errors > 0): The tablet cracks under the hammer with glowing red forge embers & smoke, and the Sluice-Dam slams down, cutting off water to downstream modules (BLAST RADIUS BLOCKED).
5	Ballista Target Parapet & Pivoting Bronze Shields (Signa)	Unit, Integration, E2E & Benchmark Suites (tests/, e2e/, *.spec.ts)	Stone proving-yard parapet lined with a row of pivoting Roman bronze shields / wooden target shutters.	As tests run down the line, passing shields flip to display Green Laurel Wreaths (PASS), while any failing test splinters upright with a Lit Crimson Warning Brazier (FAIL).
6	Cutaway Vaulted Granary (Horreum) & Scroll Rotunda (Tabularium)	Databases, Schemas, Vector Search, Caches & State Stores (db, sql, schema, search, store)	Cutaway stone vaulted warehouse & circular tiered archive revealing stacked terracotta amphorae, numbered scroll niches, and a rotating wooden ladder crane.	When a database query or RAG search runs, the wooden picker ladder rotates around the circular tiers to extract amphora/scroll records.
7	Architect’s Mosaic Drafting Table (UI) & Harbor Sea-Gate (API/CLI)	Frontend UI (web-ui, .tsx, .vue, .css) & API/CLI Endpoints (api, routes, cli, cmd)	UI: Angled wooden Roman architect’s drafting table (Abacus) framed in brass where colored mosaic tesserae & parchment panels form a recognizable window/card wireframe. API/CLI: Twin-arch stone harbor toll-gate with bronze intake wheels.	UI edits: Mosaic/parchment wireframe panels visibly rearrange on the tilted architect’s table. API/CLI: Courier ships and messengers pass through the harbor toll-arches.
8	Iron Portcullis Toll-Gate (Needs You) & Stone Milestone Track (Milliarium)	Human-in-the-Loop Approvals/Doubt Gates & refs/vox/checkpoints/ Git Snapshots	Approval Gate: Stone archway with a lowered wrought-iron portcullis grate & wooden counterweight lever. Checkpoints: Paved Roman road lined with numbered carved stone milestones (I, II, III) & wax-sealed scroll chests.	Blocked Agent: The Roman courier/legionary halts with a lit torch in front of the iron portcullis until you pull [✓ RAISE PORTCULLIS] or [✕ HOLD]. Restore Checkpoint: Clicking Milestone I/II/III rolls the wheeled archive carriage back to that stone marker.