aere-network/pqc-migration-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Publish the [VERIFY] rule this repository's 27 markers follow: a marker is a permanent NOT MEASURED disclosure, closed only by a measurement, never by deletion

Browse Source
This commit is contained in:
Liviu 2026-08-28 02:03:03 +03:00
parent 16fd087586
commit 216ef02eeb
1 changed files with 124 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
VERIFY-POLICY.md Normal file
View File

@ -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.