ae70f4ec

check: comment claims are verified, not trusted

a73x 2026-08-20 09:15

Commit message

check: comment claims are verified, not trusted

"Comments say why, not how" and "code, comments, docs drift" have been in
CLAUDE.md since the first commit, and in one week this tree drifted about
fifty findings' worth anyway. Prose is instruction. A check that RUNS is
codification — the move build.zig already makes above, where the layer laws
are comptime and a violation is impossible rather than detected.

tools/docscheck.zig, on `zig build check`. Three tiers, two of them gates.

Tier 1, cited symbols must resolve. A `.zig` reference must name a file this
repo has, unless it carries a directory prefix — client_core.zig already cites
ghostty as osc/parsers/clipboard_operation.zig, and turning that convention
into a rule is what makes the prefix mean something. Symbol citations are
checked only in the `module.symbol` form rooted at one of our own modules: 68
of them, `client.recordOnState` and `proto.MsgType` and friends, where both
halves are knowable. Bare identifiers are NOT checked, and that is measured
rather than lazy — of 1138, thirteen failed, and all thirteen were ngtcp2,
ghostty, POSIX or Zig-stdlib names this tool has no corpus for, plus
`unrecordTile`, which client.zig cites precisely to say it does not exist.
This repo wraps three foreign libraries; a bare name cannot tell "renamed last
week" from "belongs to libc", and false positives are how a gate dies.

Tier 2, no project-history codenames. "M18" names nothing reachable from the
code; "the multi-session daemon" still explains itself in a year. The patterns
were measured first, and one nearly went in wrong: `phase` is a live field
here with ten comment mentions, so `Phase N` needs the digit or the gate would
have fired on `cmd.phase`.

Tier 3, comment weight, report-only and staying that way. 430 doc blocks in
src/ outweigh what they document, which is precisely why a gate on it would be
routed around by Friday. `check` prints the count; `zig build doc-report`
lists them; neither can fail.

Every skip class is named in the tool's header with its reason. A skip nobody
wrote down cannot be told from a bug.

Four ways this fails loud, because a check that never ran is the one failure a
green tree cannot show: the tool is built from source here, so "missing" is a
compile error; the file lists are globbed with a fatal on an empty directory;
the tool refuses an empty --check or --index group; and `stdio = .inherit`
makes the run unconditional and carries its own term check. No expectExitCode
alongside it — that call would switch the step back to captured stdio and bury
the violations in a dump.

Red-tested per tier, each violation introduced, watched, reverted:

  1a  `client.recordOnStateRenamed` in wall.zig  -> rc=1, "src/wall.zig:4:
      comment cites `client.recordOnStateRenamed`"
  1b  a reference to walltiles.zig              -> rc=1, named file:line
  2   "M19, Phase 2b"                           -> rc=1, both codenames named
      separately
  3   a 3-line doc block on a 1-line decl       -> listed as "wall.zig:26
      block=3 decl=1", rc stayed 0 — report-only, proven

Test 1a is the one worth keeping: it did not go red. The corpus was built from
whole files, comments included, so a citation resolved against the very
comment that made it and every invented name passed. Fixed to index code lines
only — which immediately exposed the thirteen foreign-symbol findings that
then decided tier 1's scope. A red test that stays green is not a formality.

The ast-grep spike ran first and is recorded in decisions.md with its
measurements. It works — 0.39.6 prebuilt, tree-sitter-zig v1.1.2 compiled to a
.so ast-grep accepts, one 5-byte parse error in 37,756 lines (`await` as an
enum field, which the grammar still reserves). Rejected anyway: `comment` is a
tree-sitter *extra*, so the grammar offers no comment-to-decl attachment and
the pairing stays positional either way. Line arithmetic is exact here because
`zig fmt --check` is already a gate.

tools/ joins zig fmt --check, so the tool is held to the standard it enforces.

zig build check rc=0 · make test rc=0, 586 tests · make e2e rc=0, 55
scenarios / 35 convergence points, pin unmoved.

build.zig

