Module delivery doctrine

Protocols

The repeatable shape of every module delivery. Invariant-first, protocol-driven. Case reviews, completion reports, status snapshots, review gates — the same flow every time, regardless of module.

§ 1 · The protocol

One direction, six artifacts

Each artifact derives from the one to its left. Reversing the flow ("the code says so, update the spec") is a drift signal — fix the spec before the code lands.

01 Spec Binding contract: lifecycle, validation, forbidden states, copy boundaries.
02 Build Pure-render TSX with explicit props. No async, no backend hooks.
03 Preview Self-contained review harness with all states, deterministic mocks.
04 Test Pure-logic unit tests + browser smoke. Invariants asserted explicitly.
05 Report Validation matrix tying invariants to assertions; completion report.
06 Handoff README + STATUS finalized; live-codebase alignment audit; integration plan.
§ 2 · Artifacts

Every module ships these ten files

A module is not handoff-ready until all ten exist. Missing any one of them blocks the release gate.

✓README.md
✓STATUS.md
✓{module}-execution-spec.md
✓handover/ui/*.tsx
✓handover/preview/{module}-preview.html
✓handover/preview/screenshots/*.png
✓tests/{module}.test.ts
✓tests/smoke-*.mjs
✓handover/docs/{module}-module-completion-report.md
✓handover/docs/{module}-integration-notes.md
§ 3 · Invariant-first

Implementation follows invariants, not the reverse

Step A

Read the invariants

  • Global wallet invariants (this library)
  • Module execution spec
  • Authority chain at the top of each binding doc
Step B

Express them in code

  • TSX matches the spec, not the other way around
  • Closed enums declared once, mirrored everywhere
  • Forbidden patterns explicitly absent
Step C

Assert them in tests

  • One assertion per invariant
  • Source-scans for forbidden tokens
  • Disjointness between validation and terminal sets
Step D

Demonstrate them in preview

  • Every reviewable state navigable from sidebar
  • Edge cases (no-match, insufficient, expired) visible
  • Deterministic mocks; no live data
§ 4 · Case-review artifacts

When a decision needs a record

For non-trivial product decisions (e.g., amount-uniqueness vs tx-hash, memo/tag vs amount matching), produce a visual case-review HTML alongside the standard markdown.

✓
Hero + executive summary so reviewers can absorb the decision in 2 minutes.
✓
A "current vs correct" comparison visual, not a paragraph.
✓
A flow diagram of the recommended solution.
✓
A backend / API requirements table — the integration ask.
✓
A final-decision callout with the one-line principle.
§ 5 · Status & completion reports

Two surfaces, one history

STATUS.md

Snapshot of the latest pass

  • Author history table at top
  • Validation matrix per pass
  • Versioned (v1.0, v1.1, …) — never overwritten
  • Append a row every time STATUS changes
Completion report

Detail behind the status

  • Files modified / files NOT touched
  • Per-section invariant table
  • Backend/API assumptions called out
  • Known gaps + integration concerns
§ 6 · Review gates

What gets verified before a module ships

Spec exists, has authority chain, has author-history row for this pass.
TSX compiles, type-checks, follows pure-render rule.
Preview renders all states, zero console / pageerror.
Tests pass; invariants asserted; forbidden tokens absent (source-scan).
Screenshots regenerated this pass; release-gate "PASS X required / X present / 0 missing / 0 extra".
STATUS.md v-bump row + validation matrix; completion report updated.
Live-codebase audit confirms no architectural conflicts; integration plan documented.
Other modules untouched — Send/Deposit/Withdraw scope respected.
§ 7 · Module doctrine

The repeatable shape

Every Unit module — wallet, vault, identity, future — follows the same shape. New modules inherit this without re-derivation.

Spec → Build → Preview → Test → Report → Handoff

One direction. Spec leads. Reports follow. Standards are how the system is built — not documentation after the fact.