After 2nd prompt

2026-06-08 12:47:32 -07:00 · 2026-06-08 12:47:32 -07:00 · e15e8fd62e
commit e15e8fd62e
parent ae5738ea2f
7 changed files with 190 additions and 26 deletions
--- a/agent.md
+++ b/agent.md
@ -51,7 +51,44 @@ PRs must include the verifier scripts. Don't commit a "verified" claim without t

 ---

-## 3. Required tools
+## 3. Three-tier evidence model
+
+This repository keeps the breadth of the existing Claude-assisted extraction, but promotes claims through the narrower three-tier process used for the LXMF extraction. Treat existing prose as useful candidate material until the relevant tier is satisfied.
+
+### Tier 1 — Source analysis report
+
+Use this tier to answer one narrow protocol question, not to rewrite a whole subsystem. The output is an analysis note, issue comment, or draft SPEC.md text that includes:
+
+- The exact upstream RNS/LXMF version or commit inspected.
+- The files, functions, constants, and line numbers that define the behavior.
+- A byte layout or state-machine description precise enough to test.
+- A clear list of unresolved cases and assumptions.
+
+Tier 1 is enough to add an `⚠️ UNVERIFIED` claim with citations. It is not enough to remove a marker for a foundational wire-format claim.
+
+### Tier 2 — Executable verification
+
+Convert the Tier 1 claim into runnable evidence under `tools/` and, where byte-level data is involved, deterministic vectors under `test-vectors/`.
+
+Prefer upstream-runtime verification: a Python script should exercise installed upstream RNS/LXMF and compare exact bytes, parsed fields, signatures, keys, or state transitions. For high-risk layouts, add an independent reconstruction or decoder as a cross-check. The LXMF extraction's Perl MessagePack verifier is a good example of this second form.
+
+Tier 2 is enough to remove an `⚠️ UNVERIFIED` marker when the verifier is committed beside the claim and passes against the pinned upstream versions.
+
+### Tier 3 — Specification promotion and maintenance
+
+Only after Tier 2, update `SPEC.md` as normative prose:
+
+- Add or correct the section text.
+- Link the verifier or vector that backs the claim.
+- Preserve version-specific behavior if upstream changed.
+- Add a `README.md` spec-correction entry when earlier published text would mislead implementers.
+- Add a `playbook.md` incident entry when the finding explains a non-obvious interoperability failure.
+
+For foundational wire behavior, prefer two evidence forms before calling the result stable: upstream-runtime verification plus either an independent decoder/reconstruction or a live interop test. Flows and troubleshooting prose may be source-cited without this second form, but must not claim byte-level finality they do not have.
+
+---
+
+## 4. Required tools

 Agents working on this repo should have access to:

@ -86,7 +123,7 @@ This spec is only as good as the upstream version it was checked against. **Befo

 ---

-## 4. Marking convention
+## 5. Marking convention

 Use these GitHub-flavored Markdown blockquote forms so they render distinctly:

@ -100,7 +137,7 @@ When you verify a previously-marked claim, **delete the entire blockquote** and

 ---

-## 5. Audit pass — initial state of `SPEC.md`
+## 6. Audit pass — initial state of `SPEC.md`

 The bootstrap `SPEC.md` was assembled from the working notes of two reverse-engineering efforts ([webclient](https://github.com/thatSFguy/reticulum-lora-webclient) and [mobile-app](https://github.com/thatSFguy/reticulum-mobile-app)). Some sections are already strongly verified by working code in those repos; some are source-cited but not directly tested in this spec repo's tools; some are observational claims that need formal verification.

@ -126,20 +163,20 @@ Initial confidence assessment (subjective, not authoritative — re-do this audi
 | §8 KISS / HDLC framing | High — both work in production on the reference clients |
 | §9.1–§9.8 Implementation gotchas | Each was a real bug that bit a real implementation. High confidence each is real; some lack formal test scripts. |
 | §10 Resource fragmentation | Source-cited from `RNS/Resource.py` against RNS 1.2.4; not yet runtime-verified in this repo's `tools/`. |
-| §11 Test vectors | The vectors themselves are verified; the test-vectors/ directory needs to be populated in this repo (currently partially populated). |
+| §11 Test vectors | Historical bootstrap item. `test-vectors/` is now populated with identities, announces, opportunistic LXMF, and Link vectors. Future work should add negative vectors and link-delivered LXMF coverage. |
 | §12 Source map | High |

-**Concrete next-task list** for the agent picking this up:
+**Historical bootstrap tasks from the initial audit, now mostly complete:**

-1. Run the audit — re-evaluate the table above with your own reasoning, don't just trust it.
-2. Populate `test-vectors/` with at least: identity material, a signed announce, an opportunistic-LXMF round-trip, a Link handshake.
-3. Write `tools/verify_announce.py` that loads a test vector and verifies bytes against upstream RNS.
-4. For each `> ⚠️` or `> 🔮` callout you add, write the verifier alongside.
-5. Open issues for any claim you can't verify and tag them `needs-verification`.
+1. Re-evaluate the table above with your own reasoning, not by copying it.
+2. Keep completed vectors current: identities, signed announces, opportunistic LXMF, and Link handshake.
+3. Maintain the verifier suite listed in `tools/README.md`; add focused scripts for new claims instead of broad catch-all verifiers.
+4. For each new `> ⚠️` or `> 🔮` callout, track the Tier 2 verifier or issue needed to resolve it.
+5. Open issues for claims that cannot be verified yet and tag them `needs-verification`.

 ---

-## 6. PR rules
+## 7. PR rules

 For any PR touching `SPEC.md`:

@ -156,7 +193,7 @@ For PRs adding to `test-vectors/`:

 ---

-## 7. What to do when upstream changes
+## 8. What to do when upstream changes

 RNS evolves. When a future RNS version changes the wire format (or the in-source behavior cited in this spec):

@ -169,7 +206,7 @@ The goal is for this spec to be useful even when run against an RNS version a ye

 ---

-## 8. Don't
+## 9. Don't

 - Don't paste large blocks of upstream code into this repo (license & churn). Cite by file + line + small inline snippet only.
 - Don't add claims based purely on what some other client does. Other clients have bugs too.
@ -179,7 +216,7 @@ The goal is for this spec to be useful even when run against an RNS version a ye

 ---

-## 9. Repo layout (current and aspirational)
+## 10. Repo layout

 ```
 reticulum-specifications/
@ -188,15 +225,17 @@ reticulum-specifications/
 ├── agent.md               This file
 ├── SPEC.md                Combined spec (will be split into per-layer files as it grows)
 ├── tools/                 Verifier scripts (Python, callable against upstream RNS)
-│   ├── verify_announce.py        (TODO)
-│   ├── verify_packet_header.py   (TODO)
-│   ├── verify_lxmf_roundtrip.py  (TODO)
-│   └── verify_link_handshake.py  (TODO)
+│   ├── verify_announce_roundtrip.py
+│   ├── verify_packet_header.py
+│   ├── verify_lxmf_opportunistic.py
+│   ├── verify_link_handshake.py
+│   └── ...
 └── test-vectors/          Known-good byte sequences
-    ├── README.md          (TODO — describe vector format)
-    ├── identities.json    (TODO)
-    ├── announces.json     (TODO)
-    └── ...
+    ├── README.md
+    ├── identities.json
+    ├── announces.json
+    ├── lxmf.json
+    └── links.json
 ```

 Tools are Python because Python RNS is the reference. Verifiers should be self-contained scripts that print PASS/FAIL plus a diagnostic on mismatch. Exit code 0 on PASS, non-zero on FAIL.