universal-dev-standards 5.4.0 → 5.6.0

package/bundled/ai/standards/full-coverage-testing.ai.yaml

@@ -0,0 +1,192 @@
+# Full Coverage Testing Standards - AI Optimized
+# XSPEC-178: Replaces pyramid threshold model with behavior-completeness paradigm
+# Source: core/full-coverage-testing.md
+
+standard:
+  id: full-coverage-testing
+  name: Full Coverage Testing Standards
+  description: Behavior-completeness full coverage paradigm replacing pyramid thresholds. Enforces anti-fake-test rules, STUB marker protocol, ratchet CI, and @ac traceability.
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-06"
+    source: core/full-coverage-testing.md
+    replaces: "testing pyramid thresholds (UT≥80%/IT≥70%/E2E happy-path-only)"
+    xspec: "XSPEC-178"
+    description: AI-era full coverage paradigm — cost of writing tests equals cost of writing code, so there is no reason to set lower thresholds for any test layer.
+
+  rationale: |
+    Traditional pyramid thresholds (UT≥80%, IT≥70%) assumed tests were expensive to write.
+    AI code generation eliminates this cost differential — code and tests are produced at the
+    same speed. Therefore: maximize coverage everywhere, with behavior-completeness as the
+    measure, not a percentage floor.
+
+  coverage_model:
+    type: behavior_completeness
+    description: Every public function must have tests for all three behavioral paths
+    required_paths:
+      - id: happy_path
+        description: Normal input produces correct output
+        example: "calculateDiscount(100, 0.1) → 90"
+      - id: edge_case
+        description: Boundary values do not cause unexpected errors
+        example: "calculateDiscount(0, 1.0) → 0 without throwing"
+      - id: error_path
+        description: Invalid input raises clear error or returns error state
+        example: "calculateDiscount(-1, 2.0) → throws ArgumentError"
+
+  ratchet_policy:
+    enabled: true
+    description: Coverage can only increase, never decrease. PR that regresses coverage is blocked.
+    mechanism:
+      - Store baseline in .coverage-baseline.json on main branch
+      - Every PR compares current coverage against baseline
+      - Regression = PR blocked, not merged
+      - Improvement = new baseline set on merge
+    note: No fixed floor threshold. The current coverage IS the threshold.
+
+  rules:
+    # ── Behavior completeness ──────────────────────────────────────
+    - id: three-path-coverage
+      trigger: writing tests for any public function
+      instruction: |
+        Write at least three tests per public function:
+        1. happy_path — normal inputs, expected output
+        2. edge_case — boundary values (zero, max, empty, null)
+        3. error_path — invalid inputs trigger explicit error or error state
+      priority: required
+
+    - id: ac-traceability
+      trigger: writing any test
+      instruction: |
+        Tag each test with the Acceptance Criteria it covers using JSDoc @ac tag.
+        Format: /** @ac AC-ID */ above the test function.
+        If no AC maps to this test, use: /** @ac UNTRACED */
+      priority: recommended
+      example: |
+        /**
+         * @ac AC-US03-2
+         */
+        it('should block PR when coverage regresses', () => { ... })
+
+    # ── Anti-fake test rules ───────────────────────────────────────
+    - id: no-tautology-assertions
+      trigger: writing any test assertion
+      instruction: |
+        FORBIDDEN: Tautology assertions that always pass regardless of behavior.
+        These add false coverage without verifying anything.
+      priority: required
+      forbidden_patterns:
+        - "expect(true).toBe(true)"
+        - "expect(false).toBe(false)"
+        - "expect(result).toBeDefined()  // without specific value"
+        - "expect(result).not.toBeNull()  // without specific value"
+      required_instead: "expect(result).toBe(<specific expected value>)"
+
+    - id: no-mock-business-logic
+      trigger: deciding what to mock
+      instruction: |
+        FORBIDDEN: Mocking core business logic or your own service functions.
+        Mocking your own code means the business logic is never actually executed.
+      priority: required
+      allowed_to_mock:
+        - External HTTP APIs (payment gateways, OAuth providers)
+        - Hardware interfaces (sensors, GPIO, Docker daemon)
+        - Third-party SDKs with no test mode
+        - File system (use tmpdir, not mock)
+      forbidden_to_mock:
+        - Core business calculation functions
+        - Your own service layer methods
+        - Database queries (use in-memory SQLite instead)
+        - Your own utility functions
+
+    - id: mock-must-have-reason
+      trigger: writing any mock/stub/spy
+      instruction: |
+        Every jest.mock(), vi.mock(), jest.spyOn(), or sinon.stub() must be preceded
+        by a comment explaining WHY this dependency must be mocked.
+        Format: // MOCK: <reason — what external dependency and why it cannot be real>
+      priority: required
+      example: |
+        // MOCK: External Stripe payment API — no sandbox available in CI
+        jest.mock('./payment-gateway', () => ({ charge: jest.fn().mockResolvedValue({ id: 'ch_test' }) }))
+
+    # ── STUB marker protocol ───────────────────────────────────────
+    - id: stub-marker-required
+      trigger: writing any temporary/placeholder implementation
+      instruction: |
+        ALL temporary implementations, placeholder functions, and fake returns
+        MUST be marked with the standard STUB marker.
+        Format: // WARNING: STUB — Remove before UAT
+        This marker is scanned by pre-push hooks and deploy.sh.
+        STUB markers block pushes to main and deployments to UAT/production.
+      priority: required
+      example: |
+        // WARNING: STUB — Remove before UAT
+        async function validatePayment(card: Card): Promise<boolean> {
+          return true; // Always approve — replace with real Stripe call
+        }
+
+    - id: coverage-exempt-format
+      trigger: dealing with genuinely untestable external dependencies
+      instruction: |
+        If a dependency truly cannot be tested (hardware, live external API with no sandbox),
+        declare an explicit exemption with a mandatory reason.
+        Format: // COVERAGE_EXEMPT: <specific reason why real test is impossible>
+        This exemption is respected by STUB scanners and will not trigger blocking.
+        The reason MUST be non-empty and specific.
+      priority: required
+      example: |
+        // COVERAGE_EXEMPT: Hardware temperature sensor — no simulation available in CI
+        async function readTemperature(): Promise<number> {
+          return hardwareSensor.read();
+        }
+
+    - id: no-silent-stub
+      trigger: reviewing code before commit
+      instruction: |
+        Stubbed/placeholder code without // WARNING: STUB is a violation.
+        Common patterns to watch for: functions that always return hardcoded values,
+        empty function bodies that should have logic, TODO comments without STUB marker.
+        These will eventually reach production undetected.
+      priority: required
+
+  deployment_gates:
+    pre_push_to_main:
+      action: block
+      trigger: "// WARNING: STUB" marker found in src/
+      message: "[STUB-BLOCK] STUB markers detected. Push to main rejected."
+    deploy_to_uat:
+      action: block
+      trigger: "// WARNING: STUB" marker found in src/
+      message: "[DEPLOY-BLOCK] STUB markers detected. UAT deployment aborted."
+    deploy_to_production:
+      action: block
+      trigger: "// WARNING: STUB" marker found in src/
+      message: "[CRITICAL] Production deployment with STUB markers is strictly prohibited."
+    deploy_to_staging:
+      action: warn
+      trigger: "// WARNING: STUB" marker found in src/
+      message: "[STUB-WARN] Deploying with STUB markers to staging. NOT permitted in UAT/production."
+    feature_branch_push:
+      action: warn
+      trigger: "// WARNING: STUB" marker found in src/
+      message: "[STUB-WARN] STUB markers found. Must remove before merging to main."
+
+  migration_from_pyramid:
+    deprecated:
+      - "UT ≥ 80% coverage threshold"
+      - "IT ≥ 70% coverage threshold"
+      - "E2E happy-path-only requirement"
+    replaced_by:
+      - "Behavior-completeness: happy/edge/error per public function"
+      - "Ratchet CI: coverage can only increase"
+      - "Anti-fake rules: no tautology, no business-logic mocks"
+      - "STUB protocol: deployment gates on all environments"
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: >
+      test -f scripts/check-stubs.sh && test -f scripts/check-anti-fake-tests.sh
+    rule: "xspec178_enforcement_scripts_present"

