@xenos1996/usat 1.0.0

package/dist/util/yaml.js

@@ -0,0 +1,48 @@
+/**
+ * Shape helpers for decoded YAML.
+ *
+ * `yaml.parse` hands back plain JS objects, which is exactly the *wrong* thing
+ * to sprinkle through the engine: every downstream field access would be `any`
+ * and a typo in a rule pack would surface as `undefined` three modules later.
+ * These helpers force the parse boundary to state up front what shape it
+ * expects, and make the "absent" case explicit rather than implicit.
+ */
+export function isMap(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function asMap(v) {
+    return isMap(v) ? v : {};
+}
+/** Present and a string. */
+export function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+/** Present and a number. */
+export function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+/** Present and a boolean. */
+export function bool(v) {
+    return typeof v === 'boolean' ? v : undefined;
+}
+/** Present and an array. */
+export function list(v) {
+    return Array.isArray(v) ? v : undefined;
+}
+/** Present and an array — every element stringified. */
+export function strList(v) {
+    return Array.isArray(v) ? v.map((x) => String(x)) : undefined;
+}
+/** A scalar suitable for `json_path.equals` comparisons. */
+export function scalar(v) {
+    if (v === null)
+        return null;
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+        return v;
+    return undefined;
+}
+/** One entry of an array, as a mapping. */
+export function maps(v) {
+    return Array.isArray(v) ? v.filter(isMap) : [];
+}
+//# sourceMappingURL=yaml.js.map

package/dist/util/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/util/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,UAAU,KAAK,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,CAAU;IAC9B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3B,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,GAAG,CAAC,CAAU;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,GAAG,CAAC,CAAU;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7B,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAe,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,MAAM,CAAC,CAAU;IAC/B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACvF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACjD,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# Architecture
+
+USAT is a **rule interpreter**, not a linter. Nothing about any particular
+language, framework, or standard is hard-coded in TypeScript. The engine knows
+how to walk a directory, match a glob, grep a file, and do arithmetic on
+weights. Everything _opinionated_ lives in `rules/`, as YAML.
+
+That split is the whole design. It is why a user can delete every pack we ship,
+drop in their own, and still get a working audit — and why adding support for a
+new framework is a five-line YAML diff rather than a release.
+
+## The five stages
+
+```
+   project tree
+        │
+        ▼
+  ┌───────────┐   rules/detectors.yaml    ┌──────────┐
+  │  Project  │ ─────────────────────────▶│  Facts   │  lang, pm, fw, maturity…
+  │  (index)  │                           └────┬─────┘
+  └───────────┘                                │
+        │                                      ▼
+        │                        ┌──────────────────────────┐
+        │                        │  Pack selection          │
+        │                        │  pack.applies_when ⊨ facts│
+        │                        └────────────┬─────────────┘
+        │                                     ▼
+        │                        ┌──────────────────────────┐
+        │                        │  Rule evaluation         │
+        │                        │  15 check kinds → status │
+        │                        └────────────┬─────────────┘
+        │                                     ▼
+        │                        ┌──────────────────────────┐
+        └───────────────────────▶│  Maturity dampening      │
+                                 │  severity × profile      │
+                                 └────────────┬─────────────┘
+                                              ▼
+                                 ┌──────────────────────────┐
+                                 │  Scoring → Markdown      │
+                                 └──────────────────────────┘
+```
+
+| Module        | File                     | Responsibility                                                                                    |
+| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
+| Project index | `src/util/project.ts`    | One pass over the tree. Honours `.gitignore` + user ignores. Caches reads. Never greps lockfiles. |
+| Glob matcher  | `src/util/glob.ts`       | Dependency-free glob → RegExp. Handles `**`, `{a,b}`, `[abc]`, `?`.                               |
+| YAML shape    | `src/util/yaml.ts`       | Makes the parse boundary explicit, so a typo in a pack is a warning, not `undefined`.             |
+| Detection     | `src/detect/index.ts`    | Evaluates 230 detector primitives into a fact set, then classifies maturity.                      |
+| Pack loading  | `src/engine/loader.ts`   | Parses + validates packs, applies user overrides. Bad packs warn, never crash.                    |
+| Evaluation    | `src/engine/evaluate.ts` | Runs one check against the index; resolves `applies_when` predicates.                             |
+| Maturity      | `src/engine/maturity.ts` | Dampens severity by lifecycle stage. CRITICAL is never dampened.                                  |
+| Scoring       | `src/engine/score.ts`    | Weighted credit arithmetic. Returns `null` for unverified sections.                               |
+| Report        | `src/report/markdown.ts` | Deterministic Markdown + a machine-readable YAML trailer.                                         |
+| Diff          | `src/engine/diff.ts`     | Compares two reports via their trailers.                                                          |
+
+## Why the fact system
+
+A rule that checks something needs to know when it is relevant. The naive
+approach — `if (hasFile('package.json'))` — is a decision hard-coded in the
+rule, invisible to the reader and impossible to override.
+
+USAT separates the two. Detectors produce **facts** (`lang:typescript`,
+`fw:next`, `maturity:mvp`, `has:ci`). Rules declare **predicates over facts**
+(`applies_when`). The consequence:
+
+- Detection is shared. Two hundred rules can key off `lang:typescript`
+  without re-deriving it.
+- Users can inject facts (`--fact monorepo`, or `facts:` in `.usat.yaml`)
+  when detection guesses wrong.
+- `usat detect` prints the fact set, so a wrong audit is _debuggable_ — you
+  can see exactly what the engine believes before you argue with it.
+
+## Why severity dampening exists
+
+A prototype with no rate limiting and a payment service with no rate limiting
+are not the same finding. Most scanners report both as HIGH, which teaches
+teams to ignore the scanner.
+
+USAT keeps the _rule's_ severity (the intrinsic badness) and computes a
+_reported_ severity from the project's lifecycle stage. The rule never lies
+about what it found; the report just stops shouting about the wrong things
+right now. CRITICAL is exempt — a hardcoded credential is a hardcoded
+credential on day one.
+
+## Why scores can be `null`
+
+A section the engine could not verify is not a 10 and it is not a 0. It is
+_unknown_, and it is excluded from both the numerator and the denominator.
+Pretending otherwise is how dashboards end up at 94/100 while 30% of the
+checklist sits in a queue nobody reads. Every section therefore reports a
+**confidence** figure alongside its score.
+
+## Performance
+
+The tree is walked once. File contents are cached lazily and never read twice.
+Grep excludes lockfiles, minified bundles, source maps, and generated files,
+which is where the bytes are. A repository of 10k files audits in a couple of
+seconds; the cost is `O(patterns × matching files)`, not `O(patterns × repo)`.
+
+## What USAT deliberately does not do
+
+- **No plugins.** Packs are data. Data can be forked, diffed, reviewed, and
+  vendored; a plugin ABI cannot.
+- **No network calls.** Ever. An audit must be reproducible offline.
+- **No auto-fixing.** USAT reports; humans decide. (It does print the exact
+  remediation text, which is the part that actually helps.)
+- **No daemon, no database, no config server.** One process, one tree, one
+  Markdown file.
+
+## Extension points
+
+| To add…                          | You touch…                                                                        |
+| -------------------------------- | --------------------------------------------------------------------------------- |
+| A check                          | any `rules/**/*.yaml`                                                             |
+| A technology USAT must recognise | `rules/detectors.yaml`                                                            |
+| A lifecycle profile              | `rules/profiles/maturity.yaml`                                                    |
+| A new check _kind_               | `src/engine/evaluate.ts` + `src/types.ts` — the only change that needs TypeScript |
+
+See [`adr/`](adr/) for the decisions behind each of these.

package/docs/README.md

@@ -0,0 +1,27 @@
+# USAT documentation
+
+| Doc                                       | What's in it                                                                             |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [`USAT.md`](../USAT.md)                   | **The template itself** — all 16 sections, the severity model, the agent behaviour rules |
+| [Getting started](getting-started.md)     | Install, first audit, reading the report                                                 |
+| [Concepts](concepts.md)                   | Severity × status, scoring maths, confidence, applicability                              |
+| [Configuration](configuration.md)         | `.usat.yaml` reference                                                                   |
+| [Rule packs](rule-packs.md)               | Every check kind, with examples — start here to contribute a pack                        |
+| [Detectors](detectors.md)                 | The fact catalogue and how to add signals                                                |
+| [Maturity profiles](maturity-profiles.md) | Lifecycle stages, dampening, expected bands                                              |
+| [Agent integration](agent-integration.md) | Driving USAT from Claude, Cursor, Codex, Copilot                                         |
+| [CI integration](ci-integration.md)       | GitHub Actions, GitLab CI, quality gates, drift detection                                |
+| [Standards mapping](standards-mapping.md) | USAT ↔ ASVS 5.0, SSDF, SLSA, Scorecard, ISO 5055, WCAG, CRA, OWASP LLM/ASI               |
+| [Architecture](ARCHITECTURE.md)           | How the engine is put together, and what it deliberately does not do                     |
+| [API reference](reference/api.md)         | Programmatic use: `runAudit`, `detect`, `Project`, scoring, diffing                      |
+| [ADRs](adr/)                              | The five decisions behind the design, and what each one cost                             |
+
+## Reading order
+
+- **Auditing a project?** → [Getting started](getting-started.md) → [Concepts](concepts.md)
+- **Wiring up CI?** → [CI integration](ci-integration.md)
+- **Using an agent?** → [Agent integration](agent-integration.md)
+- **Contributing a rule pack?** → [Rule packs](rule-packs.md) → [Detectors](detectors.md)
+- **Comparing to a standard?** → [Standards mapping](standards-mapping.md)
+- **Embedding USAT in a tool?** → [API reference](reference/api.md)
+- **Wondering why it is built this way?** → [Architecture](ARCHITECTURE.md) → [ADRs](adr/)

package/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,35 @@
+# 1. Record architectural decisions
+
+- **Date:** 2026-09-08
+- **Status:** Accepted
+
+## Context
+
+USAT is a template that other people will fork and extend. Every non-obvious
+choice in it will be questioned by a contributor who was not in the room: "why
+is the engine TypeScript instead of Python?", "why is everything YAML instead of
+code?", "why is the output only Markdown?"
+
+Those questions get asked in issues, answered from memory, and then re-asked six
+months later by the next person.
+
+## Decision
+
+Architecture decisions are recorded as short numbered files in `docs/adr/`,
+following the [Nygard
+format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions):
+context, decision, consequences. They are immutable — a decision that changes
+gets a new ADR that supersedes the old one, rather than an edit.
+
+## Consequences
+
+**Good:** the reasoning survives the people; disagreeing with a decision becomes
+a reviewable act rather than an archaeology project; USAT's own `ARCH-002` rule
+(ADRs exist) now passes on itself, which is the only honest way to ship a rule.
+
+**Bad:** ADRs rot. An ADR whose context no longer holds is worse than no ADR,
+because it lends false authority to a stale choice. Mitigation: each file carries
+a status, and superseded ones are kept, not deleted.
+
+**Neutral:** three ADRs is a start, not a corpus. The convention matters more
+than the count.

package/docs/adr/0002-typescript-engine-over-python.md

@@ -0,0 +1,49 @@
+# 2. Build the engine in TypeScript, not Python
+
+- **Date:** 2026-09-08
+- **Status:** Accepted
+- **Supersedes:** an earlier `src/auditor.py` prototype (deleted)
+
+## Context
+
+USAT audits software projects. Most of those projects are JavaScript or
+TypeScript, and the two natural candidate languages for the tool were:
+
+- **Python**, the traditional home of linters and security tooling
+  (Bandit, Semgrep's original core, most scanners).
+- **TypeScript**, which can run in the same process and on the same runtime as
+  the projects it audits.
+
+The repository already contained a bare-minimum `src/index.ts` stub when this
+work started, which biased towards TypeScript but did not decide it.
+
+## Decision
+
+Build the engine in TypeScript, published as an npm package, distributed as a
+GitHub Action.
+
+## Rationale
+
+1. **The audience is the runtime.** Anyone auditing a Node project already has
+   Node. `npx usat audit .` requires no interpreter negotiation, no virtualenv,
+   no `pip install --user` foot-gun.
+2. **TypeScript's type system pays for itself here.** The engine is a
+   tree-walker with fifteen check kinds and a scoring formula; those are exactly
+   the shapes where a compiler catches the "renamed a field, missed a call site"
+   class of bug.
+3. **GitHub Actions runs Node natively.** A TypeScript action starts in
+   milliseconds; a Python action pays interpreter setup on every run.
+
+## Consequences
+
+**Good:** zero-install path for the largest audience; `tsc` catches whole bug
+classes; the Action is fast; the tool audits itself with `npm run self-audit`.
+
+**Bad:** Python, Go, Rust, and Java projects auditing themselves now need Node
+present, even though the tool has nothing to do with Node. This is a real cost
+and the reason the Action exists — CI brings the runtime so the user does not
+have to. The check _contents_ are language-agnostic (globs and regexes), so a
+future second engine would reuse all 27 rule packs unchanged.
+
+**Neutral:** `pyproject.toml` and `src/auditor.py` were deleted; the CONTRIBUTING
+document was rewritten to match.

package/docs/adr/0003-rules-are-data-not-code.md

@@ -0,0 +1,50 @@
+# 3. Rule packs are YAML data, not TypeScript code
+
+- **Date:** 2026-09-08
+- **Status:** Accepted
+
+## Context
+
+The alternative design was a plugin API: each rule pack is a TypeScript module
+exporting checks, loaded dynamically. That is what Semgrep started with, what
+ESLint does, and what most mature linters converge on — because a rule that can
+run arbitrary code can express anything.
+
+## Decision
+
+A rule pack is a **YAML file**. The engine supplies exactly fifteen check kinds
+(`file_exists`, `grep_present`, `json_path`, `count_min`, `manual`, …). A pack
+declares what to look for; the engine does the looking. `manual` is the escape
+hatch for anything a regex cannot honestly decide.
+
+## Rationale
+
+1. **Forkability is the product.** USAT is a _template_. A user who wants their
+   company's engineering standard should be able to fork `rules/`, delete what
+   they disagree with, and commit. Data can be diffed, reviewed, vendored, and
+   disagreed with in a pull request. A plugin ABI can only be _used_.
+2. **Rules get read by non-authors.** A security lead who will never open
+   `src/` can still read `rules/core/security.yaml` and say "that's wrong, and
+   here's why."
+3. **No sandboxing problem.** Running third-party rule code is running
+   third-party code. Data cannot exfiltrate your source tree.
+4. **The audit is reproducible.** Rules are declarative, so the same tree always
+   produces the same findings — no rule can depend on the date, the network, or
+   a cache.
+
+## Consequences
+
+**Good:** packs are auditable by the people who own the standard; adding a
+framework is a five-line diff; no sandboxing; deterministic output; the same
+packs could drive a second engine in another language.
+
+**Bad:** the fifteen check kinds are a ceiling. Anything needing real parsing —
+"this SQL string is built by concatenation" — cannot be expressed, and lands in
+the `manual` queue instead. That is deliberate (a scanner that guesses at taint
+analysis produces confident nonsense), but it caps automation coverage at roughly
+70–80%, which is why the report shows a confidence figure instead of pretending
+otherwise.
+
+**Neutral:** adding a sixteenth check kind requires a TypeScript change. This has
+happened zero times since the initial design, which suggests the set is close to
+sufficient.

package/docs/adr/0004-markdown-only-output.md

@@ -0,0 +1,41 @@
+# 4. Markdown is the only output format
+
+- **Date:** 2026-09-08
+- **Status:** Accepted
+
+## Context
+
+Audit tooling usually emits JSON (for machines), SARIF (for GitHub code
+scanning), HTML (for executives), and JUnit XML (for CI). Shipping all four is
+the conventional move and roughly quadruples the reporter surface.
+
+## Decision
+
+USAT renders **Markdown only**.
+
+Two things make this sufficient:
+
+1. **Every report ends with a machine-readable YAML trailer** inside an HTML
+   comment (`<!-- USAT:TRAILER:BEGIN -->`). `usat diff` parses it to compare two
+   runs; CI thresholds read it; a user who wants JSON can extract it in one line.
+   The machine interface exists — it just lives inside the human document rather
+   than beside it.
+2. **Markdown is the native format of the places audits are read.** GitHub
+   renders it in a pull request comment, a gist, an issue, or a repo file. No
+   hosting, no build step, no stylesheet.
+
+## Consequences
+
+**Good:** one renderer, one set of golden tests, no format skew. The report
+committed to a repo stays readable forever without a viewer. `usat diff old.md
+new.md` works on any two reports ever generated.
+
+**Bad:** no native SARIF, so USAT findings do not appear in GitHub's **Security**
+tab as code-scanning alerts. For teams whose compliance workflow centres on the
+code-scanning API this is a genuine gap. The workaround is the PR comment plus
+`--fail-on`, which covers the enforcement case but not the dashboard case.
+
+**Neutral:** if SARIF demand materialises, it is a ~100-line addition fed from
+the same `AuditReport` object — the trailer already carries everything SARIF
+needs, so no engine change would be required. Revisit if three or more issues
+ask for it.

package/docs/adr/0005-maturity-dampens-severity.md

@@ -0,0 +1,56 @@
+# 5. Lifecycle stage dampens severity; CRITICAL is exempt
+
+- **Date:** 2026-09-08
+- **Status:** Accepted
+
+## Context
+
+Static analysis has a credibility problem. A 200-line weekend prototype and a
+payment service are handed the same list of HIGH findings, the prototype's
+authors correctly conclude that the tool does not understand their situation,
+and they learn to ignore it — right up until the year the tool would have been
+right.
+
+Severity that ignores context is not severity. It is a list of things that
+_could_ be wrong.
+
+## Decision
+
+USAT detects a lifecycle stage — `prototype`, `mvp`, `beta`, `production`,
+`legacy` — from repository signals (history, tags, CI, tests, security policy,
+contributing guide, containerisation, monitoring).
+
+Each stage has a **dampening table**: for each rule class (security,
+correctness, maintainability, documentation, …) a number of severity rungs to
+step down. `production` steps down nothing; `prototype` steps documentation down
+two rungs and security down one.
+
+**CRITICAL is never dampened, at any stage.** A committed credential, a
+publicly-exposed secret, and an unauthenticated destructive endpoint are
+emergencies on day one of a prototype.
+
+## Rationale
+
+The goal is not to be _nicer_ to prototypes. It is to keep the top of the
+findings list true. If the first five things a founder reads are all things
+they would defend, the scanner has lost them.
+
+## Consequences
+
+**Good:** a prototype's report leads with "no rate limiting, no auth on the
+admin route", not "no ADRs and your README lacks a badge". Findings stay
+ordered by what matters _now_. The dampening is visible in every finding, so
+nothing is hidden.
+
+**Bad:** a user in a hurry reads a MEDIUM where the rule says HIGH and
+under-reacts. Mitigated by `--profile production`, which turns dampening off
+entirely, and by `usat explain <rule>`, which always shows the rule's intrinsic
+severity.
+
+**Bad:** mis-detected stage mis-dampens everything. Because of this the stage is
+always overridable (`--profile`, or `maturity:` in `.usat.yaml`) and always
+printed with the signals that produced it, so a wrong guess is visible rather
+than silent.
+
+**Neutral:** the band table (prototype 30–65 … production 75–95) is a heuristic,
+not a law. Scoring _above_ your band is not a goal.

package/docs/adr/0006-severity-status-two-axes.md

@@ -0,0 +1,48 @@
+# 6. Severity and status are separate axes; WRONG outranks MISSING in credit
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+Most checklists conflate two questions: "how bad is this?" and "what did we
+find?". A single pass/fail bit cannot distinguish "auth is missing" from
+"auth is present but checks the wrong field" — yet those demand different
+responses, and an auditor that cannot tell them apart teaches teams that a
+decorative control scores the same as a working one.
+
+Worse, binary scoring rewards box-ticking: a `passwords-hashed: true` flag in
+a config file earns full marks whether the hasher is argon2id or ROT13.
+
+## Decision
+
+Every rule carries a **severity** (set by the rule author: how bad, if
+violated) and every finding carries a **status** (set by the evidence: what
+was actually observed). Score credit comes from status:
+
+| Status         | Credit | Meaning                             |
+| -------------- | ------ | ----------------------------------- |
+| GOOD           | 1.00   | Verified present and correct        |
+| EXPERIMENTAL   | 0.50   | Present, unvalidated                |
+| DEPRECATED     | 0.40   | Present, EOL                        |
+| WRONG          | 0.15   | Present but incorrectly implemented |
+| MISSING / FAIL | 0.00   | Absent, or present and violated     |
+
+`WRONG` deliberately scores _above_ `MISSING` (0.15, not 0.00): something
+exists, so there is partial credit — but a wrong implementation is _more
+dangerous_ than nothing, because it looks finished. Surfacing always orders
+`WRONG` above `MISSING` so the dangerous problem gets fixed first.
+
+## Consequences
+
+**Good:** reports distinguish "you have no auth" from "your auth checks the
+wrong field", and the roadmap prioritises the scarier of the two. Partial
+credit keeps teams from hiding half-done work to avoid a zero.
+
+**Bad:** two axes are harder to explain than pass/fail (see `docs/concepts.md`,
+which exists largely to teach this). Any consumer that collapses status to a
+boolean (a badge, a gate) must decide where WRONG lands — and document it.
+
+**Neutral:** `EXPERIMENTAL` and `DEPRECATED` exist so the engine can describe
+reality instead of rounding it to good/bad. They cost scoring-model surface
+in exchange for honest reports.

package/docs/adr/0007-suppressions-are-visible-and-expiring.md

@@ -0,0 +1,46 @@
+# 7. Accepted risk stays visible, stops costing points, and expires
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+Every real project has findings it will not fix: a known N+1 in an admin
+panel with 40 rows, docs living in Notion instead of the repo, a prototype
+with no runbook. An audit tool has three options for these: keep failing the
+build (teams disable the tool), silently ignore them (the audit lies), or
+record the decision.
+
+The failure mode that matters most: a waiver granted in 2024 silently
+suppressing a finding in 2027, long after the context changed. An auditing
+tool that honours expired risk acceptances without a murmur produces false
+assurance — the one failure it must never have.
+
+## Decision
+
+Suppressions live in `.usat.yaml`, each with a mandatory `reason` and an
+optional `until` date:
+
+1. A suppressed finding is **excluded from the score and the severity
+   tallies** but **listed under Accepted Risk** in every report. Deliberate
+   decisions stay visible but stop costing points.
+2. An `until` date in the past — or one that cannot be parsed — **fails
+   closed**: the waiver is ignored, the finding reports normally, and a
+   warning names the rule. Expired risk is re-audited, not grandfathered.
+3. Suppressed findings never appear in Immediate Action or the roadmap.
+   The Findings Summary counts only active findings, so it cannot contradict
+   those sections.
+
+## Consequences
+
+**Good:** the report is honest about what was decided vs what was found.
+Stale waivers resurface automatically instead of rotting silently.
+
+**Bad:** teams must maintain waiver dates to keep a green build — a small
+recurring cost, and the correct one. `until` parsing follows `Date.parse`,
+so only unambiguous ISO dates should be used (documented in
+`docs/configuration.md`).
+
+**Neutral:** suppressions are rule-ID-granular, not file:line-anchored.
+Site-level waivers with unused-suppression reporting (the ESLint model) are
+a documented future direction, not this decision.

package/docs/adr/0008-report-trailer-and-diff.md

@@ -0,0 +1,48 @@
+# 8. Every report embeds a machine-readable trailer; audits are diffable
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+An audit you cannot compare to the last one is just a number. Teams need to
+answer "did we get better since June?" and CI needs to gate on "did this PR
+introduce a new HIGH?". The conventional answer is a second machine format
+(JSON/SARIF beside the human report) plus a server to store history in.
+
+USAT already decided Markdown is the only output format (ADR-0004). The
+question was how to get trendability without a second artifact or a server.
+
+## Decision
+
+Every rendered report ends with a machine-readable YAML trailer inside an
+HTML comment (`<!-- USAT:TRAILER:BEGIN --> … <!-- USAT:TRAILER:END -->`):
+schema version, timestamp, overall score, per-section scores, severity
+totals, and every rule's status/severity/section. `usat diff old.md new.md`
+parses two trailers and reports fixed, regressed, changed-still-open, and
+newly-applicable rules with net point movement.
+
+Trailer hygiene rules, learned the hard way:
+
+1. Rule IDs are pack-author-controlled input to a machine channel, so keys
+   are YAML-quoted with escaping. An unquoted id containing `:`, `#`, a
+   newline, or a fence once corrupted the mapping `usat diff` parses.
+2. Extraction takes the **last** trailer in the document (concatenations
+   yield the newest report, not the oldest) and tolerates trailing spaces,
+   CRLF, and `yml` vs `yaml` fences.
+3. The closing fence is located from the end, because a hostile id may
+   legally contain a fence inside its quoted string.
+
+## Consequences
+
+**Good:** the report stays a single self-contained artifact — committable,
+emailable, pasteable into a PR — that is also its own database row. Progress
+reports (`usat diff Q2.md Q3.md`) work with zero infrastructure.
+
+**Bad:** the trailer duplicates human-visible content, so reports are larger
+than prose alone. Any renderer change must keep the trailer schema stable;
+`schema: usat-report-v1` exists so a future v2 can be detected, not guessed.
+
+**Neutral:** the trailer is unsigned. Anyone with write access to the report
+file can edit history. Signed reports (Sigstore) are a documented future
+direction for supply-chain-grade evidence, not this decision.

package/docs/adr/0009-fail-closed-on-malformed-input.md

@@ -0,0 +1,56 @@
+# 9. Malformed input fails closed and loudly, never silently
+
+- **Date:** 2026-09-09
+- **Status:** Accepted
+
+## Context
+
+USAT consumes untrusted, hand-written input at three boundaries: rule packs
+(third-party YAML), `.usat.yaml` project config, and `applies_when`
+predicates evaluated in the audit hot loop. Each boundary once had a silent
+failure mode, and every one of them corrupted results rather than stopping:
+
+- An unknown predicate operator fell through to "present", silently
+  **including** rules a typo should have excluded.
+- An empty grep pattern (`new RegExp('')` matches every line) turned a
+  malformed rule into a mass-FAIL (or free-credit PASS) score weapon.
+- An invalid `matches` regex threw out of the hot loop and aborted audits.
+- An invalid severity/weight override produced `NaN` overall scores.
+- A corrupt pack or index YAML crashed the run with a stack trace.
+
+For an auditing tool, silent corruption is strictly worse than a loud stop:
+a crash is visible; a wrong score ships.
+
+## Decision
+
+1. **Evaluation fails closed.** Unknown predicate operators, unknown
+   predicate shapes, non-object predicates, and uncompilable `matches`
+   regexes all evaluate to `false` (rule skipped). No-constraint (`undefined`
+   or `{}`) still means "applies always".
+2. **Loading warns.** Every fail-closed case above, plus duplicate rule IDs
+   across packs, unsupported check kinds, missing check kinds, empty grep
+   patterns, invalid severity/weight overrides, expired or undated
+   suppressions, and unknown config sections, produce a named warning on
+   stderr. The CLI prints all warnings; the audit continues with the valid
+   subset.
+3. **One corrupt pack never aborts the audit.** Pack-level YAML errors skip
+   that pack with a warning. A corrupt rule index warns and loads zero packs
+   rather than throwing — with the warning explaining why the report is
+   empty.
+4. **Config overrides are validated.** Severity must be on the ladder;
+   weight must be a finite number ≥ 0. Anything else is ignored with a
+   warning naming the rule.
+
+## Consequences
+
+**Good:** typos and corruption degrade to visible warnings plus conservative
+verdicts, never to wrong scores or stack traces. Each rule documents the
+invariant in a comment at the decision point.
+
+**Bad:** fail-closed can _hide_ findings when packs are malformed (a skipped
+rule finds nothing). The warnings channel is load-bearing — CI that swallows
+stderr loses the signal. The self-audit e2e test ("audits itself without
+warnings") exists to keep the shipped packs warning-free.
+
+**Neutral:** this ADR does not cover adversarial rule IDs in output channels
+— see ADR-0008 for trailer quoting.