| name | jgdms-board-review |
| description | JGDMS design/security/code review heuristics distilled from four retired board seats (ASN.1/DER + module-boundary, adversarial security, JERI transport, rule-fidelity/determinism/cross-language). Use before scoping or conducting any nontrivial design review, security review, or PR review in this repo — covers canonical-form contracts, outcome-vs-mechanism checks, fail-closed audits, confused-deputy hunts, and domain-specific war stories/checklists. Triggers on "review this design", "security review", "is this safe", "board guidance", "review heuristics", or any request to review JGDMS code/design for correctness or security. |
JGDMS Board Reviewer Guidance
Distilled review heuristics from four retired JGDMS board seats. Load this before scoping or
conducting any nontrivial design review, security review, or PR review in JGDMS.
Full text: JGDMS/docs/JGDMS-Board-Reviewer-Guidance.md
(1180 lines). Don't read it end-to-end by default — read Part I always, then jump to the domain
section(s) that match the change under review (use Read with offset/limit on the line
ranges below, not a full read).
Always read: Part I — General principles (lines 50-265)
13 cross-cutting principles (G1-G13) that recurred across all four board seats independently,
regardless of domain:
- G1 canonical form is the contract — one valid encoding per value; a decoder that encodes
canonically but accepts non-canonical input on decode is still broken.
- G2 outcome is a claim, mechanism is the proof — convert every stated guarantee into "what
concrete enforced construct guarantees this, and is it actually in the design?"
- G3 verify independently, don't trust the self-report — green tests prove nothing about
untested input; reproduce tallies yourself, run adversarial input against built classes.
- G4 declaration-is-the-signal — every rule keys on what the developer already wrote, never a
runtime instance/hash/restating annotation.
- G5 structure on the wire, behaviour in the constructor — Layer 1 (wire/schema, digest-covered)
vs. Layer 2 (
check(GetArg)/constructor, semantic); a proposal misplacing a behavioral contract
onto the wire has misplaced a layer.
- G6 fail-closed on ambiguity, always — but check the fail-closed decision doesn't leave a
fail-open side effect (trace the cleanup path of every security throw, every platform).
- G7 repair not amputate, report faithfully — rank by real exploitability with a concrete
scenario; distinguish verified/CONFIRMED from recommended/PLAUSIBLE.
- G8 all sources of truth must agree — prose spec, machine-checkable module, built code;
citations are load-bearing, open the dependency and confirm.
- G9 a normative spec is the interop test — could a peer implement it from the doc alone?
Cross-language claims need active testing against a second runtime, not extrapolation.
- G10-G13 (fresh-reviewer-vs-veteran A/B findings) — a boundary fence is not an interior fence
(check what a guarded recursive call recurses into); probe empty/degenerate inputs, not just
populated ones; "verified" must mean bound-to-known-good, not merely self-consistent; run the
adversarial input, don't just reason about the bound.
Then read: the matching domain section(s)
Each domain section has hazards (cost/severity order), JGDMS-specific gotchas, war stories
(defect + "the tell" that surfaced it), and a one-page checklist.
| Domain | When the change touches | Lines |
|---|
| §2.1 ASN.1/DER & module boundary | wire encoding, schema digests, Entry byte-matching, canonical forms | 268-460 |
| §2.2 Adversarial security | new remote-facing entry points, object reconstruction paths, caller/principal handling, authorization | 461-695 |
| §2.3 JERI transport | endpoints, connection lifecycle, transport layering, replacing/deprecating a transport | 696-935 |
| §2.4 Rule-fidelity/determinism/cross-language | serialization rules, cross-JVM/cross-language consistency, spec-vs-implementation drift | 936-1165 |
Reviews often span more than one domain — e.g. a DER change to a remote-facing type usually needs
both §2.1 and §2.2.
Two reflexes general enough to apply outside their home domain
- §2.2's ungated reconstruction door — a new form reaching object-reconstruction that bypasses
the primary path's gate; "wire-names-the-class" is where capability escalation hides. Check this
on any new deserialization/reconstruction entry point, not just security-labeled ones.
- §2.2's confused-deputy / role-reversal hunt — any new direction of request inverts
"caller = connection initiator"; re-derive caller/execution-subject/stamped-principal explicitly
rather than assuming the usual direction holds.
- §2.3's pre-deletion audit — before replacing or deprecating any layer, check what the old
layer does beyond its headline job; no half-retirement.
These generalized once already: first applied outside DER/transport review to a completely
different domain (the DirtyChai OIS/OOS SPI-replacement design, java.io serialization) and both
reflexes surfaced real findings there — evidence they're genuinely general, not domain trivia.
Provenance
Consolidated 2026-07-05 from four retired board seats' retirement capstones. Originals preserved
at JGDMS/docs/board-guidance/{asn1-der-module,security-adversarial,transport-jeri,rule-fidelity-determinism}.md
for provenance only — the consolidated doc supersedes them as the thing to actually read.
