@xenos1996/usat 1.0.0

package/docs/reference/api.md

@@ -0,0 +1,193 @@
+# API reference
+
+Everything the CLI does is available as a library. Types are exported from the
+package root.
+
+```ts
+import { runAudit, detect, Project, renderMarkdown, diffReports } from 'usat';
+```
+
+## `runAudit(options): AuditOutcome`
+
+Runs a full audit. Only `target` is required — every other option falls back to
+the same default the CLI uses.
+
+```ts
+import { runAudit } from 'usat';
+
+const { report, profile, warnings } = runAudit({
+  // synchronous — no await needed
+  target: '/path/to/project',
+  depth: 'standard', // 'quick' | 'standard' | 'deep'
+  profile: 'auto', // 'auto' | 'prototype' | 'mvp' | 'beta' | 'production' | 'legacy'
+  config: { version: 1, ignore: ['vendor/**'] }, // or omit to read .usat.yaml
+  allowCommands: false, // let `command` checks execute
+  includePacks: ['stacks/node-typescript'],
+  excludePacks: ['stacks/solidity'],
+});
+
+console.log(report.score.overall); // 88.7
+console.log(warnings); // malformed packs — never throws
+```
+
+| Option                          | Type                 | Default                               |
+| ------------------------------- | -------------------- | ------------------------------------- |
+| `target`                        | `string`             | — (required)                          |
+| `rulesDir`                      | `string`             | `rules/` inside the installed package |
+| `depth`                         | `Depth`              | `'standard'`                          |
+| `profile`                       | `Maturity \| 'auto'` | `'auto'`                              |
+| `config`                        | `UsatConfig`         | parsed from `<target>/.usat.yaml`     |
+| `allowCommands`                 | `boolean`            | `false`                               |
+| `usatVersion`                   | `string`             | version from `package.json`           |
+| `includePacks` / `excludePacks` | `string[]`           | `undefined`                           |
+
+Returns `{ report: AuditReport, profile: MaturityProfile, warnings: string[] }`.
+
+## `detect(project, detectors, git, extraFacts?): DetectionResult`
+
+Turns a tree into a fact set.
+
+```ts
+import { Project, detect, loadDetectorFile } from 'usat';
+
+const project = new Project('/path/to/project', ['vendor/**']);
+const detection = detect(
+  project,
+  loadDetectorFile('node_modules/usat/rules/detectors.yaml'),
+  project.gitInfo(),
+  ['monorepo'], // facts asserted by the caller
+);
+
+detection.facts.flags; // Set { 'lang:typescript', 'pm:npm', 'has:ci', … }
+detection.maturity; // 'mvp'
+detection.maturitySignals; // ['+1 tests present', '+0 release tags (absent)', …]
+```
+
+## `Project`
+
+The tree index. Cached, read-only, built once.
+
+```ts
+const p = new Project(root, extraIgnores);
+
+p.files; // string[] — every indexed path, relative, sorted
+p.glob('**/*.ts'); // string[]
+p.has('package.json'); // boolean
+p.dirExists('src'); // boolean
+p.anyFile(['**/*.tf', 'pulumi/**']); // boolean
+p.count('**/*.test.ts'); // number
+p.read('package.json'); // string | null
+p.readJson('package.json'); // unknown | null (tolerates comments + trailing commas)
+p.grep('TODO|FIXME', ['**/*.ts'], ['**/generated/**']); // GrepHit[]
+p.gitInfo(); // { commits, contributors, tags, branches, daysSinceLastCommit, isRepo }
+p.trackedFiles(); // string[] — paths git knows about (respects .gitignore semantics)
+```
+
+**`grep` never touches lockfiles, minified bundles, source maps, or generated
+files**, so a 40 MB `package-lock.json` cannot dominate the runtime. Those files
+are still _indexed_, so the presence of a lockfile is checkable.
+
+## `loadRulePacks(rulesDir): { packs, warnings }`
+
+Parses and validates every pack reachable from `rules/index.yaml`. A malformed
+pack produces a warning and is skipped — the audit continues rather than
+failing, because one broken pack should not cost you the other twenty-six.
+
+```ts
+import { loadRulePacks, applyRuleOverrides } from 'usat';
+
+const { packs, warnings } = loadRulePacks('rules');
+applyRuleOverrides(packs, { 'SEC-042': { severity: 'LOW' } });
+```
+
+## `evaluateRule(rule, ctx): Finding`
+
+Evaluates a single rule. Useful for testing a pack without running an audit.
+
+```ts
+import { evaluateRule, ruleApplies, packApplies } from 'usat';
+
+if (ruleApplies(rule, facts, depth)) {
+  const finding = evaluateRule(rule, ctx);
+  finding.status; // 'PASS' | 'FAIL' | 'MISSING' | 'UNKNOWN' | …
+}
+```
+
+## `score(evaluated, sections, profile): ScoreCard`
+
+```ts
+import { score } from 'usat';
+
+const card = score(evaluated, sections, profile);
+card.overall; // 88.7 — 0 when nothing resolved (never null; see below)
+card.automationCoverage; // 70.8 — share of applicable rules verified without a human
+card.sections; // [{ id, title, score: number | null, confidence, … }]
+card.counts; // per-status totals, suppressed findings excluded
+card.severityCounts; // per-severity open findings, suppressed excluded
+card.expectedBand; // e.g. [60, 85] for the detected maturity stage
+```
+
+A section whose rules all resolved to `UNKNOWN` scores **`null`**, not 10. It is
+excluded from the numerator _and_ the denominator, and rendered as
+`— not verified`. The **overall** score, however, is a number: `0` when
+nothing resolved. A bare `0` cannot tell "everything failed" from "nothing
+was verifiable" — read it together with `automationCoverage`, which is
+exactly the confusion `docs/concepts.md` warns is the most misleading thing
+an audit tool can produce.
+
+## `renderMarkdown(report, profile): string`
+
+Deterministic Markdown, including the machine-readable trailer. Rule IDs in
+the trailer are YAML-quoted, so pack-author-controlled IDs cannot corrupt
+the machine-parsed channel.
+
+```ts
+import { renderMarkdown, parseTrailer, trailer } from 'usat';
+
+const md = renderMarkdown(report, profile);
+const yaml = trailer(report); // the YAML string embedded in the trailer fences
+const parsed = parseTrailer(md); // read a trailer back out (latest wins on concatenation)
+```
+
+## `diffReports(beforeRaw, afterRaw): string`
+
+Takes two trailer YAML strings (or full reports — `parseTrailer` extracts),
+returns Markdown. Reports fixed, regressed, changed-still-open, and newly
+applicable rules with net point movement. Judgement-queue transitions are
+first-class: `UNKNOWN → PASS` lists as fixed _(resolved by review)_ and
+`PASS → UNKNOWN` as regressed _(needs review)_.
+
+```ts
+import { diffReports, parseTrailer } from 'usat';
+
+const md = diffReports(parseTrailer(beforeMd)!, parseTrailer(afterMd)!);
+console.log(md); // # 🔁 USAT Audit Diff …
+```
+
+## `validatePredicate(p, where, warnings): void`
+
+Validates an `applies_when` predicate the way the loader does: unknown keys
+and operators, non-list `all`/`any`, and uncompilable `matches` regexes each
+push a named warning. Use it when authoring packs programmatically —
+evaluation fails closed (rule skipped) on anything this flags.
+
+```ts
+import { validatePredicate } from 'usat';
+
+const warnings: string[] = [];
+validatePredicate({ fact: 'has:ci', op: 'bogus' }, 'my-pack MY-001', warnings);
+// warnings: ['my-pack MY-001: unknown predicate op "bogus" — rule will never apply']
+```
+
+## `loadConfig(target, explicitPath?): UsatConfig`
+
+Reads `.usat.yaml`. A missing file is not an error — it returns an empty config.
+A malformed one throws, loudly, because silent config loss produces an audit
+that quietly disagrees with the user's intent.
+
+## Types
+
+`Severity` · `Status` · `RuleClass` · `Depth` · `Maturity` · `Location` ·
+`Finding` · `Predicate` · `FactOp` · `Check` · `Rule` · `RulePack` ·
+`AuditReport` · `UsatConfig` · `SectionDef` · `MaturityProfile` ·
+`ScoredRule` · `EvalContext`

