Skip to content

fix(gates): stop citing out-of-repo session instruments and guard the rule - #311

Merged
argszero merged 1 commit into
mainfrom
fix/no-citation-of-out-of-repo-instruments
Sep 27, 2026
Merged

argszero merged 1 commit into
mainfrom
fix/no-citation-of-out-of-repo-instruments

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Repo prose (src/** comments and ui/README.md) cited "the instrument that proves the other half" by file name — jsdom probes, Python compile gates, edit sheets. Those instruments live outside the repository and never entered it (there is no JS runner in CI), so every such citation is a dead link for every reader.

The repo had already written the convention down — state_gate.rs's R165 block says "the instrument lives outside the repo, so no file name here (#606)" — but nothing enforced it. Recon measured 62 occurrences violating it, one of them in that same file, three lines after that very sentence.

This PR keeps the statement and drops the file name at all 62 sites, and adds src/citation_gate.rs so the rule has an enforcer.

Related Issue

No issue was open; this came out of repository recon.

Changes

  • 62 prose sites stop naming out-of-repo instruments — src/state_gate.rs 42, ui/README.md 17, src/i18n_pack.rs 2, ui/js/app.js 1. The surrounding sentence is preserved; exactly one line changes per site (62 insertions / 62 deletions).
  • New gate src/citation_gate.rs (test-only, registered as #[cfg(test)] mod citation_gate;). Corpus = the repo's text files, walked at runtime from CARGO_MANIFEST_DIR so new files enter scope automatically; for .rs only the comment text is scanned (the citation sites live in comments, while this gate's own synthetic fixtures live in string literals). Site = a backticked, file-shaped token; verdict = basename matches the session-instrument naming (^[rc][0-9]+[-_]) and no file of that name exists.
  • ui/README.md records the convention (new section) together with its exact scope.
  • ui/js/app.js was touched, so its cache-bust token was bumped: app.js?v=20260927-1 → -2.

Tests

  • cargo test — 413 passed / 0 failed (baseline 409; +4 new tests)
  • cargo fmt --check — rc=0
  • clippy --all-targets -- -D warnings — rc=0
  • New tests — four: the rule itself; a positive control asserting the corpus really contains ≥200 backticked file-shaped tokens (so "0 violations" cannot be confused with a blind scanner); a synthetic teeth set (comment citation → flagged, string literal → not, present file → not, runtime path → not by declared scope, Markdown → flagged); and the naming predicate's precision (no real repo file name is caught).

A/B on the live tree: injecting one citation into a .rs comment and one into ui/README.md makes the rule fail, naming both file:line locations, while the other three tests stay green.

Scope (stated honestly)

The predicate is naming shape + presence, not "any out-of-repo reference". It deliberately does not flag runtime artefacts (<data>/config.toml), negated statements ("the repo has no ui/package.json"), historical changelog entries ("Removed data/models.example.json") or output-file placeholders (aitokenpool-transactions-YYYYMMDD.csv) — those are either runtime facts or true precisely because the file does not exist.

Checklist

  • 分支命名符合约定(fix/<描述>)
  • Commit message 使用 Conventional Commits 格式
  • 单一职责,改动最小化

… rule

Repo prose (src/** comments and ui/README.md) cited "the instrument that proves the
other half" by file name -- jsdom probes, Python compile gates, edit sheets. Those
instruments live outside the repository and never entered it (there is no JS runner
in CI), so every such citation is a dead link for every reader.

The repo had already written the convention down -- state_gate.rs's R165 block says
"the instrument lives outside the repo, so no file name here (#606)" -- but nothing
enforced it: 62 occurrences violate it, one of them in that same file, three lines
after that very sentence.

Keep the statement, drop the file name, at all 62 sites. Add src/citation_gate.rs so
the rule has an enforcer: for every backticked file-shaped token in the repo's text
files (Rust comments only for .rs, since the sites live in comments and this gate's
own fixtures live in string literals), if the basename matches the session-instrument
naming (^[rc][0-9]+[-_]) and no file of that name exists, the test fails. The scope is
deliberately narrow: runtime artefacts (<data>/config.toml), negated statements,
historical entries and output-file placeholders are not flagged -- they are either
runtime facts or true precisely because the file does not exist.

Evidence: 62 sites fixed (62 insertions / 62 deletions, one line each); cargo test
409 -> 413 (four new tests: the rule, a >=200-token positive control, the synthetic
teeth set, and the naming predicate); cargo fmt --check rc=0; clippy --all-targets
-D warnings rc=0. A/B on the live tree: injecting one citation into a .rs comment and
one into ui/README.md makes the rule fail with both file:line locations, while the
other three tests stay green.
@argszero
argszero merged commit 11aaba5 into main Sep 27, 2026
2 checks passed
@argszero
argszero deleted the fix/no-citation-of-out-of-repo-instruments branch September 27, 2026 13:35
@argszero argszero mentioned this pull request Sep 30, 2026
12 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant