Reviewer docs: drop "Tier 0/Tier-0" vocabulary — design 009 reserved "tier" for hacky-vs-hardened nf-ilrd ← Beads

Twinned from https://github.com/cfsh/ninefold/issues/1077 by tools/beads/import_github.py's reconcile pass.

Aedan's ask, verbatim: "why do we still say tier 0 review? can this be rewritten post design 009"

Context

Design 009 (design_docs/009-the-games-audit-lane.md) found **three unrelated meanings of "tier"** coexisting in this repo — the reviewer's advisory tier:1/2/3 risk labels, the perimeter's "Tier 1" merge authority, and NINEFOLD_PHILOSOPHY.md's two investment tiers — and fixed the first one (T3, issue #971, closed/shipped): tier:* → risk:{routine,infra,feel} labels, with the doc's own ruling in §5:

> The word tier is freed to mean only NINEFOLD_PHILOSOPHY.md's hacky vs > hardened — prose vocabulary, never a label.

A fourth meaning was never in #971's scope and is still live: "Tier 0" describing the reviewer bot's *own* comment-only authority stage (as opposed to a hypothetical future stage where it merges PRs itself). It's the title of tools/reviewer/CHARTER.md ("Tier 0 (comment-only)"), the Status: line and two headings of tools/reviewer/DESIGN.md, a bullet and a ## Roadmap section of tools/reviewer/README.md, the title of notes/reviewer.md, a heading and a sentence in DEVEL.md, two lines in CLAUDE.md, and two more in notes/merging.md (full list below).

This is worse than merely leftover, because it now collides with design 009's own shipped vocabulary: tools/reviewer/DESIGN.md's unbuilt roadmap names its next stage "Tier 1: reviewer-merged low-risk PRs" (the reviewer bot performing the merge itself) — a completely different mechanism from design 009's shipped, unrelated "Tier 1" merge authority (games/ single-game PRs merging via the ordinary perimeter + jcantsp-bot, no reviewer-initiated merge involved). A reader hitting "Tier 1" in one file and "Tier 1" in another is now getting two unrelated claims, which is exactly the confusion design 009 was written to remove.

Verified current state (grep -rniE "tier.?0|tier-0" --include='*.md' .): every one of the sites below still reads "Tier 0" / "Tier-0" today, on this branch, post-009.

Prescription

Rename every "Tier 0" / "Tier-0" occurrence that describes the **reviewer bot's own comment-only authority stage** (not the perimeter's "Tier 1" merge authority, which design 009 deliberately kept — see Non-goals) to plain, non-numbered vocabulary. Reuse "comment-only" — it's already the parenthetical gloss at nearly every site, so most edits *drop* words rather than add them (no CLAUDE.md budget risk). Where the surrounding text names a *future, unbuilt* stage (the reviewer merging PRs itself, or a required check), name it by what it does, not by a tier number — per design 009's own Appendix, Aedan's ask for "meaningful names instead of 1,2,3" applies exactly as much to a roadmap heading as it did to a label.

Sites to change (file:line, current → replacement sense):

- tools/reviewer/CHARTER.md:1 — title `# ninefold-reviewer charter — Tier 0 (comment-only)` → drop "Tier 0", keep "(comment-only)". - tools/reviewer/CHARTER.md:11 — "Tier 0 rules: you never approve…" → "Comment-only: you never approve…". - tools/reviewer/DESIGN.md:3 — "Status: Tier 0 shipped (comment-only)." → "Status: shipped (comment-only)." (also drop "the tiers that are not built yet" on the next line if it now reads oddly without tier numbers — reword to "the stages that are not built yet"). - tools/reviewer/DESIGN.md:120 — ## 4. The verdict contract (Tier 0) → ## 4. The verdict contract (comment-only). - tools/reviewer/DESIGN.md:155 — "Reviewer output is advisory at this tier — aedanpope's word always wins." → "Reviewer output is advisory — aedanpope's word always wins." (the "at this tier" qualifier is now meaningless without a tier number; just drop it). - tools/reviewer/DESIGN.md:167 — ## 6. Tier roadmap → `## 6. Authority roadmap`. - tools/reviewer/DESIGN.md:169-186 — the three roadmap bullets: rename "Tier 0 (this PR): comment-only" → "Comment-only (shipped)"; "Tier 1: reviewer-merged low-risk PRs" → "Reviewer-performed merges (not built)"; "Tier 2 (maybe): required check" → "Required check (not built, maybe)". Update the internal cross-reference ("Deferred until Tier 0 shows…" → "Deferred until the comment-only stage shows…"). - tools/reviewer/README.md:51 — "- Tier 0 = comment-only." → "- Comment-only.". - tools/reviewer/README.md:352-356 (## Roadmap) — same rename pattern as DESIGN.md's roadmap: drop "Tier 0 (now)" / "Tier 1 (two admin clicks away)" numbering, name each stage by what it does. - notes/reviewer.md:1 — title # \ninefold-reviewer\` (nfr) — Tier-0 automated review → # \ninefold-reviewer\ (nfr) — comment-only automated review`. - DEVEL.md:7 and DEVEL.md:156 — the heading `## Tier-0 reviewer credentials` and its cross-reference both drop "Tier-0" → "## Reviewer credentials" (the section is about the credential, not the authority stage — "Tier-0" was never load-bearing here). - CLAUDE.md:199 — "normally after converging with the Tier-0 reviewer on an approval:human PR" → "normally after converging with the reviewer on an approval:human PR". - CLAUDE.md:265 — "\ninefold-reviewer\ is advisory Tier-0 review." → "\ninefold-reviewer\ is advisory review." (CLAUDE.md is capped at 5 added lines per its own header — this edit only removes characters). - notes/merging.md:170 — "opened design_docs/tools/ to the normal Tier-0 gate" → "opened design_docs/tools/ to the normal review gate" (or equivalent — the sense is "ordinary reviewer + merge gate," not a specific numbered tier). - notes/merging.md:193 — "with shared/ added to rule 1 by Tier-0 review, which found…" → "with shared/ added to rule 1 on review, which found…" (or equivalent).

