# Stub-Indicator Allow-List Conventions

**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 markers
- `silent-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-847` is the canonical example today).
- Tests / mocks that deliberately use `Math.random` for fuzz seeds.
- Comments documenting historical decisions that include the word `placeholder`
  in 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).

```ts
// 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.

```ts
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:

1. Identifies why the line _looks like_ a stub (e.g. "noise injection",
   "scheduled cleanup", "vendor doc verbiage in comment").
2. 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
  literal `Math.random` call, 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 under `tests/` or `test/`) 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:** `0` clean, `1` actionable hits found, `2` invocation error.

CI workflows that consume the scanner:

- `.github/workflows/stub-indicator-scan.yml` — runs `--mode=stubs` and
  `--mode=random` against the PR diff.
- (V1-P2-0356) future pre-commit hook — runs `--staged --mode=all` on staged
  files only, target <2 s.
- (V1-P2-0357) future PR-comment job — runs `--format=pr-comment` and posts the
  result as a sticky review comment.

Changes to scanner behavior must update this document in the same PR.
