Date: 2026-04-27 Owner: eng-platform Implements: V1-P2-0353
(allow-list comment convention) alongside the scanner contracts in V1-P2-0350
(stub-indicator-scan CI) and V1-P2-0351 (silent-random-scan CI). Code:
scripts/stub-indicator-scan.sh is the single source of truth for scanner
behavior. This document is the human-facing contract.
TL;DR#
The stub-indicator scanner runs in two modes against PR-diff files only. Both
modes honor inline // stub:legitimate <reason> and
// random:legitimate <reason> opt-out comments on the same line as the hit.
New stub-vocabulary or Math.random() use without the marker fails the build;
existing hits in untouched files are grandfathered.
Why this exists#
The OSHUN_V1_TODOS_P2.md quality bar (§2.6) requires that every PR's
implementation source survive an adversarial grep for stub vocabulary ("in
production this would…", "TODO:", "placeholder", Math.random() in
deterministic functions, etc.). Two CI jobs enforce this:
stub-indicator-scan(V1-P2-0350) — qualitative stub markerssilent-random-scan(V1-P2-0351) —Math.random()uses
A small number of lines legitimately match those patterns:
- Synthetic-data generators that intentionally inject noise
(
gap-filling.ts:845-847is the canonical example today). - Tests / mocks that deliberately use
Math.randomfor fuzz seeds. - Comments documenting historical decisions that include the word
placeholderin prose, where the surrounding code is real. TODO:markers tracked against an open ticket and explicitly scheduled.
These are rare, but they exist. The allow-list mechanism exists so the scanner does not have to maintain a global ignore list — every exception is justified, in-place, by the engineer adding it.
The convention#
// stub:legitimate <reason> — qualitative stub markers#
Add to the same line as a hit when one of the §2.6 stub-vocabulary matches
is intentional. The trailing reason is required and ungrep-able in absence
(// stub:legitimate alone is rejected — without a reason future readers cannot
judge whether it still applies).
// TODO: revisit fee-rounding once the FX provider switches // stub:legitimate scheduled in OSHUN-1234
// random:legitimate <reason> — Math.random() uses#
Add to the same line as a Math.random() call when the randomness is
intentional and would not be replaced by a deterministic algorithm. Common
cases: noise injection in synthetic data, jitter in retry backoff, A/B bucket
assignment that's intentionally probabilistic.
const noise = (Math.random() - 0.5) * scale; // random:legitimate gap-filling synthetic data
When to use which#
| If the line matches… | Use |
|---|---|
Anything in the §2.6 stub vocabulary except Math.random() |
// stub:legitimate <reason> |
Math.random() |
// random:legitimate <reason> |
| Both on the same line | Either tag suppresses the line. Prefer // random:legitimate since the qualitative check has lower base-rate of false positives. |
What the reason should be#
A short justification that:
- Identifies why the line looks like a stub (e.g. "noise injection", "scheduled cleanup", "vendor doc verbiage in comment").
- Either (a) names a tracking ticket, or (b) explains why no follow-up is needed.
Bad reasons (rejected in code review):
// stub:legitimate ok— gives the reader nothing.// stub:legitimate temporary— temporary until when?// stub:legitimate Claude said so— does not survive turnover.
Good reasons:
// random:legitimate jitter for cluster-deconfliction; deterministic alternative would defeat the purpose// stub:legitimate flagging vendor copy that uses the word 'placeholder'; surrounding code is real// stub:legitimate scheduled in OSHUN-1234 for next sprint
Grandfathered files#
Pre-existing hits in untouched files are grandfathered automatically by the
scanner: it only scans files the PR diff touches. There is no global ignore
list. If an engineer touches a file that already contains unrelated stub
markers, only the new hits introduced by the diff fail the build (because
git diff --name-only returns the file but the scanner reports per-line, and an
unchanged line that was already there is not "new" — except: the scanner does
not currently diff per-line, which means touching a file with old hits triggers
them. Mitigation: a follow-up to scripts/stub-indicator-scan.sh adding a
--new-only mode that compares matched lines against the base ref). For V1, the
practical workaround is to add
// stub:legitimate grandfathered, see <lineage doc> to the existing line as
part of the PR that touches the file.
This trade-off was deliberately chosen over a global ignore list: allow-list comments live next to the offending code, are visible in review, and rot more visibly than a separate file would.
Counter-examples — what NOT to do#
- Do not rename a function or argument to dodge the scanner (e.g.
_placeholder→_p). The scanner targets the comment vocabulary and the literalMath.randomcall, not identifier names. - Do not wrap the offender in a string concatenation to escape the literal
regex (
'Math' + '.random'). This is a code-review red flag and reviewers should reject such changes. - Do not add a global ignore. There is none on purpose.
- Do not strip a real
TODO:to make CI happy. Either turn the TODO into the actual code change in the same PR, or annotate it with// stub:legitimate <ticket-link>.
Scanner internals#
scripts/stub-indicator-scan.sh is the single source of truth.
- Inputs: explicit paths,
--staged(pre-commit), or--diff=<ref>(CI). - Modes:
--mode=stubs(default),--mode=random,--mode=all. - Test files (
*.test.ts,*.spec.ts,*.test.tsx,*.spec.tsx,test_*.py,*_test.py, anything undertests/ortest/) are auto-excluded — they routinely contain stub vocabulary inside fixtures and are not implementation code. node_modules/,dist/,.next/,build/are auto-excluded.- The scanner script itself (
scripts/stub-indicator-scan.sh) is excluded so its own pattern strings do not match. - Exit codes:
0clean,1actionable hits found,2invocation error.
CI workflows that consume the scanner:
.github/workflows/stub-indicator-scan.yml— runs--mode=stubsand--mode=randomagainst the PR diff.- (V1-P2-0356) future pre-commit hook — runs
--staged --mode=allon staged files only, target <2 s. - (V1-P2-0357) future PR-comment job — runs
--format=pr-commentand posts the result as a sticky review comment.
Changes to scanner behavior must update this document in the same PR.