institution/ROADMAP.md

# The Institution suite — master roadmap

A set of RimWorld mods about **what an institution does to the people inside it** — and the crime,
policing, and justice that put them there. Each mod is a separate install on a shared **Core**;
together they form one system.

> **Status (2026-07-15): shipped as a five-layer suite behind one install.** The monolith split into
> **Core** (propensity, criminal record, secured context, the shared treatment engine), **Contraband**
> (the physical smuggling loop), **Justice** (classification, deterrence, discipline, parole, regime,
> and **policing** — colony crime → a weighed arrest), **Gangs** (contraband economies), and **Ward**
> (psychiatric care), folded in from a former standalone sister mod. All five bundle into the single
> **Institution** mod with a toggle each while staying separate repos; **Foul Play** stands alone and
> bridges in. See the [README](README.md) for the current mod table.
>
> The pre-arrest loop (crime → witnesses → investigate → weighed arrest) and the post-arrest
> corrections arc (rehabilitate → parole, discipline-as-order, classification enforcement, on the
> shared treatment engine) are **wired and harness-verified**. What remains is **Regime depth**
> (schedule / needs / visitation), **ideology-flavoured** release, and — above all — real
> **playtesting** to tune the numbers, none of which are play-tested yet. The design sections below
> predate the split in how they *group* modules, but the mechanics and north star are unchanged.

## North star

> **Every pawn has a criminal propensity on a spectrum — nature (traits) × nurture (circumstance,
> mood, treatment) — and the colony can police it.**

The same seeded disposition engine that drives the piss spree (`WouldFoulPeople` = disposition ×
circumstance, fixed per pawn), generalized. The suite is the two halves of that:

- **Pre-arrest** — colonists commit crimes on a spectrum; a policing layer discovers, investigates,
  and catches them. Arrest is the hinge.
- **Post-arrest** — prison, contraband, improvised weapons, escape, wards, secure areas, the daily
  life of the held, and the path back out (parole / discharge / manumission).

## The load-bearing principle: SECURED CONTEXT, not "prisoner"

Nothing hard-codes "prisoner." The subject of every held-person system is a **secured context** —
a pawn held in a controlled space, subject to search, following a regime:

| Context | Members | Authority | Release path |
|---|---|---|---|
| Prison | prisoners | warden | **parole** |
| Psych ward (Ward mod) | committed patients | orderly / warden | **discharge** (when treated) |
| Slavery (Ideology) | slaves | overseer | **manumission** (Ideology) |
| Secure area | anyone inside a zone | assigned guard | leave the zone |

