Tracking: SAGE project health audit — correctness, completeness, and delivery gaps

[ninthworld]

Purpose

Track the actionable findings from a repository-wide audit of main at 53304e1 (2026-08-04),
after the prototype-driven client rebuild and the latest payment/draft work.

This is a bounded health and completion tracker, not a permanent speculative roadmap. It records
confirmed contradictions, unfinished acceptance criteria, major product gaps, and maintenance
risks that were otherwise absent from the open tracker. Implementation detail lives in focused
child issues.

Re-measured 2026-08-07 against main at 47e26cc. Every number in the original audit has
moved and most of the linked work is closed; the figures below are the current ones and the
original assessment is preserved at the bottom. What is left is almost entirely the part
automated coverage cannot do — playing the game and judging it.

Where this stands

Nine of the ten linked issues are closed:

Issue	Outcome
#704 undo advertised before it existed	closed — superseded by #648 landing for real
#707 format names vs. seat ranges	closed
#712 status and capability claims	closed
#709 legible settle	closed — docs/client-design.md §6.9, the band, in #785
#708 spectator rendering	closed — §6.10, in #812
#705 deck-builder design pass	closed
#710 phone-accessible deployment	closed as deferred, not rejected — reopen when someone other than the maintainer needs to play. The acceptance criteria stand as written
#648 authoritative per-room undo	closed — end to end in #814, UndoPolicy::Off by default
#706 next compatibility tranche	closed as delivered — Core Set 2019 is complete
#711 oversized production files	open, body re-measured; every file it originally named is split and twelve different ones are over the limit

Also open, and not part of the original audit: #791 — delete exclusions.json and prohibit
curated denylists. It is the one open issue whose acceptance criteria conflict with instructions
elsewhere in the repository, and closing #706 and #776 removed two of the three places that told
contributors to maintain the registry.

Re-measured audit score

Area	Then	Now	Assessment
Architecture	9/10	9/10	Unchanged; the boundaries held through the tranche
Testing discipline	8.5/10	8.5/10	Gates unchanged and green
Rules/card breadth	5.5/10	7.5/10	299 supported definitions, all of M19; 45 named exclusions
Client completeness	6.5/10	8/10	Settle, spectator, deck builder, and undo all shipped
Documentation	6/10	6/10	Same class of drift found again — see below
Maintainability	6.5/10	6/10	The tranche regrew the seams #711 was opened for
Deployment readiness	3/10	3/10	Unchanged, and now a recorded decision rather than an omission

What is actually left

1. Playing it, which nothing here can substitute for

• Play at least one complete 3-player FFA through the shipping client.
• Play at least one complete 4-player FFA or Commander game through the shipping client.
• Exercise dense developed boards, per-attacker defenders, stack interaction, public piles,
  commander damage, and eliminated seats.
• Repeat the critical paths on desktop, phone landscape/portrait, and 200% browser zoom.
• Run the supported-viewport sweep that reports the smallest rendered permanent, and decide
  the legibility threshold (docs/client-design.md §10 question 1).
• Judge whether the settle band is enough for a player who missed a five-event settle
  (§10 question 4) and whether a spectator ever wants to move chairs (§10 question 5).
• Drive the deck editor at 299 cards and report where it stops feeling immediate
  (§10 question 2).
• Play a game with Root Snare in it and report whether the log was enough for a turn-long
  effect no region of the board states (§10 question 7).
• File narrow reproducible issues for every failure; do not keep generic "validate
  multiplayer" work open after findings are split.

Structural support is not usability evidence, and this is the whole of the merge criterion the
project actually holds itself to.

2. Structural debt, before the next expansion

• refactor: split oversized production files to satisfy repository policy #711 — twelve production files over 1,000 code lines, led by
  crates/sage-engine/src/ability/effect.rs (1,936) and
  crates/sage-server/src/rules_text/effects.rs (1,625). The M19 tranche regrew exactly the
  seams the first wave of splits cleared.

3. The exclusion registry

• Remove exclusions.json and prohibit card/mechanic denylists #791 — remove exclusions.json, and with it the idea that a missing mechanic can be
  recorded rather than built. 45 entries today. Every one of them must survive as affirmative
  implementation work or as an honest report of what the catalog does not do.

4. Documentation drift, found a second time

The original audit closed #712 for stale capability claims. The same class of drift recurred as
the tranche landed, and is fixed in the PR linked below:

