@xenos1996/usat 1.0.0

package/rules/core/dependencies.yaml

@@ -0,0 +1,132 @@
+id: core/dependencies
+title: Dependencies & Third-Party
+section: S10
+section_title: Dependencies & Third-Party
+description: >
+  Every dependency is a bet on someone else's maintenance discipline.
+  USAT scores the observable parts and hands the rest to review.
+version: '1.0'
+
+rules:
+  - id: DEP-001
+    title: Dependencies are declared in a manifest
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: MEDIUM
+    class: supply-chain
+    check:
+      kind: any_file
+      patterns:
+        [
+          'package.json',
+          'pyproject.toml',
+          'requirements*.txt',
+          'Cargo.toml',
+          'go.mod',
+          'pom.xml',
+          'build.gradle*',
+          'composer.json',
+          'Gemfile',
+          'Package.swift',
+          'pubspec.yaml',
+          'mix.exs',
+        ]
+    why: 'Undeclared dependencies mean the build works on one machine and nowhere else.'
+    remediation: 'Declare every import in the manifest; pin transitive risk with a lockfile.'
+    references: ['NIST-SSDF-PS.3.2']
+
+  - id: DEP-002
+    title: No known-HIGH/CRITICAL vulnerabilities in dependencies
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: HIGH
+    class: supply-chain
+    check:
+      kind: command
+      run: '! (npm audit --production --audit-level=high 2>/dev/null | grep -qiE "critical|high")'
+      expect_exit: 0
+    evidence: '`npm audit` / `pip-audit` / `osv-scanner` / `trivy fs` output dated today.'
+    why: 'Most modern compromises arrive through a transitive dependency, not your own code.'
+    remediation: 'Patch or replace the flagged package; if no fix exists, pin an unaffected version or drop the dependency.'
+    references: ['OpenSSF-Scorecard:Vulnerabilities', 'NIST-SSDF-RV.1.1']
+
+  - id: DEP-003
+    title: Dependencies are actively maintained
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: MEDIUM
+    class: supply-chain
+    depths: [deep]
+    check: { kind: manual }
+    evidence: 'For the top 10 direct dependencies: last release date, open-issue trend, and bus factor.'
+    why: 'An unmaintained dependency is a future incident you have already scheduled.'
+    remediation: 'Replace anything with no release in 24+ months, or fork it deliberately and own the fork.'
+    references: ['OpenSSF-Scorecard:Maintained', 'OpenSSF-Criticality-Score']
+
+  - id: DEP-004
+    title: No obviously redundant dependencies
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: LOW
+    class: maintainability
+    check: { kind: manual }
+    evidence: 'Two libraries doing the same job (e.g. both axios and node-fetch; both moment and date-fns).'
+    why: 'Two HTTP clients means two sets of CVEs, two upgrade paths, and an argument every PR.'
+    remediation: 'Pick one per concern and migrate; add a lint rule banning the loser.'
+    references: ['OpenSSF-Scorecard']
+
+  - id: DEP-005
+    title: Unused dependencies are pruned
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: LOW
+    class: maintainability
+    applies_when: { fact: 'pm:npm' }
+    check:
+      kind: command
+      run: '! (npx --yes depcheck@latest --json 2>/dev/null | grep -qE "\"unused\": \\[[^]]+\\]")'
+      expect_exit: 0
+    why: >-
+      Unused dependencies still install, still scan, and still produce CVEs. They are pure liability with no benefit.
+    evidence: 'depcheck / knip / pip-extra-reqs output.'
+    remediation: 'Remove unused packages; they still count against your CVE surface and install time.'
+    references: ['NIST-SSDF-PS.3.2']
+
+  - id: DEP-006
+    title: Licenses are compatible with the project license
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: MEDIUM
+    class: compliance
+    check: { kind: manual }
+    evidence: 'An SPDX license inventory of direct dependencies and any GPL/AGPL entries in a permissively-licensed or commercial project.'
+    why: 'One AGPL transitive dependency can force disclosure of your entire source.'
+    remediation: 'Generate an SBOM, run a license policy check in CI, and review anything copyleft before shipping.'
+    references: ['SPDX', 'OpenSSF-Scorecard:License', 'EU-CRA']
+
+  - id: DEP-007
+    title: External services have documented failure modes
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: manual }
+    evidence: 'For each third-party API you call: timeout, retry policy, and what the user sees when it is down.'
+    why: 'Your uptime is the product of every service you depend on, unless you degrade gracefully.'
+    remediation: 'Set explicit timeouts, bounded retries with jitter, circuit breakers, and a fallback path per integration.'
+    references: ['NIST-SSDF-PW.4', 'Release-It']
+
+  - id: DEP-008
+    title: Webhook payloads are signature-verified
+    section: S10
+    section_title: Dependencies & Third-Party
+    severity: HIGH
+    class: security
+    applies_when: { fact: 'has:payments' }
+    check: { kind: manual }
+    evidence: 'The webhook handler: file:line where the provider signature (HMAC) is verified before the payload is trusted.'
+    why: 'An unverified webhook endpoint is an unauthenticated API that writes to your database.'
+    remediation: 'Verify the provider HMAC over the raw body with a constant-time comparison before processing.'
+    references: ['CWE-345', 'ASVS-13.2.2']

package/rules/core/documentation.yaml

@@ -0,0 +1,119 @@
+id: core/documentation
+title: Documentation & Knowledge
+section: S12
+section_title: Documentation & Knowledge
+description: >
+  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.
+version: '1.0'
+
+rules:
+  - id: DOC-001
+    title: README covers what / install / run / contribute
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: MEDIUM
+    class: documentation
+    applies_when: { fact: 'doc:readme' }
+    check: { kind: manual }
+    evidence: 'The four headings. If any is missing, the README fails this check.'
+    why: 'A README that only says the project name is a README-shaped placeholder.'
+    remediation: 'Four sections: what it is, how to install, how to run it locally, how to contribute.'
+    references: ['CII-Best-Practices']
+
+  - id: DOC-002
+    title: Setup instructions have been verified recently
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: MEDIUM
+    class: documentation
+    check: { kind: manual }
+    evidence: 'A clean-machine clone-and-run within the last quarter, or CI that installs from scratch on every PR.'
+    why: 'Setup docs rot faster than any other file, and the cost lands on whoever joins next.'
+    remediation: 'Run the README steps in a container from scratch; fix every command that fails.'
+    references: ['CII-Best-Practices']
+
+  - id: DOC-003
+    title: Public APIs are documented
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: MEDIUM
+    class: documentation
+    applies_when:
+      any:
+        - { fact: 'project:library' }
+        - { fact: 'project:api' }
+        - { fact: 'doc:api-reference' }
+    check:
+      kind: any_file
+      patterns:
+        [
+          '**/openapi.{yaml,yml,json}',
+          '**/swagger.{yaml,yml,json}',
+          '**/*.graphql',
+          'docs/api/**',
+          'docs/reference/**',
+          '**/*.d.ts',
+        ]
+    why: 'For a library or API, the docs are the product surface.'
+    remediation: 'Publish an OpenAPI spec or typedoc/jsdoc output; generate it in CI so it cannot drift silently.'
+    references: ['OpenAPI', 'OpenSSF-Scorecard']
+
+  - id: DOC-004
+    title: Complex logic is explained at the point of use
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: LOW
+    class: documentation
+    check: { kind: manual }
+    evidence: 'Two non-obvious modules: does a comment explain WHY, not WHAT?'
+    why: 'Code tells you what it does. Only a comment can tell you why the obvious solution was wrong.'
+    remediation: 'Comment the surprising parts: workarounds, invariants, and anything you had to look up twice.'
+    references: ['Clean-Code']
+
+  - id: DOC-005
+    title: Docs live in the repo with the code
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: LOW
+    class: documentation
+    check:
+      kind: any_file
+      patterns: ['docs/**', '**/*.md']
+    why: 'Docs in a separate wiki are docs that outlive nobody and get updated by no one.'
+    remediation: 'Move docs next to the code so they are reviewed in the same PR.'
+    references: ['Docs-as-Code']
+
+  - id: DOC-006
+    title: An onboarding path exists
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: LOW
+    class: documentation
+    applies_when: { fact: 'metric:contributors', op: 'gt', value: 2 }
+    check:
+      kind: any_file
+      patterns:
+        [
+          '**/ONBOARDING*',
+          '**/onboarding*',
+          'docs/GETTING_STARTED*',
+          'docs/getting-started*',
+          'docs/onboarding/**',
+        ]
+    why: 'Without it, onboarding is a series of interruptions for whoever has been there longest.'
+    remediation: 'A single page: architecture in five bullets, setup, the three commands you need, and who to ask.'
+    references: ['CII-Best-Practices']
+
+  - id: DOC-007
+    title: Documentation examples are tested
+    section: S12
+    section_title: Documentation & Knowledge
+    severity: FUTURE
+    class: documentation
+    applies_when: { fact: 'project:library' }
+    check: { kind: manual }
+    evidence: 'Doctests, README code blocks executed in CI, or example apps built against the published API.'
+    why: 'The only thing worse than no example is an example that no longer works.'
+    remediation: 'Run README snippets in CI (mdsh, pytest-examples, or a small example app).'
+    references: ['Docs-as-Code']