@@ @@ -417,6 +417,101 @@ fn shellGate(b: *std.Build, step: *std.Build.Step) void { @@
+    } else |_| {}
+/// Collect `<sub>/*.zig`, sorted, into `paths`. Globbed rather than listed for
+/// shellGate's reason: a module added tomorrow is covered without anybody
+/// remembering to add it.
+fn zigFilesIn(b: *std.Build, sub: []const u8, paths: *std.ArrayList([]const u8)) void {
+    var dir = b.build_root.handle.openDir(sub, .{ .iterate = true }) catch |e|
+        fatal("doc gate: cannot open {s}/ ({s})", .{ sub, @errorName(e) });
+    defer dir.close();
+    const first = paths.items.len;
+    var it = dir.iterate();
+    while (it.next() catch |e|
+        fatal("doc gate: cannot list {s}/ ({s})", .{ sub, @errorName(e) })) |ent|
+    {
+        if (ent.kind != .file or !std.mem.endsWith(u8, ent.name, ".zig")) continue;
+        paths.append(b.allocator, b.fmt("{s}/{s}", .{ sub, ent.name })) catch @panic("OOM");
+    }
+    if (paths.items.len == first) fatal("doc gate: no .zig files in {s}/", .{sub});
+    std.mem.sort([]const u8, paths.items[first..], {}, struct {
+        fn lt(_: void, a: []const u8, c: []const u8) bool {
+            return std.mem.lessThan(u8, a, c);
+        }
+    }.lt);
+}
+/// The comment-discipline gate (tools/docscheck.zig). CLAUDE.md has said
+/// "comments say why, not how" and "code, comments, docs drift" since the
+/// first commit; a week of drift showed that prose is instruction and only a
+/// check that RUNS is codification — the same reasoning behind the comptime
+/// layer laws above.
+///
+/// The tool is a build tool, not part of the program, so it stays out of the
+/// module table: that table is the program's import graph, and a row there
+/// would claim docscheck is something muxd links.
+///
+/// Nothing about this step can silently skip, which is the whole hazard with
+/// a gate: the tool is built from source in this repo, so "not installed" is a
+/// compile error rather than a green tree; the file lists are globbed with a
+/// fatal on an empty directory; the tool itself refuses an empty --check or
+/// --index group; and `stdio = .inherit` makes the run unconditional, so no
+/// cache hit can stand in for a check that did not happen. Inherit also puts
+/// the violations on the terminal at the moment of failure instead of inside a
+/// captured-stderr dump, and lets tier 3's one-line count be seen at all.
+/// Every source file is still passed as a FILE arg: that is what declares the
+/// dependency and lets the build system resolve the paths.
+fn docGate(b: *std.Build, target: std.Build.ResolvedTarget, check_step: *std.Build.Step) void {
+    const mod = b.createModule(.{
+        .root_source_file = b.path("tools/docscheck.zig"),
+        .target = target,
+        .optimize = .Debug,
+    });
+    const exe = b.addExecutable(.{ .name = "docscheck", .root_module = mod });
+    exe.use_llvm = true;
+    exe.use_lld = true;
+    var checked: std.ArrayList([]const u8) = .empty;
+    zigFilesIn(b, "src", &checked);
+    var indexed: std.ArrayList([]const u8) = .empty;
+    zigFilesIn(b, "src", &indexed);
+    zigFilesIn(b, "test", &indexed);
+    // build.zig is cited by name in src/main.zig's comments and is a real
+    // file of this repo, so it belongs in the corpus even though it is not
+    // under src/ or test/.
+    indexed.append(b.allocator, "build.zig") catch @panic("OOM");
+    // The tool's own rules are asserted, not assumed: its unit tests pin the
+    // codename patterns against the domain vocabulary they must not catch.
+    const unit = b.addTest(.{ .root_module = mod });
+    const run_unit = b.addRunArtifact(unit);
+    run_unit.setName("test docscheck");
+    check_step.dependOn(&run_unit.step);
+    for ([_]struct { name: []const u8, report: bool }{
+        .{ .name = "gate", .report = false },
+        .{ .name = "report", .report = true },
+    }) |variant| {
+        const run = b.addRunArtifact(exe);
+        if (variant.report) run.addArg("--report");
+        run.addArg("--check");
+        for (checked.items) |p| run.addFileArg(b.path(p));
+        run.addArg("--index");
+        for (indexed.items) |p| run.addFileArg(b.path(p));
+        // `.inherit` carries its own term check — a non-zero exit fails the
+        // step — so this needs no expectExitCode, and adding one would
+        // silently switch the step back to captured stdio.
+        run.stdio = .inherit;
+        if (variant.report) {
+            run.setName("docscheck --report");
+            const step = b.step("doc-report", "List doc blocks heavier than the decl they document");
+            step.dependOn(&run.step);
+        } else {
+            run.setName("docscheck");
+            check_step.dependOn(&run.step);
+        }
+    }
+}
+/// Test registration order. Doctrine-laden and deliberately NOT derived
+/// from the layers: delta, cmd, shellint and sockpath run BEFORE server
+/// because their tests are seconds-long and socket-free, while a
@@ @@ -775,7 +870,7 @@ pub fn build(b: *std.Build) void { @@
+    // The format gate. `check = true` makes this a --check run: it fails
+    // naming the offending files and rewrites nothing.
+    const fmt_step = b.step("fmt", "Check formatting (zig fmt --check)");
+    const fmt = b.addFmt(.{ .paths = &.{ "build.zig", "build.zig.zon", "src", "test", "tools" }, .check = true });
+    fmt_step.dependOn(&fmt.step);
+    // The seconds-long pre-commit gate: fmt + unit tests + the shell scripts'
@@ @@ -793,4 +888,5 @@ pub fn build(b: *std.Build) void { @@
+    check_step.dependOn(fmt_step);
+    check_step.dependOn(test_step);
+    shellGate(b, check_step);
+    docGate(b, target, check_step);

docs/decisions.md

@@ @@ -4721,3 +4721,158 @@ and now names both shapes. @@
+The rule this cost re-learning is the one already in these notes: a mutation
+that fails the suite somewhere is not a mutation that fails the leg you aimed
+it at. When the two differ, go get the targeted answer, and quote THAT.
+## 2026-08-20 (the comment-discipline gate: prose became a check)
+CLAUDE.md has said "comments say *why*, not *how*" and "code, comments, docs
+drift" since the first commit. In one week the tree accumulated about fifty
+findings' worth of exactly that drift, and a manual sweep cleaned it. This
+entry is the *next* move: text in CLAUDE.md is instruction, and only a check
+that RUNS is codification — the same reasoning that put the layer laws in
+build.zig's comptime block, where violations are impossible rather than
+detected.
+`tools/docscheck.zig`, wired into `zig build check`. Three tiers, two of them
+gates.
+### The ast-grep spike, and why it was rejected
+Timeboxed, and run before any line of the fallback was written, because
+structural comment-to-decl pairing would have been strictly better than line
+arithmetic if it worked. Every question got a measured answer:
+  Installs pinned?          YES. ast-grep 0.39.6, prebuilt
+                            app-x86_64-unknown-linux-gnu.zip, 7.4MB
+                            compressed / 47MB binary. No build needed.
+  Zig grammar exists?       YES. tree-sitter-grammars/tree-sitter-zig v1.1.2
+                            (2025-09-10), pregenerated parser.c, no external
+                            scanner. `cc -shared -fPIC -O2` produced a 713KB
+                            zig.so exporting tree_sitter_zig, first try, and
+                            ast-grep accepted it as a customLanguage.
+  Parses Zig 0.15 cleanly?  ESSENTIALLY. One ERROR node across all 32 modules
+                            and 37,756 lines: `await` used as an enum field
+                            name in muxa.zig:37 (`verb: enum { …, await }`),
+                            a word the grammar still reserves and Zig 0.15
+                            does not. The error span is 5 bytes on one line —
+                            tree-sitter recovered, and 47 function_declaration
+                            nodes were still found in that file.
+So the tooling works. It was rejected anyway, on the one question that
+actually decides it: **`comment` is a tree-sitter *extra*.** It floats; it is
+not a child of the declaration it documents. The grammar therefore does not
+offer comment-to-decl attachment at all — pairing a doc block with its decl is
+positional line arithmetic under ast-grep exactly as it is without it. Nor
+does the grammar distinguish `///` from `//`, so telling a doc comment from an
+ordinary one means re-reading the raw text either way. What ast-grep would
+have contributed is decl ranges, in exchange for a 47MB pinned binary, a
+vendored grammar, a compile step and a custom-language config inside a
+pre-commit gate.
+The fallback is also *better* here, not merely cheaper, and for a reason
+specific to this repo: `zig fmt --check` is already a gate. Indentation is
+canonical, so a decl's closing brace sits at the decl's own indent and nowhere
+else, and the line arithmetic is exact rather than approximate.
+### Tier 1 — cited symbols must resolve
+Two halves, both tuned against the corpus rather than guessed.
+`.zig` file references, backticked or bare: measured 10 backticked against 99
+bare, and the bare ones are overwhelmingly this repo's own modules — so
+backticking is NOT the discriminator, and both are checked. What discriminates
+is a directory prefix: `osc/parsers/clipboard_operation.zig` and
+`lib/types.zig` name foreign trees (ghostty-vt, the Zig stdlib) and are
+skipped. The repo already wrote references that way; the gate turns the
+convention into a rule, which is what makes the prefix load-bearing — it is
+how a reader, and now the tool, tell "not in this repo" from "renamed last
+week".
+Symbol citations: **only `module.symbol` rooted at one of this repo's own
+modules is checked** — 68 citations, 41 distinct, `client.recordOnState`,
+`proto.MsgType`, `quic.default_port`. Both halves are knowable there: the root
+is a src/*.zig the tool was handed, the tail must appear in code.
+Bare identifiers are NOT checked, and that decision is the measured one. Of
+bare citations, 1125 resolved and 13 did not — and all 13 were names the
+tool cannot possibly verify:
+  ngtcp2_conn_writev_stream, ngtcp2_vec_copy,        ngtcp2's C API
+  ngtcp2_pkt_encode_stream_frame, writev_stream, ndatalen
+  max_title_len                                      ghostty
+  sockaddr_un, isig                                  POSIX
+  keep_sigpipe, NameTooLong                          Zig stdlib
+  scroll_pages                                       a field described in the
+                                                     past tense, deliberately
+  unrecordTile                                       cited by client.zig
+                                                     precisely to say it does
+                                                     NOT exist
+This repo wraps three foreign libraries and names their symbols constantly. A
+bare identifier gives the tool nothing to tell "renamed last week" from
+"belongs to libc", and false positives are the death of a gate. Widening the
+corpus to ghostty, ngtcp2 and the Zig stdlib would fix all eleven foreign
+cases and was rejected for a reason already in these notes: it puts
+machine-specific, sometimes-absent paths inside a pre-commit gate, which is
+the skip hazard wearing a new hat. The gap accepted in exchange is that
+renaming a MODULE silently un-checks every citation rooted at its old name;
+the `.zig` file rule covers module renames from the other side, which is why
+that half is not narrowed the same way.
+Every skip class — phrase, flag, wire, enumlit, numeric, short, keyword,
+placeholder, bare — is named in the tool's own header with its reason. A skip
+nobody wrote down is indistinguishable from a bug.
+### Tier 2 — no project-history codenames in src/*.zig comments
+"M18" and "Phase 3c" name nothing a reader can look up from the code. The
+EVENT survives: "which is why the multi-session daemon is where it surfaced"
+still explains itself in a year. Scope is src/*.zig comment lines only —
+decisions.md, roadmap.md, handoff.md, test/, web/ and commit messages are
+dated journals, and history is what they are for.
+The patterns were measured before being turned on, and one of them nearly went
+in wrong. `M[0-9]{1,2}`: 13 occurrences in src/, every one a milestone, zero
+collisions — safe. But `phase` is *live domain vocabulary* here: `cmd.phase`
+is a real field with ten comment mentions ("phase is already back to
+`at_prompt`"). A pattern on the bare word would have fired on all of them. The
+digit is what makes it a codename, so the rule is `Phase N` / `Task N`, and
+`Tasks 6-7` is caught by the plural.
+The brief said one known leftover, in replica.zig. The gate found **24 sites
+across 12 of the 32 modules** — including the one named. That gap is the
+entry's real content: a sweep that had just been through this tree by hand saw
+one of twenty-four.
+### Tier 3 — comment weight, and deliberately not a gate
+Per doc block: block lines against the decl's own line span. 430 blocks in
+src/ outweigh what they document. That number is exactly why this is a report:
+long comments are earned here often enough that a gate on it would be
+retrained-around within a day. `zig build check` prints the count; `zig build
+doc-report` lists them; neither can fail on it.
+### The red tests, and the one that found a bug
+Each tier got a deliberate violation, watched, and reverted. The tier 1 red
+test failed to go red — and the reason was a real defect: the word corpus was
+built from whole files, comments included, so a citation resolved against **the
+very comment that made it**. Every invented name passed. The corpus is now
+built from code lines only, and re-running on the swept tree immediately
+surfaced the 13 foreign-symbol findings above, which is what forced tier 1's
+scope decision. A red test that stays green is not a formality.
+### Wiring
+`stdio = .inherit` on both runs. Inherit carries its own term check, so a
+non-zero exit fails the step without `expectExitCode` — and adding one would
+have silently switched the step back to captured stdio, hiding the violations
+inside a dump. Inherit also makes the run unconditional: no cache hit can
+stand in for a check that did not happen. The tool is built from source in
+this repo, so "not installed" is a compile error rather than a green tree; the
+file lists are globbed with a fatal on an empty directory; and the tool
+refuses an empty `--check` or `--index` group. Four separate ways for this
+gate to fail loud, because the one failure mode a green tree cannot show is a
+check that never ran.
+`tools/` joined `zig fmt --check`'s paths, which is how the tool's own
+formatting is held to the same standard as the code it inspects.

tools/docscheck.zig

@@ @@ -0,0 +1,572 @@ @@
+//! The comment-discipline gate: "comments say why, not how" and "code,
+//! comments, docs drift" were prose in CLAUDE.md for a week and drifted about
+//! fifty findings' worth. Prose is instruction; a check that RUNS is
+//! codification, which is the same move build.zig's comptime layer laws make.
+//!
+//! Three tiers, two of them gates:
+//!
+//!   1. Every symbol a comment cites must resolve. A drift tripwire, not a
+//!      compiler: a cited name has to appear as a word SOMEWHERE in the CODE
+//!      of src/ or test/ (definition or use — comment lines contribute
+//!      nothing, or a citation would resolve against itself). Renaming
+//!      `sendResync` and leaving the old spelling in a comment is the drift
+//!      this catches.
+//!   2. No project-history codenames in src/*.zig comments. "M18" and
+//!      "Phase 3c" name nothing a reader can look up from the code; the EVENT
+//!      ("the multi-session daemon") survives. Dated journals — decisions.md,
+//!      roadmap.md, handoff.md, commit messages — are where codenames belong
+//!      and are deliberately out of scope, as are test/ and web/.
+//!   3. Doc blocks that outweigh the decl they document. REPORT ONLY, never a
+//!      gate: long comments are often earned in this repo, and the report
+//!      exists so a human looks. `zig build check` prints the count and
+//!      nothing else; `zig build doc-report` lists them.
+//!
+//! Usage:
+//!   docscheck [--report] --check FILE... --index FILE...
+//!
+//! --check names the files whose comments are inspected (src/*.zig).
+//! --index names the files that make up the "does this name exist" corpus
+//! (src/*.zig, test/*.zig, build.zig). Both groups arrive as build-graph file
+//! args so the step re-runs when any of their CONTENTS change — the lesson
+//! web/verify.js paid for. Zero files in either group is a hard error: a check
+//! that never ran passes green forever (decisions.md).
+//!
+//! ## What tier 1 checks, and what it deliberately skips
+//!
+//! Skip classes were chosen by reading the corpus, not guessed — 1138 of 2049
+//! backtick-quoted tokens in src/ survive the filters. False positives are the
+//! death of a gate, so when a class was ambiguous it was dropped and named
+//! here:
+//!
+//!   phrase       anything with whitespace: shell commands (`zig build test`),
+//!                CLI invocations (`mux wall`), key chords (`Ctrl-\ w`),
+//!                argument spellings (`mux TARGET`), prose emphasis.
+//!   flag         leading `-`: `--via`, `--sock`. A flag is a CLI spelling,
+//!                not an identifier, and lives in main.zig's parser as a
+//!                string literal that grep -w would match by accident anyway.
+//!   wire         contains any of / : # ? \ and friends: `quic://`,
+//!                `HOST#SESSION`, `?2004l`. Wire and protocol spellings.
+//!   enumlit      leading `.`: `.none`, `.never`. Resolving an enum tag needs
+//!                the type, which this tool does not have.
+//!   numeric      leading digit: `0x1b`, `2004`.
+//!   short        under 3 characters: `x`, `n`, `fd`. Too short to be a drift
+//!                signal — every 2-letter word matches something.
+//!   keyword      Zig keywords and primitive types. `else` is not a citation.
+//!   placeholder  ALL-CAPS: `HOST`, `PATH`, `CMDLINE`. Usage-text
+//!                placeholders; Zig code has no SCREAMING_CASE consts.
+//!
+//! ...and one more, the largest and the one that cost the most to decide:
+//!
+//!   bare         an unqualified identifier — `sendResync`, `paint_mu`,
+//!                `deinit`. NOT CHECKED, and the reason is measured. Of 1138
+//!                such citations in src/, 1125 resolved and 13 did not, and
+//!                every one of the 13 was a name this tool cannot possibly
+//!                verify: ngtcp2's C API (`ngtcp2_vec_copy`,
+//!                `ngtcp2_conn_writev_stream`), ghostty's `max_title_len`,
+//!                POSIX's `sockaddr_un` and `isig`, Zig std's
+//!                `keep_sigpipe` and `NameTooLong` — plus `unrecordTile`,
+//!                cited by client.zig precisely to say it does NOT exist.
+//!                This repo wraps three foreign libraries and names their
+//!                symbols constantly; a bare identifier gives the tool
+//!                nothing to tell "renamed last week" from "belongs to
+//!                libc". Widening the corpus to ghostty, ngtcp2 and the Zig
+//!                stdlib would fix it and was rejected: it puts
+//!                machine-specific, sometimes-absent paths inside a
+//!                pre-commit gate, which is the skip hazard again.
+//!
+//! What IS checked is `module.symbol` rooted at one of this repo's own
+//! modules — `client.lostMsg`, `proto.MsgType`, `quic.default_port`. Both
+//! halves are then knowable: the root is a src/*.zig this tool was handed,
+//! and the tail must appear in code. That form is also exactly the citation
+//! that goes stale when a module's member is renamed, which is the drift
+//! worth catching. A citation rooted anywhere else — `std.options.x`,
+//! `error.BadPayload`, `conn.r` — names something outside this repo's
+//! jurisdiction and is skipped whole.
+//!
+//! The gap this leaves: renaming a MODULE silently un-checks every citation
+//! rooted at its old name. The `.zig` file rule below covers module renames
+//! from the other side, which is why it is not narrowed the same way.
+//!
+//! `.zig` file references are checked whether or not they are backticked —
+//! measured: 10 backticked against 99 bare, and the bare ones are this repo's
+//! own modules, so backticking is not the discriminator. A reference carrying
+//! a directory prefix that is not `src` or `test` (`osc/parsers/foo.zig`,
+//! `lib/types.zig`) names a foreign tree — ghostty-vt, the Zig stdlib — and is
+//! skipped. That prefix is therefore load-bearing documentation: it is how a
+//! reader, and this tool, tell "not in this repo" from a stale name.
+//!
+//! Trailing comments (code, then `//` on the same line) are skipped: telling
+//! one from `//` inside a string literal needs a lexer, and the 219 candidate
+//! lines in src/ are overwhelmingly `quic://` inside string literals. Only
+//! lines whose first non-space characters are `//` are inspected.
+const std = @import("std");
+fn writeAll(fd: std.posix.fd_t, bytes: []const u8) !void {
+    var off: usize = 0;
+    while (off < bytes.len) off += try std.posix.write(fd, bytes[off..]);
+}
+fn out(comptime fmt: []const u8, args: anytype) void {
+    var buf: [4096]u8 = undefined;
+    const s = std.fmt.bufPrint(&buf, fmt, args) catch return;
+    writeAll(std.posix.STDOUT_FILENO, s) catch {};
+}
+fn err(comptime fmt: []const u8, args: anytype) void {
+    var buf: [4096]u8 = undefined;
+    const s = std.fmt.bufPrint(&buf, fmt, args) catch return;
+    writeAll(std.posix.STDERR_FILENO, s) catch {};
+}
+fn usage() u8 {
+    err("usage: docscheck [--report] --check FILE... --index FILE...\n", .{});
+    return 2;
+}
+// ---------------------------------------------------------------- lexical
+fn isWordByte(c: u8) bool {
+    return std.ascii.isAlphanumeric(c) or c == '_';
+}
+/// A comment line for this tool's purposes: the first non-space bytes are
+/// `//`. Covers `//`, `///` and `//!` alike; excludes trailing comments, for
+/// the reason in the header.
+fn commentBody(line: []const u8) ?[]const u8 {
+    const t = std.mem.trimLeft(u8, line, " \t");
+    if (!std.mem.startsWith(u8, t, "//")) return null;
+    return t;
+}
+fn indentOf(line: []const u8) usize {
+    var i: usize = 0;
+    while (i < line.len and line[i] == ' ') i += 1;
+    return i;
+}
+const keywords = [_][]const u8{
+    "align",          "allowzero", "and",         "anyframe",  "anytype",   "asm",
+    "async",          "await",     "break",       "callconv",  "catch",     "comptime",
+    "const",          "continue",  "defer",       "else",      "enum",      "errdefer",
+    "error",          "export",    "extern",      "false",     "fn",        "for",
+    "if",             "inline",    "linksection", "noalias",   "noreturn",  "nosuspend",
+    "null",           "opaque",    "or",          "orelse",    "packed",    "pub",
+    "resume",         "return",    "struct",      "suspend",   "switch",    "test",
+    "threadlocal",    "true",      "try",         "undefined", "union",     "unreachable",
+    "usingnamespace", "var",       "volatile",    "while",     "void",      "bool",
+    "type",           "usize",     "isize",       "anyerror",  "anyopaque", "comptime_int",
+    "comptime_float",
+};
+fn isKeyword(tok: []const u8) bool {
+    for (keywords) |k| if (std.mem.eql(u8, k, tok)) return true;
+    // Primitive integer/float types are generated, not listed: u8, i32, f64…
+    if (tok.len >= 2 and (tok[0] == 'u' or tok[0] == 'i' or tok[0] == 'f')) {
+        var all_digits = true;
+        for (tok[1..]) |c| if (!std.ascii.isDigit(c)) {
+            all_digits = false;
+        };
+        if (all_digits) return true;
+    }
+    return false;
+}
+const Class = enum { check, phrase, flag, wire, enumlit, numeric, short, keyword, placeholder, other };
+fn classify(tok: []const u8) Class {
+    if (tok.len == 0) return .other;
+    for (tok) |c| if (c == ' ' or c == '\t') return .phrase;
+    if (tok[0] == '-') return .flag;
+    for (tok) |c| switch (c) {
+        '/', ':', '#', '?', '\\', '@', '%', '"', '\'', '(', ')', '[', ']', '{', '}', '<', '>', '|', '&', '*', '+', '=', ',', ';', '!', '~', '^', '$' => return .wire,
+        else => {},
+    };
+    if (tok[0] == '.') return .enumlit;
+    if (std.ascii.isDigit(tok[0])) return .numeric;
+    if (tok.len < 3) return .short;
+    if (isKeyword(tok)) return .keyword;
+    var has_lower = false;
+    for (tok) |c| if (std.ascii.isLower(c)) {
+        has_lower = true;
+    };
+    if (!has_lower) return .placeholder;
+    for (tok) |c| if (!isWordByte(c) and c != '.') return .other;
+    return .check;
+}
+// ------------------------------------------------------------------ tiers
+const Finding = struct {
+    file: []const u8,
+    line: usize,
+    text: []const u8,
+};
+/// Tier 2's codename patterns. Each returns the matched span's length at `i`,
+/// or 0. Measured against the corpus before being turned on:
+///
+///   `M<digits>`  13 occurrences in src/, every one a milestone name, zero
+///                collisions — uppercase M only, because that is the
+///                convention and lowercase `m8` would be a coin flip.
+///   `Phase N` / `Task N`  the NUMBER is what makes it a codename. Bare
+///                "phase" is domain vocabulary here — `cmd.phase` is a live
+///                field with 10 comment mentions — so the digit is required.
+fn codenameAt(s: []const u8, i: usize) usize {
+    // M-web: the browser-client milestone.
+    if (std.ascii.startsWithIgnoreCase(s[i..], "M-web")) {
+        if (i == 0 or !isWordByte(s[i - 1])) return 5;
+    }
+    // M<digit><digit?> as a milestone name.
+    if (s[i] == 'M' and (i == 0 or !isWordByte(s[i - 1]))) {
+        var n: usize = 1;
+        while (i + n < s.len and n <= 2 and std.ascii.isDigit(s[i + n])) n += 1;
+        if (n > 1 and (i + n == s.len or !isWordByte(s[i + n]))) return n;
+    }
+    // Phase N / Task N, plural or not, any case, optional a/b/c suffix.
+    for ([_][]const u8{ "phases", "phase", "tasks", "task" }) |w| {
+        if (!std.ascii.startsWithIgnoreCase(s[i..], w)) continue;
+        if (i != 0 and isWordByte(s[i - 1])) continue;
+        var j = i + w.len;
+        const before_space = j;
+        while (j < s.len and (s[j] == ' ' or s[j] == '\t')) j += 1;
+        if (j == before_space or j >= s.len or !std.ascii.isDigit(s[j])) continue;
+        while (j < s.len and std.ascii.isDigit(s[j])) j += 1;
+        if (j < s.len and s[j] >= 'a' and s[j] <= 'c') j += 1;
+        return j - i;
+    }
+    return 0;
+}
+/// Where a `.zig` reference sits: the basename, and the directory prefix that
+/// precedes it (empty when there is none). `replica.zig/wasm_core.zig` — the
+/// repo's way of writing "both of these" — yields an empty prefix for the
+/// second name, because a prefix segment that is itself a .zig file is not a
+/// directory.
+const ZigRef = struct { name: []const u8, prefix: []const u8 };
+fn zigRefAt(s: []const u8, dot: usize) ?ZigRef {
+    if (dot + 4 > s.len or !std.mem.eql(u8, s[dot .. dot + 4], ".zig")) return null;
+    if (dot + 4 < s.len and isWordByte(s[dot + 4])) return null; // .zigzag
+    var start = dot;
+    while (start > 0 and isWordByte(s[start - 1])) start -= 1;
+    if (start == dot) return null;
+    var prefix: []const u8 = "";
+    if (start > 0 and s[start - 1] == '/') {
+        var p = start - 1;
+        while (p > 0 and (isWordByte(s[p - 1]) or s[p - 1] == '.' or s[p - 1] == '-' or s[p - 1] == '/')) p -= 1;
+        const cand = s[p .. start - 1];
+        if (!std.mem.endsWith(u8, cand, ".zig")) prefix = cand;
+    }
+    return .{ .name = s[start .. dot + 4], .prefix = prefix };
+}
+fn prefixIsOurs(prefix: []const u8) bool {
+    return prefix.len == 0 or std.mem.eql(u8, prefix, "src") or
+        std.mem.eql(u8, prefix, "test") or std.mem.eql(u8, prefix, "./src") or
+        std.mem.eql(u8, prefix, "./test");
+}
+// ------------------------------------------------------------------- main
+pub fn main() !u8 {
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+    const args = try std.process.argsAlloc(alloc);
+    defer std.process.argsFree(alloc, args);
+    var report = false;
+    var check_files: std.ArrayList([]const u8) = .empty;
+    defer check_files.deinit(alloc);
+    var index_files: std.ArrayList([]const u8) = .empty;
+    defer index_files.deinit(alloc);
+    var group: enum { none, check, index } = .none;
+    var ai: usize = 1;
+    while (ai < args.len) : (ai += 1) {
+        const a = args[ai];
+        if (std.mem.eql(u8, a, "--report")) {
+            report = true;
+        } else if (std.mem.eql(u8, a, "--check")) {
+            group = .check;
+        } else if (std.mem.eql(u8, a, "--index")) {
+            group = .index;
+        } else switch (group) {
+            .none => return usage(),
+            .check => try check_files.append(alloc, a),
+            .index => try index_files.append(alloc, a),
+        }
+    }
+    // A gate handed nothing to gate is the "check that never ran" failure
+    // mode, and it passes green forever. Refuse instead.
+    if (check_files.items.len == 0 or index_files.items.len == 0) {
+        err("docscheck: empty --check or --index group ({d} check, {d} index) — " ++
+            "a gate with no inputs passes green forever\n", .{ check_files.items.len, index_files.items.len });
+        return 2;
+    }
+    // The corpus: every word in src/ and test/, and every .zig basename.
+    var words: std.StringHashMapUnmanaged(void) = .empty;
+    defer words.deinit(alloc);
+    var basenames: std.StringHashMapUnmanaged(void) = .empty;
+    defer basenames.deinit(alloc);
+    var bufs: std.ArrayList([]u8) = .empty;
+    defer {
+        for (bufs.items) |b| alloc.free(b);
+        bufs.deinit(alloc);
+    }
+    for (index_files.items) |p| {
+        const f = std.fs.cwd().openFile(p, .{}) catch |e| {
+            err("docscheck: cannot open index file {s} ({s})\n", .{ p, @errorName(e) });
+            return 2;
+        };
+        defer f.close();
+        const src = try f.readToEndAlloc(alloc, 64 * 1024 * 1024);
+        try bufs.append(alloc, src);
+        try basenames.put(alloc, std.fs.path.basename(p), {});
+        // CODE only: a comment line contributes no words. Found by the red
+        // test — with comments indexed, a citation resolved against the very
+        // comment that made it, and every invented name passed. A comment
+        // that cites itself is not evidence that the symbol exists.
+        var il = std.mem.splitScalar(u8, src, '\n');
+        while (il.next()) |line| {
+            if (commentBody(line) != null) continue;
+            var i: usize = 0;
+            while (i < line.len) {
+                if (!isWordByte(line[i]) or std.ascii.isDigit(line[i])) {
+                    i += 1;
+                    continue;
+                }
+                const s = i;
+                while (i < line.len and isWordByte(line[i])) i += 1;
+                try words.put(alloc, line[s..i], {});
+            }
+        }
+    }
+    var t1: std.ArrayList(Finding) = .empty;
+    defer t1.deinit(alloc);
+    var t2: std.ArrayList(Finding) = .empty;
+    defer t2.deinit(alloc);
+    var t3: std.ArrayList([]const u8) = .empty;
+    defer {
+        for (t3.items) |s| alloc.free(s);
+        t3.deinit(alloc);
+    }
+    var lines: std.ArrayList([]const u8) = .empty;
+    defer lines.deinit(alloc);
+    for (check_files.items) |p| {
+        const f = std.fs.cwd().openFile(p, .{}) catch |e| {
+            err("docscheck: cannot open {s} ({s})\n", .{ p, @errorName(e) });
+            return 2;
+        };
+        defer f.close();
+        const src = try f.readToEndAlloc(alloc, 64 * 1024 * 1024);
+        try bufs.append(alloc, src);
+        const name = std.fs.path.basename(p);
+        lines.clearRetainingCapacity();
+        var it = std.mem.splitScalar(u8, src, '\n');
+        while (it.next()) |l| try lines.append(alloc, l);
+        for (lines.items, 1..) |line, lineno| {
+            const body = commentBody(line) orelse continue;
+            // Tier 2 — history codenames.
+            var i: usize = 0;
+            while (i < body.len) {
+                const n = codenameAt(body, i);
+                if (n == 0) {
+                    i += 1;
+                    continue;
+                }
+                try t2.append(alloc, .{ .file = name, .line = lineno, .text = body[i .. i + n] });
+                i += n;
+            }
+            // Tier 1a — .zig file references, backticked or bare.
+            i = 0;
+            while (i < body.len) : (i += 1) {
+                const r = zigRefAt(body, i) orelse continue;
+                if (!prefixIsOurs(r.prefix)) continue; // foreign tree, deliberate
+                if (!basenames.contains(r.name))
+                    try t1.append(alloc, .{ .file = name, .line = lineno, .text = r.name });
+            }
+            // Tier 1b — backtick-quoted symbol citations.
+            i = 0;
+            while (i < body.len) {
+                if (body[i] != '`') {
+                    i += 1;
+                    continue;
+                }
+                const close = std.mem.indexOfScalarPos(u8, body, i + 1, '`') orelse break;
+                const tok = body[i + 1 .. close];
+                i = close + 1;
+                if (classify(tok) != .check) continue;
+                // Only `module.symbol`, rooted at one of THIS repo's modules.
+                // See the header: a bare identifier is unverifiable here.
+                var segs = std.mem.splitScalar(u8, tok, '.');
+                const root = segs.next() orelse continue;
+                var modfile: [64]u8 = undefined;
+                if (root.len + 4 > modfile.len) continue;
+                @memcpy(modfile[0..root.len], root);
+                @memcpy(modfile[root.len..][0..4], ".zig");
+                if (!basenames.contains(modfile[0 .. root.len + 4])) continue;
+                while (segs.next()) |seg| {
+                    if (classify(seg) != .check) continue;
+                    if (!words.contains(seg))
+                        try t1.append(alloc, .{ .file = name, .line = lineno, .text = tok });
+                }
+            }
+        }
+        // Tier 3 — doc blocks heavier than the decl they document. Line
+        // arithmetic, not a parser, and exact enough because `zig fmt --check`
+        // is already a gate: indentation is canonical, so a decl's closing
+        // brace sits at the decl's own indent and nowhere else.
+        var li: usize = 0;
+        while (li < lines.items.len) {
+            const t = std.mem.trimLeft(u8, lines.items[li], " \t");
+            // `//!` is a file header, attached to no decl.
+            if (!std.mem.startsWith(u8, t, "///")) {
+                li += 1;
+                continue;
+            }
+            const block_start = li;
+            while (li < lines.items.len and
+                std.mem.startsWith(u8, std.mem.trimLeft(u8, lines.items[li], " \t"), "///")) li += 1;
+            const block = li - block_start;
+            if (li >= lines.items.len) break;
+            const decl = li;
+            const dt = std.mem.trimLeft(u8, lines.items[decl], " \t");
+            if (dt.len == 0 or std.mem.startsWith(u8, dt, "//")) continue;
+            const indent = indentOf(lines.items[decl]);
+            // The decl's span: every following line indented deeper, plus the
+            // closing brace that returns to the decl's own indent.
+            var last = decl;
+            var j = decl + 1;
+            while (j < lines.items.len) : (j += 1) {
+                const lt = std.mem.trim(u8, lines.items[j], " \t\r");
+                if (lt.len == 0) continue;
+                if (indentOf(lines.items[j]) > indent) {
+                    last = j;
+                    continue;
+                }
+                if (indentOf(lines.items[j]) == indent and lt[0] == '}') last = j;
+                break;
+            }
+            const span = last - decl + 1;
+            if (block > span) {
+                const nm = declName(dt);
+                const s = try std.fmt.allocPrint(alloc, "{s}:{d}  block={d} decl={d}  {s}\n", .{ name, decl + 1, block, span, nm });
+                try t3.append(alloc, s);
+            }
+        }
+    }
+    for (t1.items) |v|
+        err("src/{s}:{d}: comment cites `{s}`, which appears nowhere in src/ or test/\n", .{ v.file, v.line, v.text });
+    for (t2.items) |v|
+        err("src/{s}:{d}: comment names the project-history codename \"{s}\" — " ++
+            "name the event instead; codenames belong in docs/decisions.md\n", .{ v.file, v.line, v.text });
+    if (report) {
+        out("doc blocks heavier than the decl they document ({d}):\n", .{t3.items.len});
+        for (t3.items) |s| out("  {s}", .{s});
+        out("\nReport only, never a gate: a long comment is often earned here.\n", .{});
+    } else {
+        out("docscheck: {d} files, {d} doc blocks outweigh their decl " ++
+            "(`zig build doc-report` lists them)\n", .{ check_files.items.len, t3.items.len });
+    }
+    if (t1.items.len + t2.items.len > 0) {
+        err("docscheck: {d} unresolved citation(s), {d} codename(s)\n", .{ t1.items.len, t2.items.len });
+        return 1;
+    }
+    return 0;
+}
+/// Best-effort name for the report's third column. Cosmetic: the file:line is
+/// what a reader navigates by.
+fn declName(dt: []const u8) []const u8 {
+    var it = std.mem.tokenizeAny(u8, dt, " \t(:=");
+    while (it.next()) |w| {
+        if (std.mem.eql(u8, w, "pub") or std.mem.eql(u8, w, "export") or
+            std.mem.eql(u8, w, "extern") or std.mem.eql(u8, w, "inline") or
+            std.mem.eql(u8, w, "threadlocal") or std.mem.eql(u8, w, "comptime") or
+            std.mem.eql(u8, w, "fn") or std.mem.eql(u8, w, "const") or
+            std.mem.eql(u8, w, "var")) continue;
+        return w;
+    }
+    return dt;
+}
+test "codenames are recognised, domain vocabulary is not" {
+    // The corpus that set these rules: `cmd.phase` is a live field with ten
+    // comment mentions, so bare "phase" must never fire.
+    try std.testing.expect(codenameAt("M18 landed", 0) == 3);
+    try std.testing.expect(codenameAt("pre-M18 payload", 4) == 3);
+    try std.testing.expect(codenameAt("M-web Task 1", 0) == 5);
+    try std.testing.expect(codenameAt("Phase 3c of the wall", 0) == 8);
+    try std.testing.expect(codenameAt("Tasks 6-7", 0) == 7);
+    try std.testing.expect(codenameAt("phase is back to at_prompt", 0) == 0);
+    try std.testing.expect(codenameAt("the attach-or-create task on", 24) == 0);
+    // A word that merely starts with M, and a symbol that embeds one.
+    try std.testing.expect(codenameAt("MAX8 is a bound", 0) == 0);
+    try std.testing.expect(codenameAt("frame_M18", 6) == 0);
+}
+test "citation classes match what the corpus actually contains" {
+    try std.testing.expectEqual(Class.check, classify("sendResync"));
+    try std.testing.expectEqual(Class.check, classify("state_since_attach"));
+    try std.testing.expectEqual(Class.check, classify("MsgType"));
+    try std.testing.expectEqual(Class.check, classify("deinit"));
+    try std.testing.expectEqual(Class.phrase, classify("zig build test"));
+    try std.testing.expectEqual(Class.flag, classify("--sock"));
+    try std.testing.expectEqual(Class.wire, classify("quic://"));
+    try std.testing.expectEqual(Class.wire, classify("HOST#SESSION"));
+    try std.testing.expectEqual(Class.enumlit, classify(".none"));
+    try std.testing.expectEqual(Class.short, classify("fd"));
+    try std.testing.expectEqual(Class.keyword, classify("unreachable"));
+    try std.testing.expectEqual(Class.keyword, classify("u16"));
+    try std.testing.expectEqual(Class.placeholder, classify("CMDLINE"));
+    try std.testing.expectEqual(Class.numeric, classify("0x1b"));
+}
+/// Resolve the LAST `.zig` in `s`, the way the scanner reaches it.
+fn lastRef(s: []const u8) ZigRef {
+    return zigRefAt(s, std.mem.lastIndexOf(u8, s, ".zig").?).?;
+}
+test "a .zig reference knows whose tree it names" {
+    // The prefix is the discriminator, and this repo already writes it:
+    // client_core.zig cites ghostty as osc/parsers/clipboard_operation.zig.
+    const ours = lastRef("see server.zig for");
+    try std.testing.expectEqualStrings("server.zig", ours.name);
+    try std.testing.expect(prefixIsOurs(ours.prefix));
+    const foreign = lastRef("(osc/parsers/clipboard_operation.zig)");
+    try std.testing.expectEqualStrings("clipboard_operation.zig", foreign.name);
+    try std.testing.expectEqualStrings("osc/parsers", foreign.prefix);
+    try std.testing.expect(!prefixIsOurs(foreign.prefix));
+    // "both of these" is written with a slash and must not read as a path.
+    const pair = lastRef("replica.zig/wasm_core.zig call");
+    try std.testing.expectEqualStrings("wasm_core.zig", pair.name);
+    try std.testing.expect(prefixIsOurs(pair.prefix));
+    try std.testing.expectEqualStrings("src", lastRef("src/protocol.zig").prefix);
+}
+test "only leading // is a comment, so string literals are left alone" {
+    try std.testing.expect(commentBody("    /// why, not how") != null);
+    try std.testing.expect(commentBody("//! module header") != null);
+    try std.testing.expect(commentBody("    const u = \"quic://box:4433\";") == null);
+    try std.testing.expect(commentBody("    ov.setMode(); // raw") == null);
+}