# Audit Standard (canonical)

This is the fixed rubric. Every module audit must follow it verbatim so scores are
comparable across modules, runs, and projects. Do not improvise scoring.

## Scoring rubric (0–100) → grade

| Score | Grade | Meaning |
|------:|:-----:|---------|
| 90–100 | A | Clean, well-scoped, idiomatic. No material smells. |
| 75–89 | B | Minor issues: a documented shim, mild bloat, a localized cast. |
| 60–74 | C | Notable hacks/fallbacks, real bloat, or duplication that has a clear owner. |
| 40–59 | D | Significant legacy/stubs/duplication, or a dual-format/protocol violation. |
| 0–39 | F | Broken, fake output, or an unfinished feature wired in as if done. |

Be rigorous and evidence-based, not generous. A module with one HIGH finding rarely
scores above 60; with only LOW findings it usually scores 80+.

## Smell taxonomy (the `tags`)

Use these exact tag strings. `clean` is the only positive tag; the rest are negative
(the map colors them red and counts them in the report).

- `monkeypatch` — runtime mutation of another module / stdlib / vendor; `setattr` on
  foreign objects; `sys.modules` / `sys.meta_path` surgery; reassigning store actions.
- `fallback` — "try the real thing, then fake/degrade"; chained `a || b || c` /
  `a ?? b` defaults that hide which value is real.
- `silent-except` / `silent-catch` — `except: pass`, bare `except`, empty `catch {}`
  that swallow errors with no log/signal.
- `legacy` — deprecated/back-compat shims, retired vocabulary, dead-but-shipped code,
  parallel "old + new" code paths kept side by side.
- `dual-format` — accepting both snake_case and camelCase (or two payload shapes) for
  the same field; the classic `display_name || displayName` patch.
- `stub` / `placeholder` — `NotImplemented`, `TODO: implement`, dead buttons, demo
  scripts, hardcoded sample data presented as real.
- `fake-output` — returns random/canned/hardcoded results where real computation is implied.
- `duplication` — logic copy-pasted from a sibling or that an existing shared
  abstraction already covers.
- `bloat` / `god-component` — oversized file/function; many responsibilities in one unit.
- `glue` — thin, valueless pass-through / boilerplate forwarding: rows of one-line
  wrappers that only forward args to another layer (e.g. dozens of `send({type:...})`
  methods), an adapter that copies a payload field-for-field without transforming, a
  store/function that only re-exports or delegates to another. The indirection earns
  nothing. Distinct from `bloat` (size) and `duplication` (copy-paste): glue is about
  forwarding that adds no value.
- `any-escape` — `as any`, `@ts-ignore`, untyped boundaries used to bypass the type system.
- `over-fit` — hardcoded to one case where a small generalization was expected.
- `clean` — no material issues.

### The taxonomy is language-agnostic — recognize the per-language form

The tags name *behaviors*, not syntax. Map each to whatever the target language does:

| tag | Python | TS / JS | C# / .NET | Rust | C / C++ |
|---|---|---|---|---|---|
| `any-escape` | `# type: ignore`, `Any` | `as any`, `@ts-ignore`, `!` | `dynamic`, `object` casts, `#nullable disable` | `unsafe`, `transmute`, blanket `.unwrap()` | `void*`, `reinterpret_cast`, C-style casts |
| `silent-except` | `except: pass` | empty `catch {}` | `catch (Exception) {}` | `let _ = x;`, `.ok()`, `unwrap_or_default` to hide | empty `catch`, ignored return codes / `errno` |
| `monkeypatch` | `setattr`, `sys.modules` | prototype patching, global override | reflection / Harmony patching | macro / `static mut` hacks | `#define` overrides, weak-symbol swap |
| `dual-format` | `a or b` (snake/camel) | `a ?? b`, `a \|\| b` | nullable + alias props | `Option` chains for two shapes | overloads accepting two layouts |
| `fallback` | try real then stub | `try/catch` → canned data | `try/catch` fallback | `unwrap_or(fakeDefault)` | `#ifdef` to fake impl |

`legacy`, `stub`, `fake-output`, `bloat`, `god-component`, `duplication`, `glue`,
`over-fit` are the same idea in every language. Build / test / generated files are out of
audit scope — the module `paths` globs plus `scan.py` excludes handle that across stacks
(`target/`, `bin/`, `obj/`, `node_modules/`, `__pycache__/`, `dist/`, …).

Judgement rules:
- A *documented, bounded* compat shim that deliberately refuses to silently coerce is
  `legacy` at most LOW — do not over-penalize disciplined shims.
- A fallback that is a real security control or numeric guard (e.g. identity matrix on
  singular input, stripping untrusted shaders) is **not** a smell.
- Native-dependency gating that *raises or returns an error* when a lib is missing is
  correct; only `fake-output` if it silently returns fabricated data.
- A `*Placeholder` name is not automatically a stub — read it; it may be a finished
  read-only widget.
