Fix repayments that overcharged, and act on the first Frontier playtest

A debt repayment took its whole instalment even when less was owed: four
dollars owed at the store cost twenty. Content could not express "pay what is
owed", so an add effect's amount may now be read from state, with a cap. Five
repayments across both packs use it, and a conformance test holds every pack to
it. The turn record now says which options were hidden, so the analyser stops
counting doors nobody saw, and it reads only feedback logs.

From the same session: wages are labelled as wages, a clamped change says where
it stopped, two unreadable option labels are rewritten, the sale barn no longer
offers what the player already owns, Ward hints at what the promotion waits for,
and the office has five more events. DECISIONS #38-40.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6UDQ9o6L6Ey173U7XVou6

docs/DECISIONS.md

@@ -656,3 +656,112 @@ promoted is not independent of how they spend, so the comparison mostly measured
 the mix. It inverted the moment there was something to spend money on. It is now
 derived from upkeep arithmetic, and the lifestyle's effect is tested with two
 players who differ in exactly one habit.
+
+## 38. A repayment pays what is owed, never more
+
+Recorded 2026-09-15, for 0.3.4. Designer's call: a small engine addition rather
+than a content workaround.
+
+The first human session of the Frontier on a current build — 112 turns — owed the
+store four dollars on turn 27 and chose "Put money against the book". It took
+twenty dollars and cleared four: the option was a flat `money -20, owed -20`, and
+`owed` clamped at zero while `money` did not. The ledger showed "−$4 at its
+limit", which the player read, reasonably, as a debt still standing.
+
+The same shape was in five options across both packs — the Frontier's store and
+both of its hard-times repayments, and both of Corporate Ladder's loan
+repayments — and none had been caught, because every archetype that pays debt
+pays large debts.
+
+**Content could not fix it.** Effects add or set a number the pack wrote, and a
+balance built from +14, +32, +4, −45 and −10 can be anything, so no fixed payment
+can equal it. The alternatives were to gate each instalment on the balance
+covering it (leaving small balances to cost more than they are) or to retune
+every credit amount to a common step (changing tuned numbers to suit a missing
+primitive).
+
+**So an `add` effect's value may now be read from state:**
+`{ path: 'money', op: 'add', value: { from: 'owed', times: -1, cap: 20 } }` is
+"take away whatever is owed, but no more than 20". The amount is resolved at the
+moment the effect applies, so a repayment lists the money effect before the
+balance effect — both read the balance before it moves. The change record keeps
+the number actually applied, with the reference in `source`.
+
+This is not the engine learning about debt. It reads a number from a path without
+knowing what the path means, exactly as a condition does, and #1 and #2 still
+hold: it is data, validated at load. The validator requires the referenced path to
+be declared and `times` and `cap` to be numbers. The test archetypes score such an
+effect at its cap, the most a player reading the label could expect.
+
+A conformance test now holds every pack to it: an option that spends money and
+reduces a balance — any money-formatted stat other than money — must read the
+amount from the balance, or be gated on the balance covering the whole instalment.
+
+## 39. A hidden option is not a locked door in the log either
+
+`whenLocked: 'hide'` (#37) kept "Put money against the book" off the screen of a
+player who owed nothing, and it worked. But the turn record listed offered options
+without saying which were hidden, so `npm run analyze` reported the option as a
+locked door shown three times to a player who never saw it. The instrument was
+counting the very thing the fix removed.
+
+The turn record now carries `hidden` for every offered option, and the analyser
+skips hidden options when counting locked doors. Logs exported before 0.3.4 do not
+have the field and still over-count.
+
+The same session's exports also put a save file next to the feedback log in
+`logs/`. The analyser read "the newest `.json`", so whichever of the two was
+exported last would have been read as the log. It now reads only
+`theladder-feedback-*.json` when no file is named.
+
+## 40. What the first Frontier playtest changed
+
+The session (112 turns, 0.3.3, promoted on turn 44) confirmed the systems #36 and
+#37 were built for: both lifestyle purchases were found and taken, the standing
+charge fired as designed, money never went below zero, and the run ended flat —
+the break-even the Frontier intends at the top. Everything it found wrong was
+legibility, plus the defect in #38. All eight of the player's comments were
+questions about what a number meant, and both thumbs-down were on events that
+confused them.
+
+- **Wages are called wages.** "Settlement" and "Deputy pay" became "Wages from
+  Vane" and "Wages from the county". The player could not connect "Settlement"
+  to the twenty-four a run the first morning quotes, and read a run's own +$9 as
+  the pay going missing (#27: the ledger is written for a player).
+- **A clamped change says where it stopped** — "stopped at $0", "stopped at 100" —
+  instead of "at its limit", which was read as a balance still outstanding.
+- **Two option labels were rewritten** that the player could not parse: "Have no
+  view on the axle" and "take hold of the nearest one".
+- **The horse and the room are separate events.** One event offered both, with a
+  description that was always about the horse, so the room was offered under
+  horse text and "Buy the bay" was shown locked to a player who had bought it — a
+  door that could never open. Each is now gated on the tier it sells, and a test
+  holds that neither is offered once bought.
+- **The promotion gets a warning.** "How do I find out how close I am to
+  promotion?" had no answer anywhere. `ward_takes_notice` comes once, to a hand
+  past turn 24 with standing 55, and says in the town's terms what the offer waits
+  for — a name the street says for the right reasons, and a man Ward takes at his
+  word or one with the Ridge road behind him — without printing a threshold. Across
+  72 archetype runs it fired in 67, at a median of turn 29, always before the offer.
+  A numeric progress display was not built: it would need the interface to know
+  what a promotion is, which #22 keeps in content.
+- **The office got five more days.** 69 deputy turns saw 13 distinct situations,
+  and `office_day` and `the_cells` were 17% of the stage each — the same thinness
+  #24 caught in Dispatch. Five events were added (the stage in short, the county's
+  fees, a bounty hunter, a fire at the store, Dutch wanting the Ridge road) and the
+  horse/room split adds a sixth. Measured across 72 archetype runs of 250 turns,
+  the three floor events fell from about 17.5% of deputy turns each to about
+  13.5%. Every new event has an ungated way through, and its skill gates (nerve 30
+  and 34, trade 28 and 30) sit under growth available without them (#32).
+
+**Measured and not yet understood.** In the same simulation, promoted runs now end
+with a median of $164 rather than $88, and a median standing of 89 rather than 98.
+Two changes plausibly account for it — repayments no longer overcharge, and lower
+standing triggers the $4 standing charge less often — but it has not been
+isolated. The declared baselines and every tuning test still pass. The Frontier is
+meant to be roughly level at the top, so the next Frontier session should watch
+whether money stops mattering again, as it did in Corporate Ladder before #36.
+
+"Owed at the store" was asked for as "a major field at the top". It already is,
+second after Money whenever anything is owed. Whether it is prominent enough can
+only be judged in a browser, which this machine cannot render (#18).