package/rules/core/future-readiness.yaml

@@ -0,0 +1,91 @@
+id: core/future-readiness
+title: Future Readiness
+section: S16
+section_title: Future Readiness
+description: >
+  Not needed today, expensive to bolt on later. These are plans, not defects —
+  every rule here is FUTURE severity and never blocks a release.
+version: '1.0'
+
+rules:
+  - id: FUT-001
+    title: A path off the current architecture exists
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: maintainability
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'A written note on what the current architecture stops supporting (scale, team size, latency) and what you would do about it.'
+    why: 'Every architecture has a ceiling. Knowing where yours is turns a crisis into a project.'
+    remediation: 'Write one page: current limits, the trigger that would force a change, and the likely direction.'
+    references: ['Team-Topologies']
+
+  - id: FUT-002
+    title: No core technology is at or near end of life
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: maintainability
+    check: { kind: manual }
+    evidence: 'Runtime version, framework major versions, and their upstream EOL dates.'
+    why: 'Node 16, Python 3.8, and CentOS 7 all had an EOL date that everyone knew about in advance.'
+    remediation: 'Track EOL dates in the README; schedule upgrades one major behind current, never two.'
+    references: ['endoflife.date']
+
+  - id: FUT-003
+    title: Data archiving strategy exists
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: operations
+    applies_when: { fact: 'has:database' }
+    check: { kind: manual }
+    evidence: 'Retention policy per table/dataset and where cold data goes.'
+    why: 'A table nobody can archive eventually makes every query slow and every migration terrifying.'
+    remediation: 'Define retention per dataset; partition by time; move cold rows to object storage.'
+    references: ['AWS-Well-Architected']
+
+  - id: FUT-004
+    title: Multi-region or failover is at least designed
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: operations
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'Either a multi-region design, or a documented decision to accept single-region risk (with an RTO you have told customers about).'
+    why: 'You do not have to run multi-region. You do have to have decided.'
+    remediation: 'Document the decision; if single-region, keep backups cross-region so recovery is possible.'
+    references: ['AWS-Well-Architected:Reliability']
+
+  - id: FUT-005
+    title: A tech radar or equivalent exists
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: maintainability
+    applies_when: { fact: 'metric:contributors', op: 'gt', value: 4 }
+    check: { kind: manual }
+    evidence: 'A document listing technologies as adopt / trial / assess / hold, last reviewed within 12 months.'
+    why: 'Without it, every new project re-litigates the same choices with whoever argues hardest.'
+    remediation: 'Create a one-page radar; review it quarterly.'
+    references: ['Thoughtworks-Tech-Radar']
+
+  - id: FUT-006
+    title: Cost/usage is monitored
+    section: S16
+    section_title: Future Readiness
+    severity: FUTURE
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'has:serverless' }
+        - { fact: 'has:kubernetes' }
+        - { fact: 'has:terraform' }
+        - { fact: 'ai:llm-sdk' }
+    check: { kind: manual }
+    evidence: 'Cloud billing alerts, per-service cost attribution, or LLM token spend tracking.'
+    why: 'The bill is the one metric that always surprises people, usually quarterly.'
+    remediation: 'Tag resources by service; set budget alerts at 50/80/100%; review the top five line items monthly.'
+    references: ['FinOps', 'AWS-Well-Architected:Cost']

package/rules/core/release.yaml

