@xenos1996/usa 2.0.0

package/rules/core/code-quality.yaml

@@ -0,0 +1,261 @@
+id: core/code-quality
+title: Code Quality
+section: S5
+section_title: Code Quality
+description: >
+  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.
+version: '1.0'
+
+rules:
+  - id: CQ-001
+    title: A linter is configured
+    section: S5
+    section_title: Code Quality
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: any_file
+      patterns:
+        - '.eslintrc*'
+        - 'eslint.config.*'
+        - 'biome.json*'
+        - '.ruff.toml'
+        - 'ruff.toml'
+        - '.flake8'
+        - 'setup.cfg'
+        - '.pylintrc'
+        - 'pyproject.toml'
+        - '.golangci*'
+        - 'clippy.toml'
+        - '.rustfmt.toml'
+        - 'rustfmt.toml'
+        - '.rubocop.yml'
+        - 'phpcs.xml*'
+        - 'detekt.yml'
+        - '.swiftlint.yml'
+    why: 'Style arguments in review are a tax on every pull request. Automate them and argue about design instead.'
+    remediation: 'Add the standard linter for your stack, start with its recommended config, fix what it finds.'
+    references: ['NIST-SSDF-PW.7']
+
+  - id: CQ-002
+    title: A formatter is configured
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: style
+    check:
+      kind: any_file
+      patterns:
+        [
+          '.prettierrc*',
+          'prettier.config.*',
+          'biome.json*',
+          '.editorconfig',
+          '.rustfmt.toml',
+          'rustfmt.toml',
+          '.clang-format',
+          'pyproject.toml',
+          '.gofmt*',
+        ]
+    why: 'Formatting diffs hide real changes. Let a tool own it.'
+    remediation: 'Prettier/Black/gofmt/rustfmt — pick the default config and stop discussing it.'
+    references: ['NIST-SSDF-PW.7']
+
+  - id: CQ-003
+    title: Type checking is enabled and strict
+    section: S5
+    section_title: Code Quality
+    severity: MEDIUM
+    class: correctness
+    applies_when:
+      any:
+        - { fact: 'lang:typescript' }
+        - { fact: 'lang:python' }
+    check:
+      kind: grep_present
+      pattern: '("strict"\s*:\s*true|strict\s*=\s*true|\[tool\.mypy\]|\[tool\.pyright\]|noImplicitAny|disallow_untyped_defs)'
+      include:
+        [
+          'tsconfig.json',
+          'tsconfig.*.json',
+          'pyproject.toml',
+          'setup.cfg',
+          'mypy.ini',
+          '.mypy.ini',
+          'pyrightconfig.json',
+        ]
+      flags: i
+    why: 'Types are the cheapest tests you will ever write. Lenient mode is types with the batteries removed.'
+    remediation: 'TypeScript: "strict": true. Python: mypy or pyright with strict settings on new modules.'
+    references: ['ISO-5055']
+
+  - id: CQ-004
+    title: Type escapes are not used as a default
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: maintainability
+    applies_when: { fact: 'lang:typescript' }
+    check:
+      kind: grep_absent
+      pattern: '(@ts-ignore|@ts-expect-error|:\s*any\b|\bas any\b|as unknown as)'
+      include: ['**/*.{ts,tsx}']
+      exclude: ['**/*.test.*', '**/*.spec.*', '**/*.d.ts']
+    why: 'Every `any` is a place the type system was told to stop helping. A few are fine; a pattern is a problem.'
+    remediation: 'Type the boundary properly, or narrow with a type guard. Delete stale @ts-ignore comments.'
+    references: ['ISO-5055']
+
+  - id: CQ-005
+    title: Errors are handled, not swallowed
+    section: S5
+    section_title: Code Quality
+    severity: HIGH
+    class: correctness
+    check:
+      kind: grep_absent
+      pattern: '(catch\s*\(\s*\w*\s*\)\s*\{\s*\}|except\s*:\s*(pass|\.\.\.)\s*$|catch\s*\{\s*\}|rescue\s*\n\s*end)'
+      include: ['**/*.{ts,tsx,js,jsx,mjs,cjs,py,go,rs,java,kt,rb,php,cs}']
+      exclude: ['**/*.test.*', '**/*.spec.*']
+      flags: i
+    why: 'An empty catch block converts a failure into a mystery. The bug report you get six weeks later will be useless.'
+    remediation: 'Log with context and either handle it or re-throw. If it is genuinely ignorable, say why in a comment.'
+    references: ['CWE-390', 'ASVS-7.4.1']
+
+  - id: CQ-006
+    title: There is a central error handler
+    section: S5
+    section_title: Code Quality
+    severity: MEDIUM
+    class: correctness
+    applies_when:
+      any:
+        - { fact: 'platform:server' }
+        - { fact: 'platform:web' }
+    check:
+      kind: grep_present
+      pattern: '(ErrorBoundary|errorHandler|error_handler|@ControllerAdvice|ExceptionHandler|app\.use\(\s*\(\s*err|onerror|useErrorBoundary|Sentry\.(captureException|init))'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php}']
+      exclude: ['**/*.test.*', '**/*.spec.*']
+    why: 'Without a top-level handler, an unhandled rejection is a white screen or a dropped request.'
+    remediation: 'Add a framework-level error handler and an ErrorBoundary (React); report to your error tracker.'
+    references: ['ASVS-7.4.1']
+
+  - id: CQ-007
+    title: Logging is structured and levelled
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'platform:server' }
+        - { fact: 'project:cli' }
+    check:
+      kind: manual
+    why: >-
+      Unstructured logs cannot be queried, alerted on, or correlated. At 3am, grep is not a strategy.
+    evidence: 'Sample log output: JSON or key=value, with DEBUG/INFO/WARN/ERROR used consistently.'
+    remediation: 'Emit JSON logs with a timestamp, level, message, and structured fields. Never log a bare concatenated string.'
+    references: ['OpenTelemetry-Logs', 'ASVS-7.1.1']
+
+  - id: CQ-008
+    title: Requests carry a correlation/trace ID
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: operations
+    applies_when: { fact: 'platform:server' }
+    check:
+      kind: grep_present
+      pattern: '(correlation[_-]?id|request[_-]?id|trace[_-]?id|x-request-id|traceId|requestId|traceContext)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt}']
+      exclude: ['**/*.test.*', '**/*.spec.*']
+      flags: i
+    why: 'Without a request ID, debugging a production incident means grepping 40 million lines and praying.'
+    remediation: 'Generate an ID per request, put it in every log line and in the response header.'
+    references: ['OpenTelemetry', 'W3C-Trace-Context']
+
+  - id: CQ-009
+    title: Debug statements are not left in production paths
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: style
+    applies_when:
+      not: { fact: 'project:cli' }
+    check:
+      kind: grep_absent
+      pattern: '(console\.(log|debug|info)\s*\(|print\s*\(\s*[''"]DEBUG|pdb\.set_trace|debugger\s*;|var_dump\s*\()'
+      include: ['**/*.{ts,tsx,js,jsx,mjs,cjs,py,php,rb,go,rs,java,kt}']
+      exclude: ['**/*.test.*', '**/*.spec.*', '**/scripts/**', '**/tools/**', '**/debug/**']
+    why: 'Stray debug output is noise at best and a data leak at worst.'
+    remediation: 'Use the project logger, or delete the line. Add a lint rule to keep it out.'
+    references: ['CWE-532']
+
+  - id: CQ-010
+    title: TODO/FIXME debt is tracked, not just annotated
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: maintainability
+    check:
+      kind: grep_wrong
+      pattern: '(TODO|FIXME|XXX|HACK|WORKAROUND)\b'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php,cs,yml,yaml}']
+      exclude: ['**/*.md', '**/docs/**', '**/node_modules/**']
+    why: 'A TODO with no owner and no ticket is a lie the codebase tells itself.'
+    remediation: 'Convert each one to a tracked issue with a link in the comment, or delete it if it no longer applies.'
+
+  - id: CQ-011
+    title: Functions do one thing
+    section: S5
+    section_title: Code Quality
+    severity: LOW
+    class: maintainability
+    depths: [deep]
+    check: { kind: manual }
+    why: >-
+      A function that needs "and" to describe is two functions. Long functions hide branches nobody tests.
+    evidence: 'Three representative functions over ~60 lines: can each be described in one sentence?'
+    remediation: 'Extract until each function reads as a single step at the current level of abstraction.'
+    references: ['Clean-Code', 'ISO-5055']
+
+  - id: CQ-012
+    title: Duplicated logic has been consolidated
+    section: S5
+    section_title: Code Quality
+    severity: MEDIUM
+    class: maintainability
+    depths: [deep]
+    check: { kind: manual }
+    evidence: 'Output of a duplication checker (jscpd, PMD CPD, sonar) — and the top three duplicates by size.'
+    why: 'Every copy is a place a bug fix will not reach.'
+    remediation: 'Extract the shared logic; accept duplication only when the two copies are expected to diverge.'
+    references: ['ISO-5055', 'Anti-pattern:Shotgun-Surgery']
+
+  - id: CQ-013
+    title: Complexity is measured
+    section: S5
+    section_title: Code Quality
+    severity: FUTURE
+    class: maintainability
+    depths: [deep]
+    check:
+      kind: grep_present
+      pattern: '(complexity|cyclomatic|radon|gocyclo|cognitive)'
+      include:
+        [
+          '**/.eslintrc*',
+          'eslint.config.*',
+          'pyproject.toml',
+          '.ruff.toml',
+          'setup.cfg',
+          '.golangci*',
+          'sonar-project.properties',
+        ]
+      flags: i
+    why: 'You cannot argue about complexity without a number.'
+    remediation: 'Enable an eslint complexity rule (≤10) or radon/gocyclo; report rather than hard-fail at first.'
+    references: ['ISO-5055']

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.
+  USA 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. USA 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']