After the edits, grep -rniE "tier.?0|tier-0" --include='*.md' . should return zero hits outside notes/history.md, design_docs/*.md, and design_docs/tools/tests/testdata/** (see Non-goals).

Non-goals

- The perimeter's "Tier 1"/"Tier 2" merge-authority naming (tools/nflib/authority.py's tier1_authority(), "ordinary Tier 1" in CLAUDE.md and notes/merging.md, design 009's own "Tier 2 (tools/nflib/)" reference to the philosophy's hardened tier). Design 009 deliberately kept this vocabulary — it isn't the leftover this issue is about, and renaming it would reopen a decision design 009 already made. A future round can revisit it if it ever causes real confusion; this issue doesn't argue that case. - Historical/frozen text: notes/history.md (case law, quotes real history — E6 governs it, not this issue), design_docs/001-009.md and their appendices (accepted decisions with a date; amendments get appended, prose isn't rewritten after acceptance), and the doc-diff test fixtures under design_docs/tools/tests/testdata/**. Leave all of these exactly as written. - The legacy tier=N grammar in tools/nflib/verdict.py (the parser that must keep accepting old verdict comments forever, per design 009 T3) and its test fixtures (tools/nflib/test_data/pr_sample.json, engine_test.py's LEGACY_TIER_LABELS cases, verdict_test.py). These intentionally document and test backward compatibility with the pre-rename grammar — do not touch. - Other open issues that happen to use "Tier-0" in their own title (e.g. #678, about review cost) — not this issue's job to rename; they're independent topics that predate this cleanup.

Test plan

No behavior changes anywhere in this issue — pure doc/prompt-file prose. Verify:

1. grep -rniE "tier.?0|tier-0" --include='*.md' . returns only the Non-goals paths listed above. 2. ./presubmit.py --all green (this exercises tools/reviewer/charter_notes_test.py and test_nflib_verdict.py's CHARTER.md-vs-parser contract test — confirm neither breaks; they read CHARTER.md's §C notes-list and its "Verdict format" grammar line, not the title or the "Tier 0 rules" sentence being changed here, but run the suite to be sure). 3. Manual read-through of each changed file to confirm the surrounding sentence still reads correctly after the numbered "Tier N" phrase is removed (a few of the edits above are marked "or equivalent" — exact phrasing is the implementing dev's call, per C1/C6: present tense, least surprising, no history-lesson prose).

PR shape

One PR — this is a single cognitive level (mechanical doc rename, E3), all files are prose/prompt-files, no code changes. CHARTER.md and DEVEL.md sit under docs/**/notes/reviewer.md governance (tools/nflib/perimeter.py's GOVERNANCE) alongside CLAUDE.md, so the PR waits for Aedan's approval regardless of how it's split — no benefit to splitting further.

Open questions

1. Exact replacement wording where marked "or equivalent" above (the notes/merging.md sentences, DESIGN.md's roadmap stage names). Default: ship the dev's best present-tense phrasing preserving the original sentence's meaning — this is wording, not a decision, and isn't worth a review cycle to pre-negotiate. 2. Whether to also touch ## 6. Tier roadmap's content (i.e., is the "reviewer merges PRs itself" future stage still live, or effectively superseded now that design 009 shipped unattended merging via a different mechanism — the perimeter, not reviewer-initiated merges)? Default: rename only, keep the content — deciding whether that roadmap item is still wanted is a product call for Aedan, out of scope for a wording cleanup; flag it in the PR body as a question rather than deleting the section.