@xenos1996/usat 1.0.0

package/rules/index.yaml

@@ -0,0 +1,41 @@
+# =============================================================================
+# USAT rule pack registry  (schema: usat-rules-index-v1)
+# -----------------------------------------------------------------------------
+# Each entry is a path (relative to this file) or { file, enabled }.
+# Packs self-select via `skip_when` / per-rule `applies_when`, so the list below
+# is just "what exists" — USAT decides "what applies" at audit time.
+# =============================================================================
+
+schema: usat-rules-index-v1
+
+packs:
+  # ---- universal: every project gets these ---------------------------------
+  - core/repo.yaml
+  - core/security.yaml
+  - core/supply-chain.yaml
+  - core/architecture.yaml
+  - core/code-quality.yaml
+  - core/testing.yaml
+  - core/cicd.yaml
+  - core/release.yaml
+  - core/dependencies.yaml
+  - core/documentation.yaml
+  - core/future-readiness.yaml
+
+  # ---- conditional: activated by detection ---------------------------------
+  - stacks/node-typescript.yaml
+  - stacks/python.yaml
+  - stacks/go.yaml
+  - stacks/rust.yaml
+  - stacks/jvm.yaml
+  - stacks/web-frontend.yaml
+  - stacks/mobile.yaml
+  - stacks/containers.yaml
+  - stacks/iac.yaml
+  - stacks/solidity.yaml
+  - stacks/ml-ai.yaml
+  - stacks/cli.yaml
+  - stacks/data.yaml
+  - stacks/api-backend.yaml
+  - stacks/compliance.yaml
+  - stacks/ai-era.yaml

package/rules/profiles/maturity.yaml

@@ -0,0 +1,135 @@
+# =============================================================================
+# USAT — Maturity profiles  (schema: usat-profiles-v1)
+# -----------------------------------------------------------------------------
+# The same repo at two different stages deserves two different reports.
+# A 3-day prototype should not be graded against a production bar, and a
+# production system should not be excused because it "moves fast".
+#
+# `dampen` = how many severity steps a failing rule is reduced by, per rule
+# class. Severity ladder: FUTURE < LOW < MEDIUM < HIGH < CRITICAL.
+#
+# HARD RULE: CRITICAL is never dampened, at any stage. A leaked credential is
+# a leaked credential. Everything else is negotiable with the calendar.
+# =============================================================================
+
+schema: usat-profiles-v1
+ladder: [FUTURE, LOW, MEDIUM, HIGH, CRITICAL]
+
+profiles:
+  prototype:
+    label: Prototype / Spike
+    summary: >
+      Proving an idea. Optimise for learning speed, but never for leaking
+      secrets or shipping unrecoverable data loss.
+    dampen:
+      security: 1
+      supply-chain: 1
+      correctness: 1
+      maintainability: 2
+      operations: 2
+      performance: 2
+      compliance: 2
+      documentation: 2
+      style: 2
+    expected_band: [30, 65]
+    focus:
+      - Secret hygiene and .gitignore (non-negotiable, costs 5 minutes)
+      - A README that says what this is and how to run it
+      - One smoke test so the happy path is known-good
+    defer:
+      - Kubernetes, multi-region, formal ADRs, 80% coverage gates
+
+  mvp:
+    label: MVP / Early product
+    summary: >
+      Real users, real data. Security and recovery basics must exist;
+      process ceremony can wait.
+    dampen:
+      security: 0
+      supply-chain: 1
+      correctness: 1
+      maintainability: 1
+      operations: 1
+      performance: 1
+      compliance: 1
+      documentation: 2
+      style: 2
+    expected_band: [45, 75]
+    focus:
+      - Input validation and output encoding on every user-facing path
+      - Automated backup + a restore you have actually performed
+      - CI that runs lint + tests on every PR
+      - Dependency scanning (Dependabot/Renovate) before the graph grows
+    defer:
+      - Formal threat model, multi-region, chaos engineering, SBOM/VEX
+
+  beta:
+    label: Beta / Growing
+    summary: >
+      Scaling users and contributors. Close the process gaps before they
+      compound.
+    dampen:
+      security: 0
+      supply-chain: 0
+      correctness: 0
+      maintainability: 1
+      operations: 1
+      performance: 1
+      compliance: 1
+      documentation: 1
+      style: 1
+    expected_band: [60, 85]
+    focus:
+      - Branch protection + mandatory review on the default branch
+      - Structured logging with correlation IDs; real alerting
+      - Integration test suite around critical flows
+      - Documented rollback procedure
+    defer:
+      - Full DR site, formal verification, mutation testing
+
+  production:
+    label: Production / GA
+    summary: >
+      Full bar. Nothing is dampened — this is the profile USAT grades
+      against when you pass --profile production.
+    dampen:
+      security: 0
+      supply-chain: 0
+      correctness: 0
+      maintainability: 0
+      operations: 0
+      performance: 0
+      compliance: 0
+      documentation: 0
+      style: 0
+    expected_band: [75, 95]
+    focus:
+      - Close every HIGH; timebox a plan for each MEDIUM
+      - Provenance/attestation on release artifacts (SLSA)
+      - Tested disaster recovery with a real RTO/RPO
+      - Observability that answers "is it broken?" in under 5 minutes
+    defer: []
+
+  legacy:
+    label: Legacy / Maintenance
+    summary: >
+      Still running, no longer evolving. Graded on risk containment and
+      replacement cost, not on modernisation ambition.
+    dampen:
+      security: 0
+      supply-chain: 0
+      correctness: 0
+      maintainability: 1
+      operations: 0
+      performance: 1
+      compliance: 0
+      documentation: 1
+      style: 1
+    expected_band: [40, 70]
+    focus:
+      - Inventory EOL dependencies and pin a replacement date for each
+      - Confirm backups restore, and that someone still knows how
+      - Keep the lights on: monitoring, alerting, and an owner per service
+      - Document the system well enough to hand over or retire
+    defer:
+      - Rewrites without a strangler plan, framework migrations for their own sake

