@xenos1996/usa 2.3.4 → 2.5.0

package/rules/core/foundation.yaml

@@ -0,0 +1,307 @@
+id: core/foundation
+title: Foundation Readiness
+section: S3
+section_title: Foundation Readiness
+description: >
+  Deterministic repo-setup readiness checks across seven pillars — docs,
+  governance, AI-readiness, testing, environment, pipelines, and standards —
+  so a project can be audited, built, and extended by humans and agents alike.
+  Intent-gated rules apply only when the interview declares a matching intent;
+  without the foundation file those rules skip and the generic ones still apply.
+version: '1.0'
+
+rules:
+  - id: FND-001
+    title: A README exists at the top level
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: documentation
+    tags: ['pillar:docs']
+    check:
+      kind: any_file
+      patterns:
+        - 'README.md'
+        - 'README.rst'
+        - 'README.txt'
+        - 'README'
+        - 'readme.md'
+        - 'readme.txt'
+        - 'readme'
+    why: 'A repo without a README has no front door: neither a human nor an agent can learn what it is or how to start.'
+    remediation: 'Add a README with purpose, setup steps, and how to run the checks.'
+    references: ['CII-Best-Practices']
+
+  - id: FND-002
+    title: License, contribution, and security docs are present
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: compliance
+    tags: ['pillar:docs']
+    check:
+      kind: count_min
+      patterns:
+        - '**/LICENSE*'
+        - '**/LICENCE*'
+        - '**/COPYING*'
+        - '**/CONTRIBUTING*'
+        - '**/SECURITY*'
+        - '**/CODE_OF_CONDUCT*'
+      min: 2
+    why: 'Missing license, contribution, or security-contact docs turn every external contribution and disclosure into a judgement call.'
+    remediation: 'Commit a LICENSE plus at least one of CONTRIBUTING, SECURITY, or CODE_OF_CONDUCT.'
+    references: ['OpenSSF-Scorecard:License', 'OpenSSF-Scorecard:Security-Policy', 'SPDX']
+
+  - id: FND-003
+    title: A CODEOWNERS file assigns review ownership
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: compliance
+    tags: ['pillar:governance']
+    check:
+      kind: any_file
+      patterns:
+        - '**/CODEOWNERS'
+    why: 'Without declared owners, reviews fall to whoever happens to look, and critical paths go unreviewed.'
+    remediation: 'Add a CODEOWNERS file mapping critical paths to the teams that must review them.'
+    references: ['OpenSSF-Scorecard:Code-Review']
+
+  - id: FND-004
+    title: Branch-protection evidence lives in .github
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: compliance
+    tags: ['pillar:governance']
+    check:
+      kind: grep_present
+      pattern: '(branch-?protection|required_pull_request_reviews|required_status_checks|require_code_owner_reviews|dismiss_stale_reviews)'
+      include: ['.github/**/*']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'Branch protection configured only in the forge UI is invisible to audit; checked-in evidence keeps the control reviewable.'
+    remediation: 'Check in branch-protection evidence (e.g. a settings or policy file under .github) requiring reviews and status checks.'
+    references: ['OpenSSF-Scorecard:Branch-Protection', 'SLSA-Source']
+
+  - id: FND-005
+    title: Architecture decisions are recorded as ADRs
+    section: S3
+    section_title: Foundation Readiness
+    severity: LOW
+    class: documentation
+    tags: ['pillar:governance']
+    check:
+      kind: any_file
+      patterns:
+        - 'docs/adr/**'
+        - 'docs/adrs/**'
+        - 'doc/adr/**'
+        - 'adr/**'
+        - 'adrs/**'
+        - 'docs/decisions/**'
+    why: 'Decisions without records get re-litigated forever; ADRs preserve the context future changes need.'
+    remediation: 'Record significant decisions as ADRs under docs/adr.'
+    references: ['ADR-Nygard']
+
+  - id: FND-006
+    title: Agent instructions (AGENTS.md or llms.txt) exist
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: documentation
+    tags: ['pillar:ai-readiness']
+    check:
+      kind: any_file
+      patterns:
+        - 'AGENTS.md'
+        - 'agents.md'
+        - 'llms.txt'
+    why: 'Agents working without project instructions improvise conventions; a checked-in instruction file makes machine collaboration deterministic.'
+    remediation: 'Add an AGENTS.md (or llms.txt) with build, test, and contribution instructions for agents.'
+    references: ['Agent-Skills', 'Docs-as-Code']
+
+  - id: FND-007
+    title: Docs carry machine-readable markers
+    section: S3
+    section_title: Foundation Readiness
+    severity: LOW
+    class: documentation
+    tags: ['pillar:ai-readiness']
+    check:
+      kind: grep_present
+      pattern: '(usa:[a-z0-9:_-]+|machine-readable|llms\.txt|AGENTS\.md)'
+      include: ['**/*.md', '**/*.txt']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'Markers agents can parse (fact flags, machine-readable pointers) turn prose docs into instructions automation can follow.'
+    remediation: 'Reference AGENTS.md/llms.txt from the README and tag machine-actionable facts with usa: markers.'
+    references: ['Agent-Skills', 'Docs-as-Code']
+
+  - id: FND-008
+    title: A test directory exists
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: correctness
+    tags: ['pillar:testing']
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/**'
+        - 'test/**'
+        - '__tests__/**'
+        - 'spec/**'
+        - 'e2e/**'
+    why: 'A conventional test location tells contributors and CI exactly where confidence lives.'
+    remediation: 'Create a tests (or test/__tests__/spec) directory and put the first happy-path test there.'
+    references: ['OpenSSF-Scorecard:CI-Tests', 'NIST-SSDF-RV.1.1']
+
+  - id: FND-009
+    title: A coverage configuration exists
+    section: S3
+    section_title: Foundation Readiness
+    severity: LOW
+    class: correctness
+    tags: ['pillar:testing']
+    check:
+      kind: any_file
+      patterns:
+        - '.codecov.yml'
+        - '.codecov.yaml'
+        - 'codecov.yml'
+        - 'codecov.yaml'
+        - '**/vitest.config.*'
+        - '**/jest.config.*'
+        - '**/vitest.coverage.*'
+        - '**/.nycrc*'
+        - '**/coveragerc'
+        - '**/.coveragerc'
+        - '**/coverage.config.*'
+    why: 'Coverage that is never configured is never collected; the config is the commitment that coverage runs somewhere.'
+    remediation: 'Add a coverage config (e.g. codecov.yml or coverage settings in your test runner config).'
+    references: ['NIST-SSDF-RV.1.1']
+
+  - id: FND-010
+    title: The runtime version is pinned
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: operations
+    tags: ['pillar:environment']
+    check:
+      kind: any_file
+      patterns:
+        - '.nvmrc'
+        - '.node-version'
+        - '.tool-versions'
+        - '.python-version'
+        - '.ruby-version'
+        - '.go-version'
+        - 'runtime.txt'
+        - 'go.mod'
+        - 'Cargo.toml'
+        - 'pom.xml'
+        - 'Package.swift'
+        - '.java-version'
+    why: 'An unpinned runtime means every machine builds with a different toolchain; "works on my machine" starts here.'
+    remediation: 'Pin the runtime with .nvmrc, .tool-versions, .python-version, or the ecosystem equivalent.'
+    references: ['NIST-SSDF-PS.3.2', 'Reproducible-Builds']
+
+  - id: FND-011
+    title: The environment is reproducible from checked-in files
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: operations
+    tags: ['pillar:environment']
+    check:
+      kind: count_min
+      patterns:
+        - '.env.example'
+        - '.env.sample'
+        - '.env.template'
+        - 'Dockerfile'
+        - 'Dockerfile.*'
+        - 'Containerfile'
+        - 'compose.yml'
+        - 'compose.yaml'
+        - 'docker-compose.yml'
+        - 'docker-compose.yaml'
+        - '.devcontainer/devcontainer.json'
+        - 'Vagrantfile'
+      min: 2
+    why: "Setup that lives in one person's shell history is not setup; an env example plus a container definition lets anyone boot the project."
+    remediation: 'Commit a .env.example and a Dockerfile (or compose/devcontainer definition) so setup is declarative.'
+    references: ['12-Factor:Config', '12-Factor:Dev-Prod-Parity']
+
+  - id: FND-012
+    title: A CI workflow exists
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: operations
+    tags: ['pillar:pipelines']
+    check:
+      kind: any_file
+      patterns:
+        - '.github/workflows/*.yml'
+        - '.github/workflows/*.yaml'
+        - '.gitlab-ci.yml'
+        - 'Jenkinsfile'
+        - '.circleci/config.yml'
+        - 'azure-pipelines.yml'
+        - '.buildkite/**'
+        - 'bitbucket-pipelines.yml'
+    why: 'Without CI, every quality gate is advisory; the workflow file is the proof the gates actually run.'
+    remediation: 'Add a CI workflow that runs build, tests, and lint on every pull request.'
+    references: ['OpenSSF-Scorecard:CI-Tests', 'DORA']
+
+  - id: FND-013
+    title: A local task runner captures common workflows
+    section: S3
+    section_title: Foundation Readiness
+    severity: LOW
+    class: operations
+    tags: ['pillar:pipelines']
+    check:
+      kind: any_file
+      patterns:
+        - 'Makefile'
+        - 'makefile'
+        - 'GNUmakefile'
+        - 'justfile'
+        - 'Justfile'
+        - '.justfile'
+        - 'Taskfile.yml'
+        - 'Taskfile.yaml'
+        - 'Taskfile.dist.yml'
+        - 'tasks.py'
+    why: 'Tribal "run these five commands" knowledge rots; a task runner makes setup, test, and lint one documented command each.'
+    remediation: 'Add a Makefile or justfile with setup, test, and lint targets.'
+    references: ['DORA']
+
+  - id: FND-014
+    title: A machine-readable API contract is checked in
+    section: S3
+    section_title: Foundation Readiness
+    severity: MEDIUM
+    class: compliance
+    tags: ['pillar:standards']
+    applies_when:
+      any:
+        - { fact: 'intent:api' }
+        - { fact: 'intent:service' }
+    check:
+      kind: any_file
+      patterns:
+        - '**/openapi.{json,yaml,yml}'
+        - '**/swagger.{json,yaml,yml}'
+        - '**/asyncapi.{json,yaml,yml}'
+        - '**/api/*.yaml'
+        - '**/api/*.yml'
+        - '**/api/*.json'
+    why: 'An API without a checked-in contract cannot be reviewed, mocked, or tested by machines; the spec is the interface under version control.'
+    remediation: 'Check in an OpenAPI (or AsyncAPI) document describing the service contract.'
+    references: ['OpenAPI']