@@ -0,0 +1,131 @@
+id: core/release
+title: Release & Change Management
+section: S9
+section_title: Release & Change Management
+description: >
+  How a merged commit becomes a version someone else depends on. This section
+  is what separates "we deploy" from "we ship".
+version: '1.0'
+
+rules:
+  - id: REL-001
+    title: Versioning is semantic and consistent
+    section: S9
+    section_title: Release & Change Management
+    severity: MEDIUM
+    class: maintainability
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: manual }
+    evidence: 'Current version, and whether MAJOR/MINOR/PATCH changes match SemVer in practice.'
+    why: 'Consumers (including your future self) need to know whether upgrading is safe.'
+    remediation: 'Adopt SemVer; automate version bumps from Conventional Commits (Changesets, semantic-release).'
+    references: ['SemVer', 'OpenSSF-Scorecard:Signed-Releases']
+
+  - id: REL-002
+    title: Releases are tagged in version control
+    section: S9
+    section_title: Release & Change Management
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: manual }
+    evidence: '`git tag --list` output, or the release automation config that creates tags.'
+    why: 'Without tags, "what is running in production?" has no answer you can look up.'
+    remediation: 'Tag every release (v1.2.3) and deploy from the tag, not from a branch tip.'
+    references: ['SLSA-Source', 'OpenSSF-Scorecard:Signed-Releases']
+
+  - id: REL-003
+    title: Release notes are published
+    section: S9
+    section_title: Release & Change Management
+    severity: LOW
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: grep_present
+      pattern: '(semantic-release|release-drafter|changesets|changeset version|generate-notes|release_notes|changelog)'
+      include:
+        [
+          '.github/workflows/*.yml',
+          '.github/workflows/*.yaml',
+          '.github/release.yml',
+          'package.json',
+          '.changeset/config.json',
+          'Makefile',
+        ]
+      flags: i
+    why: 'A tag with no notes makes every upgrade an archaeology project for your users.'
+    remediation: 'Generate notes from commit scope; hand-edit the breaking-changes section.'
+    references: ['Keep-a-Changelog']
+
+  - id: REL-004
+    title: Risky changes sit behind a feature flag
+    section: S9
+    section_title: Release & Change Management
+    severity: LOW
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'maturity:production' }
+        - { fact: 'maturity:beta' }
+    check:
+      kind: grep_present
+      pattern: '(launchdarkly|unleash|flagsmith|growthbook|posthog|openfeature|isFeatureEnabled|featureFlag|useFlag|flipper)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb}']
+      exclude: ['**/*.test.*', '**/node_modules/**']
+      flags: i
+    why: 'Deploy and release are different verbs. Flags let you deploy on Tuesday and release on Thursday.'
+    remediation: 'Wrap new behaviour in a flag with a default-off rollout and a documented kill switch.'
+    references: ['DORA', 'Progressive-Delivery']
+
+  - id: REL-005
+    title: Database migrations run forward and are reversible
+    section: S9
+    section_title: Release & Change Management
+    severity: HIGH
+    class: correctness
+    applies_when: { fact: 'has:database' }
+    check: { kind: manual }
+    evidence: 'Migration tool in use, and for the last destructive migration: the expand/contract or down-migration plan.'
+    why: 'A migration you cannot reverse is a one-way door taken during a deploy, usually at the worst moment.'
+    remediation: 'Use expand/contract: add column → backfill → switch reads → drop later. Keep down-migrations tested for everything else.'
+    references: ['NIST-SSDF-PO.5']
+
+  - id: REL-006
+    title: Migrations are separated from application deploys
+    section: S9
+    section_title: Release & Change Management
+    severity: MEDIUM
+    class: correctness
+    applies_when: { fact: 'has:database' }
+    check: { kind: manual }
+    evidence: 'Deploy order: does the schema change ship before the code that requires it?'
+    why: 'Deploying code and schema simultaneously means the old code briefly runs against the new schema.'
+    remediation: 'Run migrations as a separate, first step; keep every change backward-compatible with the currently deployed version.'
+    references: ['Expand-Contract']
+
+  - id: REL-007
+    title: There is a documented incident/runbook path
+    section: S9
+    section_title: Release & Change Management
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'maturity:production' }
+    check:
+      kind: any_file
+      patterns:
+        [
+          '**/RUNBOOK*',
+          '**/runbook*',
+          'docs/runbooks/**',
+          'runbooks/**',
+          'docs/on-call*',
+          'docs/incident*',
+          'INCIDENT.md',
+        ]
+    why: 'The middle of an incident is the worst possible time to discover nobody wrote down how to restart the queue.'
+    remediation: 'One runbook per service: how to check health, restart, roll back, escalate, and who owns it.'
+    references: ['NIST-SSDF-RV.2', 'Google-SRE']