125 lines
7.0 KiB
Markdown
125 lines
7.0 KiB
Markdown
# 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.
|