Audit pass over the public-facing surface so a customer can read it
end-to-end without tripping on stale numbers or self-contradictions.
README + docs accuracy:
- Test counts 426 → 445, assertions 2 557 → 2 753 (verified via
doctest run); E5 row was missing test_e5_kat (19 cases)
- Interop checks 24 → 31, COMPLIANCE.md message count 149 → 164,
COMPLIANCE.md "291 cases / 1515 assertions" → 445 / 2 753
- README "60+ test IDs" for MES_INTEROP → actual 59
- PVD example counts: 32 SVIDs/17 CEIDs → 29/21, "~40 handlers
in ~200 lines" → 51 in ~460, "~700 lines" → ~1,100; main.cpp
header table-of-contents resynced with the actual 7 sections
Out-of-scope honesty (COMPLIANCE.md §8 + FAQ.md):
- Removed HSMS-GS (was both ✅ implemented in §1 and "out of scope"
in §8; INTEGRATION.md §7 documents using it)
- Removed multi-block SECS-I (split_message/assemble_message exist
with 4 dedicated tests)
- Added serial-port wiring as the genuine open ⬜ item — FSM is
tested end-to-end over TCP; only the asio serial_port glue is
deferred
- COMPLIANCE.md intro now lists E42 and notes "E37 (SS + GS)"
README restructure:
- Moved the 8-command proof table and per-standard test-coverage
table to a new PROOFS.md (72 lines)
- README now leads with what / Quick start / Documentation map,
then a one-paragraph "How it's proved" linking to PROOFS.md
- Updated cross-refs in FAQ.md, GLOSSARY.md, VERIFICATION.md, and
interop/README.md to point at PROOFS.md
CI fix — tshark-dissector job:
- interop/tshark_validate.sh hardcoded /app/build/secs_server etc.
which only works inside the docker image. Now derives ROOT from
the script's own location and accepts BUILD/SERVER/CLIENT/DATA
env overrides, so CI can run it from the workspace dir
- Verified still passes in docker (69 frames, 0 malformed)
.gitignore:
- Added build-fuzz/ and build-tsan/ (were showing as untracked)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Fills four documentation gaps surfaced by the doc audit:
1. README "Documentation map" was missing VERIFICATION.md (the file
that backs the proof-of-feature-completeness claims) and is now
pointing at the new files added in this commit too — ARCHITECTURE,
GLOSSARY, FAQ, examples/pvd_tool/ (the last two land next).
2. interop/README.md only documented secsgem-py. Three of the five
external validators (tshark, secs4j, libFuzzer) plus the E5 KAT
were invisible from the directory's own README. Rewritten as a
complete index — what's external, what each catches, how to run,
what bugs they've already surfaced, when to add a new validator.
3. GLOSSARY.md is new. Every SEMI acronym used in the codebase or
the docs gets one row: SVID, DVID, CEID, RPTID, ALID, ECID, PPID,
MID, CARRIERID, PRJOBID, CTLJOBID, SUBSTID, OBJSPEC, OBJTYPE,
MDLN, SOFTREV, EQPTYP, DATAID + every ACK code (COMMACK, ONLACK,
OFLACK, HCACK, CMDA, ACKC5-7-10, DRACK, LRACK, ERACK, EAC, TIACK,
GRANT, ALCD, OBJACK) + stream/function shorthand + HSMS terms +
T-timers + E84 signals + the standards lineup + codebase shortcuts
("the model", "the router", "the proof", etc.). Cuts week-1
onboarding time.
4. FAQ.md is new. Canonical answers to the questions that come up
once per integration: why HSMS unencrypted, SVID vs DVID, PJ vs
CJ, who fires FSM transitions, what runs on which thread, how to
add a new SECS-II message, ASCII vs Binary, common MES quirks,
how spool works, robustness fuzz vs libFuzzer, conformance vs
interop, what's not implemented.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
raphael