universal-dev-standards 5.1.1 → 5.3.0

package/bundled/ai/options/push/single-owner-mode.ai.yaml

@@ -0,0 +1,60 @@
+# Push Option: Single Owner Mode - AI Optimized
+# Parent: push-standards (XSPEC-081)
+# Source: options/push/single-owner-mode.md
+
+id: single-owner-mode
+meta:
+  parent: push-standards
+  version: "1.0.0"
+  updated: "2026-04-24"
+  source: options/push/single-owner-mode.md
+  description: Reduced-friction push mode for personal/solo repositories — removes collaboration guardrails while keeping essential safety checks
+
+best_for:
+  - Personal repositories with sole ownership
+  - Solo open source projects with no external contributors
+  - Forked repositories for personal experimentation
+
+configuration:
+  repo_mode: single-owner
+  protected_branches: [main, master, "release/*", "hotfix/*"]
+  push_gates:
+    default: [lint, test]
+  receipt:
+    output: console
+  auto_pr: false
+
+behaviors:
+  protected_branch_detection:
+    enabled: true
+    confirmation_required: false
+    action: warning_only
+    note: Shows branch name and pending commit count; user proceeds without typing confirmation string
+
+  force_push_guardrail:
+    enabled: true
+    confirmation_required: false
+    action: warning_only
+    shows: commits_count_only
+    note: No author breakdown; records force_push=true in receipt
+
+  pre_push_gates:
+    gates: [lint, test]
+    execution: sequential
+    skip_flag: "--skip-gates"
+    skip_records: gates_skipped=true
+
+  pr_automation:
+    enabled: false
+    auto_pr: false
+    note: No PR prompts after push; use 'gh pr create' manually if needed
+
+  push_receipt:
+    output: console
+    fields: [branch, commit_sha, gates_passed, gates_skipped, force_push, timestamp, target_remote]
+
+comparison_with_team_mode:
+  protected_branch_detection: warning_only  # team: full + confirmation required
+  force_push_guardrail: warning_only        # team: confirmation text required
+  pre_push_gates: identical                 # both: lint + test
+  pr_automation: disabled                  # team: enabled

package/bundled/ai/options/push/team-mode.ai.yaml

@@ -0,0 +1,64 @@
+# Push Option: Team Mode - AI Optimized
+# Parent: push-standards (XSPEC-081)
+# Source: options/push/team-mode.md
+
+id: team-mode
+meta:
+  parent: push-standards
+  version: "1.0.0"
+  updated: "2026-04-24"
+  source: options/push/team-mode.md
+  description: Default push mode with full collaboration guardrails for multi-contributor repositories
+
+best_for:
+  - Team projects with 2+ contributors
+  - Open source repositories accepting external contributions
+  - Projects using protected branch policies
+  - Any repository requiring code review before merge
+
+configuration:
+  repo_mode: team
+  protected_branches: [main, master, "release/*", "hotfix/*"]
+  push_gates:
+    default: [lint, test]
+  receipt:
+    output: console
+  auto_pr: true
+
+behaviors:
+  protected_branch_detection:
+    enabled: true
+    confirmation_required: true
+    action: full_guardrail
+    note: Displays warning banner; user must explicitly confirm before proceeding
+
+  force_push_guardrail:
+    enabled: true
+    confirmation_required: true
+    confirmation_text: "yes, force push"
+    shows: [commits_count, authors]
+    note: User must type confirmation string; records force_push=true in receipt
+
+  pre_push_gates:
+    gates: [lint, test]
+    execution: sequential
+    failure_message: includes_suggested_fix
+    skip_flag: "--skip-gates"
+    skip_records: gates_skipped=true
+
+  pr_automation:
+    enabled: true
+    trigger: push_to_non_protected_branch
+    checks_existing_pr: true
+    no_pr_action: prompt_pr_automation_assistant
+    skip_flag: "--no-pr"
+
+  push_receipt:
+    output: console
+    fields: [branch, commit_sha, gates_passed, gates_skipped, force_push, timestamp, target_remote]
+
+comparison_with_single_owner_mode:
+  protected_branch_detection: full_confirmation_required  # single-owner: warning only
+  force_push_guardrail: confirmation_text_required        # single-owner: warning only
+  pre_push_gates: identical                               # both: lint + test
+  pr_automation: enabled                                  # single-owner: disabled