A committed patient rides the vanilla prisoner rail (Ward's `Ward_PsychiatricCare` mode), so
contraband, search, schedule, needs, and visitation **already apply to ward patients for free** —
and to slaves via a small Ideology-gated extension. Every system below reads
`SecuredContextOf(pawn)`, never `IsPrisonerOfColony` directly. Build prisoner-first, against the
predicate, and ward + slave + secure-area fall out without a rewrite.

Design tone: **standards are low on the rim.** Needs and expectations for the held are modest — a
prisoner does not expect a spa. Don't over-model comfort; a little goes a long way.

---

## System wiring — the four connections that make it a system, not a pipeline

A full-lifecycle audit (propensity → crime → policing → prison → release → back) found the gaps
are not missing *features* — they are missing *connections*. Without these four, the suite is a
linear pipeline of modules; with them, it is a living system. Build them as first-class, not
afterthoughts.

- **A. A shared substrate (build FIRST).** One implementation, in Contraband (the central
  framework), that every module reads and writes: a **propensity** stat (nature × nurture, the
  `Disposition` engine generalized). **Cross-mod merge shipped 2026-07-15:** Foul Play answers "how
  disposed is this pawn" through a `Disposition.Source` seam that defaults to its own light read; when
  Contraband is present, the bridge repoints it at Contraband's full nature×nurture, so the two mods
  never disagree about the same person (harness: `FPBRIDGE propensity.merged = True`). This is the
  substrate principle applied ACROSS mods, not just within one. Also the **`SecuredContextOf(pawn)`** predicate
  (prisoner/ward/slave/zone), and a per-pawn **`CriminalRecord`** (crimes committed, escapes,
  contraband made, reform progress). Without this, each module reinvents "how criminal is this
  pawn" and they disagree — the crime system thinks a pawn is dangerous while classification
  thinks they are docile. Everything downstream keys off the substrate.

- **B. Crime has real effects.** Theft actually removes the goods; assault actually injures;
  sabotage actually damages the building; targets are chosen via vanilla relationships. Without
  real, detectable harm, crime is a flag with nothing for an investigation to find (no missing
  goods = no evidence).

- **C. Deterrence feedback closes the loop.** Catching and punishing crime feeds back into the
  propensity engine: **visible justice deters** (others' propensity drops), **unpunished crime
  spreads** (propensity rises when it pays), **visible cruelty radicalizes** (over-harsh
  punishment breeds resentment → more crime). This is what makes policing *govern* rather than
  merely clean up, and it is the connection that turns the pipeline into a cycle.

- **D. Reintegration.** A caught → imprisoned → reformed → released colonist carries their record
  back: distrust from those they wronged, or a genuine clean slate if truly reformed
  (ideology-flavoured). Closes the colonist-crime cycle instead of leaving it dangling.

A/B/C are load-bearing; D rounds it out. These are the *wiring*; everything in the module table
below is the *features* that hang off it.

**Design constraint (2026-07-15): defer the depth, never the payoff.** The propensity → contraband
→ detection → record *spine* is entirely ours and is self-complete without any third-party mod — it
is what the suite is *about*, and deferring PR's prisoner-behaviour sims (recidivism, riot,
solitary-toll, institutionalization, mood-contagion) leaves no hole in it, because none of those sit
*on* that spine. The one place the deferral could ring hollow solo is the RESPONSE side: Discipline
and Parole. So each response action must carry its **own minimal self-complete effect** — parole
gives an immediate faction-goodwill / relationship nudge; discipline revokes privileges with a
modest mood/record consequence — rather than borrowing PR's deeper toll. That is *not* a rebuild of
PR (no returning raiders, no 3-tier solitary): it is our own decision having an immediate payoff,
which PR then *enriches* when present. The test of a healthy deferral: with PR absent the loop still
*closes* (the decision has an effect); with PR present the effect gets *deeper*, never doubled.

## Suite modules

| Layer (repo) | Scope | Status |
|---|---|---|
| **Core** | propensity, criminal record, secured context, the shared treatment engine, the deterrence seam | **shipped** |
| **Contraband** | conceal / improvise / search / confiscate / intake / escape / secure-areas / corruption | **shipped** |
| **Justice** | policing (crime → witnesses → investigate → weighed arrest), classification, deterrence feedback, discipline, parole, rehabilitation, regime | **shipped** |
| **Gangs** | prisoner & colony gangs, rivalries, contraband networks | **shipped** |
| **Ward** | involuntary psychiatric care — the third pawn state, on Core's treatment engine | **shipped** (folded in) |
| **Foul Play** | throw a container of something off a body; vessels + substances + Piss Nuke flagship | **shipped** (standalone, bridges in) |

The seven-mod plan became **five layers over Core**: **Regime** and **Discipline** folded into
**Justice** rather than minting separate mods. Discipline-as-order, classification enforcement (grade
readout, a dangerous-prisoner alert, and **wing-routing** — a wall-mounted security marker grades a
whole cell block and flags a prisoner held in a wing too weak for them), cell safety,
ideology-flavoured parole, visitation, and the **Yard/Lockup schedule** (via Prison Labor's prisoner
timetable — read, never fought) all ship. **The roadmap's feature list is complete.** What remains is
not features but **playtesting** — none of the suite is tuned by real play, and that is the single
largest thing between here and a good release.

---

## Regime — daily life of the held

### Schedule (use vanilla, don't reinvent)

RimWorld already has `Pawn_TimetableTracker` + `TimeAssignmentDef` and the Restrict tab. **Extend
that to secured pawns** rather than building a new regime UI. Prison Labor (`1899474310`, 176k)
already puts force-to-work prisoners in the Restrict grid — build on that pattern, don't fight it.

- Give secured pawns a timetable; surface it in the Restrict tab.
- Two new `TimeAssignmentDef`s cover the prison-specific blocks vanilla lacks: **Yard** (go to a
  designated yard/commons — ties to Prison Commons) and **Lockup** (confined to cell). Eat/Sleep/
  Work/Joy map to existing assignments.
- A think-tree branch makes secured pawns honour their timetable (they already have a prisoner
  think-tree branch to hook).
- Ward routine and slave work-schedule are the same machinery, different default timetables.

### Needs (modest — standards are low)

Do NOT build a full Prison Architect needs sim. One or two low-stakes needs, keyed to the schedule:

- **Yard / open air** — satisfied by the Yard block. Vanilla already has the Outdoors need; check
  whether it applies to secured pawns and lean on it before adding one.
- **Safety** — a modest mood factor from feeling safe (few violent cellmates, guards present).
- Recreation is already covered by Prisoner Recreation (`815726158`) — don't rebuild.

Keep the magnitudes small. A satisfied schedule = a quiet wing; neglect = the disposition engine
tips more pawns over the edge (feeding contraband, breaks, gang recruitment).

### Visitation

Off-map visitors and related pawns visit the held. A genuine greenfield gap — Hospitality is
guests only and never touches prisons.

- A **visitation room** role; scheduled visiting hours (a schedule block).
- A prisoner/patient with family or faction ties gets visits; the warden/orderly supervises.
- Feeds a modest Family/social mood boost. **Thematically strongest for the ward** — a committed
  patient's family visiting is exactly right — and it is a supply route for contraband (a visitor
  smuggles something in → Contraband's conceal system).

---

## Justice — the crime loop (the missing middle)

The heart. Without discovery + investigation, "crime" is just a random bad event, not something you
police. The loop:

**commit → discover → investigate → attribute → arrest → (held) → release**

- **Commit.** A colonist acts on their propensity (nature: traits incl. VTE `2296404655` 646k
  kleptomaniac/pyromaniac — *integrate as inputs, don't rebuild*; nurture: our stat). Crimes:
  theft, contraband possession, sabotage, arson, assault, at the serious end murder.
- **Discover.** The colony learns a crime happened: missing goods, a body, damage, filth, or a
  **witness**. Discovery is not automatic — a crime in an unwatched place may go unnoticed.
- **Witnesses / informants.** A colonist near the act may witness it → report, be intimidated
  into silence, or inform for favour. The cheap, characterful detection layer.
- **Investigate.** A policing officer works the scene: evidence, opportunity, the stolen goods in
  someone's concealed stash (ties to Contraband search!), narrowing suspects.
- **Attribute.** Evidence points to a pawn. Confidence, not certainty — wrongful accusation is a
  possible, dramatic failure.
- **Arrest.** Vanilla's one law verb. The hinge into the held systems.

### Policing officer

Guarding is owned (Guards For Me `1855885448`, 88k — patrol/bodyguard, external threats only), the
*catching* is not. Build the officer who investigates and arrests criminal colonists; **lean on
Guards For Me's guard role** where present rather than reinventing patrol.

### Parole / discharge / manumission — release, driven by IDEOLOGY

The payoff that makes Ward's treatment and good behaviour *mean* something. Release is not a flat
timer — the colony's **Ideology precepts** decide the policy (`MayRequire` Ideology; a vanilla
fallback for non-Ideology games):

- A harsh / execution-favouring ideoligion rarely paroles (executes or works-to-death instead).
- A rehabilitative / lenient ideoligion paroles readily on reform + good behaviour.
- **Parole** (prisoner), **discharge** (ward patient, when treated — the Ward analog),
  **manumission** (slave, Ideology's own freeing) are one mechanism with three faces.
- A released, reformed pawn has **reduced recidivism** — integrate with Prisoner Realism's
  recidivism (`3760196312`) rather than duplicate it: our reform lowers its return chance.

Sentencing timers exist (Prisoner Sentencing `3736998871`) — defer to it; add only the
ideology-driven *decision*, not another timer.

---

## Discipline — control

- **Classification / segregation — make the wings players already build MEAN something.**
  Players already hand-build min / medium / max / solitary blocks with zones, cells and locks.
  RimWorld just has no notion of *who belongs where* or *whether they are correctly placed*. We do
  not replace the building — we add the intelligence layer on top of it, and it becomes the
  **router** that connects the whole suite:

  - **Grade (information).** Each secured pawn gets a risk grade computed from disposition × traits
    × history (escape attempts, contraband made, guards attacked, murder on record). The player
    stops guessing who is dangerous — the game tells them "this one is max."
  - **Assignment + misplacement flag (enforcement).** Tag a wing's grade; the system routes
    prisoners to the matching wing and **warns** when a max-grade pawn sits in a min cell. Vanilla
    gives zero feedback here today.
  - **Dynamic re-classification (dynamics).** Grade moves with behaviour: an escape attempt or a
    shanking **upgrades** them; Ward treatment + good conduct + time **downgrades** them. This
    wires classification straight into the behaviour loop.
  - **Grade gates the other systems (the payoff).** Grade drives search frequency (Contraband —
    max = frisked often), privileges (Regime — yard/visitation/recreation restricted by grade),
    escape risk (a dangerous pawn in a weak cell escapes more), and reform eligibility (Justice).
  - **The tension that makes it a decision.** Over-classify (everyone in max/solitary) = safe but
    mood craters, reform fails, ideology frowns on cruelty, and warden-hours explode.
    Under-classify (everyone min) = cheap and happy but they walk out. Classifying *correctly* is
    the game; we supply the information and the consequences that make it one.

  No mod auto-classifies (manual wing-building is emergent player behaviour, not a mod), so the
  *system* is an uncontested gap even though the physical tiers are common.
- **Punishment as a player order.** Issue solitary / lockdown / privilege-revocation as a
  discipline *action*. Distinct from Prisoner Realism's *passive* solitary toll — we add the
  order and its interface; defer the mood consequence to Realism where present.
- **Warden personality & corruption (expanded 2026-07-15).** A search is only as thorough as the
  warden running it. Diligence is a function of the warden's **personality** (traits: a Kind or Lazy
  warden frisks gently; an Abrasive or dutiful one turns the cell over) and **circumstance** (mood,
  their relationship to the prisoner, how run-down the prison is). Three faces of the same
  guard-integrity axis, all reading the same warden→prisoner state:
  - **Search intensity.** Personality + circumstance scale find-chance and how often a warden bothers
    — the lax warden misses what the hard-ass finds. (Extends `WorkGiver_Warden_Search` +
    `JobDriver_SearchPawn`'s find roll, which already take Social skill; add the warden's disposition.)
  - **Forgiveness.** A warden may *deliberately overlook* certain items — a sympathetic guard ignores
    a prisoner's smokeleaf, a jar of hooch, a family photo. Per-warden tolerance, per-item, so the
    same contraband survives one guard and not another.
  - **Bent wardens smuggle IN.** A corrupt/bribed/romantically-entangled warden becomes a **supply
    route** — they hand contraband TO a prisoner (the `Conceal` door already noted in Contraband as
    "a bent warden"). This is the corruption payoff and the thing that feeds a Gang's network.
  - **Secure zones are the counter-play.** A search-zone checkpoint frisks *anyone* passing through,
    **guards included** — so a bent warden carrying contraband in can be caught at the door. This
    wires corruption ↔ secure zones (the generalized secure-area search) ↔ the search loop: the same
    `JobDriver_SearchPawn` that turns over a prisoner turns over a guard at a checkpoint.

  Self-complete (reads vanilla traits/mood/relationships); no dependency. This is where the
  contraband loop stops being "the game vs. the player" and becomes "the player's own guards, who
  each have their own angle."

---

## Gangs — as contraband economies (NOT mood)

Re-scoped 2026-07-15: Prisoner Realism's **Ringleader** already owns mood contagion from a dominant
prisoner, and it is good — so we do not touch mood. Our gap is the **contraband network**: prisoners
(and colonists) form factions that *move contraband* — a supply chain with a supplier, runners, and a
tax, where segregating rivals (Classification) starves a network and a bent warden (Corruption) feeds
one. Ties to disposition (who joins), contraband (what they move, the one system PR has nothing like),
and classification (segregate rivals). The richest, latest module — build after the loop works.

---

## Build order (fills the meta-gap: don't build it all at once)

1. **The crime loop core** — discover + witnesses + investigate + attribute, applied to **free
   colonists** (the uncontested gap: vanilla+PR already handle prisoner arrest). Without it the whole
   crime thesis is inert. Build *before* individual crime types.
2. **Regime** — schedule (vanilla Restrict) + one or two modest needs. Cheap, high-value, and it
   feeds the disposition engine (neglect → crime).
3. **Visitation** — greenfield, thematically strong for the ward, doubles as a contraband route.
4. **Parole / discharge / manumission** — the *release decision*, ideology-driven, PLUS its
   substrate-native payoffs: **prisonization** (the regime reshapes propensity over the sentence) and
   **reintegrated-reoffending** (a parolee who joins the colony carries their record and may reoffend).
   PR's departed-raider return layers on top when present. Gives Ward and good behaviour a real payoff.
5. **Classification** (a router that reads the record + propensity and assigns a tier), then
   **punishment-orders**, then **corruption**.
6. **Gangs** as contraband economies — last; needs the rest in place.

Deferred to Prisoner Realism on 2026-07-15 (it owns them, and it is good), as MECHANICS we do not
rebuild: the isolation toll, mood-contagion gangs, and the departed-prisoner return. We still own the
substrate-native, differently-axised versions of institutionalization (prisonization) and recidivism
(reintegrated-reoffending) — the namesake themes — because only our propensity/record engine can.

Already in flight (Contraband/Foul Play): hooch, improvised weapons, fire-starter, escape tools,
intake search, secure areas. See [Contraband ROADMAP](https://git.onetick.ninja/flan/rimworld-contraband).

Intake shipped **Harmony-free** (2026-07-15): rather than the planned patch on the contested
`SetGuestStatus`, it polls from the MapComponent tick that already visits every held pawn — a pawn
not yet processed is one newly in custody. Keeps Contraband's zero-Harmony core intact and steers
clear of the method Hospitality/Prison Labor already stack three patches on.

### Foul Play — substance system, expanded (2026-07-15)

The chosen "finish substances" work grew into a full **substance-cocktail** system. Three parts,
built on the existing `SubstanceDef` (data) + `CompVessel` (delivery) + `CompFerment` split:

- **Hooch.** A fermentable substance whose harm is **incendiary** — set its `damageDef` to a flame
  def and the framework's own `GenExplosion` splash starts fires (a Molotov), no splash-code change.
  Fermentation makes a *ripe* (high-alcohol) hooch a stronger firebomb — the harm-vs-time axis, but
  running the other way. Also **drinkable** as alcohol (share vanilla `Chemical_Alcohol` if cheap).
- **Ferment in any liquid-holding furniture, not just toilets.** Generalise to a capability: a
  fermentation SITE is any *building that can hold liquid* — a DBH toilet/tub/sink, a vanilla
  `FermentingBarrel`, a modded vat. Detected by recognizable identity (defName/label vocabulary:
  toilet, barrel, tub, sink, tank, vat, trough, cistern, latrine, urinal, basin) + known vanilla
  defs, **dependency-free**. Hooch *requires* a site (pruno needs a vessel); piss can *use* one for a
  bigger/faster batch but still brews from the body. Fits Foul Play's standing "works with all
  containers" rule.
- **Mixing — combine any substances.** A vessel's contents become a **blend** of `SubstanceDef`s
  (piss + feces + semen + …), and `SubstanceSplash` applies each one's effects together — caustic +
  disease + humiliation in one throw. "Mix everything": the blend is a runtime list on the vessel,
  defaulting to the def's single substance when unmixed, so every existing vessel still works.

**Universality principle (2026-07-15): Foul Play is for EVERY pawn; Contraband is the prison lens.**
Filling a vessel, fermenting it, throwing it, drinking it, and addicting to it are behaviours of *any*
pawn — colonist, prisoner, slave, raider, visitor — gated by **disposition (propensity)**, never by
prisoner status. "Not just prisoners fill vessels; any pawn can and will." That is the propensity
engine (already universal) driving substance behaviour, and it is the mechanics-level expression of
the whole thesis: every pawn on a spectrum. The prisoner-only concept is **concealment/search**, which
is Contraband's held-pawn overlay: a prisoner *hides* the vessel they filled as a secret; a free
colonist just has it. So the prisoner gate lives ONLY on the conceal path (`AcquireWorker`), never on
the fill/ferment/throw/drink behaviours. A universal "a disposed pawn fills a vessel" job is its own
piece, separate from the contraband brew that hides the result.

**Reframed 2026-07-15 (user directive): vessels are GENERIC, contents are RUNTIME.** Hooch is not a
bespoke item — it 1:1 models piss *except it is flammable*. A vessel is a generic container; what is in
it (piss, hooch, feces, a blend) is instance state that can be **filled, fermented, poured between
vessels, drunk, and mixed**. So there is no `FP_Weapon_Hooch`; there is `FP_Hooch` (a substance with a
`Flame` damageDef) and a `CompVessel` whose `substance` is now runtime. Any fluid is **drinkable with
different consequences** — a substance carries a *drink outcome* (hooch → alcohol, piss → sickness,
feces → disease) alongside its *throw* outcome. Staged, each green, piss harness guarding throughout:
  1. **Runtime substance on `CompVessel`** — instance field (default = def's substance), scribed;
     throw/splash/label read it. Vessels become substance-agnostic. (Def names kept to avoid a
     breaking rename; label shows contents at runtime — "jar of hooch".)
  2. **Drink any fluid, with different consequences** — `SubstanceDef.drinkOutcome`; vessels
     ingestible, applying the current substance's consequence (hooch → alcohol high, piss → sickness,
     feces → gut rot, **blood** → nutrition + a disturbing thought / possible disease). Every fluid is
     a valid drink, just a worse or better idea. **Blood is a substance too** — a liquid like any
     other, drinkable and throwable. And **any drink can breed addiction like a drug**: each
     `SubstanceDef` carries an addiction *rarity* (hooch common, most fluids extremely rare), and the
     per-drink roll is modified by mental health + circumstances (a despairing, mistreated pawn
     addicts to things a content one never would) — same nature×nurture spine as propensity.
  3. **Contraband content tag** — a concealed vessel carries a generic content tag (Contraband stays
     ignorant of `SubstanceDef`; the bridge interprets it), so "a hidden jar of hooch" redeems correctly.
  4. **Pour between vessels + mixing** — a blend is a weighted amount-table; splash and drink apply
     every constituent scaled by its share. **Container physics (user spec, 2026-07-15):** vessels
     have a **capacity**; you can only mix into one with **headroom**, and a pour takes only up to
     that (a 50%-full jar of piss + cum poured in = 50/50, filled and no more). `CompVessel.Pour`
     moves liquid between carryable vessels in their current ratios, the destination reacting. STILL
     TO BUILD (the next layer): **furniture containers hold liquid too** (a DBH toilet, a barrel of
     wort) — but a fixed fixture cannot be *tipped*, so you **dip** a small vessel into it (fill the
     carryable from the fixture) rather than pour it out; and **the one pawn action is pouring** —
     a pawn-driven pour/dip job (uses the `Pour` primitive), which is what makes mixing happen in the
     world instead of only in code. This subsumes "ferment in a toilet": a fixture is just a big
     container you dip into.
  5. **Fermentation-model overhaul** — age + top-up dilution + sealed/open + temperature (mirror
     `CompRottable`) + spoil threshold; applies to every vessel, piss included. **[SHIPPED]**

**Potency model (corrected 2026-07-15): age + storage, NOT container size.** A liquid's potency is a
function of how long it has fermented and how it is stored (a *sealed* vessel ripens and holds; an
*open* one ferments differently and loses to evaporation) — never of how big the container is. Size
already only drives fill-time and blast (VesselProfile), so `CompFerment.Potency` stays age-driven;
the correction is that **topping up dilutes age**. A shared bucket/carboy that several prisoners keep
using stays *fresh* (each fresh addition pulls the volume-weighted average age down), while a jar one
prisoner fills once and hides *ages to full potency*. So "a jar of old piss and a bucket of fresh"
both make sense — it is the usage pattern, not the vessel, that decides. Implementation: track age as
a volume-weighted average, diluted on each add; sealed/open scales the ripen rate.

**Temperature + spoilage (2026-07-15): mirror vanilla food rot.** Fermentation is temperature-driven,
exactly like meat — warm speeds it, a freezer nearly halts it, and past a point it **spoils** (goes
from potent to ruined/maximally foul). Rather than invent this, reuse the vanilla mechanic:
`CompRottable` already tracks temperature-weighted rot progress for food. The ferment model should
lean on that same curve (or `GenTemperature`-driven accumulation) so "spoils like meat" is literally
the meat code path — a prisoner's stash left in a hot cell turns fast, one in a cold one keeps. This
makes the whole substance model a **fermentation-model overhaul** of `CompFerment` (age + dilution +
sealed/open + temperature + spoil threshold), sequenced AFTER the hooch item ships, since it applies
to every vessel — piss included — not just hooch.

## Compatibility — the non-negotiable

The suite must load and run cleanly alongside the **all-time most-subscribed Workshop mods**, not
just prison-adjacent ones — that is the load order most players actually run. The harness
(`Tools/run-compat-test.sh` in the Ward repo) boots a real headless RimWorld with the suite plus
this stack loaded at once and fails on any error naming our code.

Baseline stack (all 1.6, verified subs):

- **Frameworks:** Harmony (3.2M) · HugsLib (2.5M) · Vanilla Expanded Framework (2.0M) · Humanoid
  Alien Races (1.1M).
- **Ubiquitous gameplay/AI:** Pick Up And Haul (1.7M) · Common Sense (1.05M) · Simple Sidearms
  (954k) · Vanilla Furniture Expanded (1.08M) · EdB Prepare Carefully (1.67M).
- **UI (load-order neighbours):** RimHUD (1.5M) · Allow Tool (1.36M) · Interaction Bubbles (1.15M)
  · Camera+ (997k).
- **Weapon/our-domain risk:** Vanilla Weapons Expanded (985k) · VFE Furniture Security (865k) ·
  Vanilla Brewing Expanded (589k) · Hospitality (798k).
- **Prison-adjacent (design overlap):** Prison Labor · Prison Commons · Locks · Restraints ·
  Custom Prisoner Interactions · Prisoner Realism · Prisoner Recreation · Dubs Bad Hygiene ·
  Psychology · Rim Disorders · More Mental Breaks.

**Combat Extended** (387k, 1.6) gets its OWN dedicated pass, not the mixed stack: it overhauls
verbs, projectiles, damage and armour — exactly our thrown-weapon surface — so an ambiguous
failure in a 25-mod stack would be useless. Loading-clean-under-CE is a must-have; a tuned CE
armour-penetration patch (`MayRequire`) is a strongly-recommended follow-up, not a release blocker.

How the suite earns this: zero-Harmony cores, Contraband optional via a `LoadFolders` bridge, every
DLC/mod tie-in `MayRequire`-gated, and new content registered by capability (`IsWeapon`, `IsDrug`,
category) rather than hard-coded lists — so modded weapons, drugs and races are covered without
being named.

## Self-complete, dependency-free — the standing rule

Two rules, and the second is the sharper one:

1. **Judge by QUALITY, not sub count. If an incumbent is actually good, keep it.** A genuinely
   good mod — even a small one — is worth coexisting with rather than rebuilding: don't waste
   effort duplicating something done well (Prisoner Realism at 11k is a *good* deep sim → keep
   it). Only build our own where the incumbent is **thin, absent, or mediocre** on one of our
   crucial loops (Prisoner Recreation just flips vanilla Joy → trivially ours; the 334-sub crime
   mod is niche → the slot is open). Sub count is a hint, not the test.

2. **No hard dependencies. Every crucial loop is self-complete.** The suite must be a whole,
   working system on its own. Third-party mods are **coexistence targets that ENHANCE**, never
   requirements. Where we integrate (Ideology precepts, Prisoner Realism's recidivism, Prison
   Labor's regime), it is always `MayRequire`-soft: the feature lights up if the mod is present
   and the loop still closes without it.

What this changes vs. a naive "defer to whoever got there first":

- **Recreation is ours to enable.** Prisoner Recreation (38k) and Prisoner Realism (11k) ship no
  custom need — they just flip on the *vanilla Joy need* for prisoners. We do the same in our
  needs system: idempotent, coexists, zero dependency, no citing.
- **Recidivism → split by population, don't defer wholesale.** (Revised twice: first "build modest",
  then "defer entirely", now corrected — see the namesake correction in the deep scan below.) PR's
  Recidivism handles the pawns who **leave** (released/escaped → return ally-or-raider by treatment);
  that is good and we do not rebuild it. We own the **mirror**: the paroled pawn who **stays**, joins
  the colony, and can reoffend inside it (their `CriminalRecord` + residual propensity → wiring gap D).
  Different population, no overlap. The release *decision* stays self-complete (ideology-driven);
  the *reintegrated-reoffending* is ours; the *departed-return* is PR's.
- **Solitary / isolation toll → DEFER to Prisoner Realism.** PR's Solitary is a full 3-tier
  deterioration hediff with a Ringleader counterplay. Our Classification module does NOT
  reimplement the toll; it is a **router** — it reads the shared record + propensity and *assigns*
  the security tier (including whether to isolate). PR (or vanilla) then supplies the consequence of
  that assignment. Routing is the gap; the isolation sim is not.
- **Escape** is self-complete: vanilla mental-break breaks + our disposition-driven arming + our
  **contraband-tool wall-cut**, which is scoped precisely to the pawns PR's break system does NOT
  move — chiefly ward patients (never "mood prisoners") and pawns too low-skill to pick a lock. PR
  owns the skilled-lockpick-a-DOOR-during-a-break path; we own the slow-file-through-a-WALL path for
  the calmly-committed. Complementary, not overlapping.

Genuinely leave alone (giant + redundant + not a gap in our loops): forced labor (Prison Labor
176k), hygiene (Dubs Bad Hygiene 632k), crime *traits* (Vanilla Traits Expanded 646k — we consume
them as nature inputs), guest hosting (Hospitality 798k). Coexist with all; depend on none.

### Prisoner Realism deep scan (2026-07-15) — the big incumbent, mapped feature-by-feature

Prisoner Realism (Steam `3760196312`, **11,286 subs / 1,090 favs / 5-star**, published 2026-07-07)
is the one incumbent large enough to reshape our roadmap. It is a *good* mod (clean documented C#,
multi-factor balance, defers to other mods where they overlap), so the standing rule says keep it
and cut our overlaps. Its 20 features and our verdicts:

| PR feature | What it does | Institution verdict |
|---|---|---|
| PrisonBreak rework | MTB scaled by mood/relation/captor/strength | Defer. Our arming rides vanilla/PR breaks. |
| No-mining / melee breakout | strips sapper-dig; escapees bash doors | Defer. Our wall-cut is a *tool* route, additive. |
| Keys / Lockpick | skilled prisoner picks a DOOR, fast, no item | Defer. We own file-through-a-WALL for non-break pawns. |
| Recidivism | released/escaped return ally-or-raider by treatment | Defer PR's mechanic; own the MIRROR — the reintegrated who STAY and reoffend (see below). |
| Institutionalized | expectation/mood decay + reintegration struggle | Defer the mood axis; own the PROPENSITY axis — prisonization (see below). |
| Solitary | 3-tier isolation deterioration | Defer the toll; Classification only *routes* to it. |
| Ringleader | mood contagion from dominant prisoner | Defer. Re-scopes our Gangs to contraband-networks. |
| Riot | securely-caged-but-miserable → lash out | Defer. |
| ArrestGrace / ArrestHere | in-place arrest, no immediate bolt | Defer. Our intake (keep-inventory + search) coexists. |
| Recreation | flips on vanilla Joy for prisoners | We enable the same idempotently (no citing). |
| Surrender, ForceFeed, RecruitOffer, Despair, Turrets, Cleaning, Carry, BedOwner, Surgery, Commons, AssistedBreak | assorted prisoner-behavior sims | Defer all; coexist. |

Net effect: **two modules re-scoped** (Classification → pure router; Gangs → contraband economy, not
mood) and the reintegration module **re-founded on our substrate** (see next). What remains is
Institution's uncontested core: hidden-contraband + search, propensity across *all* pawns, Ward, Foul
Play, classification-as-router, and the standout nobody touches — **policing free colonists**.

#### Namesake correction (2026-07-15): institutionalization & recidivism ARE ours — on a different axis

"Defer entirely" was an over-correction: in a suite named **Institution**, these are the namesake, and
our substrate lets us build them on an axis PR structurally cannot, so it is complementary, not a
rebuild. The rule: **don't duplicate PR's mechanic; own the substrate-native version only we can.**

- **Institutionalization → prisonization, and it is NOT a new system (2026-07-15).** The lean form:
  `Propensity.Nurture` *already* raises criminal disposition for a badly-kept held pawn, dynamically.
  The only thing incarceration adds is PERMANENCE — an effect that outlasts the sentence — and we
  already have the field for it: `CriminalRecord.reform` (signed: harsh regime → negative/prisonized →
  propensity up; rehabilitative → positive/reformed → propensity down). So prisonization = have the
  EXISTING Nurture read that ONE existing field, which Discipline/Parole write. No parallel mechanic,
  no new stat. And we do **not** patch PR's institutionalization (that would make us depend on a
  one-week-old, fast-moving mod): when PR is present we *soft-read* its hediff as one more Nurture
  input (`MayRequire`, reflective, no patch) — the same additive-not-override posture as the tunnel.
- **Recidivism → the reintegrated who STAY (not the departed who leave).** PR returns released/escaped
  pawns as allies-or-raiders. We own the mirror population: a paroled pawn who *joins the colony*
  carries their `CriminalRecord` + residual propensity and can **reoffend inside your own walls** —
  wiring gap D, closing the colonist-crime cycle. PR handles who left; we handle who stayed. No overlap.

These two are also the **self-complete payoffs** for Discipline and Parole (per the "defer the depth,
never the payoff" constraint above): the regime you run visibly reshapes people, and a badly-reformed
parolee bites you later — both work with PR absent, and PR's departed-raider return deepens it when present.

### Prior-art sweeps done (2026-07-14/15)

Uncontested gaps, safe to build clean: contraband/search, improvised weapons, keep-inventory
intake, secure-area search, nurture criminality stat, investigating officer, patient escape,
visitation, classification, punishment-order, gangs, corruption. Partial (build the uncovered
slice only): prisoner timetable, yard/safety/privacy needs, evidence/forensics investigation,
active snitch/informant, reform-and-ideology-driven parole. The only prior art in the
crime/parole space (Rimworld Law and Order, 334 subs) fails the *popular* bar, so that slot is
open — build it without duplicating that niche mod exactly.

## Architecture already honors rule 2

Zero hard dependencies anywhere: Foul Play stands alone, Contraband is optional to it (the
`LoadFolders` bridge loads only when both are present), Ward stands alone, and every DLC/mod
tie-in is `MayRequire`. No suite mod requires another suite mod or any third-party mod.

## AI disclosure

Designed and built with substantial assistance from Claude (Anthropic).