Study: tier-true rename campaign report — the complete record and roadmap

Status: FINAL for stage 1 (rehearsal GREEN, 2026-08-16). This is the operator-ordered full report: everything done, how it was done, the agents and their instructions, the mediation machinery, the telemetry, and the generalized roadmap for future refactoring work on this or any project. Companion documents: rehearsal study docs/research/tier-true-rename-rehearsal-2026-08-16.md, campaign plan docs/planning/TIER-TRUE-RENAME-CAMPAIGN.md, thesis docs/research/language-as-architecture-thesis-v2.md, measurements docs/research/e2-name-comprehension-2026-08-16.md and docs/research/doc-audit-study-2026-08-16.md.

Abstract

We renamed all 394 crates of this workspace so that every name states the crate's true architectural layer — and we did it without hand-editing a single file. The rename was planned as 35,879 database rows (one row per place a name appears), applied by a deliberately simple program that verifies each row before replacing it, into a throwaway copy of the repository. The copy was compiled, tested, and doc-checked; every failure became a named class with a tested rule in the tools, and the copy was thrown away and regenerated until it came up green. It is green: the renamed world builds, its 394 test suites pass, and its layer registry is consistent. Nothing has been merged — the green copy and this report are the evidence the operator rules on. The reason for the work: measurement E2 showed the old names actively misinform language models (models read the brand prefix as an architectural claim and answer wrong), while tier-true names are understood with no extra context. Correct names are the cheapest context there is.

Diagrams

The campaign end to end:

flowchart LR
    E2[measure: E2 name-only\ncomprehension test] --> RULE[operator ruling:\nrename, staged]
    MOCK[price: crate mock in DB\n35,879 reference sites] --> RULE
    RULE --> PLAN[(rename_edit rows\nplan-as-data)]
    PLAN --> EXPORT[applier: verify\nthen replace]
    EXPORT --> WT[rehearsal worktree\ndisposable copy]
    WT --> PROBES[probes: build, test,\ndoc-truth, check-deps]
    PROBES -->|failure class| RULES[tested rule in\nplanner or applier]
    RULES --> PLAN
    PROBES -->|GREEN| GATE[stage-2 merge gate:\noperator ruling]

The iterate-to-green loop that produced the result:

flowchart TD
    R[replay rows into fresh copy] --> P{probe}
    P -->|red| C[name the failure CLASS]
    C --> T[write a TESTED rule in the tool\nnever edit the copy by hand]
    T --> R
    P -->|green| V[verdict + full accounting\nof every refused row]

Rounds to green (applied rows and probe state per round):

flowchart LR
    r1[R1-4: export rules\n~30,700 applied] --> r5[R5-6: build red\nTOML + rs-grammar classes]
    r5 --> r7[R7: build GREEN\ntest red: include_str]
    r7 --> r8[R8: replan +3,185 rows\nmd + registry classes]
    r8 --> r9[R9: 33,931 applied\nbuild GREEN]
    r9 --> r10[R10: tests GREEN\nlayers GREEN -> VERDICT]

What was done, in order

1. Measured the problem (E2). 41 crates, name-only layer classification, two model tiers. Current names: 24/41 (haiku), 16/41 (sonnet), and 28 of 82 answers misread the brand prefix as meaning "foundational". Tier-true names: 41/41 on both tiers. Conclusion: the names inject false facts; renaming removes a standing source of model error and the context spent correcting it. 2. Priced the rename in the database before touching anything. The crate mock (crate_desired_state, 394 target names) counted every reference class from the corpus mirror: dependent manifests, source idents, doc mentions, registry rows, consumer-repo locks. The consumer cost collapsed to 128 one-line package = aliases across 12 repos. The ruling to rename was made on these two numbers together — benefit (E2) and cost (mock) — not on taste. 3. Planned the rename as data. tools-org-knowledge corpus rename-plan wrote one rename_edit row per site: file, line, before-text, after-text, edit class. Final plan: 35,879 rows (registry 12,988 · doc_ref 10,388 · ident 6,959 · other 3,539 · manifest 2,005). 4. Applied by a deliberately simple exporter. rename-export refuses to run anywhere but a named worktree, verifies every row against the file's current content before replacing (whole-word, grammar-aware), refuses loudly when a row is stale, and prints a taxonomy of every refusal. Replayable: same rows, same result. 5. Probed and iterated. 10 rounds (plus one discarded plan regression). Every red probe became a failure class and a tested rule in the planner or applier — never a hand-edit in the copy. The full class table with commits is in the rehearsal study. 6. Verdict GREEN, with every refused row classified (1,948 stale = correct refusals: paths that must not rename, compound tokens, lines already edited) and a six-item merge-time list for stage 2.

Before / after

Name examples (layer prefix carries the classification):

Measured comprehension (E2):

Process comparison:

Agents used and their instructions

Two agents did this work, coordinated by message passing; one owner per file at all times.

1. Coordinator (this session). Held the operator's constraints, ruled on scope questions, relayed checkpoints, and never edited fork-owned files. Also authored the campaign plan, thesis v2, and this report. 2. Rehearsal fork (background agent, charter set at spawn): own the rename_edit batch and the rehearsal worktree; iterate export→probe until green; record telemetry per round; write the study; never merge, push, or present the branch as in-play. The coordinator's directives to it during the run, verbatim:

"Operator has made the rename rehearsal the top-focus item. Continue iterate-to-green without pausing between rounds. [...] keep recording round telemetry to the tier-true-rename-2026-08-16 series and keep the study doc current as you go, not at the end. Constraints unchanged: worktree only, experiment only, no merge/push/use of the result."