package/bundled/ai/options/release/publish-mode-github-actions.ai.yaml

@@ -0,0 +1,65 @@
+# Release Option: GitHub Actions Publish Mode - AI Optimized
+# Parent: release-standards
+# Source: options/release/publish-mode-github-actions.md
+
+id: publish-mode-github-actions
+meta:
+  parent: release-standards
+  version: "1.0.0"
+  updated: "2026-04-24"
+  source: options/release/publish-mode-github-actions.md
+  description: CD publish pattern for npm packages — publish is triggered automatically by GitHub Release, not by manual `npm publish`
+
+best_for:
+  - npm packages hosted in GitHub repositories
+  - Projects with GitHub Actions publish workflow (publish.yml or similar)
+  - Single-owner or small-team repos using GitHub Actions CD
+  - Projects where NPM_TOKEN is stored as a GitHub Actions secret
+
+configuration:
+  publish_mode: github-actions
+  publish_trigger: gh_release_create
+  publish_command: none  # npm publish is handled by GitHub Actions
+  tag_format: "v{semver}"
+
+behaviors:
+  release_finish_sequence:
+    steps:
+      - bump_version      # scripts/bump-version.sh or npm version
+      - update_changelog  # add [X.Y.Z] section, remove from [Unreleased]
+      - commit_and_tag    # git commit + git tag vX.Y.Z
+      - push_with_tag     # git push origin main vX.Y.Z
+      - create_gh_release # gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
+    note: >
+      DO NOT run `npm publish` manually. The `gh release create` command triggers
+      the publish workflow via `release: published` event. GitHub Actions handles
+      the actual npm publish using NPM_TOKEN stored as a repository secret.
+
+  gh_release_create:
+    command: 'gh release create v{version} --title "v{version}" --notes "{changelog_entry}"'
+    triggers: publish_workflow
+    publishes_to_npm_tag:
+      stable: latest       # versions without pre-release suffix (e.g. 5.2.0)
+      prerelease: next      # versions with beta/alpha/rc suffix (e.g. 5.2.0-beta.1)
+
+  publish_workflow:
+    trigger_event: "release: published"
+    secret_required: NPM_TOKEN
+    runs_on: github_actions
+    note: >
+      Workflow file is typically `.github/workflows/publish.yml`.
+      It runs `npm publish` with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
+
+  local_verification:
+    before_release:
+      - run_tests         # npm test / vitest
+      - verify_build      # npm run build (if applicable)
+      - check_version     # confirm package.json version matches intended tag
+    note: All local gates must pass before `gh release create`
+
+comparison_with_manual_mode:
+  publish_command: "not run locally"    # manual: npm publish
+  publish_trigger: gh_release_create   # manual: direct npm publish
+  npm_token_location: github_secret    # manual: local .npmrc or env var
+  audit_trail: github_actions_log      # manual: none (local terminal)
+  reproducibility: full_ci_isolation   # manual: depends on local environment

package/bundled/ai/standards/agent-behavior-discipline.ai.yaml

