universal-dev-standards 5.4.0 → 5.6.0

package/bundled/ai/standards/runbook.ai.yaml

@@ -0,0 +1,104 @@
+# Runbook Standards - AI Optimized
+# Source: XSPEC-063 Wave 3 SRE Pack
+
+id: runbook
+title: Runbook Writing Standards
+version: "1.0.0"
+status: Active
+tags: [sre, operations, runbook, incident, oncall]
+summary: |
+  Defines how operational runbooks are written, organized, maintained, and
+  tested. Covers required sections, writing principles (reproducible,
+  unambiguous steps), directory structure, review cadence, and drill
+  frequency. A well-written runbook reduces Mean Time To Repair (MTTR) by
+  ensuring any on-call engineer can execute recovery steps without requiring
+  tribal knowledge.
+
+requirements:
+  - id: REQ-001
+    title: Required Runbook Sections
+    description: |
+      Every runbook MUST include the following sections in order:
+      (1) Overview — alert name, severity, affected services, owner, last
+      updated, last drilled date; (2) Symptoms — observable indicators;
+      (3) Impact Assessment — user-facing effect and blast radius;
+      (4) Diagnostic Steps — ordered steps with copy-pasteable commands;
+      (5) Fix Steps — ordered remediation with verification for each step;
+      (6) Escalation — specific contacts with role and availability;
+      (7) Post-Actions — follow-up tasks, tickets, postmortem triggers.
+    level: MUST
+    examples:
+      - "Overview: Alert=HighErrorRate, Severity=P2, Service=payment-api, Owner=@alice"
+      - "Diagnostic: `kubectl get pods -n payments | grep -v Running`"
+      - "Escalation: If not resolved in 30min, page @payment-lead (PD: pd-payments)"
+
+  - id: REQ-002
+    title: Reproducible and Unambiguous Steps
+    description: |
+      Each step in a runbook MUST be reproducible and unambiguous. Steps
+      MUST use copy-pasteable commands with no placeholders left undefined.
+      Decision points MUST include explicit branch conditions (if X then Y,
+      else Z). Every fix step MUST include a verification command confirming
+      the fix worked before proceeding. Expected output MUST be shown.
+    level: MUST
+    examples:
+      - "Bad: 'Restart the service' — Good: `systemctl restart payment-api && systemctl status payment-api`"
+      - "Branch: If error count > 100/min go to step 5a, else go to step 5b"
+      - "Verify: `curl -s https://api/health | jq .status` should return 'ok'"
+
+  - id: REQ-003
+    title: Runbook Naming and Directory Organization
+    description: |
+      Runbooks MUST use kebab-case names that describe the problem, not the
+      solution. Files MUST be organized into typed directories:
+      alerts/ for alert-response runbooks, operations/ for standard ops,
+      emergency/ for major incident procedures, troubleshooting/ for
+      general investigation guides. Each runbook file MUST declare its type
+      in the front matter.
+    level: MUST
+    examples:
+      - "Good: alerts/payment-api-high-error-rate.md"
+      - "Bad: runbooks/restart-payment-service.md"
+      - "Front matter: type: alert_response, alert: HighErrorRateAlert"
+
+  - id: REQ-004
+    title: Review and Drill Cadence
+    description: |
+      Runbooks MUST be reviewed on schedule based on type: alert-response
+      runbooks quarterly, emergency procedures monthly, standard operation
+      and troubleshooting guides bi-annually, change procedures after each
+      use. Runbooks MUST be drilled: P1 runbooks monthly, P2 quarterly,
+      emergency procedures quarterly. Drill records must be appended to the
+      runbook or linked from it.
+    level: MUST
+    examples:
+      - "Drill record: 2026-03-15, participants: @alice @bob, result: pass, MTTR: 12min"
+      - "Quarterly review: updated diagnostic commands after k8s upgrade"
+      - "Post-change update: change-procedure/db-failover.md updated after March 14 drill"
+
+  - id: REQ-005
+    title: Rollback and Fallback Steps
+    description: |
+      Any runbook describing a change or fix MUST include a clearly labeled
+      rollback section describing how to undo the change if the fix fails
+      or causes additional issues. The rollback section MUST appear before
+      the escalation section and include its own verification steps.
+    level: MUST
+    examples:
+      - "Rollback: `helm rollback payment-api 1 && kubectl rollout status deployment/payment-api`"
+      - "Rollback verify: error rate returns below 1% within 3 minutes"
+      - "If rollback fails: escalate immediately, do not attempt further fixes"
+
+  - id: REQ-006
+    title: Alert Integration Metadata
+    description: |
+      Alert-response runbooks SHOULD include a metadata block linking the
+      runbook to specific alert rules. This enables automatic runbook
+      linking in alerting tools (PagerDuty, Alertmanager). Metadata MUST
+      include the alert name, dashboard URL, and Prometheus/logging query
+      used to investigate.
+    level: SHOULD
+    examples:
+      - "alert_name: PaymentAPIHighErrorRate5xx"
+      - "dashboard: https://grafana/d/payment-api-overview"
+      - "query: sum(rate(http_requests_total{status=~'5..'}[5m])) by (service)"