"Operator directive: continue to green and deliver the final verdict. Run rounds back-to-back until probes are green (build + test + tools-doc-truth classified + layers), then report the final verdict in this exact shape: (1) verdict line [...] (7) study doc path + final commit hash in the rehearsal branch."

"Operator directive: the outcome target is GREEN — keep iterating until it is earned. That means: rerun the flaked test on the quiet host; if it passes consistently (3x), record it as contention and call the suite green. If it fails deterministically, it is a real failure class — name it, add the tested rule, re-export, re-probe, and keep going until green. Do not declare green on anything unproven; the verdict must survive the operator rerunning the probes himself."

The last directive is the honesty contract in one paragraph: green is a measurement, not a declaration. The fork's own discipline matched it — it retracted a round-5 "green" when it found a pipe had masked a red build, and re-ran its final suite on a quiet host rather than call a contended run decisive.

Sharding and semantic mediation

The campaign ran on the mediation stack built in sprints 4.8–4.11:

• Ratified registries as single sources. tier-vocabulary.tsv (the

six tiers), lexicon.tsv, doc-skeletons.tsv, noun-senses.tsv, model-routing.tsv. The rename's target names derive from the ratified tier vocabulary — the rename is the registry projected onto the crate namespace.

• Mechanical detectors (D9–D14) with shrink-only baselines. The same

tools-doc-truth run that gates every commit gated the renamed tree; its 374 residual findings were attributed class-by-class rather than waved through.

• Word-level hooks in the write path. The lexicon pre-commit hook

rejected a banned metaphor in this campaign's own thesis draft minutes before this report was written (the rejected word is quoted below with attribution) — the machinery polices its authors, which is the point. <!-- NAMING-ALLOW: quoting the exact word the hook rejected, as a record --> Rejected term: "load-bearing"; replacement: "model inputs treated as facts".

• Plan rows as shards. Each rename_edit row is a judgment-free unit

a program can verify independently — the same sharding principle as the doc-audit's byte-verbatim shards with content hashes, applied to edits instead of prompts. Model judgment was spent only where it belongs: naming failure classes and writing rules. Counting, matching, and replacing were code (operator rule 14: AI never counts what code can count).

• One-noun-one-referent and grammar-aware replacement. The .rs

grammar split (identifier form in code, package form in strings and comments) and the path-shaped shield are semantic mediation at the character level: the applier decides what a token MEANS in its position before it may replace it.

Telemetry

Complete series tier-true-rename-2026-08-16 in run_measurement (provenance on every row); flake criterion: 3x isolation pass on a quiet host = contention:

Final: 33,931 applied · 1,948 stale (member-path 212, path-shielded 378, embedded-token 881, shadowed/line-drift 477) · 0 lost · 6/6 flake isolation passes · ~1.1 h recorded round time · rehearsal commit 07de7d57 on rehearse/tier-true-rename.

Why this serves the linguistic-programming goal

The goal (operator, verbatim intent): correctness of language so the model needs less context to be correct. This campaign is that goal executed at the namespace level:

1. Names became facts. After the rename, reading a crate name IS reading its architectural classification — no priming document, no guessing, no misread brand claim. E2 measures the gain: 100% name-only comprehension, up from 41–61%, with the misinformation pattern gone. 2. The vocabulary is enforced, not aspirational. Registries feed detectors; detectors gate commits; baselines only shrink. Drift is a failing check, not a review comment. 3. The refactor method is itself linguistic. Failure classes are NAMED; stale rows carry a taxonomy; rules are tested sentences about what a token means in a position. The campaign's artifacts speak the same ratified vocabulary they install. 4. Future speech gets cheaper. Every future instruction — human or harness — that names a crate now transmits its layer for free. This is the substrate the guided development harness translates operator speech onto.

Roadmap: how to run this on any repository

The generalized playbook, each step with its exit condition:

1. Mirror the repo into a database (files, docs, dependencies, references). Exit: counts from SQL match spot checks. 2. Measure the linguistic defect with a real-model experiment (E2 pattern: name-only tasks, two model tiers, score against ground truth). Exit: a number for the harm, not an opinion. 3. Ratify the target vocabulary with the human owner. Registries are TSV seeds, single-source. Exit: written ruling. 4. Price the change in the database before any edit: one desired-state row per artifact, one count per reference class. Exit: benefit and cost numbers side by side; ruling to proceed. 5. Plan as rows: term-level before/after per site, edit class per row, batch id. Exit: class counts reconciled against the mock. 6. Build a refusing applier: worktree-only guard, verify-then-replace, whole-word with grammar awareness, loud stale taxonomy, replayable. Exit: same rows twice = identical tree. 7. Probe with the repo's own truth machinery: build, full tests, doc/lint gates, registry consistency — pipefail everywhere. Exit: every red names a class. 8. Iterate to green: every class becomes a tested rule in the tools; never hand-edit the generated tree; reset and replay. Exit: green probes AND every refused row classified AND a written merge-time list. 9. Gate the merge on a human ruling with the green tree, the study, and the list in hand. Exit: the owner merges (or doesn't) — the rehearsal never self-promotes. 10. Record everything as research: telemetry series per round, study document updated live, failure-class table with commits. Exit: the next campaign starts from rules, not memories.

What follows

• Stage 2 (operator-gated): merge = rehearsal diff + baseline re-settle +

D1 fact redefinition + mirror regeneration + git-hook reinstall + the six prefix-keyed mechanism migrations, in one change.

• Stage 3: generate the 128 consumer alias lines (12 repos).
• Stage 4: live-doc migration through the loop; archives stay history.
• Research: the held-out control (same tasks, old vs new names) that

upgrades thesis v2 from experience report to tested claim.

• Base defects surfaced for their owners: location.rs untracked on

master, BUG-0006 flake, cited-but-untracked report files.