diff --git a/VERIFY-POLICY.md b/VERIFY-POLICY.md new file mode 100644 index 0000000..a6ebaed --- /dev/null +++ b/VERIFY-POLICY.md @@ -0,0 +1,124 @@ +# The `[VERIFY]` marker: what it means in this repository + +**Status:** normative for every Aere Network repository published on `git.aere.network`. +**Written:** 2026-08-03. Supersedes the earlier wording that described these markers as items +"for a human to confirm before publication". + +--- + +## The rule, in one paragraph + +A `[VERIFY]` or `[VERIFY: ...]` marker is a **permanent, deliberate disclosure that one named fact +is NOT MEASURED**. It is published exactly as it stands. It does not block publication. It is closed +in exactly one way, by a measurement that settles the named fact, and the closing measurement is +written down next to it. **A marker is never closed by deleting it**, and it is never closed by +softening the sentence around it. + +## Why the earlier wording was wrong, and how + +Three documents in this bundle used to say that these markers were flags "for a human to confirm +before publication" or "before publishing": + +- `AERE-EIP-COMPATIBILITY-MATRIX.md`, the "How to read this" list and the open-flags heading +- `AERE-NIST-VALIDATION-STATUS.md`, the Appendix A heading and one marker body +- `AERE-PROTOCOL-SPECIFICATION.md`, the honesty conventions list and the Section 11 register heading + +That sentence was not true. These repositories were published on 2026-07-20 with **263** exact +`[VERIFY]` markers still open across **83** files (measured 2026-08-03 against the published trees, +not against a working copy). A document that says its unknowns will be resolved before publication, +and is then published with the unknowns in place, asserts more than was done. That is the same class +of defect the markers exist to prevent, one level up: **the honesty convention itself was making an +unmeasured claim.** + +The repair was to make the text match the practice, not to make the practice match the text. Deleting +243 disclosures so that a grep would come back empty would have removed real information from readers +and replaced an honest document with a quiet one. + +## Why publishing open unknowns is the right choice here + +This is the same reasoning already recorded in `KNOWN-ISSUES.md` in `aere-contracts`, where our own +test suite's findings are published deliberately, with status attached. Publishing a finding is +useful. Publishing it with no status was the oversight, and the fix was to add status, not to remove +the finding. + +The prior art we followed is the Rust RFC process, where every RFC carries a mandatory +"Unresolved questions" section, so the unknowns of a design are an enumerated, permanent part of the +published document rather than something that disappears at publication time +(`https://github.com/rust-lang/rfcs/blob/master/0000-template.md`). + +The prior art we deliberately did **not** follow is the common docs-CI habit of failing a build on +the literal string `TODO` (for example a Vale `existence` rule at `level: error`, +`https://docs.vale.sh/topics/styles`). That rule is right for a marker that means "I have not +finished writing this sentence". It is wrong for a marker that means "this fact about a live chain +has not been measured", because the only thing it can force is deletion, and deletion here is a lie. +It is worth noting that GitLab, which runs one of the more thorough public documentation pipelines +(Vale, markdownlint, link checking, Mermaid validation), does **not** gate on placeholder markers at +all (`https://docs.gitlab.com/development/documentation/testing/`). + +## What is actually enforced + +The guard is `aerenew/scripts/deschise/flaguri-verify.cjs` in the private working repository. It is +not a marker ban. It checks four things, and it distinguishes "measured and wrong" from +"could not measure": + +1. **No document may promise that markers are closed before publication.** The forbidden phrasings + are matched across line breaks, because a sentence split by a line wrap is the same sentence. +2. **Every published repository that carries at least one marker must carry this file at its root.** + A marker whose meaning is only defined in some other repository is undefined for the reader who + found it. +3. **The count is tracked, never asserted.** Markers are counted in both forms, `[VERIFY]` and + `[VERIFY: ...]`, and compared against the recorded snapshot below. Silent drift fails. +4. **The published surface is measured over the network, not from disk.** A working copy is not + evidence about what the world can read. If the network cannot be reached, that half of the + measurement reports NOT MEASURED and never reports green. + +## Recorded snapshot + +This file is excluded from every count below and from the guard's own counting, because it defines +the marker rather than carrying a disclosure. Counting the definition would make the number grow by +writing the rule down. + +## This repository (added 2026-08-28, at staging time) + +`pqc-migration-toolkit`, measured on the published tree the day this file was staged: +**26 `[VERIFY]` exact, 27 any form, 8 files carrying a marker.** The dated tables below +are the family-wide census from 2026-08-03 and are kept as history; the rule above, not +the numbers, is what this file promises. + +Working tree of `aerenew/publish-bundle`, measured 2026-08-03: + +| Repository | `[VERIFY]` exact | `[VERIFY` any form | Files carrying a marker | +|---|---|---|---| +| `aere-contracts` | 8 | 16 | 10 | +| `aere-docs` | 177 | 226 | 46 | +| `aere-node` | 0 | 0 | 0 | +| `aere-research` | 60 | 66 | 18 | +| **total** | **245** | **308** | **74** | + +Published trees on `git.aere.network`, cloned and measured 2026-08-03 +(`aere-docs` at `58780bd`, `aere-contracts` at `c0fcf3d`, `aere-node` at `48416df`, +`aere-research` at `37f55e4`, all four commits dated 2026-07-20): + +| Repository | `[VERIFY]` exact | `[VERIFY` any form | Files carrying a marker | +|---|---|---|---| +| `aere-contracts` | 8 | 16 | 10 | +| `aere-docs` | 171 | 224 | 46 | +| `aere-node` | 0 | 0 | 0 | +| `aere-research` | 84 | 92 | 27 | +| **total** | **263** | **332** | **83** | + +The two tables do not agree, and that disagreement is itself a finding rather than an error in the +counting. The working copy and the published repositories have drifted apart in **both** directions +since 2026-07-20: the working copy holds 21 files that were never published (including +`KNOWN-ISSUES.md`, `LICENSING.md`, `CITATIONS-UNRESOLVED.md`, `RUN-A-NODE.md`, `genesis.json` and +`bootnodes.txt`), and the published `aere-research` holds 33 files under `formal-consensus/` that no +longer exist in the working copy. Any future publication has to reconcile that first, because a +naive re-stage and force-push would silently delete 33 files that are public today. + +## For a reader who is not us + +If you found a `[VERIFY]` marker in one of these documents: it is there on purpose. It marks the +exact boundary of what we measured. Everything around it is intended to be literally true, and the +marker tells you which specific claim we could not stand behind on the date the document was written. +If a marker matters to you, the fastest way to close it is usually to measure it yourself against +the public endpoint, and we would rather you did that than trust us.