package/bundled/ai/standards/iac-design-principles.ai.yaml

@@ -0,0 +1,83 @@
+# IaC Design Principles - AI Optimized
+# Source: XSPEC-065 Wave 4 IaC Pack
+
+id: iac-design-principles
+title: Infrastructure as Code Design Principles
+version: "1.0.0"
+status: Active
+tags: [iac, infrastructure, terraform, pulumi, cloudformation, immutable-infrastructure]
+summary: |
+  Defines the four foundational principles for Infrastructure as Code (IaC)
+  authoring: reproducible, immutable, idempotent, and versioned. Covers state
+  management requirements including remote state with locking, drift detection
+  categories, and CI/CD integration. Designed to ensure infrastructure changes
+  are traceable, reversible, and safe to apply repeatedly without unintended
+  side effects.
+
+requirements:
+  - id: REQ-001
+    title: IaC Four Principles
+    description: |
+      All infrastructure definitions MUST adhere to four foundational principles:
+      (1) Reproducible — given the same inputs and state, applying IaC produces
+      identical infrastructure. (2) Immutable — infrastructure changes are
+      applied by replacing resources, not mutating them in-place; blue/green or
+      rolling replacement patterns are preferred over in-place mutations.
+      (3) Idempotent — applying the same IaC configuration multiple times
+      produces the same result without error or unintended side effects.
+      (4) Versioned — all IaC definitions are stored in version control with
+      meaningful commit messages; no infrastructure change is made outside the
+      VCS workflow.
+    level: MUST
+    examples:
+      - "Terraform modules pinned to specific provider versions for reproducibility"
+      - "EC2 instance replacement via launch template version bump, not in-place AMI update"
+      - "`terraform apply` is safe to re-run; no manual pre-checks needed for idempotency"
+      - "All Pulumi programs committed to git; no ad-hoc CLI changes accepted"
+
+  - id: REQ-002
+    title: State Management
+    description: |
+      IaC state MUST be stored in a remote backend with locking enabled to
+      prevent concurrent modifications. Local state files MUST NOT be committed
+      to version control or used in CI/CD pipelines. Recommended backends:
+      Terraform Cloud / S3+DynamoDB (Terraform), Pulumi Service / S3 (Pulumi),
+      CloudFormation native stack state. State access MUST be restricted to
+      authorized principals via IAM or equivalent. State encryption at rest
+      is REQUIRED.
+    level: MUST
+    examples:
+      - "Terraform S3 backend with DynamoDB lock table; `.terraform/` in .gitignore"
+      - "Pulumi state stored in Pulumi Cloud with team access controls"
+      - "CI pipeline uses OIDC to assume role with state bucket access; no static credentials"
+      - "State file encrypted using AWS KMS customer-managed key"
+
+  - id: REQ-003
+    title: Drift Detection
+    description: |
+      Teams MUST run `plan` (or equivalent) in CI on every pull request to
+      detect configuration drift. Drift outcomes MUST be classified into one
+      of three categories and handled accordingly: (1) rollback-to-code —
+      actual infra deviates from code due to manual change; revert actual to
+      match code on next apply. (2) update-code-from-actual — actual reflects
+      intentional change not yet codified; update IaC to match, then apply.
+      (3) manual-reconcile — drift requires human judgment (e.g., data volume
+      changes); escalate to infra owner with documented decision. Drift reports
+      SHOULD be published to a team channel on a scheduled cadence (e.g., daily).
+    level: MUST
+    examples:
+      - "CI runs `terraform plan` on PR; plan output posted as PR comment"
+      - "Security group rule added via console → classified rollback-to-code; removed on next apply"
+      - "RDS storage autoscaled → classified update-code-from-actual; IaC updated to new size"
+      - "Daily drift scan via scheduled CI job; report posted to #infra-alerts Slack channel"
+
+anti_patterns:
+  - "Committing local state files (terraform.tfstate) to version control"
+  - "Applying mutable in-place changes (e.g., sed-patching running VMs) instead of replacing resources"
+  - "Making manual console changes without updating the corresponding IaC definition"
+  - "Using no remote locking, allowing concurrent applies that corrupt state"
+  - "Pinning to `latest` provider or module versions, breaking reproducibility"
+
+related_standards:
+  - containerization-standards
+  - secret-management-standards