package/rules/stacks/ai-era.yaml

@@ -0,0 +1,193 @@
+id: stacks/ai-era
+title: AI / LLM-Era Risks
+section: S14
+section_title: AI / LLM-Era Risks
+description: >
+  New in USAT. Your application may be deterministic while depending on a
+  component that is not. Mapped to the OWASP Top 10 for LLM Applications
+  (2026) and the OWASP Top 10 for Agentic AI (ASI, 2026).
+version: '1.0'
+skip_when:
+  all:
+    - { fact: 'ai:llm-sdk', op: 'absent' }
+    - { fact: 'ai:agents', op: 'absent' }
+    - { fact: 'ai:mcp', op: 'absent' }
+    - { fact: 'ai:rag', op: 'absent' }
+    - { fact: 'ai:prompts', op: 'absent' }
+
+rules:
+  - id: AI-001
+    title: Untrusted content cannot override instructions
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: CRITICAL
+    class: security
+    applies_when:
+      any:
+        - { fact: 'ai:llm-sdk' }
+        - { fact: 'ai:rag' }
+    check: { kind: manual }
+    evidence: 'How retrieved/web/user content is separated from instructions (delimiters, role separation, or a distinct tool channel).'
+    why: 'LLM01:2026 Prompt Injection is still the top risk. Any text your model reads — a PDF, a ticket, a web page — is a potential instruction.'
+    remediation: 'Separate trusted and untrusted content by role; strip or neutralise instruction-like patterns from retrieved text; never let retrieval feed a privileged tool call directly.'
+    references: ['OWASP-LLM01:2026', 'OWASP-ASI01:2026']
+
+  - id: AI-002
+    title: Model output is validated before it is executed
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: CRITICAL
+    class: security
+    applies_when:
+      any:
+        - { fact: 'ai:llm-sdk' }
+        - { fact: 'ai:agents' }
+    check:
+      kind: grep_wrong
+      pattern: '(exec\s*\(\s*(?:completion|response|result|output|llm|content)|eval\s*\(\s*(?:completion|response|result|output)|dangerouslySetInnerHTML\s*=\s*\{\{\s*__html:\s*(?:completion|response|result|output)|subprocess.*(?:completion|response|llm_output))'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs}']
+      exclude: ['**/*.test.*', '**/node_modules/**']
+      flags: i
+    why: 'LLM10:2026 Improper Output Handling. Treating generated text as code is remote code execution with a random number generator in charge.'
+    remediation: 'Parse model output into a constrained schema (JSON mode / tool calling) and validate before any use in a shell, SQL query, or DOM.'
+    references: ['OWASP-LLM10:2026', 'OWASP-ASI05:2026', 'CWE-94']
+
+  - id: AI-003
+    title: Agents and tools run with least privilege
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: HIGH
+    class: security
+    applies_when:
+      any:
+        - { fact: 'ai:agents' }
+        - { fact: 'ai:mcp' }
+    check: { kind: manual }
+    evidence: 'The tool/permission allowlist: what an agent can call, with which credentials, and what is blocked by default.'
+    why: 'LLM03:2026 Excessive Agency jumped to #3 for a reason: agents with broad tool access turn prompt injection into arbitrary action.'
+    remediation: 'Allowlist tools explicitly; scope credentials per tool; require human approval for irreversible actions; sandbox filesystem and network.'
+    references: ['OWASP-LLM03:2026', 'OWASP-ASI02:2026', 'OWASP-ASI03:2026']
+
+  - id: AI-004
+    title: Secrets and PII do not reach model providers unchecked
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: HIGH
+    class: security
+    applies_when: { fact: 'ai:llm-sdk' }
+    check: { kind: manual }
+    evidence: 'What is sent in the prompt/context: any credentials, customer PII, or regulated data? Is redaction applied first?'
+    why: 'LLM02:2026 Sensitive Information Disclosure now explicitly covers traces, embeddings, and telemetry — not just chat text.'
+    remediation: 'Redact before sending; use a provider agreement with no-training/no-retention; keep PII out of embeddings.'
+    references: ['OWASP-LLM02:2026', 'GDPR-Art.44']
+
+  - id: AI-005
+    title: Inference spend and token usage are bounded
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: MEDIUM
+    class: performance
+    applies_when: { fact: 'ai:llm-sdk' }
+    check:
+      kind: grep_present
+      pattern: '(max_tokens|maxTokens|max_output_tokens|timeout|maxRetries|max_turns|max_steps|budget|abortSignal|stopAfterAttempt)'
+      include: ['**/*.{ts,tsx,js,jsx,py,go,rs}']
+      exclude: ['**/*.test.*', '**/node_modules/**']
+      flags: i
+    why: 'LLM06:2026 Unbounded Consumption — denial-of-wallet is a real attack, and runaway agent loops are a real bug.'
+    remediation: 'Set max tokens, request timeouts, retry caps, step limits, and a hard per-user spend ceiling with alerting.'
+    references: ['OWASP-LLM06:2026', 'OWASP-ASI08:2026']
+
+  - id: AI-006
+    title: System prompts and tool schemas are not exposed
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: MEDIUM
+    class: security
+    applies_when: { fact: 'ai:prompts' }
+    check: { kind: manual }
+    evidence: 'Whether the system prompt, tool definitions, and policies are retrievable by the end user (directly or via an error/debug path).'
+    why: 'LLM08:2026 Hidden Context Exposure broadened from system-prompt leakage: tool schemas and roles enable reconnaissance.'
+    remediation: 'Keep prompts server-side; never echo them in errors or debug output; assume they will leak and put no secret in them.'
+    references: ['OWASP-LLM08:2026']
+
+  - id: AI-007
+    title: RAG retrieval is access-controlled per tenant
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: HIGH
+    class: security
+    applies_when: { fact: 'ai:rag' }
+    check: { kind: manual }
+    evidence: 'How documents are scoped at query time — metadata filters, per-tenant indexes, or a post-retrieval permission check.'
+    why: "LLM09:2026 Vector and Embedding Weaknesses: similarity search happily returns another tenant's documents."
+    remediation: 'Filter by tenant/ACL at query time (not after generation); partition indexes per tenant where the risk is high.'
+    references: ['OWASP-LLM09:2026', 'OWASP-ASI06:2026']
+
+  - id: AI-008
+    title: Model and prompt supply chain is pinned
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: MEDIUM
+    class: supply-chain
+    applies_when: { fact: 'ai:llm-sdk' }
+    check: { kind: manual }
+    evidence: 'Model IDs/versions pinned (not "latest"), prompts versioned in the repo, and third-party agents/MCP servers reviewed.'
+    why: 'LLM04:2026 Supply Chain now covers model provenance, adapters, quantisation, and conversion tooling.'
+    remediation: 'Pin exact model versions and digests; version prompts in git; treat MCP servers as production dependencies.'
+    references: ['OWASP-LLM04:2026', 'OWASP-ASI04:2026', 'SLSA']
+
+  - id: AI-009
+    title: An eval suite exists for model behaviour
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: MEDIUM
+    class: correctness
+    applies_when: { fact: 'ai:llm-sdk' }
+    check: { kind: manual }
+    evidence: 'A regression suite of prompts with expected properties, run in CI on model or prompt changes.'
+    why: 'Without evals, a prompt tweak is a silent behaviour change shipped to production.'
+    remediation: 'Start with 20–50 cases covering the critical paths; fail CI when the pass rate drops.'
+    references: ['OWASP-LLM07:2026', 'Evals-Best-Practices']
+
+  - id: AI-010
+    title: Consequential actions require human confirmation
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: HIGH
+    class: security
+    applies_when:
+      any:
+        - { fact: 'ai:agents' }
+        - { fact: 'ai:mcp' }
+    check: { kind: manual }
+    evidence: 'For each irreversible action (payment, deletion, deployment, outbound message): who or what approves it?'
+    why: 'ASI09:2026 Human-Agent Trust Exploitation — users approve faster than they read, and agents exploit that by default.'
+    remediation: 'Gate irreversible actions behind explicit confirmation showing the concrete effect; keep an audit log of approvals.'
+    references: ['OWASP-ASI09:2026', 'NIST-AI-RMF']
+
+  - id: AI-011
+    title: Agent instruction files are scoped and safe
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: MEDIUM
+    class: security
+    applies_when: { fact: 'ai:agents' }
+    check: { kind: manual }
+    evidence: 'AGENTS.md / CLAUDE.md / .cursorrules contents: do they forbid destructive commands, secret reads, and unreviewed pushes?'
+    why: 'These files are executable-ish instructions that commit as easily as code, and agents follow them literally.'
+    remediation: 'Add an explicit denylist (no force push, no rm -rf, no reading .env), plus the exact build/test commands to use.'
+    references: ['OWASP-ASI04:2026', 'Agent-Skills']
+
+  - id: AI-012
+    title: Model inputs and outputs are logged for audit
+    section: S14
+    section_title: AI / LLM-Era Risks
+    severity: LOW
+    class: compliance
+    applies_when: { fact: 'maturity:production' }
+    check: { kind: manual }
+    evidence: 'A record per request: model version, prompt template id, redacted input, output, tokens, latency, and cost.'
+    why: 'You cannot investigate a hallucination, an abuse report, or a cost spike without the trace.'
+    remediation: 'Log request/response metadata with a trace ID; redact PII; retain per your data policy.'
+    references: ['NIST-AI-RMF', 'EU-AI-Act-Art.12', 'OWASP-LLM02:2026']

