@xenos1996/usat 1.0.0

package/docs/adr/0010-detector-design.md

@@ -0,0 +1,54 @@
+# 10. Detectors are cheap syntactic signals resolved to a fixed point
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+Rule selection needs facts ("is this a Node project? does it have a
+database?"), and facts must come from the tree itself with no network, no
+build, and no language server. The temptation is a clever detector: parse
+`pyproject.toml` properly, resolve `extends` chains in tsconfig, understand
+TOML tables. The constraint is that detectors run over arbitrary repos in
+milliseconds and must never crash the audit.
+
+The opposing risk is over-firing: docs, tests, examples, and templates _talk
+about_ technology without _using_ it. A detector that counts the word
+"postgres" in `docs/` reports a database the project does not have.
+
+## Decision
+
+1. **Syntactic signals only.** Detectors match file names, directory names,
+   manifest keys, and single-line content patterns. No parsing beyond
+   section-scoped text search and JSON path lookup.
+2. **Prose is excluded from content signals.** Markdown, docs, examples,
+   templates, tests, fixtures, and mocks never count as technology evidence
+   (`CONTENT_EXCLUDES`). A deliberately conservative list, extended only
+   with evidence of a miss — `__tests__/`, `spec/`, and `*.stories.*` were
+   added after review showed Jest and Storybook layouts leaking through.
+3. **Manifest queries are section-scoped where sections exist.** A dotted
+   key (`tool.poetry.dependencies`) must match a full header segment
+   (case-insensitive; `[dev-dependencies]` is not `[dependencies]`), the
+   leaf must match on word boundaries (`test` is not `latest`), and
+   `contains` is checked against the matched block — never the whole file.
+   Flat files with no headers keep whole-text search (YAML has no sections
+   to scope to).
+4. **`implies` chains resolve to a fixed point**, bounded by
+   `detectors.length + 1` passes with early exit. Two hardcoded passes
+   silently dropped chains of length 3+ declared worst-first, inflating
+   scores — the bound is now structural, not a magic number.
+
+## Consequences
+
+**Good:** detection is fast, total (no network), crash-free, and order-
+independent. The precision rules above each cite the false positive they
+killed, so future relaxations know what they are re-introducing.
+
+**Bad:** syntactic detection has a ceiling: `extends` chains leaving the
+repo, aliased imports, and commented-out config are invisible. Detectors
+report evidence, not proof — rules that need proof belong in the judgement
+queue, not in a cleverer regex.
+
+**Neutral:** the fixed-point bound is `detectors.length + 1` passes worst
+case; typical runs exit after two. Performance is unchanged for existing
+registries.

package/docs/adr/0011-coexist-with-deep-scanners.md

@@ -0,0 +1,52 @@
+# 11. Coexist with deep scanners: verify configuration, consume evidence
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+A regex engine cannot do dataflow analysis (CodeQL), reachability-filtered
+CVE prioritisation (Snyk, Semgrep Supply Chain), whole-program taint
+tracking, or API-verified hygiene (Scorecard branch protection, SLSA
+attestation verification). Pretending otherwise would mean shipping weak
+copies of those tools and claiming parity — the fastest way to destroy an
+auditor's credibility.
+
+But USAT's value proposition includes supply chain, vulnerability posture,
+and hygiene verdicts. Ignoring those dimensions leaves the report with
+holes exactly where executives look first.
+
+## Decision
+
+USAT **verifies configuration and consumes evidence; it does not duplicate
+analysis**:
+
+1. Where a deep scanner exists, the rule checks that it is **configured and
+   running** (lockfile + frozen install, scanner in CI, SBOM published,
+   attestations present) — never that USAT re-derives its findings.
+2. Where a scanner emits machine output, future check kinds may **ingest**
+   it (SARIF/JSON: coverage numbers, HIGH/CRITICAL CVE counts, attestation
+   verification success) as evidence for the corresponding rules.
+3. USAT never claims what an oracle would contradict: API-verifiable checks
+   (branch protection, token permissions, signed releases) are file-text
+   approximations, documented as such, and the report prefers MISSING
+   ("not verified") over a confident verdict it cannot support.
+4. SARIF (and JSON) renderers are the approved interchange in both
+   directions: USAT findings out to dashboards and code scanning, oracle
+   findings in as evidence. The internal finding model already carries
+   file/line/severity/rule identity, so this is a renderer, not a redesign.
+
+## Consequences
+
+**Good:** no vulnerability database to maintain, no resolver to build, no
+dataflow engine to write — and no weak-duplicate claims. Each tool does
+what it is good at; the audit composes them.
+
+**Bad:** USAT reports are only as strong as the oracles the project runs.
+A repo with no scanners gets MISSING verdicts where a bundled scanner
+would give answers. That is honest but less satisfying, and must be
+explained in every such report (the confidence column exists for this).
+
+**Neutral:** this ADR draws the scope boundary that keeps USAT small. Any
+proposal to add a CVE database, a resolver, or interprocedural analysis
+re-opens this decision explicitly.

package/docs/adr/README.md

@@ -0,0 +1,32 @@
+# Architecture Decision Records
+
+Short, numbered, immutable records of the non-obvious choices in this
+repository — see [ADR-0001](0001-record-architecture-decisions.md) for why
+they exist and the rules for writing them (context, decision, consequences;
+a changed decision gets a _new_ ADR that supersedes the old one).
+
+## Index
+
+| #    | Title                                               | Status   | Supersedes |
+| ---- | --------------------------------------------------- | -------- | ---------- |
+| 0001 | Record architecture decisions                       | Accepted | —          |
+| 0002 | Build the engine in TypeScript, not Python          | Accepted | —          |
+| 0003 | Rule packs are YAML data, not TypeScript code       | Accepted | —          |
+| 0004 | Markdown is the only output format                  | Accepted | —          |
+| 0005 | Lifecycle stage dampens severity; CRITICAL exempt   | Accepted | —          |
+| 0006 | Severity/status two axes; WRONG outranks MISSING    | Accepted | —          |
+| 0007 | Accepted risk stays visible, stops scoring, expires | Accepted | —          |
+| 0008 | Machine-readable trailer; audits are diffable       | Accepted | —          |
+| 0009 | Malformed input fails closed and loudly             | Accepted | —          |
+| 0010 | Detectors are cheap signals, fixed-point resolved   | Accepted | —          |
+| 0011 | Coexist with deep scanners; consume evidence        | Accepted | —          |
+
+## Coverage map (what has no ADR, and why)
+
+- **Scoring maths** — specified normatively in `docs/concepts.md`, not an
+  ADR: it is a formula with tests, not a judgement call. Disagreeing with it
+  means changing code, and the tests adjudicate.
+- **Individual rule wordings** — rules are data (ADR-0003). Disputed rules
+  get fixed in `rules/` with a regression test, not an ADR.
+- **Release mechanics** — tracked in `ROADMAP.md` until decided, then
+  recorded here (e.g. the eventual release-automation choice).

package/docs/agent-integration.md

@@ -0,0 +1,129 @@
+# Agent integration
+
+USAT is built to be driven by an AI agent. The division of labour is explicit:
+
+|                      | Who           | Why                                                                             |
+| -------------------- | ------------- | ------------------------------------------------------------------------------- |
+| Deterministic checks | **the tool**  | An LLM grepping 400 files is slow, expensive, and non-deterministic             |
+| Judgement checks     | **the agent** | Coupling, authorisation, threat modelling — nothing settles these but reasoning |
+| The report           | **both**      | Tool renders it; agent fills the judgement queue                                |
+
+The tool settles roughly 70% of applicable rules on a typical project. The agent's
+job is the remaining 30% — the interesting 30%.
+
+## The workflow
+
+```bash
+usat audit . --out AUDIT.md    # 1. deterministic pass
+```
+
+Then, to the agent:
+
+> Read `USAT.md` and `AUDIT.md`.
+> Work the **Judgement Queue** at the bottom of the report.
+> For each item, find the evidence and record `file:line` plus one sentence of
+> reasoning. Do not mark anything ✅ without evidence (Rule 4).
+> Then rewrite the report with your findings folded in.
+
+## Why this is better than "audit this codebase"
+
+A bare prompt produces three failure modes, and the template exists to prevent all
+three:
+
+| Failure                                                             | How USAT prevents it                                                              |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Confident invention** — "✅ MFA is implemented" with no such code | Rule 4: no ✅ without evidence; every judgement item states what proof looks like |
+| **Wrong scope** — Solidity reentrancy checks on a Next.js blog      | Detection + `applies_when`; non-applicable sections are skipped silently (Rule 1) |
+| **Wrong severity** — a prototype graded like a bank, or vice versa  | Maturity profiles, with a hard floor on CRITICAL                                  |
+
+## Shipped packs
+
+### Agent Skills (`SKILL.md`)
+
+```bash
+cp -r skills/usat-audit ~/.claude/skills/       # Claude Code
+cp -r skills/usat-audit .cursor/skills/         # Cursor
+```
+
+Follows the Agent Skills convention — YAML frontmatter with `name` and `description`,
+detailed content in `references/` [1](https://github.com/addyosmani/agent-skills/blob/main/CLAUDE.md).
+The same directory works across Claude Code, Cursor, Codex, Gemini CLI, Copilot, and
+~60 other tools.
+
+### `AGENTS.md` for a target repository
+
+```bash
+usat init .
+cp templates/AGENTS.audit.md AGENTS.md
+```
+
+Gives any agent working in that repo the build/test/lint commands, the conventions,
+and an explicit denylist — which is worth doing on its own. Agent instruction files
+are executable-ish: they commit as easily as code and agents follow them literally
+(see `AI-011`).
+
+## Prompt you can paste
+
+```
+You are auditing this repository with USAT (Universal Software Audit Template).
+
+1. Run: usat detect .
+   Confirm the detected facts. If any are wrong, say so and note the correct ones.
+
+2. Run: usat audit . --out AUDIT.md
+
+3. Read USAT.md (the framework) and AUDIT.md (the deterministic results).
+
+4. Work the Judgement Queue in AUDIT.md. For each item:
+   - locate the relevant code
+   - decide PASS / WRONG / MISSING
+   - record file:line evidence and one sentence of reasoning
+   - if you cannot determine it, say UNKNOWN and say what you would need
+
+5. Produce a final report that follows the Section 14 template in USAT.md:
+   - CRITICAL and HIGH findings first, with location and fix
+   - then section-by-section
+   - then the roadmap
+   - then the judgement queue with your recorded evidence
+
+Rules:
+- Never mark ✅ without evidence (file:line or command output).
+- Skip sections that do not apply — do not explain why.
+- ⚠️ WRONG is worse than 🚫 MISSING. Surface it.
+- Priority: security > correctness > maintainability > style.
+```
+
+## Using the API directly
+
+```ts
+import { runAudit, renderMarkdown, loadProfiles } from 'usat';
+
+const { report, profile, warnings } = runAudit({
+  target: process.cwd(),
+  rulesDir: 'rules',
+  depth: 'deep',
+  profile: 'auto',
+  config: { version: 1 },
+  allowCommands: false,
+  usatVersion: '1.0.0',
+});
+
+console.log(report.score.overall); // 71.4
+console.log(report.score.counts.UNKNOWN); // 18 → send these to the agent
+const md = renderMarkdown(report, profile);
+```
+
+`report.findings.filter(f => f.status === 'UNKNOWN')` is precisely the agent's task
+list, and each item carries `why` and `evidenceHint`.
+
+## Notes for agent authors
+
+- **Do not re-run greps the tool already did.** If a finding is already ✅ or 🚫 with
+  locations, the tool settled it.
+- **Trust `suppressedReason`.** A suppressed finding was a decision someone made. Mention
+  it only if the reason has clearly expired.
+- **Respect the maturity profile.** If a finding is marked
+  _"Downgraded HIGH → MEDIUM by the MVP profile"_, do not re-escalate it — unless it is
+  CRITICAL, which is never downgraded.
+- **Say UNKNOWN when you do not know.** It is a valid answer and it keeps confidence
+  honest. Guessing is the failure mode this whole framework exists to prevent.

package/docs/ci-integration.md

@@ -0,0 +1,163 @@
+# CI integration
+
+## GitHub Actions
+
+`usat init` writes a ready-made workflow. The minimum viable version:
+
+```yaml
+name: USAT Audit
+on: [pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run USAT
+        id: usat
+        run: npx --yes @xenos1996/usat@1 audit . --depth standard --out AUDIT.md
+
+      - name: Publish to job summary
+        if: always()
+        run: cat AUDIT.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: usat-audit
+          path: AUDIT.md
+```
+
+### Quality gate
+
+```yaml
+- name: Quality gate
+  run: npx --yes @xenos1996/usat@1 audit . --fail-on high
+```
+
+| Exit | Meaning                                   |
+| ---- | ----------------------------------------- |
+| `0`  | No findings at or above the threshold     |
+| `1`  | Gate tripped — findings printed to stderr |
+| `2`  | Usage or configuration error              |
+
+**Roll-out advice:** start with `--fail-on critical`. Move to `high` once the backlog
+is clear. Never start at `medium` — you will teach the team to bypass the check.
+
+### Comment the score on the PR
+
+```yaml
+- name: Comment
+  if: github.event_name == 'pull_request'
+  uses: marocchino/sticky-pull-request-comment@v2
+  with:
+    path: AUDIT.md
+```
+
+### Composite action
+
+```yaml
+- uses: Er-Sajan-PLG/software-auditing-template@v1
+  with:
+    depth: standard
+    fail-on: high
+```
+
+See [`action.yml`](../action.yml).
+
+---
+
+## GitLab CI
+
+```yaml
+usat-audit:
+  image: node:20
+  stage: test
+  script:
+    - npx --yes @xenos1996/usat@1 audit . --out usat-report.md --fail-on critical
+  artifacts:
+    when: always
+    paths: [usat-report.md]
+    expose_as: 'USAT Audit'
+```
+
+---
+
+## Scheduled drift detection
+
+The highest-value CI job is not the PR gate — it is a monthly audit that shows
+movement:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 6 1 * *' # 1st of the month
+  workflow_dispatch:
+
+jobs:
+  audit:
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: npx --yes @xenos1996/usat@1 audit . --out reports/$(date +%Y-%m).md
+      - run: |
+          PREV=$(ls reports/*.md | tail -2 | head -1)
+          npx --yes @xenos1996/usat@1 diff "$PREV" "reports/$(date +%Y-%m).md" --out DIFF.md || true
+          cat DIFF.md >> "$GITHUB_STEP_SUMMARY"
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          title: 'chore: monthly USAT audit'
+          body-path: DIFF.md
+```
+
+A dated report per month plus `usat diff` gives you an audit trail that shows
+improvement — the thing a single audit can never do.
+
+---
+
+## Reference: this repo's own CI (`.github/workflows/`)
+
+USAT audits itself with the full stack — copy what fits:
+
+| Workflow           | What it does                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ci.yml`           | lint+format+typecheck · Vitest with coverage thresholds · build + CLI smoke · rule-pack validation · npm audit + gitleaks + license scan · **hygiene** (`check-adrs` + `check-docs`) |
+| `self-audit.yml`   | `usat audit . --depth deep --fail-on critical` on every PR, score as PR comment                                                                                                      |
+| `scorecard.yml`    | OpenSSF Scorecard monthly + on push (API-verified hygiene; SARIF to Security tab)                                                                                                    |
+| `automerge.yml`    | Dependabot patch/minor auto-merge once CI is green (majors stay manual)                                                                                                              |
+| `gitleaks-pin.yml` | Monthly check that the curl-pinned gitleaks binary in `ci.yml` is current (no bot watches it) — opens a deduped issue when stale                                                     |
+| `release.yml`      | Tag push `v*` → OIDC trusted publishing (no long-lived token) + `--provenance` + CycloneDX SBOM artifact                                                                             |
+
+Release setup note: trusted publishing needs a one-time owner step on
+npmjs.com (package Settings → Trusted Publisher → this repo + workflow)
+before the first OIDC publish succeeds.
+
+## Choosing a depth in CI
+
+| Depth      | Rules                                          | Runtime (≈10k files) | Use for              |
+| ---------- | ---------------------------------------------- | -------------------- | -------------------- |
+| `quick`    | high-signal only                               | ~1–3 s               | Every PR             |
+| `standard` | default                                        | ~3–10 s              | PRs + nightly        |
+| `deep`     | adds cycles, duplication, complexity, mutation | ~10–30 s             | Weekly / pre-release |
+
+`deep` is where the judgement-heavy rules live; the extra cost is mostly I/O.
+
+## Notes
+
+- **No network at audit time.** USAT reads files and writes Markdown. It never uploads
+  anything, which is why it is safe on private repositories.
+- **`--allow-commands` in CI.** Only if you trust the target repo — it shells out for
+  checks like `npm audit`. Off by default; those rules report ❓ NEEDS REVIEW instead.
+- **Pin the version** in production pipelines (`@xenos1996/usat@1`, not `@latest`) so a
+  rule-pack change cannot fail your build without a commit.
+- **Commit `.usat.yaml`.** Suppressions and overrides without a commit are invisible
+  decisions, and they are the first thing a reviewer asks about.

package/docs/concepts.md

@@ -0,0 +1,196 @@
+# Concepts
+
+## Two axes: severity and status
+
+Most audit checklists merge "how bad is it" and "what did we find" into one column.
+That makes scoring impossible to reproduce — two auditors tag the same observation
+differently, and the totals diverge. USAT keeps them apart.
+
+### Severity — a property of the rule
+
+Set by whoever wrote the rule. It says: _if this is violated, how bad is that?_
+
+| Tag | Severity   | Meaning                                           | Default weight |
+| --- | ---------- | ------------------------------------------------- | -------------- |
+| 🔴  | `CRITICAL` | Breaks security, data integrity, or core function | 10             |
+| 🟠  | `HIGH`     | Major risk or substantial debt                    | 6              |
+| 🟡  | `MEDIUM`   | Important gap                                     | 3              |
+| 🟢  | `LOW`      | Minor improvement                                 | 1.5            |
+| 🔵  | `FUTURE`   | Not needed now, needed at scale                   | 0.5            |
+
+### Status — a property of the observation
+
+Produced by the engine (or by a reviewer, for judgement checks).
+
+| Tag | Status         | Score credit | When                                               |
+| --- | -------------- | ------------ | -------------------------------------------------- |
+| ✅  | `GOOD`         | 1.00         | Verified present and correct                       |
+| 🧪  | `EXPERIMENTAL` | 0.50         | Present, unvalidated (`grep_experimental`)         |
+| 💀  | `DEPRECATED`   | 0.40         | Present but EOL (`grep_deprecated`)                |
+| ⚠️  | `WRONG`        | 0.15         | Present but implemented incorrectly (`grep_wrong`) |
+| 🚫  | `MISSING`      | 0.00         | Required and absent                                |
+| ❓  | `NEEDS REVIEW` | _excluded_   | Judgement required; no evidence recorded           |
+| ➖  | `SKIPPED`      | _excluded_   | Not applicable to this project                     |
+
+**Why WRONG scores 0.15 and not 0.00.** Something exists, so there is partial
+credit — the intent was right and the surface is smaller than a greenfield fix.
+But a wrong implementation is _more dangerous_ than an absent one, because it looks
+finished: nobody puts "add CSRF protection" on the roadmap when CSRF protection
+appears to be there. Rule 9 of the agent behaviour rules exists for exactly this.
+
+**Why NEEDS REVIEW is excluded rather than scored zero.** An unanswered question is
+not a failure. It is a hole in the audit, and the place it shows up is
+**confidence**, not the score.
+
+---
+
+## Scoring
+
+### Per rule
+
+```
+creditᵢ = weightᵢ × CREDIT[statusᵢ]
+```
+
+### Per section
+
+```
+sectionScore = 10 × Σ creditᵢ / Σ weightᵢ        (over resolved, applicable rules)
+```
+
+### Overall
+
+```
+overall = 100 × Σ (creditᵢ × sectionWeight) / Σ (weightᵢ × sectionWeight)
+```
+
+Rule-level weighting, rather than averaging section scores, means a section with
+three rules cannot swing the total as hard as one with thirty.
+
+### Section weights
+
+Security, supply chain, and testing carry the heaviest multipliers — a repo that
+fails an authorisation control is worse than one with a slightly untidy README, and
+the number should say so.
+
+|                     | Section                                           | Weight  |
+| ------------------- | ------------------------------------------------- | ------- |
+| **S2**              | Security                                          | **1.7** |
+| **S3**              | Supply Chain & Build Provenance                   | 1.3     |
+| **S7**              | Testing & Quality Assurance                       | 1.3     |
+| **S10**             | Dependencies & Third-Party                        | 1.2     |
+| **S14**             | AI / LLM-Era Risks                                | 1.1     |
+| S4, S5, S6, S8, S15 | Architecture, Code Quality, Data, CI/CD, Platform | 1.0     |
+| **S13**             | Accessibility, i18n & Compliance                  | 0.9     |
+| **S11**             | Performance & Resilience                          | 0.8     |
+| S1, S9, S12         | Repository, Release, Documentation                | 0.7     |
+| **S16**             | Future Readiness                                  | 0.4     |
+
+Override any of them in `rules/sections.yaml`.
+
+### Confidence
+
+```
+confidence = resolved / applicable
+```
+
+`resolved` counts rules the engine could settle (PASS, FAIL, WRONG, MISSING,
+DEPRECATED, EXPERIMENTAL). `applicable` counts everything `applies_when` let through.
+
+- Sections with **zero** resolved rules are reported as _"— not verified"_ and
+  excluded from the overall score. You cannot earn points for questions nobody answered.
+- A high score at low confidence is the single most misleading thing an audit tool
+  can produce, which is why confidence sits next to every score in the report.
+
+---
+
+## Maturity dampening
+
+Severity is reduced by the detected lifecycle stage, per rule class — but
+**CRITICAL is never dampened, at any stage.**
+
+| Stage      | security | supply-chain | correctness | maintainability | operations | performance | compliance | documentation | style |
+| ---------- | -------- | ------------ | ----------- | --------------- | ---------- | ----------- | ---------- | ------------- | ----- |
+| Prototype  | −1       | −1           | −1          | −2              | −2         | −2          | −2         | −2            | −2    |
+| MVP        | −0       | −1           | −1          | −1              | −1         | −1          | −1         | −2            | −2    |
+| Beta       | −0       | −0           | −0          | −1              | −1         | −1          | −1         | −1            | −1    |
+| Production | −0       | −0           | −0          | −0              | −0         | −0          | −0         | −0            | −0    |
+| Legacy     | −0       | −0           | −0          | −1              | −0         | −1          | −0         | −1            | −1    |
+
+Steps move down the ladder `FUTURE < LOW < MEDIUM < HIGH < CRITICAL`.
+
+Every dampened finding says so in the report:
+
+```
+- 🚫 **LICENSE present** `REPO-005`
+  - 🪶 Downgraded HIGH → LOW by the Prototype / Spike profile
+```
+
+so a prototype reading knows which items will climb on their own as it grows up.
+See [maturity-profiles.md](maturity-profiles.md).
+
+---
+
+## Applicability
+
+A rule participates when **all** of these hold:
+
+1. Its pack is not skipped (`skip_when` is false)
+2. `applies_when` evaluates true against the detected facts
+3. Its `depths` (if any) include the current `--depth`
+4. It is not disabled in `.usat.yaml`
+
+Two escape hatches, both loud: a force-included pack (`include:`) applies
+all its rules regardless of 2 and 3 — the operator asked for it — and a
+malformed `applies_when` (unknown key or operator, bad regex, non-mapping)
+warns at load time and evaluates to false, so a typo can never silently
+include rules. See ADR-0009.
+
+```yaml
+- id: DATA-007
+  applies_when: { fact: 'has:database' }
+  depths: [deep]
+  check: { kind: manual }
+```
+
+Packs can contribute facts (`provides:`), and facts can make further packs apply.
+The engine resolves this to a fixed point (max 3 passes) so a monorepo pack can pull
+in boundary-enforcement rules without either pack knowing about the other.
+
+---
+
+## Suppressions
+
+Anything suppressed needs a reason. That is not bureaucracy — it is the difference
+between "we decided not to do this" and "we forgot".
+
+```yaml
+suppressions:
+  - rule: PERF-005
+    reason: 'Known N+1 in the admin panel; 40 rows max.'
+    until: '2026-12-31'
+```
+
+Suppressed findings are **excluded from the score, the severity tallies, and
+the action sections, but still listed** under _Accepted Risk_. Anyone reading
+the report can see what was waived and why — and the Findings Summary can
+never contradict Immediate Action over a waived item.
+
+Waivers **expire**: an `until` date in the past (or one that cannot be
+parsed) is ignored with a warning, and the finding reports normally. See
+ADR-0007.
+
+---
+
+## Reproducibility
+
+The same tree, rules, depth, and profile always produce the same score. The only
+inputs that can change a result between runs:
+
+- file contents (obviously)
+- the rule packs in `rules/`
+- `--depth`, `--profile`, `--allow-commands`
+- `.usat.yaml` suppressions and overrides
+
+This is what makes `usat diff` meaningful, and it is why the report records the
+commit SHA, the USAT version, and every option it ran with.