package/rules/core/testing-assurance.yaml

@@ -0,0 +1,240 @@
+id: core/testing-assurance
+title: Testing Assurance Markers
+section: S7
+section_title: Testing & Quality Assurance
+description: >
+  Deterministic presence-markers for the testing assurance program: unit,
+  integration, and system layouts; contract tests; coverage and mutation
+  evidence; retry/determinism guards; failure assertions; and test-data
+  isolation. Every rule asserts only that a marker exists — never that the
+  tests are good, sufficient, or green.
+version: '1.0'
+
+rules:
+  - id: TAS-001
+    title: A unit-test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/unit/**'
+        - 'test/unit/**'
+        - 'unit/**'
+        - '**/*.unit.test.*'
+        - '**/*.unit.spec.*'
+    why: 'A conventional unit-test location tells contributors and CI exactly where confidence lives.'
+    remediation: 'Put unit tests under tests/unit (or mark them *.unit.test.*) and wire the directory into CI.'
+    references: ['Testing-Trophy', 'OpenSSF-Scorecard:CI-Tests']
+
+  - id: TAS-002
+    title: An integration-test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/integration/**'
+        - 'test/integration/**'
+        - 'tests/integ/**'
+        - '**/*.integration.test.*'
+        - '**/*.integ.test.*'
+        - '**/*.int.test.*'
+    why: 'Unit tests with everything mocked verify the mock, not the seam; a named integration layout is where seam coverage lives.'
+    remediation: 'Add tests/integration with tests that exercise a real database, queue, or HTTP boundary.'
+    references: ['Testing-Trophy']
+
+  - id: TAS-003
+    title: A system/end-to-end test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/e2e/**'
+        - 'test/e2e/**'
+        - 'e2e/**'
+        - 'tests/system/**'
+        - 'test/system/**'
+        - 'system-tests/**'
+        - '**/*.e2e.*'
+    why: 'Unit tests cannot tell you that checkout is broken because a button moved; a system-level layout is where journey coverage lives.'
+    remediation: 'Cover three journeys first: sign up/log in, the core money path, and the path that would lose data if it failed.'
+    references: ['Testing-Trophy']
+
+  - id: TAS-004
+    title: Contract tests are present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'pacts/**'
+        - 'pact/**'
+        - '**/*.pact.*'
+        - 'tests/contracts/**'
+        - 'tests/contract/**'
+        - 'test/contracts/**'
+        - '**/*.contract.test.*'
+        - '**/*.contract.spec.*'
+    why: 'An API without checked-in consumer contracts can only be tested by hand; pact files and contract suites are the machine-checkable shadow of that agreement.'
+    remediation: 'Record consumer-driven contracts (e.g. Pact) or add a tests/contracts suite asserting request/response shapes.'
+    references: ['OpenAPI', 'Testing-Trophy']
+
+  - id: TAS-005
+    title: Coverage configuration or output is present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - '.codecov.yml'
+        - 'codecov.yml'
+        - 'codecov.yaml'
+        - '.coveragerc'
+        - '.nycrc'
+        - '.nycrc.json'
+        - '.c8rc'
+        - '.c8rc.json'
+        - 'coverage/**'
+        - '**/lcov.info'
+    why: 'Unmeasured coverage drifts down silently; a coverage config or report artifact proves measurement was set up at least once.'
+    remediation: 'Turn on coverage reporting in the test runner and publish the number on every PR.'
+    references: ['NIST-SSDF-RV.1.1']
+
+  - id: TAS-006
+    title: A coverage threshold is pinned in the package.json-embedded jest config
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: json_path
+      file: 'package.json'
+      path: 'jest.coverageThreshold'
+    why: 'A gate stops the slide — but this check reads only the package.json-embedded jest config, the one JSON location with a stable schema. Thresholds kept in vitest.config, jest.config.js, or .nycrc are invisible to it.'
+    remediation: 'Set jest.coverageThreshold in package.json, or keep the threshold wherever the runner reads it and accept this marker as not-applicable.'
+    references: ['NIST-SSDF-RV.1.1']
+
+  - id: TAS-007
+    title: Mutation-testing evidence is present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: FUTURE
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'reports/**/*mut*'
+        - 'reports/mutation/**'
+        - 'stryker.conf.*'
+        - '.stryker.conf.*'
+        - '.mutmut*'
+        - 'mutants/**'
+    why: 'Coverage tells you which lines ran, not whether the test would have failed if the line were wrong; a mutation config or report proves the question was asked.'
+    remediation: 'Run mutation testing on the highest-risk module first and keep the config or report in the repo.'
+    references: ['Mutation-Testing']
+
+  - id: TAS-008
+    title: A determinism guard is set in test config or CI
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: grep_present
+      pattern: '(forbidOnly|forbid-only|forbid_only|failOnConsole|fail-on-console)'
+      include:
+        [
+          'playwright.config.*',
+          'cypress.config.*',
+          'vitest.config.*',
+          'vitest.workspace.*',
+          'jest.config.*',
+          'package.json',
+          '.github/workflows/*.yml',
+          '.github/workflows/*.yaml',
+          '.gitlab-ci.yml',
+        ]
+    why: 'Focused-test markers (.only) committed by accident silently skip the rest of the suite; a forbid-only guard string proves the leak was thought about.'
+    remediation: 'Set forbidOnly on CI (e.g. Playwright forbidOnly) so a stray .only fails the build instead of shrinking it.'
+    references: ['Google-Testing-Blog:Flaky']
+
+  - id: TAS-009
+    title: A test retry budget is declared
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: operations
+    check:
+      kind: grep_present
+      pattern: '(retries\s*:\s*[1-9]|"retries"\s*:\s*[1-9]|retries=[1-9]|--retries[ =][1-9]|rerun-failed|flaky-test-retry|retry-on-failure)'
+      include:
+        [
+          'playwright.config.*',
+          'cypress.config.*',
+          'vitest.config.*',
+          'jest.config.*',
+          'package.json',
+          '.github/workflows/*.yml',
+          '.github/workflows/*.yaml',
+          '.gitlab-ci.yml',
+        ]
+    why: 'A retries setting proves the project pays for reruns; it proves nothing about whether the tests are flaky or stable — only that the budget exists.'
+    remediation: 'Declare an explicit retry budget (e.g. retries: 2 on CI) and track which tests consume it; quarantine chronic consumers.'
+    references: ['Google-Testing-Blog:Flaky']
+
+  - id: TAS-010
+    title: Tests assert failure paths
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: grep_present
+      pattern: '(\.toThrow\(|\.rejects|pytest\.raises|assertRaises|assert\.rejects|ShouldThrow|assert\.throws)'
+      include:
+        [
+          '**/*.test.*',
+          '**/*.spec.*',
+          '**/test_*.py',
+          '**/*_test.*',
+          'tests/**',
+          'test/**',
+          '__tests__/**',
+          'spec/**',
+        ]
+    why: 'A suite that only asserts happy paths never proves the error handling works; failure-assertion strings prove at least one test looks at the sad path.'
+    remediation: 'Add negative tests for every permission boundary and every error branch — 401/403 paths, validation rejections, and cross-tenant attempts.'
+    references: ['Testing-Patterns']
+
+  - id: TAS-011
+    title: Test-data and environment isolation markers exist
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: maintainability
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/fixtures/**'
+        - 'test/fixtures/**'
+        - '**/__fixtures__/**'
+        - '**/factories/**'
+        - '**/__factories__/**'
+        - '.env.test'
+        - '.env.testing'
+        - 'tests/.env.test'
+    why: 'Hand-built object literals in 200 tests make every schema change a 200-file migration, and tests sharing the live environment leak state; fixtures, factories, and a dedicated test env file are the markers of isolation.'
+    remediation: 'Add a factory or fixtures directory and a .env.test so tests generate data and never touch the dev or prod environment.'
+    references: ['Testing-Patterns', '12-Factor:Config']

package/rules/index.yaml

@@ -13,11 +13,13 @@ packs:
   - core/repo.yaml
   - core/security.yaml
   - core/supply-chain.yaml
+  - core/foundation.yaml
   - core/provenance-cosign.yaml
   - core/provenance-attestation.yaml
   - core/architecture.yaml
   - core/code-quality.yaml
   - core/testing.yaml
+  - core/testing-assurance.yaml
   - core/cicd.yaml
   - core/release.yaml
   - core/dependencies.yaml