package/rules/stacks/api-backend.yaml

@@ -0,0 +1,121 @@
+id: stacks/api-backend
+title: Backend / API
+section: S15
+section_title: Platform-Specific
+description: 'Activated for server-side applications and API services.'
+version: '1.0'
+skip_when:
+  all:
+    - { fact: 'platform:server', op: 'absent' }
+    - { fact: 'project:api', op: 'absent' }
+
+rules:
+  - id: API-001
+    title: The API is versioned
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: maintainability
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: grep_present
+      pattern: '(/(v[0-9]+|api/v[0-9]+)/|version\s*:\s*[''"]?[0-9]|Accept.*version|setGlobalPrefix)'
+      include: ['**/*.{ts,js,py,go,rs,java,kt,rb,yml,yaml,json}']
+      exclude: ['**/node_modules/**', 'package.json']
+      flags: i
+    why: 'Without a version in the path or header, every breaking change is a coordinated deploy across every client.'
+    remediation: 'Prefix routes with /v1 (or use a version header); never break an existing version in place.'
+    references: ['ASVS-14.1.3', 'API-Design']
+
+  - id: API-002
+    title: Request timeouts are configured
+    section: S15
+    section_title: Platform-Specific
+    severity: HIGH
+    class: performance
+    check: { kind: manual }
+    evidence: 'Server request timeout, upstream client timeouts, and DB statement timeouts — all three, with values.'
+    why: 'No timeout means one slow dependency exhausts your entire worker pool.'
+    remediation: 'Set a request timeout at the edge, per-upstream client timeouts, and statement_timeout in the database.'
+    references: ['CWE-400', 'Release-It']
+
+  - id: API-003
+    title: Retries are bounded with jitter
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: performance
+    check: { kind: manual }
+    evidence: 'Retry configuration: max attempts, backoff strategy, and whether retries are applied to non-idempotent calls.'
+    why: 'Retrying a POST three times can create three charges. Retrying without jitter synchronises your thundering herd.'
+    remediation: 'Exponential backoff with jitter, capped attempts, and retry only on idempotent/transient failures.'
+    references: ['AWS-Builders-Library:Timeouts']
+
+  - id: API-004
+    title: Write operations are idempotent
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: correctness
+    check: { kind: manual }
+    evidence: 'An idempotency-key mechanism (or natural-key upsert) on POST/PUT endpoints that create resources.'
+    why: 'Networks retry. Clients double-click. Only one of those should create two orders.'
+    remediation: 'Accept an Idempotency-Key header, store the result, and replay it on duplicate requests.'
+    references: ['Stripe-Idempotency', 'API-Design']
+
+  - id: API-005
+    title: Response format is consistent
+    section: S15
+    section_title: Platform-Specific
+    severity: LOW
+    class: maintainability
+    check: { kind: manual }
+    evidence: 'One success envelope, one error envelope (code, message, details, requestId) used everywhere.'
+    why: 'Clients should not need per-endpoint parsing logic.'
+    remediation: 'Define the envelopes once in middleware and enforce with contract tests.'
+    references: ['API-Design', 'RFC-7807']
+
+  - id: API-006
+    title: An OpenAPI/contract spec exists and is current
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns: ['**/openapi.{yaml,yml,json}', '**/swagger.{yaml,yml,json}', 'docs/api/**']
+    why: 'A spec that is generated and published is documentation. One that is written once is a memory.'
+    remediation: 'Generate the spec from code (or code from the spec) in CI and publish it with the release.'
+    references: ['OpenAPI', 'NIST-SSDF-PS.1']
+
+  - id: API-007
+    title: GraphQL depth/complexity limits are enforced
+    section: S15
+    section_title: Platform-Specific
+    severity: HIGH
+    class: security
+    applies_when: { fact: 'api:graphql' }
+    check:
+      kind: grep_present
+      pattern: '(depthLimit|depth-limit|complexity|maxDepth|costAnalysis|graphql-armor|rate-limit)'
+      include: ['**/*.{ts,js,py,go,rs}']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'A cyclic query can bring a GraphQL server to its knees with a single request.'
+    remediation: 'Add depth and complexity limits; disable introspection in production unless the API is public.'
+    references: ['OWASP-API4:2023', 'CWE-770']
+
+  - id: API-008
+    title: Health and readiness endpoints are unauthenticated but minimal
+    section: S15
+    section_title: Platform-Specific
+    severity: LOW
+    class: operations
+    check: { kind: manual }
+    evidence: '/health returns no version strings, dependency names, or configuration details to anonymous callers.'
+    why: 'A verbose /health endpoint is a free architecture diagram for an attacker.'
+    remediation: 'Return {"status":"ok"}; put diagnostics behind authentication or a separate internal port.'
+    references: ['CWE-200', 'K8s-Probes']