@@ -0,0 +1,142 @@
+# Agent Behavior Discipline Standards - AI Optimized
+# Source: core/agent-behavior-discipline.md
+# Inspired by: Karpathy X post 2026-01 + andrej-karpathy-skills CLAUDE.md (MIT)
+
+id: agent-behavior-discipline
+meta:
+  version: "1.0.0"
+  updated: "2026-04-24"
+  source: core/agent-behavior-discipline.md
+  description: Four behavioral disciplines for AI agents to elevate from functional to excellent — Ask, Simple, Precision, Test
+  related:
+    - anti-hallucination
+    - anti-sycophancy-prompting
+    - test-driven-development
+    - change-batching-standards
+
+principles:
+  ask:
+    summary: Surface assumptions before executing, not after
+    rule: Before any non-trivial task, explicitly state assumptions and wait for confirmation
+    triggers:
+      - Task has ambiguous requirements or multiple valid interpretations
+      - Confidence score < 0.7 (see epistemic-calibration)
+      - Task involves architecture changes, refactors, or multi-file modifications
+    do:
+      - State all assumptions explicitly before starting
+      - Present multiple interpretations when the prompt is ambiguous
+      - Propose simpler alternatives and challenge requests when appropriate
+      - Name confusion explicitly instead of proceeding with a guess
+      - Push back when a simpler path exists
+    do_not:
+      - Assume silently and proceed
+      - Use "I understand you want..." phrasing to paper over ambiguity
+      - Start executing to demonstrate effort before confirming direction
+    disclosure_format: |
+      My assumptions: [list]
+      Approach considered: [A] vs [B] — choosing A because [reason]
+      If my understanding is incorrect, please redirect before I proceed.
+
+  simple:
+    summary: Minimum code that solves the problem, nothing speculative
+    rule: Solve with the least code required. Never add unrequested functionality.
+    triggers:
+      - Any code generation task
+    do:
+      - Write only what the task requires
+      - Rewrite if the solution could be significantly shorter without loss of clarity
+      - Inline logic that is only used once (no premature abstraction)
+    do_not:
+      - Add features "that might be needed later"
+      - Create single-use abstractions or helper classes
+      - Add speculative flexibility or configuration hooks nobody asked for
+      - Add error handling for scenarios that cannot happen
+    three_strikes_rule: Abstract only when the same logic appears 3+ times (DRY threshold)
+
+  precision:
+    summary: Touch only what the task requires — clean up only your own mess
+    rule: Scope modifications to the minimum set of files and lines required
+    triggers:
+      - Any edit or refactor task
+    do:
+      - Declare scope before editing ("I will modify: X. I will not touch: Y.")
+      - Match the local code style rather than enforcing personal preferences
+      - Flag pre-existing issues found out-of-scope with a verbal note only
+    do_not:
+      - Improve unrelated code, formatting, or comments while on a scoped task
+      - Remove pre-existing dead code outside task scope
+      - Rename symbols not involved in the current change
+      - Remove imports or variables orphaned by someone else's previous change
+    scope_declaration_format: |
+      Modifying: [file list]
+      Not touching: [related but out-of-scope areas]
+      Out-of-scope observation (action deferred): [optional]
+
+  test:
+    summary: Define verifiable success criteria before executing; loop until verified
+    rule: Transform every task into a measurable success criterion before implementation
+    triggers:
+      - Any implementation or bug-fix task
+      - Long-running autonomous agent loops
+    do:
+      - Ask for or define quantifiable success criteria before starting
+      - Write a failing test first (TDD red phase), then implement, then refactor
+      - State multi-step plans with explicit verification checkpoints
+      - Loop autonomously toward the verified goal, recording each iteration's failureSource
+    do_not:
+      - Accept subjective criteria ("make it better", "improve search quality")
+      - Proceed without a stopping condition for autonomous loops
+      - Report completion without demonstrating the success criterion was met
+    vague_criteria_escalation: |
+      If the task uses subjective success language, ask:
+      "What specific metric or observable outcome defines success here?"
+    loop_protocol:
+      max_retries: 5
+      on_stuck: escalate to human with failureSource summary
+      record: failureSource per iteration (see failure-source-taxonomy)
+
+prohibited_behaviors:
+  - id: silent-assumption
+    description: Do NOT make assumptions about ambiguous requirements without stating them
+    correct_action: Use ask.disclosure_format before proceeding
+
+  - id: speculative-feature
+    description: Do NOT implement features that were not explicitly requested
+    correct_action: Implement only the requested scope; mention potential extensions verbally
+
+  - id: scope-creep
+    description: Do NOT modify code outside the declared scope of the task
+    correct_action: Use precision.scope_declaration_format and flag out-of-scope observations verbally
+
+  - id: subjective-success
+    description: Do NOT accept vague success criteria ("better", "improved", "successful")
+    correct_action: Use test.vague_criteria_escalation to obtain a quantifiable criterion
+
+  - id: open-ended-loop
+    description: Do NOT run autonomous correction loops without a defined stopping condition
+    correct_action: Define max_retries and escalation path before starting the loop
+
+agent_application:
+  implementation_tasks:
+    apply: [ask, simple, precision, test]
+    notes: All four principles apply to every non-trivial implementation task
+  refactoring_tasks:
+    apply: [ask, precision, test]
+    notes: Simplicity is a refactor outcome, not a separate check; Precision is critical
+  bug_fix_tasks:
+    apply: [ask, precision, test]
+    notes: Ask to confirm reproduction steps; Precision to avoid scope creep; Test to define "fixed"
+  autonomous_loops:
+    apply: [test]
+    notes: test.loop_protocol is mandatory for any multi-iteration autonomous agent task
+  trivial_tasks:
+    apply: []
+    threshold: confidence >= 0.9 AND task is single-file AND lines_changed < 5
+    notes: Trivial tasks (e.g., adding a comment) may skip ask confirmation
+
+checklist:
+  - Assumptions stated before execution starts
+  - Code solves the problem with minimum required lines
+  - Only declared-scope files were modified
+  - Success criterion is quantifiable and verified
+  - Autonomous loops have max_retries and escalation path defined