package/bundled/ai/standards/sast-advanced.ai.yaml

@@ -0,0 +1,135 @@
+# Advanced SAST Standards - AI Optimized
+# Source: XSPEC-161 SAST Advanced
+
+id: sast-advanced
+title: Advanced SAST Standards
+version: "1.0.0"
+status: Active
+tags: [sast, codeql, gitleaks, trufflehog, secret-scanning, biome, static-analysis, security, typescript, ci]
+summary: |
+  Defines advanced Static Application Security Testing (SAST) practices
+  beyond basic dependency auditing. Covers three complementary layers:
+  (1) CodeQL semantic analysis for TypeScript/JavaScript — detects injection
+  vulnerabilities, path traversal, prototype pollution, and XSS that npm audit
+  misses; (2) Secret scanning with gitleaks or TruffleHog — prevents committing
+  API keys, tokens, and credentials; (3) Biome-based code quality rules used as
+  a security lint layer for projects that adopt Biome instead of ESLint.
+  Specifies CI enforcement thresholds: block merge on any CRITICAL or HIGH
+  severity finding; 0 High findings is the passing gate.
+
+requirements:
+  - id: REQ-001
+    title: CodeQL Semantic Analysis
+    description: |
+      Projects using TypeScript or JavaScript MUST run CodeQL semantic analysis
+      on every push to the default branch and on every pull request targeting
+      the default branch. Additionally, a weekly scheduled scan MUST be
+      configured to catch newly published query packs. Use the
+      `security-extended` query suite rather than the default suite to include
+      injection, path-traversal, prototype-pollution, and XSS queries.
+      CodeQL MUST be configured with `github/codeql-action/init@v3` with
+      `languages: javascript-typescript` and query filters narrowed to
+      `security-extended`. The `autobuild` action MUST be used unless a
+      custom build command is required. Results MUST be uploaded to GitHub
+      Code Scanning so that SARIF findings appear in the Security tab and
+      block PRs when severity >= HIGH.
+    level: MUST
+    examples:
+      - "Workflow trigger: push to main + pull_request targeting main + schedule weekly"
+      - "init step: uses: github/codeql-action/init@v3 with languages: javascript-typescript"
+      - "query-filters: include tags contain security-extended"
+      - "analyze step uploads SARIF; GitHub blocks PR merge when CRITICAL/HIGH found"
+      - "Weekly cron: '0 2 * * 1' catches newly published CodeQL query packs"
+
+  - id: REQ-002
+    title: Secret Scanning on Every Push and PR
+    description: |
+      A secret scanning step MUST run on every push and pull request to detect
+      accidentally committed API keys, tokens, private keys, and credentials
+      before they reach the repository history. The recommended tool is
+      gitleaks (via `gitleaks/gitleaks-action@v2`). Projects MUST maintain a
+      `.gitleaks.toml` configuration file in the repository root to declare
+      custom patterns for project-specific secret formats and to whitelist
+      documented false positives via allowlist rules. The CI step MUST fail
+      with a non-zero exit code when any secret is detected, blocking merge.
+      Baseline false positives MUST be documented and reviewed quarterly.
+    level: MUST
+    examples:
+      - "CI job: uses gitleaks/gitleaks-action@v2 on push and pull_request events"
+      - ".gitleaks.toml defines custom patterns for project-specific tokens"
+      - "Allowlist rule added with documented justification for known false positive"
+      - "Secret detected → CI fails → developer rotates credential before re-pushing"
+
+  - id: REQ-003
+    title: Biome Security Rules as Lint Gate
+    description: |
+      Projects using Biome as their linter MUST enable the security-relevant
+      linting rules as part of the standard lint pass. Biome's `nursery` and
+      `suspicious` rule groups include patterns such as `noConsoleLog` (prevents
+      accidental secret logging), `noGlobalEval` (prevents dynamic code execution),
+      `noWith` (prevents scope pollution), and `noDebugger` (prevents debug
+      breakpoints in production). The `biome check .` command MUST be run in CI
+      as a blocking step. Projects MUST NOT use `--allow-errors` to bypass
+      security-relevant rule failures. Configuration in `biome.json` MUST set
+      `linter.enabled: true` and include the `recommended: true` ruleset plus
+      any additional security rules appropriate to the project.
+    level: MUST
+    examples:
+      - "biome.json: linter.enabled true, rules.suspicious.noGlobalEval error"
+      - "CI step: `npm run lint` maps to `biome check .`; fails on security rule violations"
+      - "noConsoleLog prevents accidental logging of JWT tokens or API keys"
+      - "noGlobalEval prevents eval() usage that could enable code injection"
+
+  - id: REQ-004
+    title: CI Quality Gate Thresholds
+    description: |
+      SAST findings MUST be classified by severity and the following merge-blocking
+      thresholds MUST be enforced: CRITICAL findings — block merge immediately,
+      no exceptions; HIGH findings — block merge; target is 0 HIGH findings in
+      all open PRs; MEDIUM findings — create tracking issue, do not block merge,
+      resolve within 30 days; LOW/INFORMATIONAL findings — optional resolution,
+      logged for visibility. GitHub Code Scanning branch protection rules MUST
+      be configured to require the CodeQL check to pass before merging.
+      The `sast` CI job MUST be listed as a required status check in branch
+      protection settings.
+    level: MUST
+    examples:
+      - "Branch protection: require CodeQL check + sast job to pass before merge"
+      - "CRITICAL finding in CodeQL → PR blocked; developer must fix or accept risk with CISO sign-off"
+      - "HIGH finding threshold: 0 HIGH open on main branch at all times"
+      - "MEDIUM finding: GitHub issue opened automatically via SARIF annotation; 30-day SLA"
+
+  - id: REQ-005
+    title: What CodeQL Finds That npm audit Misses
+    description: |
+      Teams MUST understand that npm audit only checks published CVEs in
+      dependency manifests (package.json lock file). CodeQL performs semantic
+      data-flow analysis on the actual source code and detects:
+      (1) Command injection — user-controlled data flowing into child_process.exec
+      or child_process.spawn with shell:true; (2) Path traversal — user input
+      used in fs.readFile / fs.writeFile without path.resolve + allowlist check;
+      (3) Prototype pollution — assignment to obj[userKey] = value where userKey
+      is unsanitized; (4) XSS via DOM sinks — user data assigned to innerHTML,
+      document.write, or passed to eval; (5) SQL injection via string concatenation
+      in ORM raw queries. These vulnerabilities exist in first-party code and are
+      invisible to dependency scanners.
+    level: SHOULD
+    examples:
+      - "CodeQL flags: exec(`git log ${userInput}`) as command injection"
+      - "CodeQL flags: fs.readFile(path.join(base, req.params.file)) as path traversal"
+      - "CodeQL flags: target[req.body.key] = req.body.value as prototype pollution"
+      - "npm audit shows 0 vulnerabilities; CodeQL finds path traversal in custom route handler"
+
+anti_patterns:
+  - "Running only npm audit and considering security 'done'"
+  - "Disabling CodeQL on PRs to speed up CI — defeats the purpose of shift-left security"
+  - "Adding entire file paths to gitleaks allowlist without reviewing the actual content"
+  - "Ignoring MEDIUM CodeQL findings indefinitely without tracking issues"
+  - "Using biome check --allow-errors to bypass security lint failures"
+  - "Not uploading SARIF results to GitHub Code Scanning (findings invisible in UI)"
+
+related_standards:
+  - security-standards
+  - secret-management-standards
+  - checkin-standards
+  - container-security

