@xenos1996/usat 1.0.0

package/rules/core/architecture.yaml

@@ -0,0 +1,190 @@
+id: core/architecture
+title: Architecture & Design
+section: S4
+section_title: Architecture & Design
+description: >
+  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.
+version: '1.0'
+
+rules:
+  - id: ARCH-001
+    title: Architecture is documented
+    section: S4
+    section_title: Architecture & Design
+    severity: MEDIUM
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns:
+        [
+          'ARCHITECTURE.md',
+          'docs/ARCHITECTURE.md',
+          'docs/architecture/**',
+          'docs/design/**',
+          'docs/overview.md',
+        ]
+    why: 'Undocumented architecture is whatever the last person to touch it believed.'
+    remediation: 'One page: components, data flow, external dependencies, and the three decisions a newcomer would question.'
+    references: ['arc42', 'C4-Model']
+
+  - id: ARCH-002
+    title: Architecture decisions are recorded (ADRs)
+    section: S4
+    section_title: Architecture & Design
+    severity: LOW
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns:
+        ['**/adr-*.md', '**/ADR-*.md', 'docs/adrs/**', 'docs/adr/**', 'docs/decisions/**', 'adr/**']
+    why: 'Six months from now nobody will remember why Postgres won over Mongo, and someone will relitigate it.'
+    remediation: 'Keep short ADRs in docs/adrs: context, decision, consequences. One markdown file per decision.'
+    references: ['ADR-Nygard']
+
+  - id: ARCH-003
+    title: No god files
+    section: S4
+    section_title: Architecture & Design
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: file_lines_max
+      patterns:
+        [
+          'src/**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php,cs}',
+          'app/**/*.{ts,tsx,js,jsx,py,go,rs,java,kt}',
+          'lib/**/*.{ts,tsx,js,jsx,py,go,rs}',
+          'pkg/**/*.go',
+          'internal/**/*.go',
+        ]
+      max_lines: 800
+    why: 'A file nobody can hold in their head is a file nobody changes safely.'
+    remediation: 'Split by responsibility: extract the data access, the policy, or the formatting into its own module.'
+    references: ['Anti-pattern:God-Object', 'ISO-5055']
+
+  - id: ARCH-004
+    title: Layers are separated (transport / domain / data)
+    section: S4
+    section_title: Architecture & Design
+    severity: MEDIUM
+    class: maintainability
+    applies_when:
+      any:
+        - { fact: 'platform:server' }
+        - { fact: 'project:api' }
+        - { fact: 'has:database' }
+    check: { kind: manual }
+    why: >-
+      Business logic mixed into HTTP handlers cannot be tested, reused, or moved — and every new transport duplicates it.
+    evidence: 'Directory layout or file:line showing HTTP handlers delegating to a domain/service layer rather than querying the DB inline.'
+    remediation: 'Handlers parse and authorise; services hold business rules; repositories own persistence. No SQL in a controller.'
+    references: ['Clean-Architecture', 'Hexagonal-Architecture']
+
+  - id: ARCH-005
+    title: No circular dependencies between modules
+    section: S4
+    section_title: Architecture & Design
+    severity: HIGH
+    class: maintainability
+    depths: [deep]
+    check:
+      kind: command
+      run: '! (command -v npx >/dev/null && npx --yes dpdm@latest --exit-code circular:1 "src/**/*.ts" 2>/dev/null | grep -qi circular)'
+      expect_exit: 0
+    why: 'Cycles make modules untestable in isolation and turn every build order into a guess.'
+    evidence: 'Output of dpdm / madge --circular / dependency-cruiser, or a manual import-graph review.'
+    remediation: 'Break the cycle with an interface, an event, or by extracting the shared type into a leaf module.'
+    references: ['Anti-pattern:Circular-Dependency']
+
+  - id: ARCH-006
+    title: Module boundaries are enforced by tooling
+    section: S4
+    section_title: Architecture & Design
+    severity: LOW
+    class: maintainability
+    applies_when: { fact: 'project:monorepo' }
+    check:
+      kind: grep_present
+      pattern: '(enforce-module-boundaries|no-restricted-imports|dependency-cruiser|import/no-cycle|@nx/enforce-module-boundaries|boundaries/)'
+      include:
+        [
+          '**/.eslintrc*',
+          'eslint.config.*',
+          '.dependency-cruiser.*',
+          'nx.json',
+          'project.json',
+          '**/tsconfig*.json',
+        ]
+      flags: i
+    why: 'Boundaries that are not enforced decay within one sprint of the first deadline.'
+    remediation: 'Add nx enforce-module-boundaries or eslint no-restricted-imports between packages/layers.'
+    references: ['Nx', 'dependency-cruiser']
+
+  - id: ARCH-007
+    title: Configuration is externalised
+    section: S4
+    section_title: Architecture & Design
+    severity: MEDIUM
+    class: operations
+    check:
+      kind: grep_absent
+      pattern: '(process\.env\.[A-Z_]+\s*\|\|\s*[''"](?:prod|production|https?://)|\b(?:DATABASE_URL|API_URL|REDIS_URL)\s*[:=]\s*[''"](?:postgres|mysql|mongodb|redis|https?)://(?!localhost|127\.0\.0\.1))'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php}']
+      exclude: ['**/*.test.*', '**/*.spec.*']
+      flags: i
+    why: 'A hardcoded production URL means the only way to run staging is to edit source.'
+    remediation: 'Read every environment-specific value from configuration; keep defaults that are safe for local dev.'
+    references: ['12-Factor:Config', 'ASVS-14.1.3']
+
+  - id: ARCH-008
+    title: Side effects are isolated and testable
+    section: S4
+    section_title: Architecture & Design
+    severity: LOW
+    class: maintainability
+    check: { kind: manual }
+    why: >-
+      Side effects called inline cannot be tested without the network, the clock, or the database. That is why tests get slow and flaky.
+    evidence: 'Examples of I/O (network, disk, clock, randomness) being injected or wrapped rather than called inline from business logic.'
+    remediation: 'Inject the clock, the HTTP client, and the repository; keep pure functions pure.'
+    references: ['Functional-Core-Imperative-Shell']
+
+  - id: ARCH-009
+    title: Single points of failure are identified
+    section: S4
+    section_title: Architecture & Design
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'maturity:production' }
+        - { fact: 'maturity:beta' }
+    check: { kind: manual }
+    why: >-
+      Availability incidents are almost always an SPOF somebody already knew about. Writing it down is what turns it into a project.
+    evidence: 'A list of SPOFs (single DB, single region, single queue, single vendor) and the mitigation for each.'
+    remediation: 'For each SPOF: replica, failover, or an explicitly accepted risk with a documented recovery time.'
+    references: ['AWS-Well-Architected:Reliability']
+
+  - id: ARCH-010
+    title: Async work is offloaded to a queue
+    section: S4
+    section_title: Architecture & Design
+    severity: LOW
+    class: performance
+    applies_when: { fact: 'platform:server' }
+    check:
+      kind: grep_present
+      pattern: '(bullmq|bull|amqplib|kafkajs|sqs|nats|temporal|celery|rq|sidekiq|taskiq|dramatiq|asynq)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,rb}']
+      exclude: ['**/*.test.*']
+      flags: i
+    why: 'Anything slow inside a request handler is a timeout waiting for a busy day.'
+    remediation: 'Move email, image processing, webhooks, and report generation onto a queue with retries and a DLQ.'
+    references: ['12-Factor:Processes']

