@xenos1996/usa 2.0.0

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']

package/rules/core/repo.yaml

@@ -0,0 +1,313 @@
+id: core/repo
+title: Repository & Project Structure
+section: S1
+section_title: Repository & Project Structure
+description: >
+  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.
+version: '1.0'
+
+rules:
+  - id: REPO-001
+    title: .gitignore is present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check: { kind: file_exists, files: ['.gitignore'] }
+    why: >
+      Without a .gitignore the next `git add -A` commits node_modules, build
+      output, and — sooner or later — a .env file.
+    remediation: 'Add a .gitignore for your stack (github/gitignore has templates).'
+    references: ['CWE-540', 'OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-002
+    title: No environment/secret files committed
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          '.env',
+          '.env.*',
+          '*.env',
+          '*.pem',
+          '*.key',
+          '*.p12',
+          '*.pfx',
+          'id_rsa*',
+          'credentials*',
+          'secrets/**',
+          '.npmrc',
+          '.pypirc',
+        ]
+    why: 'A committed .env is a published credential. Rotating is the only fix.'
+    remediation: 'Remove from the index, rotate every value in the file, purge history (git filter-repo / BFG), add to .gitignore.'
+    references: ['CWE-798', 'ASVS-14.3.2', 'OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-003
+    title: No secrets in git history
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check:
+      kind: command
+      # NOTE: stage 1 allows one optional quote: most real secrets in history
+      # are quoted (`"token": "abc…"`, `key = "abc…"`), and a rule blind to
+      # them is decorative. Stage 2 drops only unquoted type-annotation
+      # shapes (`privateKey: NIOSSLPrivateKey`, `token: String`) — a bare
+      # capitalized identifier after a colon is a type, not a value. Exit
+      # algebra: the first grep runs WITHOUT -q so lines flow; only the
+      # final grep is quiet (matches must never reach CI logs). -v exits 1
+      # (→ PASS) only when every match was a declaration; any other hit
+      # exits 0 (→ FAIL). Quoted values and `=` assignments are never
+      # excluded — recall first for a CRITICAL history scan.
+      run: '! git log -p --all | grep -iE "(api[_-]?key|secret|password|passwd|token|private[_-]?key)[[:space:]]*[:=][[:space:]]*[\"'']?[A-Za-z0-9/+_-]{16,}" | grep -qiEv "(api[_-]?key|secret|password|passwd|token|private[_-]?key)[[:space:]]*:[[:space:]]*[A-Z][A-Za-z0-9_]*[[:space:]]*[,);]*[[:space:]]*\{?[[:space:]]*$"'
+      expect_exit: 0
+    why: 'Deleting a secret from HEAD does not delete it from history. Anyone who cloned the repo still has it.'
+    evidence: 'Command output, or a manual `gitleaks detect --log-opts=--all` run.'
+    remediation: 'Rotate the exposed values and rewrite history with git-filter-repo. Rotation first: assume it is already public.'
+    references: ['CWE-798', 'ASVS-14.3.2']
+
+  - id: REPO-004
+    title: README present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: documentation
+    check:
+      kind: any_file
+      patterns: ['README.md', 'readme.md', 'README.rst', 'README.txt', 'README']
+    why: 'The README is the front door. Without it, every new contributor needs a human guided tour.'
+    remediation: 'Write: what this is, how to install, how to run it, how to contribute. Four headings, one page.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-005
+    title: LICENSE present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: compliance
+    check:
+      kind: any_file
+      patterns: ['LICENSE*', 'COPYING*']
+    why: 'No license means "all rights reserved" by default. Nobody can legally use it, including you, later.'
+    remediation: 'Add MIT / Apache-2.0 / GPL-3.0 as appropriate. Choose at choosealicense.com.'
+    references: ['OpenSSF-Scorecard:License', 'SPDX']
+
+  - id: REPO-006
+    title: .env.example documents required configuration
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: maintainability
+    applies_when:
+      any:
+        - { fact: 'has:database' }
+        - { fact: 'platform:server' }
+        - { fact: 'auth:jwt' }
+        - { fact: 'auth:apikey' }
+        - { fact: 'auth:oauth' }
+    check:
+      kind: any_file
+      patterns: ['.env.example', '.env.sample', '.env.template', 'env.example', 'config.example.*']
+    why: 'Undocumented required env vars turn setup into archaeology.'
+    remediation: 'Add .env.example listing every variable the app reads, with safe placeholder values and a comment per var.'
+    references: ['ASVS-14.3.2']
+
+  - id: REPO-007
+    title: Build artifacts and dependencies are not committed
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: maintainability
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          'dist/**',
+          'build/**',
+          'out/**',
+          'node_modules/**',
+          'target/**',
+          '.venv/**',
+          'venv/**',
+          '*.egg-info/**',
+          '__pycache__/**',
+          'coverage/**',
+          '.next/**',
+        ]
+    why: 'Committed build output bloats the repo, guarantees merge conflicts, and hides the real source in review noise.'
+    remediation: 'Untrack (git rm -r --cached) and add the paths to .gitignore.'
+    references: ['OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-008
+    title: Large binaries are not committed directly
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          '*.mp4',
+          '*.mov',
+          '*.zip',
+          '*.tar.gz',
+          '*.tgz',
+          '*.exe',
+          '*.dll',
+          '*.so',
+          '*.dylib',
+          '*.jar',
+          '*.war',
+          '*.psd',
+          '*.sketch',
+        ]
+    why: 'Git stores every revision of every binary forever. Use Git LFS or object storage.'
+    remediation: 'Move binaries to LFS or object storage; rewrite history if the repo has already grown past ~200 MB.'
+    references: ['OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-009
+    title: SECURITY.md published
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: security
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns: ['SECURITY.md', '.github/SECURITY.md', 'docs/SECURITY.md']
+    why: 'Without a disclosure route, researchers either stay silent or post publicly. Neither helps you.'
+    remediation: 'Add SECURITY.md with supported versions and a report address. GitHub surfaces it in the Security tab.'
+    references: ['OpenSSF-Scorecard:Security-Policy', 'NIST-SSDF-RV.1.1']
+
+  - id: REPO-010
+    title: CHANGELOG maintained
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns: ['CHANGELOG*', 'CHANGES*', 'HISTORY.md']
+    why: 'Users and downstream maintainers need to know what changed and whether it will break them.'
+    remediation: 'Adopt Keep a Changelog, or generate it from Conventional Commits / Changesets.'
+    references: ['Keep-a-Changelog']
+
+  - id: REPO-011
+    title: CONTRIBUTING guide present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: any_file, patterns: ['CONTRIBUTING*', 'docs/CONTRIBUTING*'] }
+    why: 'Turns "how do I run the tests?" from an interruption into a link.'
+    remediation: 'Setup, test/lint commands, branch naming, commit convention, review expectations.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-012
+    title: Code of conduct present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: compliance
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: any_file, patterns: ['CODE_OF_CONDUCT*', 'docs/CODE_OF_CONDUCT*'] }
+    why: 'Sets the floor for interaction and gives maintainers something to point at.'
+    remediation: 'Adopt the Contributor Covenant.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-013
+    title: .editorconfig present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: style
+    check: { kind: file_exists, files: ['.editorconfig'] }
+    why: 'Kills tabs-vs-spaces diffs before they start, across every editor.'
+    remediation: 'Add a 6-line .editorconfig (charset, EOL, indent style/size, trailing whitespace, final newline).'
+
+  - id: REPO-014
+    title: CODEOWNERS assigns review responsibility
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'metric:contributors', op: 'gt', value: 2 }
+    check: { kind: any_file, patterns: ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS'] }
+    why: 'With more than two contributors, unreviewed-by-default becomes the default.'
+    remediation: 'Add .github/CODEOWNERS mapping paths to teams; require review from code owners on the default branch.'
+    references: ['OpenSSF-Scorecard:Code-Review']
+
+  - id: REPO-015
+    title: Commit history is meaningful
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: maintainability
+    check: { kind: manual }
+    why: >-
+      Commit messages are the only history most projects ever write down. "fix stuff" costs the next person an afternoon.
+    evidence: 'Last 20 commit messages. Are they descriptive and consistently formatted?'
+    remediation: 'Adopt Conventional Commits; enforce with commitlint in CI.'
+
+  - id: REPO-016
+    title: Branch strategy is defined and stale branches pruned
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: maintainability
+    applies_when: { fact: 'metric:branches', op: 'gt', value: 3 }
+    check: { kind: manual }
+    why: >-
+      A branching strategy nobody wrote down is a branching strategy nobody follows, and stale branches hide work.
+    evidence: 'Branch list and age of the oldest non-default branch.'
+    remediation: 'Document trunk-based or Git Flow in CONTRIBUTING; delete merged branches; protect the default branch.'
+
+  - id: REPO-017
+    title: Concern separation at the root
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: any_file
+      patterns: ['src/**', 'app/**', 'lib/**', 'pkg/**', 'internal/**', 'packages/**']
+    why: 'A flat root of 40 files makes ownership and navigation guesswork.'
+    remediation: 'Group by concern (src/, tests/, docs/, scripts/, config/). Monorepos: packages/ or apps/.'
+
+  - id: REPO-018
+    title: Agent instruction file present (AGENTS.md / CLAUDE.md)
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: documentation
+    check:
+      kind: any_file
+      patterns:
+        [
+          'AGENTS.md',
+          'CLAUDE.md',
+          '.cursorrules',
+          '.github/copilot-instructions.md',
+          'codex.md',
+          '.windsurfrules',
+        ]
+    why: >
+      Coding agents perform measurably better when the repo tells them how to
+      build, test, and what not to touch. It also stops them inventing commands.
+    remediation: 'Add AGENTS.md: setup, build/test/lint commands, conventions, and explicit no-go areas.'
+    references: ['Agent-Skills']