package/bundled/ai/standards/schema-evolution.ai.yaml

@@ -0,0 +1,111 @@
+# Schema Evolution Standards - AI Optimized
+# Source: XSPEC-068 Wave 3 Data Engineering Pack
+
+id: schema-evolution
+title: Schema Evolution Standards
+version: "1.0.0"
+status: Active
+tags: [data-engineering, schema, migration, backward-compatibility, database]
+summary: |
+  Defines how database and data store schemas are evolved safely without
+  breaking existing consumers. Covers backward-compatible change patterns,
+  prohibited breaking changes, expand-contract migration strategy, schema
+  versioning, automated compatibility checking in CI/CD, and rollback
+  procedures for schema changes. Applicable to relational databases,
+  document stores, event schemas (Avro/Protobuf), and API request/response
+  schemas.
+
+requirements:
+  - id: REQ-001
+    title: Backward-Compatible Change Patterns
+    description: |
+      All schema changes MUST be backward-compatible unless a formal
+      breaking-change process is followed. Backward-compatible changes
+      include: adding new nullable columns/fields with defaults, adding
+      new tables/collections, adding new optional message fields, adding
+      new enum values (with unknown handling), widening a data type
+      (INT → BIGINT), and adding new indexes. These changes MUST be
+      deployable without coordinating consumer updates.
+    level: MUST
+    examples:
+      - "Add column: ALTER TABLE users ADD COLUMN middle_name VARCHAR(100) DEFAULT NULL"
+      - "Add optional Protobuf field: optional string nickname = 15; — safe, zero default"
+      - "Add index: CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id)"
+
+  - id: REQ-002
+    title: Prohibited Breaking Changes Without Migration Plan
+    description: |
+      The following schema changes are classified as BREAKING and MUST NOT
+      be deployed without a formal expand-contract migration plan and
+      consumer coordination: renaming or dropping columns/fields, changing
+      data types incompatibly (VARCHAR → INT, widening to narrowing),
+      adding NOT NULL constraints to existing columns without defaults,
+      changing primary or foreign key definitions, removing enum values,
+      and changing field semantics (repurposing a column for different data).
+    level: MUST
+    examples:
+      - "PROHIBITED: ALTER TABLE users DROP COLUMN legacy_id → requires expand-contract"
+      - "PROHIBITED: ALTER TABLE orders ALTER COLUMN amount TYPE BIGINT — evaluate consumer impact first"
+      - "PROHIBITED: adding NOT NULL to existing column with NULL values in production data"
+
+  - id: REQ-003
+    title: Expand-Contract Migration Strategy
+    description: |
+      Breaking schema changes MUST use the expand-contract (parallel change)
+      pattern: Phase 1 (Expand) — add new structure alongside old; Phase 2
+      (Migrate) — backfill data from old to new, update all writers;
+      Phase 3 (Contract) — update all readers to use new structure;
+      Phase 4 (Cleanup) — remove old structure after all consumers updated.
+      Each phase MUST be a separate deployment, verified before proceeding.
+      Minimum wait between phases: 1 full deployment cycle.
+    level: MUST
+    examples:
+      - "Rename column email → contact_email: add contact_email, dual-write for 1 sprint, migrate readers, drop email"
+      - "Phase gate: 'Phase 2 complete when 0 reads of old column seen in query logs over 7 days'"
+      - "Cleanup verified: `SELECT COUNT(*) FROM users WHERE email IS NOT NULL` returns 0 before dropping"
+
+  - id: REQ-004
+    title: Schema Versioning and Registry
+    description: |
+      Event-driven and API schemas (Avro, Protobuf, JSON Schema) MUST be
+      registered in a schema registry with explicit version numbers.
+      Schema versions MUST follow semantic versioning: PATCH for backward-
+      compatible additions, MINOR for new optional fields, MAJOR for
+      breaking changes. Every schema change MUST be reviewed and approved
+      before registration. Consumers MUST specify the schema version they
+      consume.
+    level: MUST
+    examples:
+      - "Confluent Schema Registry: subject 'order-events-value', version 3 registered"
+      - "Schema compatibility: BACKWARD_TRANSITIVE enforced — new schema must be readable by all prior consumers"
+      - "Consumer declaration: {schema_id: 'order-events', version: '>=2.0.0 <3.0.0'}"
+
+  - id: REQ-005
+    title: Automated Schema Compatibility Checking in CI
+    description: |
+      Every PR modifying schema definitions MUST trigger automated
+      compatibility checks in CI. For relational schemas, migration scripts
+      MUST be run against a production-snapshot database in CI to detect
+      errors before merge. For event schemas, compatibility MUST be checked
+      against all registered consumer versions. Compatibility failures MUST
+      block the PR merge.
+    level: MUST
+    examples:
+      - "CI step: `flyway validate -url=jdbc:postgresql://test-db/snapshots` on every migration PR"
+      - "Avro compatibility: `schema-registry-validate --mode BACKWARD_TRANSITIVE new-schema.avsc`"
+      - "Failed check message: 'Schema change removes required field order_id — breaks consumer v2.3'"
+
+  - id: REQ-006
+    title: Schema Change Rollback Procedures
+    description: |
+      Every schema migration script MUST have a corresponding rollback
+      (down) migration script. Rollback scripts MUST be tested in CI
+      alongside the forward migration. For destructive changes (drops,
+      type changes), a data backup MUST be taken and verified before
+      execution. The rollback plan MUST be documented in the migration
+      PR and referenced in the deployment runbook.
+    level: MUST
+    examples:
+      - "V12__add_user_tier.sql paired with V12__add_user_tier.undo.sql tested in CI"
+      - "Pre-migration backup: `pg_dump orders_table > backup-2026-04-30-pre-v12.dump`"
+      - "Rollback PR comment: 'Rollback: run V12.undo.sql, takes ~2min, no data loss'"

