aere-contracts/VERIFY-POLICY.md

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.

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.