package/rules/core/cicd.yaml

@@ -0,0 +1,212 @@
+id: core/cicd
+title: CI/CD, Infrastructure & Observability
+section: S8
+section_title: CI/CD, Infrastructure & Observability
+description: >
+  How code becomes running software, and how you find out when it breaks.
+  Heavily informed by the OpenSSF Scorecard and DORA's delivery metrics.
+version: '1.0'
+
+rules:
+  - id: CICD-001
+    title: A CI pipeline exists
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: HIGH
+    class: operations
+    check:
+      kind: any_file
+      patterns:
+        - '.github/workflows/*.yml'
+        - '.github/workflows/*.yaml'
+        - '.gitlab-ci.yml'
+        - 'Jenkinsfile'
+        - '.circleci/config.yml'
+        - '.buildkite/**'
+        - 'azure-pipelines.yml'
+        - '.drone.yml'
+        - 'bitbucket-pipelines.yml'
+    why: 'Manual release steps work exactly until the person who knows them is on holiday.'
+    remediation: 'Add a minimal pipeline first: install → lint → test → build. Expand from there.'
+    references: ['OpenSSF-Scorecard:CI-Tests', 'DORA']
+
+  - id: CICD-002
+    title: CI runs lint, test, and build
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'has:ci' }
+    check: { kind: manual }
+    evidence: 'The workflow file: which of lint / typecheck / test / build run on pull_request?'
+    why: 'A pipeline that only builds is a compiler with a dashboard.'
+    remediation: 'Add steps in fail-fast order: lint (5s) → typecheck → unit → build → integration.'
+    references: ['OpenSSF-Scorecard:CI-Tests', 'DORA']
+
+  - id: CICD-003
+    title: Deployment is automated
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: HIGH
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'maturity:production' }
+        - { fact: 'maturity:beta' }
+    check: { kind: manual }
+    evidence: 'The path from merged commit to production: is there a human typing commands into a server?'
+    why: 'Manual deploys are unrepeatable, unauditable, and always happen at the worst possible time.'
+    remediation: 'Automate deploy from a tagged commit or main-branch push with an approval step if governance requires one.'
+    references: ['DORA:Deployment-Frequency', 'NIST-SSDF-PO.5']
+
+  - id: CICD-004
+    title: A rollback path exists and has been exercised
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: HIGH
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'maturity:production' }
+        - { fact: 'maturity:beta' }
+    check: { kind: manual }
+    evidence: 'Documented rollback command/action, and the date it was last actually used (successfully).'
+    why: 'An untested rollback is a second outage with extra panic.'
+    remediation: 'Make rollback a one-command operation; rehearse it; record the last successful rollback date.'
+    references: ['DORA:Time-to-Restore', 'NIST-SSDF-RV.3']
+
+  - id: CICD-005
+    title: Separate environments exist
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: manual }
+    evidence: 'dev / staging / production configuration, and confirmation that dev cannot reach production data.'
+    why: 'Testing in production is a slogan, not a strategy.'
+    remediation: 'At minimum: local + staging + production, with separate credentials and datasets per environment.'
+    references: ['NIST-SSDF-PO.5', 'ASVS-14.1.3']
+
+  - id: CICD-006
+    title: Infrastructure is defined as code
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns:
+        [
+          '**/*.tf',
+          '**/*.tfvars',
+          'pulumi/**',
+          '**/Pulumi.*.yaml',
+          'cdk.json',
+          '**/*.cdk.ts',
+          'ansible/**',
+          '**/playbook*.yml',
+          'k8s/**/*.yaml',
+          'manifests/**/*.yaml',
+          'charts/**/Chart.yaml',
+          'docker-compose*.yml',
+          'compose.yaml',
+          'serverless.yml',
+          'Dockerfile*',
+        ]
+    why: 'Infrastructure that only exists in a console cannot be reviewed, diffed, or rebuilt after an incident.'
+    remediation: 'Move environments into Terraform/Pulumi/CDK (or at least declarative compose + helm manifests).'
+    references: ['NIST-SSDF-PO.5']
+
+  - id: CICD-007
+    title: Health check endpoints exist
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'platform:server' }
+    check:
+      kind: grep_present
+      pattern: '(/(health|healthz|readyz|livez|ready|live|status|ping)[''"`\s]|healthCheck|health_check|app\.get\(\s*[''"]/health)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php,yml,yaml}']
+      exclude: ['**/*.test.*', '**/*.spec.*', '**/node_modules/**']
+      flags: i
+    why: 'Without /health and /ready, orchestrators cannot tell a booting service from a dead one.'
+    remediation: 'Expose /health (liveness) and /ready (dependencies reachable); wire them into the orchestrator and the LB.'
+    references: ['K8s-Probes', 'OpenSSF-Scorecard']
+
+  - id: CICD-008
+    title: Error tracking / APM is configured
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: grep_present
+      pattern: '(sentry|opentelemetry|datadog|newrelic|new-relic|rollbar|bugsnag|honeycomb|grafana|prometheus|betterstack|axiom)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,yml,yaml,json,toml}']
+      exclude: ['**/node_modules/**', '**/*.test.*']
+      flags: i
+    why: 'Your users will find the bugs. The only question is whether they tell you.'
+    remediation: 'Add Sentry (or equivalent) with source maps and release tracking; alert on new error types.'
+    references: ['DORA:Monitoring', 'OpenTelemetry']
+
+  - id: CICD-009
+    title: Alerting is configured for critical failures
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'Alert rules, their thresholds, and who gets paged. Bonus: the last time one fired and what happened.'
+    why: 'Monitoring without alerting is a dashboard nobody opens until after the outage.'
+    remediation: 'Alert on symptoms users feel (error rate, latency, saturation), not on every CPU blip.'
+    references: ['Google-SRE:Monitoring', 'DORA']
+
+  - id: CICD-010
+    title: Backups exist AND restores have been tested
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: HIGH
+    class: operations
+    applies_when:
+      any:
+        - { fact: 'has:database' }
+        - { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'Backup schedule, retention, encryption at rest, and — critically — the date of the last successful restore drill.'
+    why: 'Nobody has ever been fired for having backups. Plenty of teams have died from never testing the restore.'
+    remediation: 'Automate backups, encrypt them, store them off-site, and run a restore drill quarterly with a recorded RTO.'
+    references: ['NIST-SSDF-RV.3', 'CIS-Control-11']
+
+  - id: CICD-011
+    title: A disaster recovery plan exists
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'Documented RTO/RPO, the failover procedure, and who is authorised to declare a disaster.'
+    why: 'At 3am, the plan is the only thing between you and ad-hoc database surgery.'
+    remediation: 'Write a one-page DR runbook: trigger, failover steps, rollback, comms template, and owner.'
+    references: ['NIST-SSDF-RV.3', 'AWS-Well-Architected:Reliability']
+
+  - id: CICD-012
+    title: Observability covers the golden signals
+    section: S8
+    section_title: CI/CD, Infrastructure & Observability
+    severity: LOW
+    class: operations
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'A dashboard or metric set covering latency, traffic, errors, and saturation for the primary service.'
+    why: 'Four signals answer "is it broken, how bad, and where" in under five minutes.'
+    remediation: 'Instrument RED/USE metrics; put them on one dashboard linked from the runbook.'
+    references: ['Google-SRE:Golden-Signals']

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