package/bundled/ai/standards/incident-response.ai.yaml

@@ -0,0 +1,107 @@
+# Incident Response Standards - AI Optimized
+# Source: XSPEC-063 Wave 3 SRE Pack
+
+id: incident-response
+title: Incident Response Standards
+version: "1.0.0"
+status: Active
+tags: [sre, incident, oncall, postmortem, severity]
+summary: |
+  Defines the end-to-end incident response lifecycle: severity classification,
+  response time SLAs, roles and responsibilities, communication protocols,
+  escalation paths, and blameless postmortem requirements. Designed to reduce
+  MTTR, ensure consistent stakeholder communication during incidents, and
+  drive systemic reliability improvements through structured postmortems.
+
+requirements:
+  - id: REQ-001
+    title: Severity Classification
+    description: |
+      Every incident MUST be classified at declaration using a 4-level
+      severity scale. SEV-1 (Critical): complete service outage or data
+      breach affecting all users, response within 15 minutes, C-suite
+      notification. SEV-2 (High): major feature unavailable or significant
+      performance degradation >25% users, response within 30 minutes.
+      SEV-3 (Medium): minor feature unavailable or degradation <25% users,
+      response within 4 hours. SEV-4 (Low): cosmetic issue or very minor
+      impact, response within 24 hours.
+    level: MUST
+    examples:
+      - "SEV-1: Payment processing completely down → IC declared, bridge opened in <5min"
+      - "SEV-2: Checkout latency >10s for 30% of users → on-call paged, IC assigned"
+      - "SEV-3: Search autocomplete broken → ticket created, fix in next sprint"
+
+  - id: REQ-002
+    title: Incident Commander Role
+    description: |
+      Every SEV-1 and SEV-2 incident MUST have a designated Incident
+      Commander (IC) assigned within 10 minutes of declaration. The IC is
+      responsible for: coordinating the response bridge, assigning roles
+      (scribe, comms lead, technical leads), driving timeline, making
+      go/no-go decisions on fixes, and initiating postmortem. The IC does
+      NOT directly troubleshoot — their sole focus is coordination.
+    level: MUST
+    examples:
+      - "IC assignment: 'I'm taking IC for this SEV-2, @alice please scribe, @bob comms'"
+      - "IC checklist: bridge open, roles assigned, status page updated, stakeholders notified"
+      - "IC does not debug code; delegates to technical leads who report findings"
+
+  - id: REQ-003
+    title: Stakeholder Communication Protocol
+    description: |
+      During SEV-1/SEV-2 incidents, stakeholder updates MUST be sent on a
+      defined cadence: initial notification within 15 minutes of declaration,
+      updates every 30 minutes until resolution, immediate update on any
+      severity change or major development. Updates MUST include: current
+      status, known impact, what is being done, next update time. Status
+      page MUST be updated simultaneously with internal communications.
+    level: MUST
+    examples:
+      - "T+15min: 'We are investigating elevated error rates on checkout. ~500 users affected. Next update in 30min.'"
+      - "T+45min: 'Root cause identified as database connection pool exhaustion. Fix in progress. Next update in 30min.'"
+      - "Resolution: 'Service restored at 14:32 UTC. Postmortem scheduled for 2026-05-02.'"
+
+  - id: REQ-004
+    title: Blameless Postmortem Requirements
+    description: |
+      Every SEV-1 incident MUST have a blameless postmortem completed within
+      5 business days. SEV-2 incidents MUST have a postmortem within 10
+      business days. Postmortems MUST be blameless — focusing on systemic
+      causes, not individual mistakes. Required sections: timeline, impact,
+      root cause (5 Whys), contributing factors, action items with owners
+      and due dates, lessons learned. Action items MUST be tracked to
+      completion.
+    level: MUST
+    examples:
+      - "Timeline: 14:00 Alert fired → 14:05 IC assigned → 14:23 RCA found → 14:32 resolved"
+      - "Root cause: 5 Whys tracing alert → connection pool exhaustion → missing timeout config → no review gate"
+      - "Action item: INFRA-2341 Add connection pool monitoring, owner: @dave, due: 2026-05-15"
+
+  - id: REQ-005
+    title: On-Call Rotation and Handoff
+    description: |
+      Every production service MUST have a documented on-call rotation with
+      at least 2 engineers. Rotation schedules MUST be published at least
+      2 weeks in advance. On-call handoff MUST include a written summary of:
+      active incidents, recent incidents still under investigation,
+      known flaky alerts, upcoming planned maintenance, and any service
+      health concerns. Handoff MUST be acknowledged by incoming on-call.
+    level: MUST
+    examples:
+      - "Handoff doc: 3 active flaky alerts (JIRA links), 1 ongoing SEV-3, maintenance window Friday 02:00 UTC"
+      - "Rotation: 1-week shifts, 2 primary + 1 secondary, published monthly in PagerDuty"
+      - "Handoff acknowledgment: incoming engineer replies 'Handoff received, I have the pager'"
+
+  - id: REQ-006
+    title: Incident Retrospective Metrics
+    description: |
+      Teams SHOULD track and review incident metrics monthly: MTTD (Mean
+      Time To Detect), MTTR (Mean Time To Resolve), incident frequency by
+      severity, repeat incidents (same root cause within 90 days), and
+      postmortem action item completion rate. These metrics SHOULD be
+      reviewed in monthly reliability reviews with engineering leadership.
+    level: SHOULD
+    examples:
+      - "Monthly metrics: MTTD 8min, MTTR 42min, 3 SEV-2s, 0 SEV-1s, 0 repeat incidents"
+      - "Repeat incident flag: same DB timeout root cause in March and April → escalate to reliability sprint"
+      - "Action item completion rate: 85% of previous month's items closed on time"