package/bundled/ai/standards/cd-deployment-strategies.ai.yaml

@@ -0,0 +1,73 @@
+# CD Deployment Strategies (AI-Optimized v1)
+# Source: core/cd-deployment-strategies.md
+
+standard:
+  id: cd-deployment-strategies
+  name: CD Deployment Strategies
+  description: Strategy selection matrix for blue-green, canary, rolling, and recreate deployments
+  guidelines:
+    - "Choose strategy based on: traffic volume × risk tolerance × infrastructure cost"
+    - "High traffic + low risk tolerance → blue-green (instant rollback)"
+    - "Medium traffic + medium risk → canary (progressive validation)"
+    - "Low traffic + low risk → rolling (resource efficient)"
+    - "Dev/internal only → recreate (simplest, acceptable downtime)"
+    - "Never deploy directly to production without staging validation"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-26"
+    source: core/cd-deployment-strategies.md
+    parent: deployment-standards.ai.yaml
+
+strategy_matrix:
+  blue_green:
+    traffic: high
+    risk_tolerance: low
+    infrastructure_cost: high
+    downtime: zero
+    rollback_time: "<30s"
+    use_cases: ["stateful services", "database-compatible changes", "high-SLA APIs"]
+    prerequisites: ["dual environment", "load balancer", "health checks"]
+  canary:
+    traffic: medium_to_high
+    risk_tolerance: medium
+    infrastructure_cost: medium
+    downtime: zero
+    rollback_time: "<2min"
+    use_cases: ["feature validation", "A/B testing", "high-risk changes"]
+    traffic_stages: ["1%", "5%", "25%", "50%", "100%"]
+    prerequisites: ["traffic splitting", "observability", "auto-promotion rules"]
+  rolling:
+    traffic: any
+    risk_tolerance: medium
+    infrastructure_cost: low
+    downtime: minimal
+    rollback_time: "minutes"
+    use_cases: ["stateless services", "standard updates", "batch workers"]
+    prerequisites: ["multiple instances", "health checks"]
+  recreate:
+    traffic: low
+    risk_tolerance: high
+    infrastructure_cost: minimal
+    downtime: "seconds to minutes"
+    rollback_time: "minutes"
+    use_cases: ["dev/staging", "internal tools", "single-instance services"]
+    prerequisites: ["none"]
+
+decision_tree:
+  step_1: "Is zero-downtime required? No → recreate; Yes → continue"
+  step_2: "Is traffic > 10k req/min? Yes → blue-green or canary; No → rolling"
+  step_3: "Is change high-risk? Yes → canary; No → blue-green or rolling"
+  step_4: "Is infrastructure budget constrained? Yes → rolling; No → blue-green"
+
+no_cicd_compatibility:
+  blue_green: "See no-cicd-deployment.ai.yaml for script-based implementation"
+  canary: "Requires Nginx split_clients or HAProxy for script-based canary"
+  rolling: "Achievable with sequential rsync + health check loop"
+  recreate: "Simplest — stop, deploy, start"
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: "grep -r 'deployment_strategy\\|deploy.*strategy' . --include='*.yaml' --include='*.json' -l 2>/dev/null | head -1"
+    rule: "deployment_strategy_documented"