- A *single* thin delegator, or a genuine boundary normalizer that converts/validates
  once, is fine — not `glue`. Flag `glue` only when pass-through wrappers **proliferate**
  (many near-identical forwarders that should be collapsed, generated, or replaced by a
  generic dispatch) or an adapter forwards with no transformation. Usually MED when it
  proliferates, LOW for a one-off.

## Severity (each finding)

- `HIGH` — wrong/dangerous/fake, a protocol or security issue, or a god-file that is a
  genuine maintenance hazard.
- `MED` — a real smell a maintainer should fix: a live dual-format patch, an un-migrated
  duplicate, an unfinished-but-wired path.
- `LOW` — a documented shim, a cosmetic cast, benign bloat. Worth noting, not urgent.

Always cite `file:line` and quote/paraphrase the offending snippet. Never report a
grep hit as a problem without reading the surrounding code.

## Independent-subagent protocol (REQUIRED)

Every module's score MUST be produced by a separate subagent, never inline in the main
thread, and never reused across modules. One subagent audits one module against the
paths in its state entry. Spawn them in parallel (Explore or general-purpose).

### Subagent prompt template

> You are auditing CODE QUALITY of ONE functional module for an architecture audit.
> Module: **{label}** (`{id}`). Files: {paths}. Project root: {root}.
>
> Read the module's code (grep the markers below, then READ the surrounding code —
> never flag a grep hit you haven't read). Judge it against this rubric:
> {paste the "Scoring rubric", "Smell taxonomy", "Severity" sections above}
>
> Hunt specifically for: monkeypatch / stdlib mutation, fallback chains & silent
> excepts, legacy/deprecated/back-compat shims, dual-format (snake||camel) handling,
> stubs / fake output / unfinished-but-wired code, bloat/god-files, duplication of
> logic that exists elsewhere, thin valueless glue (proliferating pass-through wrappers
> / no-op adapters), and over-fitting. Also state whether the module is appropriately
> generic.
>
> Return ONLY this JSON (no prose):
> {"score": <0-100>, "grade": "<A|B|C|D|F>",
>  "tags": ["<from the taxonomy>", ...],
>  "findings": [{"sev":"HIGH|MED|LOW","loc":"file:line","text":"concrete issue + evidence"}, ...]}
> If clean, use tags ["clean"] and findings []. Be rigorous, not generous.

Use `schema` on the Agent call to force that JSON shape when available. Then feed each
result to `scripts/apply_audit.py --id <id> --json '<result>'`.

## Test-author protocol (the `test` command + the baseline step of `fix`)

A dedicated **test-author subagent** generates tests for a module. It is separate from
the auditor, fixer, and verifier.

- **Detect, don't invent.** Find the repo's test framework and location from existing
  tests near the module (pytest / jest / vitest / go test / …); match their style and
  placement. Never introduce a new framework or harness.
- **characterization mode** (default before a fix): capture the module's CURRENT
  observable behavior — inputs→outputs, side effects, payload shapes — as assertions of
  "same as today", not "correct". Target the public surface; don't pin private internals.
  Use snapshot/golden tests only where the repo already does.
- **coverage mode**: cover the public API and the specific behaviors named in the
  module's `findings`. Aim for meaningful branches, not line count.
- **Must be GREEN on the current, unmodified code before returning.** If a test you want
  to write fails because of a real bug, FLAG it as a finding — do not assert the buggy
  output as if it were the desired behavior.
- Tests are real, committed source (the regression net); never delete or weaken them to
  move a number.
- Return JSON: `{"framework":"...","files":["..."],"locked":"<behaviors locked>",
  "gaps":"<what is still uncovered>","flagged":[{"sev":"...","loc":"...","text":"..."}]}`.

## Acceptance / regression gate (the gate in `fix`)

An **acceptance/verifier subagent**, independent of the fixer, proves a fix introduced no
regression. It does NOT score quality — pass/fail only.

- Re-run the EXACT baseline test set captured before the fix (same commands), plus the
  narrowest build/typecheck for the touched area.
- **PASS iff** every test that was green before is green after, AND no new build / type /
  lint errors appeared. A baseline-green test that is now failing, errored, skipped,
  deleted, or flaky counts as a regression → FAIL (you cannot remove a test to pass).
- New tests the fixer may have added are ignored (and the fixer should not add any).
- Return JSON: `{"pass": <bool>, "ran": "<commands>",
  "regressions": [{"test":"...","was":"pass","now":"fail|error|missing","evidence":"..."}],
  "evidence": "<short summary>"}`.
- **Gate rule:** no PASS → no re-audit and no rendered score improvement. Report the
  failure with evidence; revert or hand back to the fixer.

## Cross-cutting themes

After all modules are scored, the orchestrator (main thread) writes 4–7
`reportThemes` into `modules.json` — patterns seen across modules (e.g. "dual-format
recurs in N handlers", "duplication between X and Y", "stub backend wired live"). Each
is `[headline, body]`. These are synthesis, not per-module scoring, so the main thread
writes them.