package/docs/reference/cli.md

@@ -0,0 +1,412 @@
+<!-- GENERATED by scripts/gen-cli-docs.mjs — do not hand-edit. -->
+
+# CLI reference (generated)
+
+Regenerated from the built CLI. If this file disagrees with `--help`, the file is stale — run `node scripts/gen-cli-docs.mjs` and commit.
+
+## `usat --help`
+
+```
+usat — Universal Software Audit Template
+
+  usat audit [path]              Audit a project and write a Markdown report
+  usat detect [path]             Print the auto-detected facts and maturity
+  usat rules [--section S2]      List all loaded rule packs and rules
+  usat explain <RULE-ID>         Show everything about one rule
+  usat diff <before> <after>     Compare two previously generated reports
+  usat init [path]               Scaffold .usat.yaml + a GitHub Actions workflow
+
+audit options
+  --out <file>        Report path (default AUDIT.md)
+  --depth <level>     quick | standard | deep          (default standard)
+  --profile <stage>   auto | prototype | mvp | beta | production | legacy
+  --rules-dir <dir>   Rule pack directory             (default bundled rules/)
+  --config <file>     Explicit .usat.yaml location
+  --include <packs>   Force these packs on (comma separated)
+  --exclude <packs>   Force these packs off
+  --fact <ns:value>   Assert a fact detection missed, e.g. --fact has:database
+  --allow-commands    Run `command:` checks (shells out; off by default)
+  --fail-on <sev>     Exit 1 on findings >= sev: critical|high|medium|low|none
+  --quiet             Only errors
+
+examples
+  usat audit . --depth deep
+  usat audit ../api --profile production --fail-on high
+  usat audit . --out reports/audit-$(date +%F).md
+```
+
+## `usat rules`
+
+```
+
+## core/repo — Repository & Project Structure (18 rules)
+   Root hygiene, the essential-files baseline, and version-control quality. Cheap to fix, expensive to ignore — this is where most leaked credentials and most onboarding pain originate.
+
+   REPO-001   CRITICAL security         .gitignore is present
+   REPO-002   CRITICAL security         No environment/secret files committed
+   REPO-003   CRITICAL security         No secrets in git history
+   REPO-004   HIGH     documentation    README present
+   REPO-005   HIGH     compliance       LICENSE present
+   REPO-006   HIGH     maintainability  .env.example documents required configuration
+   REPO-007   HIGH     maintainability  Build artifacts and dependencies are not committed
+   REPO-008   MEDIUM   maintainability  Large binaries are not committed directly
+   REPO-009   HIGH     security         SECURITY.md published
+   REPO-010   MEDIUM   documentation    CHANGELOG maintained
+   REPO-011   LOW      documentation    CONTRIBUTING guide present
+   REPO-012   LOW      compliance       Code of conduct present
+   REPO-013   LOW      style            .editorconfig present
+   REPO-014   MEDIUM   operations       CODEOWNERS assigns review responsibility
+   REPO-015   LOW      maintainability  Commit history is meaningful
+   REPO-016   LOW      maintainability  Branch strategy is defined and stale branches pruned
+   REPO-017   MEDIUM   maintainability  Concern separation at the root
+   REPO-018   LOW      documentation    Agent instruction file present (AGENTS.md / CLAUDE.md)
+
+## core/security — Security (25 rules)
+   Universal security baseline. Severity is never dampened here below CRITICAL, and security-class rules carry the heaviest multiplier in the score. USAT is not a penetration test — it finds the doors that were left open.
+
+   SEC-001    CRITICAL security         No hardcoded credentials in source
+   SEC-002    HIGH     security         Sensitive data is not written to logs
+   SEC-003    HIGH     security         No plaintext HTTP endpoints in configuration
+   SEC-004    HIGH     security         TLS verification is not disabled
+   SEC-005    CRITICAL security         SQL is not built by string concatenation
+   SEC-006    HIGH     security         No unsafe dynamic code execution
+   SEC-007    CRITICAL security         Shell commands are not built from user input
+   SEC-008    HIGH     security         User input is validated at a trust boundary
+   SEC-009    HIGH     security         Output is encoded rather than interpolated as HTML
+   SEC-010    HIGH     security         Path traversal is prevented on filesystem access
+   SEC-011    CRITICAL security         Passwords use a modern adaptive hash
+   SEC-012    MEDIUM   security         Tokens and sessions expire
+   SEC-013    HIGH     security         JWTs are not accepted with alg:none or unverified
+   SEC-014    HIGH     security         Failed authentication is rate limited
+   SEC-015    HIGH     security         Authorization is enforced per request, not per route
+   SEC-016    HIGH     security         Secrets come from a manager in production
+   SEC-017    HIGH     security         CORS is not a wildcard
+   SEC-018    MEDIUM   security         Security headers are set
+   SEC-019    MEDIUM   security         CSRF protection for cookie-based sessions
+   SEC-020    MEDIUM   security         Errors do not leak internals to clients
+   SEC-021    MEDIUM   security         Cryptographic randomness for tokens and IDs
+   SEC-022    HIGH     security         Uploads are validated for type, size, and content
+   SEC-023    HIGH     compliance       PII is identified and protected at rest
+   SEC-024    MEDIUM   compliance       Secrets and PII are redacted in logs and telemetry
+   SEC-025    HIGH     security         Adaptive password hashing is present where auth exists
+
+## core/supply-chain — Supply Chain & Build Provenance (17 rules)
+   Promoted to its own section in USAT. You can write perfect code and still ship someone else's backdoor: these controls cover the path from a contributor's editor to the artifact your users run. Aligned with SLSA v1.2, NIST SSDF (SP 800-218), and the OpenSSF Scorecard.
+
+   SUP-001    HIGH     supply-chain     A lockfile is committed
+   SUP-002    MEDIUM   supply-chain     CI installs with a frozen lockfile
+   SUP-003    MEDIUM   supply-chain     Dependency versions are pinned, not floating
+   SUP-004    MEDIUM   supply-chain     Automated dependency updates are configured
+   SUP-005    HIGH     supply-chain     Dependency vulnerability scanning runs in CI
+   SUP-006    MEDIUM   supply-chain     SAST runs in CI
+   SUP-007    MEDIUM   supply-chain     Secret scanning runs in CI
+   SUP-008    HIGH     supply-chain     CI workflows avoid script-injection patterns
+   SUP-009    MEDIUM   supply-chain     Workflows declare least-privilege token permissions
+   SUP-010    MEDIUM   supply-chain     Third-party actions are pinned to a version or SHA
+   SUP-011    CRITICAL supply-chain     No secrets in CI configuration
+   SUP-012    HIGH     supply-chain     Default branch is protected
+   SUP-013    LOW      supply-chain     Commits are signed or attested
+   SUP-014    LOW      supply-chain     An SBOM is generated for releases
+   SUP-015    FUTURE   supply-chain     Release artifacts carry provenance attestation
+   SUP-016    MEDIUM   supply-chain     Container images are scanned before publish
+   SUP-017    FUTURE   supply-chain     Build pipeline is reproducible from source
+
+## core/architecture — Architecture & Design (10 rules)
+   Structure, boundaries, and the decisions behind them. Mostly judgement — USAT automates the parts that show up as files and flags the rest for review rather than pretending a regex can measure coupling.
+
+   ARCH-001   MEDIUM   documentation    Architecture is documented
+   ARCH-002   LOW      documentation    Architecture decisions are recorded (ADRs)
+   ARCH-003   MEDIUM   maintainability  No god files
+   ARCH-004   MEDIUM   maintainability  Layers are separated (transport / domain / data)
+   ARCH-005   HIGH     maintainability  No circular dependencies between modules
+   ARCH-006   LOW      maintainability  Module boundaries are enforced by tooling
+   ARCH-007   MEDIUM   operations       Configuration is externalised
+   ARCH-008   LOW      maintainability  Side effects are isolated and testable
+   ARCH-009   MEDIUM   operations       Single points of failure are identified
+   ARCH-010   LOW      performance      Async work is offloaded to a queue
+
+## core/code-quality — Code Quality (13 rules)
+   Linting, typing, error handling, and logging hygiene. These are the rules an agent should be able to settle without asking a human — most of them are answered by looking for a config file.
+
+   CQ-001     MEDIUM   maintainability  A linter is configured
+   CQ-002     LOW      style            A formatter is configured
+   CQ-003     MEDIUM   correctness      Type checking is enabled and strict
+   CQ-004     LOW      maintainability  Type escapes are not used as a default
+   CQ-005     HIGH     correctness      Errors are handled, not swallowed
+   CQ-006     MEDIUM   correctness      There is a central error handler
+   CQ-007     LOW      operations       Logging is structured and levelled
+   CQ-008     LOW      operations       Requests carry a correlation/trace ID
+   CQ-009     LOW      style            Debug statements are not left in production paths
+   CQ-010     LOW      maintainability  TODO/FIXME debt is tracked, not just annotated
+   CQ-011     LOW      maintainability  Functions do one thing
+   CQ-012     MEDIUM   maintainability  Duplicated logic has been consolidated
+   CQ-013     FUTURE   maintainability  Complexity is measured
+
+## core/testing — Testing & Quality Assurance (12 rules)
+   Coverage is a weak proxy for confidence; USAT separates "tests exist", "tests run in CI", and "tests actually cover the paths that matter".
+
+   TEST-001   HIGH     correctness      A test suite exists
+   TEST-002   HIGH     operations       Tests run in CI on every pull request
+   TEST-003   MEDIUM   correctness      There is a meaningful number of tests
+   TEST-004   MEDIUM   correctness      Coverage is measured
+   TEST-005   LOW      correctness      Coverage thresholds are enforced
+   TEST-006   MEDIUM   correctness      Integration tests cover the seams
+   TEST-007   MEDIUM   correctness      End-to-end tests cover critical user journeys
+   TEST-008   MEDIUM   security         Security-relevant behaviour is tested
+   TEST-009   MEDIUM   correctness      Tests are independent and deterministic
+   TEST-010   FUTURE   performance      Performance/load tests exist for critical paths
+   TEST-011   FUTURE   correctness      Mutation testing or equivalent
+   TEST-012   LOW      maintainability  Test data comes from fixtures or factories
+
+## core/cicd — CI/CD, Infrastructure & Observability (12 rules)
+   How code becomes running software, and how you find out when it breaks. Heavily informed by the OpenSSF Scorecard and DORA's delivery metrics.
+
+   CICD-001   HIGH     operations       A CI pipeline exists
+   CICD-002   MEDIUM   operations       CI runs lint, test, and build
+   CICD-003   HIGH     operations       Deployment is automated
+   CICD-004   HIGH     operations       A rollback path exists and has been exercised
+   CICD-005   MEDIUM   operations       Separate environments exist
+   CICD-006   MEDIUM   operations       Infrastructure is defined as code
+   CICD-007   MEDIUM   operations       Health check endpoints exist
+   CICD-008   MEDIUM   operations       Error tracking / APM is configured
+   CICD-009   MEDIUM   operations       Alerting is configured for critical failures
+   CICD-010   HIGH     operations       Backups exist AND restores have been tested
+   CICD-011   MEDIUM   operations       A disaster recovery plan exists
+   CICD-012   LOW      operations       Observability covers the golden signals
+
+## core/release — Release & Change Management (7 rules)
+   How a merged commit becomes a version someone else depends on. This section is what separates "we deploy" from "we ship".
+
+   REL-001    MEDIUM   maintainability  Versioning is semantic and consistent
+   REL-002    MEDIUM   operations       Releases are tagged in version control
+   REL-003    LOW      documentation    Release notes are published
+   REL-004    LOW      operations       Risky changes sit behind a feature flag
+   REL-005    HIGH     correctness      Database migrations run forward and are reversible
+   REL-006    MEDIUM   correctness      Migrations are separated from application deploys
+   REL-007    MEDIUM   operations       There is a documented incident/runbook path
+
+## core/dependencies — Dependencies & Third-Party (8 rules)
+   Every dependency is a bet on someone else's maintenance discipline. USAT scores the observable parts and hands the rest to review.
+
+   DEP-001    MEDIUM   supply-chain     Dependencies are declared in a manifest
+   DEP-002    HIGH     supply-chain     No known-HIGH/CRITICAL vulnerabilities in dependencies
+   DEP-003    MEDIUM   supply-chain     Dependencies are actively maintained
+   DEP-004    LOW      maintainability  No obviously redundant dependencies
+   DEP-005    LOW      maintainability  Unused dependencies are pruned
+   DEP-006    MEDIUM   compliance       Licenses are compatible with the project license
+   DEP-007    MEDIUM   operations       External services have documented failure modes
+   DEP-008    HIGH     security         Webhook payloads are signature-verified
+
+## core/documentation — Documentation & Knowledge (7 rules)
+   Documentation is the only part of the system that ships to every future maintainer. USAT checks the artefacts exist and then asks whether they are true.
+
+   DOC-001    MEDIUM   documentation    README covers what / install / run / contribute
+   DOC-002    MEDIUM   documentation    Setup instructions have been verified recently
+   DOC-003    MEDIUM   documentation    Public APIs are documented
+   DOC-004    LOW      documentation    Complex logic is explained at the point of use
+   DOC-005    LOW      documentation    Docs live in the repo with the code
+   DOC-006    LOW      documentation    An onboarding path exists
+   DOC-007    FUTURE   documentation    Documentation examples are tested
+
+## core/future-readiness — Future Readiness (6 rules)
+   Not needed today, expensive to bolt on later. These are plans, not defects — every rule here is FUTURE severity and never blocks a release.
+
+   FUT-001    FUTURE   maintainability  A path off the current architecture exists
+   FUT-002    FUTURE   maintainability  No core technology is at or near end of life
+   FUT-003    FUTURE   operations       Data archiving strategy exists
+   FUT-004    FUTURE   operations       Multi-region or failover is at least designed
+   FUT-005    FUTURE   maintainability  A tech radar or equivalent exists
+   FUT-006    FUTURE   operations       Cost/usage is monitored
+
+## stacks/node-typescript — Node.js / TypeScript (9 rules)
+   Activated when JavaScript or TypeScript is detected.
+   NODE-001   MEDIUM   operations       Node runtime version is pinned
+   NODE-002   MEDIUM   correctness      TypeScript strict mode is on
+   NODE-003   MEDIUM   correctness      Unhandled promise rejections are handled
+   NODE-004   CRITICAL security         No private registry credentials committed
+   NODE-005   MEDIUM   maintainability  No deprecated Node APIs in use
+   NODE-006   MEDIUM   correctness      Environment variables are validated at startup
+   NODE-007   LOW      performance      Libraries declare sideEffects / exports for tree-shaking
+   NODE-008   LOW      maintainability  Module system is consistent
+   NODE-009   LOW      operations       A fast, isolated runtime is used for tests
+
+## stacks/python — Python (10 rules)
+   Activated when Python is detected.
+   PY-001     MEDIUM   supply-chain     Dependencies are declared in a modern manifest
+   PY-002     MEDIUM   operations       Python version is pinned
+   PY-003     MEDIUM   supply-chain     Dependencies are pinned to exact versions
+   PY-004     MEDIUM   correctness      No bare except clauses
+   PY-005     MEDIUM   correctness      No mutable default arguments
+   PY-006     CRITICAL security         No unsafe deserialisation
+   PY-007     HIGH     security         Subprocess calls do not use shell=True
+   PY-008     CRITICAL security         Debug mode is not enabled outside local development
+   PY-009     LOW      maintainability  Type hints are used on public functions
+   PY-010     MEDIUM   maintainability  A linter/formatter is configured for Python
+
+## stacks/go — Go (8 rules)
+   Activated when Go is detected.
+   GO-001     MEDIUM   operations       go.mod declares the Go version
+   GO-002     HIGH     correctness      Errors are checked, not discarded
+   GO-003     MEDIUM   correctness      Contexts are propagated
+   GO-004     MEDIUM   correctness      No panics in request paths
+   GO-005     MEDIUM   maintainability  go vet / staticcheck / golangci-lint runs in CI
+   GO-006     MEDIUM   correctness      Goroutine lifecycle is bounded
+   GO-007     CRITICAL security         SQL is parameterised
+   GO-008     MEDIUM   performance      HTTP servers set timeouts
+
+## stacks/rust — Rust (7 rules)
+   Activated when Rust is detected.
+   RS-001     MEDIUM   maintainability  Cargo.toml declares edition and metadata
+   RS-002     MEDIUM   correctness      No unwrap/expect in non-test code
+   RS-003     HIGH     security         unsafe blocks are justified and minimal
+   RS-004     MEDIUM   maintainability  Clippy runs in CI
+   RS-005     MEDIUM   correctness      No todo!/unimplemented! in shipped paths
+   RS-006     MEDIUM   supply-chain     Dependency audit runs in CI (cargo-audit / deny)
+   RS-007     LOW      performance      Release builds are optimised and stripped
+
+## stacks/jvm — Java / Kotlin / JVM (8 rules)
+   Activated when Java, Kotlin, or Scala is detected.
+   JVM-001    MEDIUM   supply-chain     Dependency versions are managed centrally
+   JVM-002    CRITICAL security         No hardcoded credentials in configuration
+   JVM-003    MEDIUM   correctness      Exception handling does not swallow stack traces
+   JVM-004    CRITICAL security         Parameterised SQL / JPA criteria instead of concatenation
+   JVM-005    LOW      correctness      Nullability is explicit
+   JVM-006    MEDIUM   supply-chain     Static analysis runs in CI
+   JVM-007    HIGH     security         Insecure deserialisation is avoided
+   JVM-008    LOW      performance      JVM/container memory limits are respected
+
+## stacks/web-frontend — Web Frontend (9 rules)
+   Activated for browser-facing applications. Covers Core Web Vitals, a11y, and bundle discipline.
+   WEB-001    MEDIUM   performance      Core Web Vitals are measured
+   WEB-002    MEDIUM   performance      Code splitting / lazy loading is used
+   WEB-003    MEDIUM   performance      Images are optimised
+   WEB-004    MEDIUM   compliance       Accessibility basics are in place
+   WEB-005    LOW      performance      Bundle size is monitored
+   WEB-006    MEDIUM   correctness      Error boundaries exist around risky UI
+   WEB-007    CRITICAL security         No secrets in client-side bundles
+   WEB-008    MEDIUM   compliance       Forms validate and expose errors accessibly
+   WEB-009    FUTURE   performance      An offline/PWA story exists
+
+## stacks/mobile — Mobile (iOS / Android / Cross-platform) (8 rules)
+   Activated when iOS, Android, React Native, Expo, or Flutter is detected.
+   MOB-001    HIGH     operations       Crash reporting is integrated
+   MOB-002    CRITICAL security         No hardcoded API secrets in app bundles
+   MOB-003    HIGH     security         Sensitive data is not stored insecurely on device
+   MOB-004    MEDIUM   security         Network security configuration is explicit
+   MOB-005    MEDIUM   compliance       Permissions are requested minimally and with rationale
+   MOB-006    MEDIUM   correctness      Offline behaviour is handled
+   MOB-007    HIGH     compliance       Privacy manifests / data collection disclosure are present
+   MOB-008    MEDIUM   correctness      Tested on multiple screen sizes and OS versions
+
+## stacks/containers — Containers & Runtime (8 rules)
+   Activated when Docker, compose, or Kubernetes manifests are detected.
+   CTNR-001   HIGH     security         Container does not run as root
+   CTNR-002   MEDIUM   performance      Multi-stage builds are used
+   CTNR-003   MEDIUM   supply-chain     Base image is minimal and pinned
+   CTNR-004   MEDIUM   supply-chain     A .dockerignore exists
+   CTNR-005   CRITICAL security         No secrets baked into the image
+   CTNR-006   MEDIUM   operations       HEALTHCHECK is defined
+   CTNR-007   MEDIUM   performance      Kubernetes workloads declare resource limits
+   CTNR-008   MEDIUM   supply-chain     Images are scanned and signed
+
+## stacks/iac — Infrastructure as Code & Cloud (7 rules)
+   Activated when Terraform/OpenTofu, Pulumi, Ansible, or Kubernetes manifests are detected.
+   IAC-001    CRITICAL security         No public exposure of storage buckets or databases
+   IAC-002    HIGH     security         Encryption at rest is enabled
+   IAC-003    MEDIUM   supply-chain     IaC is validated and scanned before apply
+   IAC-004    HIGH     operations       State is stored remotely and locked
+   IAC-005    HIGH     security         IAM follows least privilege
+   IAC-006    LOW      operations       Cloud spend is tagged and budgeted
+   IAC-007    HIGH     security         Kubernetes manifests avoid privileged containers
+
+## stacks/solidity — Blockchain / Smart Contracts (10 rules)
+   Activated when Solidity, Foundry, or Hardhat is detected. USAT is not a substitute for a third-party audit.
+   SOLID-001  CRITICAL security         Contracts are protected against reentrancy
+   SOLID-002  HIGH     security         Compiler version is 0.8+ (or SafeMath is used)
+   SOLID-003  CRITICAL security         Access control is explicit on privileged functions
+   SOLID-004  CRITICAL security         tx.origin is not used for authorisation
+   SOLID-005  HIGH     security         External calls are checked and treated as untrusted
+   SOLID-006  MEDIUM   security         No block.timestamp dependence for critical logic
+   SOLID-007  MEDIUM   maintainability  Events are emitted for state changes
+   SOLID-008  MEDIUM   operations       An emergency pause mechanism exists
+   SOLID-009  HIGH     correctness      A test suite with fuzzing/invariants exists
+   SOLID-010  HIGH     security         Third-party security audit has been performed
+
+## stacks/ml-ai — ML / AI Systems (9 rules)
+   Activated when PyTorch/TensorFlow/JAX, notebooks, or model artefacts are detected.
+   ML-001     MEDIUM   maintainability  Training data is versioned
+   ML-002     MEDIUM   operations       Model artefacts are versioned and registered
+   ML-003     MEDIUM   correctness      Training is reproducible (seeded and pinned)
+   ML-004     MEDIUM   operations       Model/data drift is monitored in production
+   ML-005     MEDIUM   compliance       Predictions are logged for audit
+   ML-006     MEDIUM   compliance       Bias/fairness has been evaluated
+   ML-007     MEDIUM   maintainability  Notebooks are not the deployment path
+   ML-008     LOW      performance      Inference cost and latency are tracked
+   ML-009     MEDIUM   maintainability  Model files are not committed to git
+
+## stacks/cli — CLI Tools (7 rules)
+   Activated when the project exposes a binary or console script entry point.
+   CLI-001    MEDIUM   documentation    --help is implemented and useful
+   CLI-002    MEDIUM   correctness      Exit codes are meaningful
+   CLI-003    HIGH     correctness      Destructive operations support --dry-run
+   CLI-004    MEDIUM   security         Input from arguments and stdin is validated
+   CLI-005    MEDIUM   correctness      Operations are idempotent where expected
+   CLI-006    LOW      correctness      Errors go to stderr, output to stdout
+   CLI-007    LOW      maintainability  Machine-readable output mode exists
+
+## stacks/data — Data & Database (10 rules)
+   Activated when a database, ORM, or migrations directory is detected.
+   DATA-001   HIGH     correctness      A migration system is in place
+   DATA-002   MEDIUM   correctness      Foreign keys / relations are defined
+   DATA-003   MEDIUM   performance      Indexes exist on queried columns
+   DATA-004   HIGH     performance      No N+1 query patterns
+   DATA-005   HIGH     performance      List queries are paginated
+   DATA-006   MEDIUM   performance      Connection pooling is configured
+   DATA-007   HIGH     correctness      Multi-step writes are transactional
+   DATA-008   LOW      performance      No SELECT * in hot paths
+   DATA-009   LOW      compliance       Delete strategy is defined
+   DATA-010   HIGH     security         Row-level access is enforced in the data layer
+
+## stacks/api-backend — Backend / API (8 rules)
+   Activated for server-side applications and API services.
+   API-001    MEDIUM   maintainability  The API is versioned
+   API-002    HIGH     performance      Request timeouts are configured
+   API-003    MEDIUM   performance      Retries are bounded with jitter
+   API-004    MEDIUM   correctness      Write operations are idempotent
+   API-005    LOW      maintainability  Response format is consistent
+   API-006    MEDIUM   documentation    An OpenAPI/contract spec exists and is current
+   API-007    HIGH     security         GraphQL depth/complexity limits are enforced
+   API-008    LOW      operations       Health and readiness endpoints are unauthenticated but minimal
+
+## stacks/compliance — Accessibility, i18n & Compliance (10 rules)
+   Accessibility, internationalisation, and regulatory obligations. Most of these are judgement calls — USAT records what it can and asks for evidence on the rest.
+
+   COMP-001   MEDIUM   compliance       Interactive elements are keyboard accessible
+   COMP-002   MEDIUM   compliance       Form inputs have associated labels
+   COMP-003   MEDIUM   compliance       Colour contrast meets WCAG AA
+   COMP-004   MEDIUM   compliance       Content is not hardcoded to one locale
+   COMP-005   LOW      compliance       Dates, numbers, and currencies are locale-aware
+   COMP-006   MEDIUM   compliance       A privacy policy and terms exist and match reality
+   COMP-007   HIGH     compliance       Data subject rights are implemented
+   COMP-008   HIGH     compliance       Card data is kept out of scope
+   COMP-009   MEDIUM   compliance       Cookie / consent notice is compliant
+   COMP-010   LOW      compliance       Source files carry an SPDX license identifier
+
+## stacks/ai-era — AI / LLM-Era Risks (12 rules)
+   New in USAT. Your application may be deterministic while depending on a component that is not. Mapped to the OWASP Top 10 for LLM Applications (2026) and the OWASP Top 10 for Agentic AI (ASI, 2026).
+
+   AI-001     CRITICAL security         Untrusted content cannot override instructions
+   AI-002     CRITICAL security         Model output is validated before it is executed
+   AI-003     HIGH     security         Agents and tools run with least privilege
+   AI-004     HIGH     security         Secrets and PII do not reach model providers unchecked
+   AI-005     MEDIUM   performance      Inference spend and token usage are bounded
+   AI-006     MEDIUM   security         System prompts and tool schemas are not exposed
+   AI-007     HIGH     security         RAG retrieval is access-controlled per tenant
+   AI-008     MEDIUM   supply-chain     Model and prompt supply chain is pinned
+   AI-009     MEDIUM   correctness      An eval suite exists for model behaviour
+   AI-010     HIGH     security         Consequential actions require human confirmation
+   AI-011     MEDIUM   security         Agent instruction files are scoped and safe
+   AI-012     LOW      compliance       Model inputs and outputs are logged for audit
+
+275 rule(s) across 27 pack(s).
+```