package/bundled/ai/standards/no-cicd-deployment.ai.yaml

@@ -0,0 +1,134 @@
+# No-CI/CD Deployment Strategy (AI-Optimized v1)
+# Source: core/no-cicd-deployment.md
+
+standard:
+  id: no-cicd-deployment
+  name: No-CI/CD Deployment Strategy
+  description: Reliable deployment without CI/CD platforms using shell scripts, smoke tests, Blue-Green switching, and deploy.lock protection
+  guidelines:
+    - "Use set -euo pipefail in all deploy scripts — fail fast, stop on first error"
+    - "Always verify deployment after completion — check version endpoint, never assume success"
+    - "Maintain Blue-Green slots for instant rollback — recovery time must be <30 seconds"
+    - "Enforce deploy.lock to prevent concurrent deployments"
+    - "Only deploy commits with semantic version tags — no untagged HEAD deployments"
+    - "Log every deployment with timestamp, version, operator, and result (JSON Lines)"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-26"
+    source: core/no-cicd-deployment.md
+    description: Reliable deployment strategy for environments without CI/CD platforms
+    complements: deployment-standards.ai.yaml
+
+  principles:
+    core:
+      - fail_fast: "set -euo pipefail stops execution at first failure — no silent partial deploys"
+      - verify_always: "Post-deploy smoke test is mandatory, not optional"
+      - instant_recovery: "Blue-Green rollback must complete in <30 seconds"
+      - concurrent_protection: "deploy.lock prevents race conditions from simultaneous deployments"
+      - version_discipline: "Only semver-tagged commits are deployable"
+      - audit_trail: "Every deploy produces a machine-readable log entry"
+
+  architecture:
+    three_layer:
+      layer_1_prevent:
+        name: "Prevent Wrong Deployments"
+        mechanisms:
+          - "set -euo pipefail in deploy.sh"
+          - "Mandatory test pass before deploy"
+          - "Semver tag enforcement"
+          - "deploy.lock concurrency guard"
+      layer_2_verify:
+        name: "Verify Deployment Correctness"
+        mechanisms:
+          - "HTTP /health endpoint check"
+          - "Version number comparison with VERSION file"
+          - "Auto-rollback on verification failure"
+      layer_3_recover:
+        name: "Fast Recovery Capability"
+        mechanisms:
+          - "Blue-Green slot switching"
+          - "Nginx upstream pointer swap"
+          - "Single-command rollback.sh"
+
+  deploy_script:
+    required_header: "#!/usr/bin/env bash\nset -euo pipefail"
+    mandatory_steps:
+      - step: test
+        order: 1
+        description: "Run full test suite before any deployment"
+      - step: build
+        order: 2
+        description: "Produce deployment artifact"
+      - step: deploy
+        order: 3
+        description: "Transfer artifact to target server"
+      - step: verify
+        order: 4
+        description: "Run smoke test; auto-rollback on failure"
+    lock_pattern:
+      file: "/tmp/deploy.lock"
+      create: "echo $$ > $LOCK_FILE"
+      cleanup: "trap 'rm -f $LOCK_FILE' EXIT"
+      check: "[ -f $LOCK_FILE ] && echo 'Deploy in progress' && exit 1"
+    version_enforcement:
+      command: "git describe --exact-match --tags HEAD"
+      format: "v[0-9]+\\.[0-9]+\\.[0-9]+"
+      failure_message: "No semver tag on HEAD — tag before deploying"
+
+  smoke_test:
+    endpoint: "/health"
+    required_fields:
+      - field: "version"
+        source: "VERSION file"
+        comparison: "exact match"
+      - field: "status"
+        expected: "ok"
+    failure_action: "auto_rollback"
+    timeout_seconds: 30
+
+  blue_green:
+    slots:
+      - name: blue
+        port: 3001
+        state: "active (stable)"
+      - name: green
+        port: 3002
+        state: "inactive (staging)"
+    switch_mechanism: "nginx upstream pointer"
+    rollback_time_sla: "30 seconds"
+    rollback_command: "./rollback.sh"
+
+  deployment_log:
+    format: "JSON Lines"
+    required_fields:
+      - "timestamp (ISO 8601)"
+      - "version"
+      - "git_commit"
+      - "operator (whoami)"
+      - "result (success|failure)"
+      - "duration_seconds"
+    location: "/var/log/deployments.jsonl"
+
+  checklist:
+    pre_deploy:
+      - "Tests pass"
+      - "Artifact built successfully"
+      - "No deploy.lock present"
+      - "HEAD has semver tag"
+      - "Previous deployment log reviewed"
+    post_deploy:
+      - "Health check HTTP 200"
+      - "Version matches expected"
+      - "Service responds to basic requests"
+      - "Deployment log entry written"
+    rollback_readiness:
+      - "Blue slot running previous stable version"
+      - "rollback.sh tested and functional"
+      - "Nginx upstream reload works"
+
+  physical_spec:
+    type: custom_script
+    validator:
+      command: "test -f deploy.sh && grep -q 'set -euo pipefail' deploy.sh && test -f rollback.sh && test -f verify.sh"
+      rule: "no_cicd_deployment_scripts_configured"