package/bundled/ai/standards/license-compliance.ai.yaml

@@ -0,0 +1,106 @@
+# License Compliance Standards - AI Optimized
+# Source: XSPEC-066 Wave 3 Compliance Pack
+
+id: license-compliance
+title: License Compliance Standards
+version: "1.0.0"
+status: Active
+tags: [compliance, licensing, open-source, legal, supply-chain]
+summary: |
+  Defines how teams identify, track, and manage open-source and third-party
+  software licenses throughout the software development lifecycle. Covers
+  license classification (permissive vs. copyleft), prohibited licenses,
+  SBOM generation, license scanning in CI/CD, and remediation processes
+  for license violations. Designed to prevent legal exposure from
+  incompatible license combinations and ensure supply-chain transparency.
+
+requirements:
+  - id: REQ-001
+    title: License Classification and Allowlist
+    description: |
+      Every project MUST maintain a documented license policy classifying
+      licenses into three tiers. APPROVED: MIT, Apache 2.0, BSD-2-Clause,
+      BSD-3-Clause, ISC, CC0 — can be used without review. REVIEW-REQUIRED:
+      LGPL-2.1, LGPL-3.0, MPL-2.0, CDDL — requires legal/architecture
+      review before adoption. PROHIBITED: GPL-2.0 (without exception),
+      GPL-3.0, AGPL-3.0, SSPL, Commons Clause additions — MUST NOT be
+      included in proprietary or commercial products.
+    level: MUST
+    examples:
+      - "MIT dependency lodash → auto-approved, no review needed"
+      - "LGPL-3.0 dependency → open GitHub issue tagged 'license-review' before merging"
+      - "GPL-3.0 dependency found in PR → PR blocked by CI until dependency replaced"
+
+  - id: REQ-002
+    title: Automated License Scanning in CI
+    description: |
+      Every repository MUST run automated license scanning on every pull
+      request and on a daily scheduled basis. The scan MUST fail the build
+      if any PROHIBITED license is detected in direct or transitive
+      dependencies. REVIEW-REQUIRED licenses MUST generate a warning that
+      blocks merge until manually approved and documented. Scan results
+      MUST be stored as build artifacts for 1 year.
+    level: MUST
+    examples:
+      - "CI step: `npx license-checker --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC'`"
+      - "Daily scheduled scan via GitHub Actions: runs license-checker across all repos"
+      - "Build artifact: license-report-2026-04-30.json retained for 1 year"
+
+  - id: REQ-003
+    title: Software Bill of Materials (SBOM) Generation
+    description: |
+      Every production release MUST include a Software Bill of Materials
+      (SBOM) in SPDX 2.3 or CycloneDX 1.5 format. The SBOM MUST list all
+      direct and transitive dependencies with: package name, version,
+      license identifier (SPDX), and supplier. SBOMs MUST be generated
+      automatically as part of the release pipeline and stored alongside
+      release artifacts.
+    level: MUST
+    examples:
+      - "SBOM generated via: `syft . -o spdx-json > sbom-v1.2.0.spdx.json`"
+      - "SBOM uploaded to release: GitHub Release v1.2.0 includes sbom-v1.2.0.spdx.json"
+      - "SBOM SPDX entry: {name: 'lodash', version: '4.17.21', licenseConcluded: 'MIT'}"
+
+  - id: REQ-004
+    title: License Attribution and Notices
+    description: |
+      Products distributed to external users MUST include a NOTICES or
+      LICENSE-THIRD-PARTY file listing all open-source components and their
+      license texts. This file MUST be auto-generated from the SBOM data.
+      For web applications, attribution MUST be accessible via a dedicated
+      page or endpoint (e.g., /licenses or /legal/notices).
+    level: MUST
+    examples:
+      - "NOTICES file auto-generated: `npx generate-license-file --input package.json --output NOTICES`"
+      - "Web app: GET /legal/notices returns HTML page with all dependency licenses"
+      - "Mobile app: 'Open Source Licenses' screen in Settings menu"
+
+  - id: REQ-005
+    title: License Violation Remediation Process
+    description: |
+      When a license violation is detected, teams MUST follow the remediation
+      process: (1) immediately block merge/release if PROHIBITED license;
+      (2) create a tracking issue within 1 business day; (3) remediate
+      within 5 business days for PROHIBITED, 30 days for REVIEW-REQUIRED;
+      (4) document decision and alternative chosen; (5) update SBOM and
+      re-scan to verify clean. Unresolved violations MUST be reported to
+      the engineering lead monthly.
+    level: MUST
+    examples:
+      - "Violation: transitive dep uses GPL-3.0 → PR blocked, issue COMP-112 created same day"
+      - "Remediation: replaced dep with MIT-licensed alternative within 3 days"
+      - "Monthly report: 0 open violations as of 2026-04-30"
+
+  - id: REQ-006
+    title: License Review for New Technology Adoption
+    description: |
+      Before adopting any new framework, library, or tool, engineers SHOULD
+      verify its license tier as part of the technology evaluation. License
+      status SHOULD be documented in the relevant ADR or technical spike
+      document. For REVIEW-REQUIRED licenses, architecture review board
+      approval MUST be obtained before adoption.
+    level: SHOULD
+    examples:
+      - "ADR-042 notes: 'Library X uses Apache 2.0 — approved tier, no legal review needed'"
+      - "ADR-043 notes: 'Library Y uses LGPL-3.0 — review-required, legal approved 2026-03-10'"
+      - "Technology radar entry includes license classification for each evaluated tool"