← Decision records

ADR-038: The adopted percentage measures structure; substance stays the judgment tier

Context

self-verify reports a drift number and an adopted percentage. Three classes of manifest entry are scored differently, and one of them is scored on almost nothing:

• a copy entry carries a sha256 and is compared against it (added in c10cbf2),
• a merge entry cannot be hashed - it is adapted on purpose - so it may declare requiredKeys naming what must survive the merge,
• a fill-from-repo entry has neither, and by construction cannot have either: the adopter writes the content, so there is no reference to compare it against.

The consequence was measured, not argued. On a sparse repository carrying the manifest and little else, six files reading # Title and TODO. moved the reading from drift 19 - 21% adopted (5/24) to drift 19 - 37% adopted (11/30). Real substance identical, drift identical, sixteen percentage points bought by creating six files that say nothing. CONTRIBUTING.md, SECURITY.md, docs/PRODUCT.md and docs/ARCHITECTURE.md each scored PASS on three lines.

A placeholder warning already existed and is explicitly "a warning, never drift: substance stays the judgment tier's call." It had two holes: it only recognised surviving template placeholders, so a stub the adopter typed themselves was invisible to it, and it walked a hardcoded list of eight files that CONTRIBUTING.md was never on - a second source of truth beside the manifest, quietly not covering what the manifest added.

Options considered

• A - Required sections per fill-from-repo entry. self-verify already has a sections mechanism, so each entry could declare headings its file must contain. Rejected: it converts substance into ceremony. An adopter adds the heading and writes TODO under it, and the number goes green on strictly less information than before, because now the repo looks structured too. It also imposes a document shape on files whose whole classification is that the adopter writes them their way, and it would move these entries into drift, changing what the number means for every repo already adopted.
• B - A minimum-substance signal: word count, or a threshold of prose. Rejected: it is measuring prose by the yard. A genuine two-sentence SECURITY.md naming an address and a response time is complete; a padded one is not better. Any threshold that fails the first while passing the second teaches adopters to pad, and the threshold itself would have no defensible value - a number nobody can justify is a number nobody should gate on.
• C - Say what the number is, detect only what is unambiguous, and leave the rest to review (chosen).

Decision

Option C, in three parts.

1. The adopted percentage is a structural measure and says so where it is printed. It counts entries present, and content only where the content is the standard's own. When any authored file reads as unfilled, the verdict line states that the percentage counts entries present, not substance written. No numbered rule changes; what changes is that the number stops being readable as a claim it was never making.
2. The warning detects "visibly nothing written", never "not enough written". Two shapes only, both unambiguous and both cleared by writing one real sentence: a body with no content beyond its headings, and a body whose entire content is a marker meaning nobody has written this yet (TODO, TBD, WIP, coming soon and their spellings). Still a warning, never drift.
3. The file list is derived from the manifest, not written in the script. The hardcoded list was the reason CONTRIBUTING.md was checked by nothing; any fill-from-repo entry added later would have inherited the same gap.

Whether what IS written is any good remains the judgment tier - reviewed at PR, as self-verify.md describes. That is not a gap being tolerated; it is the only honest place for it. No mechanical check can tell a real architecture page from a plausible one, and a check that pretends to is worse than none, because it converts a reviewer's question into a green tick.

Consequences

• Positive: the number can no longer be inflated silently. Padding a repo with empty files now produces a named warning per file and a verdict line that says what the percentage counts. The manifest becomes the single source of truth for which files are authored.
• Positive: no existing adopter's drift number changes. The addition is warnings and wording, so nobody's CI turns red on a release that only clarified what the number meant.
• Negative: a determined adopter can still clear the warning by writing one real but empty sentence. That is accepted deliberately - the alternative is option B, and the cost of option B is teaching everyone to pad.
• Negative: the adopted percentage still rises when files are added, including the standard's own copied files. That is a separate and wider observation about the metric, recorded in the validation suite rather than resolved here.

Confirmation

tools/self-verify-fill-test.mjs carries the boundary in both directions: a self-written TODO stub warns, a heading-only file warns, each spelling of the nothing-yet marker warns, and a terse-but-real SECURITY.md and CONTRIBUTING.md do not. Neutralising the check turns exactly the three positive cases red and leaves the two negative ones green, so a fix that warned about everything would fail this record as surely as one that warned about nothing.

docs/method/self-verify.md states the split under "Which rules the number covers" and in the judgment-tier section.

Revisit when

A fill-from-repo entry acquires a genuinely machine-checkable property that is not a proxy for prose quality - a SECURITY.md that must contain a reachable contact, say, where reachability is testable. At that point the entry has something real to check and belongs in drift, and this record should be narrowed rather than worked around.

Read this page's markdown, or its source on GitHub.