package/bundled/ai/standards/pipeline-security-gates.ai.yaml

@@ -0,0 +1,71 @@
+# Pipeline Security Gates (AI-Optimized v1)
+# Source: core/pipeline-security-gates.md
+
+standard:
+  id: pipeline-security-gates
+  name: Pipeline Security Gates
+  description: Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior
+  guidelines:
+    - "Secrets scan at pre-commit — block ALL commits containing secrets"
+    - "SAST after build — block Critical/High findings"
+    - "SCA + SBOM generation at package stage"
+    - "DAST after staging deploy — warn on findings, require approval for Critical"
+    - "Never skip security gates with --force or emergency bypass without audit trail"
+    - "Treat security gate failures as pipeline failures, not warnings"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-26"
+    source: core/pipeline-security-gates.md
+    complements: security-standards.ai.yaml
+
+gate_positions:
+  pre_commit:
+    type: secrets_scan
+    tools: ["gitleaks", "trufflehog", "detect-secrets"]
+    scope: "staged files"
+    block_on: ["any secret pattern match"]
+    never_skip: true
+  post_build:
+    type: sast
+    tools: ["semgrep", "codeql", "sonarqube"]
+    scope: "source code + build output"
+    block_on: ["Critical", "High"]
+    warn_on: ["Medium"]
+    log_only: ["Low", "Info"]
+  post_staging_deploy:
+    type: dast
+    tools: ["zap", "nuclei", "burpsuite-enterprise"]
+    scope: "running staging application"
+    block_on: ["Critical"]
+    require_approval: ["High"]
+    warn_on: ["Medium"]
+  package_stage:
+    type: sca_and_sbom
+    tools: ["trivy", "syft", "grype", "dependabot"]
+    scope: "dependencies + container image"
+    block_on: ["Critical CVE with fix available"]
+    warn_on: ["High CVE", "outdated dependencies"]
+    sbom_format: ["spdx", "cyclonedx"]
+
+bypass_policy:
+  allowed: false
+  exception_process: "written security approval + audit log entry"
+  emergency_bypass: "time-limited token + mandatory post-incident review"
+
+failure_behavior:
+  Critical: {action: "block pipeline", notify: "security-team", sla: "immediate"}
+  High: {action: "block pipeline", notify: "team-lead", sla: "same-day"}
+  Medium: {action: "warn + require approval", notify: "developer", sla: "next-sprint"}
+  Low: {action: "log only", notify: "none", sla: "backlog"}
+
+integration_points:
+  secrets_vault: "Integrate with HashiCorp Vault or AWS Secrets Manager for secrets injection"
+  sbom_registry: "Upload SBOM to dependency-track or grype-db for continuous monitoring"
+  incident_response: "Critical findings automatically create incident tickets"
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: "grep -r 'secrets\\|sast\\|sca\\|dast' .github/workflows/ .gitlab-ci.yml Jenkinsfile 2>/dev/null | head -1 || echo 'no-ci-pipeline'"
+    rule: "security_gates_in_pipeline"