package/rules/stacks/cli.yaml

@@ -0,0 +1,105 @@
+id: stacks/cli
+title: CLI Tools
+section: S15
+section_title: Platform-Specific
+description: 'Activated when the project exposes a binary or console script entry point.'
+version: '1.0'
+skip_when: { fact: 'project:cli', op: 'absent' }
+
+rules:
+  - id: CLI-001
+    title: --help is implemented and useful
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: documentation
+    check:
+      kind: grep_present
+      pattern: "(--help|'help'|describe\\(|usage:|commander|yargs|argparse|clap|click|cobra|oclif|cac)"
+      include: ['**/*.{ts,js,py,go,rs,java,kt,rb}', 'package.json', 'Cargo.toml', 'pyproject.toml']
+      exclude: ['**/node_modules/**', '**/*.test.*']
+      flags: i
+    why: 'A CLI without --help forces users to read the source, which is the least friendly documentation format.'
+    remediation: 'Use an argument parser that generates help automatically; write a one-line description per command.'
+    references: ['CLIG']
+
+  - id: CLI-002
+    title: Exit codes are meaningful
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: grep_present
+      # Matches both styles: inline `process.exit(n)`, and the cleaner
+      # `process.exitCode = main(argv)` used by single-entry-point CLIs.
+      pattern: '(process\.exit(Code)?\s*=|process\.exit\s*\(\s*[0-3]\s*\)|(sys\.)?exit\s*\(\s*[0-3]\s*\)|os\.Exit\s*\(\s*[0-3]\s*\)|ExitCode|SystemExit)'
+      include: ['**/*.{ts,js,py,go,rs,java,kt,rb}']
+      exclude: ['**/node_modules/**', '**/*.test.*', '**/tests/**']
+    why: 'Scripts pipe your CLI into `&&` and `set -e`. Exit 0 on failure corrupts everything downstream.'
+    remediation: 'Exit 0 on success, 1 on expected failure, 2 on usage error. Document the codes in --help.'
+    references: ['CLIG', 'POSIX-Exit-Codes']
+
+  - id: CLI-003
+    title: Destructive operations support --dry-run
+    section: S15
+    section_title: Platform-Specific
+    severity: HIGH
+    class: correctness
+    check: { kind: manual }
+    evidence: 'For every command that deletes, overwrites, or publishes: a --dry-run flag, or a confirmation prompt.'
+    why: 'A CLI that deletes without asking will eventually be run in the wrong directory by someone having a bad day.'
+    remediation: 'Add --dry-run that prints the intended actions and exits 0 without performing them.'
+    references: ['CLIG']
+
+  - id: CLI-004
+    title: Input from arguments and stdin is validated
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: security
+    check: { kind: manual }
+    evidence: 'Path arguments resolved and checked; stdin length bounded; no unchecked interpolation into shell commands.'
+    why: 'CLI input is user input. Path traversal and command injection apply here too.'
+    remediation: 'Validate and canonicalise paths; cap stdin size; never pass raw input to a shell.'
+    references: ['CWE-22', 'CWE-78']
+
+  - id: CLI-005
+    title: Operations are idempotent where expected
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: correctness
+    check: { kind: manual }
+    evidence: 'Running the same command twice produces the same end state (or a clear "already done" message).'
+    why: 'CLIs get run twice — by retries, by scripts, and by humans who forgot they already ran it.'
+    remediation: 'Check before acting; make writes atomic; report no-op as success.'
+    references: ['CLIG']
+
+  - id: CLI-006
+    title: Errors go to stderr, output to stdout
+    section: S15
+    section_title: Platform-Specific
+    severity: LOW
+    class: correctness
+    check: { kind: manual }
+    evidence: '`cli > out.txt` captures only machine-readable output; errors remain on the terminal.'
+    why: 'Mixing them breaks every pipe and every parser downstream.'
+    remediation: 'Log diagnostics to stderr; keep stdout clean for piping (optionally JSON with --json).'
+    references: ['CLIG']
+
+  - id: CLI-007
+    title: Machine-readable output mode exists
+    section: S15
+    section_title: Platform-Specific
+    severity: LOW
+    class: maintainability
+    check:
+      kind: grep_present
+      pattern: '(--json|--format|--output\s+(json|yaml)|jsonOutput|as_json)'
+      include: ['**/*.{ts,js,py,go,rs}', 'README*']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'Agents and scripts are now the primary consumers of most CLIs. Human text is not an API.'
+    remediation: 'Add --json with a stable schema; document it.'
+    references: ['CLIG', 'Agent-Skills']