• README said undo had "no command behind it" after feat: optional per-room undo, end to end (#648) #814 shipped it end to end.
• README said "today a settle is a run of log lines" after §6.9 and feat(client): the settle, said once (#709) #785 built the band.
• README described the catalog as "a verified slice of Core Set 2019" when it is the whole set.
• README and docs/brief.md both said the replacement layer covers one event and that damage
  prevention and cost modification are out of scope; both exist (ADR 0019's own second half
  documents damage, so only the summaries were stale).
• docs/client-design.md §10 said the deck editor had "only ever been built against a catalog of
  ~134 cards" — it is 299.

The lesson worth keeping: capability prose in README and the brief goes stale on exactly the
commits that make the project better, and no gate catches it. Whoever lands a mechanic owns the
sentence that claimed it was impossible.

5. Deliberately not scheduled

• Chat and a who-is-here roster: real gaps, drawn and honestly labelled as carrying nothing,
  below everything above in priority. Open a focused issue only when scheduled.
• Deployment: ops: restore an automated phone-accessible deployment path for SAGE #710's reopen triggers, in its closing comment.
• The next card set: engine: plan and implement the next high-leverage compatibility tranche #706's method still applies; it needs a named pool first.

Completion criteria

This tracker can close when:

• Every linked implementation issue is closed or explicitly deferred with a recorded reason.
• No shipping surface claims an unsupported gameplay rule or capability.
• README and brief accurately describe current code and generated compatibility.
• Settle legibility, spectator rendering, and deck-building have implemented contracts rather
  than open design questions.
• A complete 3-player and 4-player game have been played through the shipping client and
  concrete findings resolved or tracked.
• The project has one documented, repeatable phone-accessible deployment path — or ops: restore an automated phone-accessible deployment path for SAGE #710's
  deferral stands and this criterion is struck.
• Oversized central files are within policy or carry narrow documented exceptions.
• The next rules tranche has been selected by measured payoff and split into focused work.

Non-goals

• A permanent exhaustive roadmap.
• Creating validation-only issues instead of concrete bugs.
• One issue per unsupported Magic mechanic.
• Chat, accounts, matchmaking, collection ownership, monetization, or persistence as blockers for
  the current vertical slice.
• Reopening old epics wholesale when only one residual acceptance criterion remains.

---

Original audit (2026-08-04, `main` at 53304e1)

Executive assessment

SAGE has a strong architectural foundation: pure immutable Rust rules engine; server-owned rooms,
policy, timers, automation, redaction, and reconnect; complete personalized views and issued
action identifiers; deterministic randomness; shared Rust/TypeScript protocol contract; generated,
freshness-checked card compatibility report; substantial unit, integration, agent-game, and
browser coverage; a real shipping web client rather than the former grey box.

It is nevertheless a playable vertical slice, not a deployable XMage alternative. The open
tracker previously showed only undo even though the repository itself named multiple unfinished
client surfaces, 36 excluded mechanic families, documentation drift, no current deployment path,
and central files beyond the repository's size policy.

Area	Score
Architecture	9/10
Testing discipline	8.5/10
Rules/card breadth	5.5/10
Client completeness	6.5/10
Documentation	6/10
Maintainability	6.5/10
Deployment readiness	3/10

Overall health: 7/10. Against the browser vertical slice ≈7.5/10; against XMage-in-the-browser
≈3.5/10.

Coverage at the time

134 supported functional definitions; 36 explicitly excluded mechanic families; sixteen
production files over 1,000 lines, the largest being apply/cast.rs (~2,696),
apply/combat.rs (~2,104), and ability.rs (~1,849).

Recommended execution order (as written then)

1. Truth first: bug(client): do not advertise undo before the server supports it #704, bug(server): make format names and advertised seat ranges agree #707, docs: reconcile project status and capability claims with current main #712. 2. feat(client): make auto-passed transitions and settled events legible #709. 3. feat(client): render live spectator games instead of the placeholder #708. 4. Multiplayer playtests. 5. design(client): complete the shipping deck-builder design pass #705, ops: restore an automated phone-accessible deployment path for SAGE #710.
2. Add optional per-room undo for authoritative game-state rollback #648. 7. refactor: split oversized production files to satisfy repository policy #711. 8. engine: plan and implement the next high-leverage compatibility tranche #706. 9. Chat and roster when scheduled.

Every step of that order except the playtests, #711, and the deliberately deferred #710 is done.

[ninthworld]

#710 (deployment path) is closed as deferred, not done — noting it here so this tracker does not imply it is in flight.

The reasoning is on that issue: deployment is worth paying for once the thing being reached is worth playing, and by the project's own merge criterion that judgment has not been made yet. Reopen when someone other than the maintainer needs to play it. Nothing in the current gates depends on a deployed target, so the deferral costs nothing that has to be maintained.

[ninthworld]

Documentation drift section above is now PR #818 — README, docs/brief.md, and docs/client-design.md §10. make verify green; docs only.