package/bundled/ai/standards/secret-management-standards.ai.yaml

@@ -0,0 +1,105 @@
+# Secret Management Standards - AI Optimized
+# Source: XSPEC-065 Wave 4 IaC Pack
+
+id: secret-management-standards
+title: Secret Management and Credential Hygiene Standards
+version: "1.0.0"
+status: Active
+tags: [secrets, vault, kms, sops, security, rotation, credential-management]
+summary: |
+  Defines how teams store, inject, rotate, and audit secrets and credentials
+  across development and production environments. Covers three approved secret
+  source tiers (Vault dynamic secrets, Cloud KMS, SOPS+Git), rotation policies
+  by credential type, automated hardcoded-secret prevention via pre-commit and
+  CI scanning, and safe secret injection patterns. Designed to eliminate
+  credentials from source code and CI logs while maintaining operational
+  practicality across team sizes.
+
+requirements:
+  - id: REQ-001
+    title: Secret Source Three Options
+    description: |
+      Teams MUST use one of three approved secret source tiers based on
+      operational context. (1) HashiCorp Vault dynamic secrets (preferred for
+      production and multi-team environments) — secrets are generated on-demand
+      with short TTLs; no static credentials stored anywhere. (2) Cloud KMS
+      with native secret managers (AWS Secrets Manager / GCP Secret Manager /
+      Azure Key Vault) — suitable for cloud-native deployments; secrets fetched
+      at runtime via IAM-controlled API calls. (3) SOPS + Git encryption —
+      suitable for small teams and GitOps workflows; secrets encrypted with
+      age or KMS key before committing; decrypted only in trusted runtime
+      environments. Storing unencrypted secrets in any other location (env
+      files, wiki, chat) is PROHIBITED.
+    level: MUST
+    examples:
+      - "Vault: app requests DB credentials via Vault agent sidecar with 1h TTL lease"
+      - "AWS Secrets Manager: Lambda reads secret ARN from env var; SDK fetches at cold start"
+      - "SOPS: `secrets.yaml` encrypted with age key; decrypted in CI via SOPS_AGE_KEY env var"
+      - "Prohibited: secrets in `.env` files committed to repo, even private repos"
+
+  - id: REQ-002
+    title: Rotation Policy by Type
+    description: |
+      All secrets MUST have a defined rotation policy enforced by automated
+      tooling or calendar reminders. Minimum rotation frequencies by type:
+      Database credentials: every 90 days. API keys (third-party services):
+      every 180 days. Signing keys (JWT, code signing): every 365 days.
+      One-time tokens and session credentials: revoke immediately after use;
+      MUST NOT be reused. TLS certificates: rotate at least 30 days before
+      expiry; automate with ACME/Let's Encrypt or cert-manager where possible.
+      Rotation events MUST be logged in the audit trail.
+    level: MUST
+    examples:
+      - "DB credentials rotated via Vault dynamic secrets every 90 days automatically"
+      - "Stripe API key rotation reminder calendar event set for 180-day interval"
+      - "JWT signing key rotated annually; old key retained for 7-day grace period"
+      - "CI temporary tokens scoped to single job; revoked by runner post-job"
+
+  - id: REQ-003
+    title: Hardcoded Secret Prevention
+    description: |
+      Teams MUST implement automated scanning to detect and block hardcoded
+      secrets before they reach the repository. Two layers are REQUIRED:
+      (1) Pre-commit hook using detect-secrets, gitleaks, or truffleHog —
+      scans staged files and blocks commit if patterns are detected.
+      (2) CI pipeline scan — rescans all changed files on every PR; blocks
+      merge if secrets are found. Minimum detected patterns: AWS access key
+      format (AKIA[0-9A-Z]{16}), PEM private key headers (-----BEGIN .* PRIVATE KEY),
+      generic API token patterns (api[_-]?key\s*[:=]\s*\S{16,}), and
+      connection strings containing passwords.
+    level: MUST
+    examples:
+      - "`.pre-commit-config.yaml` includes `detect-secrets` hook; fails on AWS key pattern"
+      - "CI step: `gitleaks detect --source . --exit-code 1` blocks PR merge"
+      - "False positive whitelisted via `.secrets.baseline` with documented justification"
+      - "Developer receives pre-commit error: 'High confidence secret detected: AWS Access Key'"
+
+  - id: REQ-004
+    title: Secret Injection
+    description: |
+      Secrets MUST be injected into application processes via environment
+      variables or mounted files only. Passing secrets via command-line
+      arguments is PROHIBITED (visible in process lists). Passing secrets via
+      URL query parameters is PROHIBITED (logged by proxies and servers).
+      For environment variable injection, use the platform's native secret
+      injection (Kubernetes Secrets, ECS task definition secrets, GitHub
+      Actions secrets). For file-based injection, mount secrets as
+      read-only volumes with restrictive file permissions (0400 or 0600).
+    level: MUST
+    examples:
+      - "Kubernetes: secret mounted as env var via `secretKeyRef` in pod spec"
+      - "Prohibited: `./app --db-password=s3cr3t` (visible in `ps aux`)"
+      - "Prohibited: `https://api.example.com?token=abc123` (logged by nginx)"
+      - "File injection: secret mounted at `/run/secrets/db-password` with mode 0400"
+
+anti_patterns:
+  - "Hardcoding credentials directly in source code or configuration files"
+  - "Storing secrets in CI/CD environment variables without encryption (plaintext in UI)"
+  - "Sharing credentials across multiple environments (dev/staging/prod use same secret)"
+  - "Long-lived static credentials without rotation schedules"
+  - "Committing .env files containing real secrets to version control"
+
+related_standards:
+  - iac-design-principles
+  - audit-trail
+  - pii-classification