universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/ai/standards/change-batching-standards.ai.yaml

@@ -0,0 +1,195 @@
+# Change Batching Standards - AI Optimized
+# Source: core/change-batching-standards.md
+
+standard:
+  id: change-batching-standards
+  name: Change Batching Standards
+  description: Pending changes state machine, threshold strategies, and atomicity guarantees for batch commits
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-18"
+    source: core/change-batching-standards.md
+    references:
+      - "SWEBOK v4.0 Chapter 6 (Software Configuration Management)"
+      - "ISO/IEC 12207 (Configuration Management Process)"
+      - "Continuous Delivery (Jez Humble) — Small batch sizes"
+      - "Lean Software Development — Batch size optimization"
+
+  state_machine:
+    description: Pending changes lifecycle
+    states:
+      - state: PENDING
+        description: Change recorded, waiting for threshold
+      - state: READY
+        description: Threshold met, batch prepared for merge
+      - state: MERGED
+        description: Batch successfully committed
+      - state: FAILED
+        description: Merge attempt failed
+      - state: ARCHIVED
+        description: Post-commit record for audit
+
+    transitions:
+      - from: PENDING
+        to: PENDING
+        trigger: New change added
+        action: Increment counters, re-evaluate thresholds
+      - from: PENDING
+        to: READY
+        trigger: Threshold met
+        action: Prepare merge batch, run pre-merge validation
+      - from: READY
+        to: MERGED
+        trigger: Merge succeeds
+        action: Create commit, clear batch, archive
+      - from: READY
+        to: FAILED
+        trigger: Merge fails
+        action: Log failure, preserve changes
+      - from: FAILED
+        to: PENDING
+        trigger: Reset
+        action: Re-queue changes, clear failure state
+      - from: MERGED
+        to: ARCHIVED
+        trigger: Post-commit
+        action: Record batch metadata for audit
+
+  threshold_strategies:
+    strategies:
+      - name: count
+        parameter: maxChanges
+        default: 5
+        description: Merge after N individual changes accumulated
+
+      - name: score
+        parameter: maxScore
+        default: 10
+        description: Merge when cumulative change score >= M
+
+      - name: time
+        parameter: maxAge
+        default: "30m"
+        description: Merge when oldest pending change exceeds TTL
+
+      - name: manual
+        parameter: null
+        default: null
+        description: Merge only on explicit user request
+
+    change_scoring:
+      - type: trivial
+        score: 1
+        example: Typo fix, whitespace, comment update
+      - type: minor
+        score: 2
+        example: Single function change, variable rename
+      - type: standard
+        score: 3
+        example: New function, modified logic flow
+      - type: complex
+        score: 5
+        example: Multi-file change, API modification
+      - type: critical
+        score: 8
+        example: Schema change, breaking change
+
+    composite_rule: "Multiple thresholds combine with OR logic (first met triggers merge)"
+
+  merge_rules:
+    priority_order:
+      - Same-spec affinity — changes referencing same SPEC-ID merge first
+      - Same-file grouping — changes to same files merge together
+      - Dependency order — changes with dependencies merge in order
+      - Chronological — within same priority, merge by creation time
+
+    conflict_resolution:
+      - type: Same line, same file
+        strategy: Latest change wins
+        fallback: Manual resolution
+      - type: Overlapping functions
+        strategy: Semantic merge if possible
+        fallback: Manual resolution
+      - type: Dependency conflict
+        strategy: Resolve dependency first
+        fallback: Reject batch, split
+
+    pre_merge_validation:
+      - check: All tests pass
+        required: true
+      - check: No lint errors
+        required: true
+      - check: No conflicts
+        required: true
+      - check: AC coverage maintained
+        required: false
+        note: Recommended
+
+  atomicity:
+    principle: All-or-nothing
+    rules:
+      - Single commit — each merged batch produces exactly one commit
+      - No partial merge — any change failure rejects entire batch
+      - Rollback support — failed merges restore all changes to PENDING
+      - Isolation — batch merge does not affect changes outside batch
+
+  rollback:
+    on_failure:
+      - Log failure with batch details
+      - Return all changes to PENDING state
+      - Diagnose failing change(s)
+      - Options — fix and retry, remove failing change, split batch
+
+    triggers:
+      - trigger: Test failure
+        action: Reject entire batch
+        automatic: true
+      - trigger: Lint error
+        action: Reject entire batch
+        automatic: true
+      - trigger: Merge conflict
+        action: Reject and notify
+        automatic: true
+      - trigger: Build failure
+        action: Reject entire batch
+        automatic: true
+      - trigger: Manual rejection
+        action: Return to PENDING
+        automatic: false
+
+  rules:
+    - id: set-thresholds
+      trigger: configuring batch pipeline
+      instruction: Set explicit thresholds; do not accumulate changes indefinitely
+      priority: required
+
+    - id: group-by-spec
+      trigger: batching changes
+      instruction: Group changes by specification or feature for cohesive commits
+      priority: recommended
+
+    - id: validate-before-merge
+      trigger: batch reaches READY state
+      instruction: Run full validation (tests, lint, conflicts) before merging
+      priority: required
+
+    - id: atomic-commits
+      trigger: merging a batch
+      instruction: Enforce all-or-nothing — either all changes commit or none do
+      priority: required
+
+    - id: preserve-on-failure
+      trigger: batch merge fails
+      instruction: Return all changes to PENDING state; never lose changes
+      priority: required
+
+    - id: log-batch-decisions
+      trigger: any batch state transition
+      instruction: Log batch decisions (threshold met, merge result) for auditability
+      priority: recommended
+
+related_standards:
+  - checkin-standards.md
+  - pipeline-integration-standards.md
+  - commit-message-guide.md

package/bundled/ai/standards/database-standards.ai.yaml

@@ -0,0 +1,220 @@
+# Database Standards - AI Optimized
+# Source: core/database-standards.md
+
+standard:
+  id: database
+  name: Database Standards
+  description: Schema design, indexing, migrations, query optimization, transactions, and data integrity
+  guidelines:
+    - "Data integrity enforced at database level, not only application code"
+    - "Schema as code: version-controlled, reproducible migrations"
+    - "Measure before tuning: use EXPLAIN plans before optimizing"
+    - "Backward-compatible schema changes during deployment windows"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-18"
+    source: core/database-standards.md
+    description: Schema design, indexing, migrations, query optimization, transactions, and data integrity
+
+  principles:
+    core:
+      - data_integrity_first: "Constraints and referential integrity at DB level"
+      - schema_as_code: "Version-controlled, reproducible migration scripts"
+      - least_privilege: "Minimum permissions for each database account"
+      - measure_before_tuning: "EXPLAIN plans and metrics before optimizing"
+      - defense_in_depth: "Encryption, masking, access controls at multiple layers"
+      - backward_compatibility: "Schema changes maintain compat during deployments"
+
+schema_design:
+  naming:
+    tables: "snake_case, singular (user_account, order_item)"
+    columns: "snake_case (first_name, created_at)"
+    primary_keys: "id"
+    foreign_keys: "<referenced_table>_id"
+    booleans: "is_ or has_ prefix (is_active, has_verified_email)"
+    timestamps: "_at suffix (created_at, updated_at, deleted_at)"
+    indexes: "idx_<table>_<columns>"
+    unique_constraints: "uq_<table>_<columns>"
+  normalization:
+    target: "3NF for transactional systems"
+    1NF: "Atomic values only, no repeating groups"
+    2NF: "1NF + no partial dependencies on composite keys"
+    3NF: "2NF + no transitive dependencies"
+  denormalization:
+    when_to_use:
+      - "Read-heavy workloads (>90% reads)"
+      - "Eventual consistency acceptable"
+      - "Joins cause unacceptable latency"
+    requirements:
+      - "Document source of truth and sync mechanism"
+      - "Implement consistency checks"
+  data_types:
+    monetary: "DECIMAL(19,4) or NUMERIC — never FLOAT/DOUBLE"
+    timestamps: "TIMESTAMPTZ (with timezone)"
+    booleans: "BOOLEAN — not INT(0/1) or CHAR('Y'/'N')"
+    json: "JSONB (PostgreSQL) or native JSON — not TEXT"
+  uuid_vs_auto_increment:
+    auto_increment: "Internal-only IDs, single-database systems"
+    uuid: "Distributed systems, publicly exposed IDs, UUIDv7 preferred"
+
+indexing:
+  create_when:
+    - "Column in frequent WHERE clauses"
+    - "Column used in JOIN conditions"
+    - "Column used in ORDER BY or GROUP BY"
+    - "Unique constraint needed"
+  avoid_when:
+    - "Table < 1,000 rows"
+    - "Very low cardinality column"
+    - "Write-heavy table with rare reads"
+    - "Already > 8 indexes per table"
+  composite_order: "equality first → IN next → range last → ORDER BY last"
+  covering_indexes: "Include all query columns to enable index-only scans"
+  partial_indexes: "Index subset of rows to reduce size (WHERE clause on CREATE INDEX)"
+  anti_patterns:
+    - "Over-indexing: slows writes, audit quarterly"
+    - "Unused indexes: monitor pg_stat_user_indexes"
+    - "Duplicate indexes: (a,b) covers queries on (a)"
+    - "Function on indexed column: use expression index"
+    - "Missing FK index: always index foreign key columns"
+
+migration:
+  naming: "YYYYMMDDHHMMSS_description.sql"
+  principles:
+    - "Version-controlled alongside application code"
+    - "Sequential, deterministic execution order"
+    - "Idempotent: running twice produces same result"
+    - "Tested against production-like data volumes"
+  zero_downtime:
+    pattern: "Expand-Contract"
+    phase_1: "Expand — add nullable column, no constraints"
+    phase_2: "Migrate — backfill data, dual-write"
+    phase_3: "Contract — add constraints, drop old column"
+  rollback:
+    reversible: "Use for non-destructive changes (add column, add index)"
+    forward_only: "Use for destructive changes (drop column, drop table)"
+    critical_rule: "Never drop columns in same deployment that stops writing"
+
+query_practices:
+  n_plus_1: "Use JOINs or batch loading instead of per-row queries"
+  explain_plan: "EXPLAIN ANALYZE for queries > 100ms or > 100 calls/min"
+  pagination:
+    offset: "Simple, supports random access — avoid for large datasets"
+    keyset: "Consistent performance — preferred for APIs and large datasets"
+  anti_patterns:
+    - "SELECT * — list specific columns"
+    - "String concatenation — use parameterized queries"
+    - "NOT IN with NULLs — use NOT EXISTS"
+    - "LIKE '%prefix' — use full-text search"
+    - "Implicit type casting — cast explicitly"
+
+transactions:
+  acid:
+    atomicity: "All operations succeed or all fail"
+    consistency: "DB moves from one valid state to another"
+    isolation: "Concurrent transactions don't interfere"
+    durability: "Committed data survives system failure"
+  isolation_levels:
+    read_uncommitted: {dirty_read: possible, use_case: "Never recommended"}
+    read_committed: {dirty_read: prevented, use_case: "Default; general-purpose"}
+    repeatable_read: {dirty_read: prevented, phantom: possible, use_case: "Financial reports"}
+    serializable: {dirty_read: prevented, phantom: prevented, use_case: "Money transfers, bookings"}
+  default_level: "Read Committed"
+  deadlock_prevention:
+    - "Consistent lock ordering across transactions"
+    - "Keep transactions short"
+    - "Set lock_timeout to fail fast"
+    - "Implement retry with exponential backoff"
+  locking:
+    optimistic: "Version column check — low-conflict environments"
+    pessimistic: "SELECT FOR UPDATE — high-conflict environments"
+
+nosql_decision:
+  relational: "Structured data, complex joins, ACID — PostgreSQL, MySQL"
+  document: "Semi-structured, flexible schema — MongoDB, CouchDB"
+  key_value: "Simple lookups, caching, sessions — Redis, Memcached"
+  graph: "Relationship traversals — Neo4j, Amazon Neptune"
+  polyglot: "Use multiple database types for different workloads"
+
+connection_management:
+  pooling: required
+  defaults:
+    min_pool: "2-5"
+    max_pool: "10-20"
+    connection_timeout: "5 seconds"
+    idle_timeout: "10 minutes"
+    max_lifetime: "30 minutes"
+  formula: "pool_size = (core_count * 2) + effective_spindle_count"
+  warning: "More connections is NOT better — causes contention"
+
+sensitive_data:
+  classification:
+    public: "No special handling"
+    internal: "Access control"
+    confidential: "Encryption at rest, access logging"
+    restricted: "Column encryption, masking, strict audit"
+  pii_requirements:
+    - "Encrypt PII at rest and in transit"
+    - "Mask data in non-production environments"
+    - "Define retention policies"
+    - "Support GDPR data subject requests"
+    - "Log all PII access"
+  audit_logging: "Trigger-based audit log with old/new values, user, timestamp"
+
+backup:
+  strategies:
+    full: "Complete copy — slowest backup, fastest restore"
+    incremental: "Changes since last backup — fastest backup, slowest restore"
+    differential: "Changes since last full — medium speed"
+  rpo_rto:
+    critical: {rpo: "<1 min", rto: "<15 min", strategy: "Sync replication + WAL"}
+    important: {rpo: "<1 hour", rto: "<1 hour", strategy: "Streaming replication + hourly WAL"}
+    standard: {rpo: "<24 hours", rto: "<4 hours", strategy: "Daily full + hourly incremental"}
+  testing: "Restore test monthly, verify integrity, measure actual RTO"
+
+rules:
+  - id: DB-SCHEMA-001
+    rule: "Enforce data constraints at database level, not only in application code"
+    severity: error
+  - id: DB-INDEX-001
+    rule: "Always index foreign key columns"
+    severity: error
+  - id: DB-QUERY-001
+    rule: "Use parameterized queries; never concatenate user input into SQL"
+    severity: error
+  - id: DB-QUERY-002
+    rule: "Use EXPLAIN ANALYZE for queries with execution time > 100ms"
+    severity: warning
+  - id: DB-MIGRATION-001
+    rule: "All schema changes via version-controlled migration scripts"
+    severity: error
+  - id: DB-MIGRATION-002
+    rule: "Use expand-contract pattern for zero-downtime schema changes"
+    severity: warning
+  - id: DB-CONN-001
+    rule: "Always use connection pooling; never create per-request connections"
+    severity: error
+  - id: DB-DATA-001
+    rule: "Encrypt PII at rest and in transit; log all PII access"
+    severity: error
+
+quick_reference:
+  schema:
+    - "snake_case for all identifiers"
+    - "Singular table names"
+    - "_id suffix for foreign keys"
+    - "Always have id, created_at, updated_at"
+    - "Normalize to 3NF, denormalize with documented reasoning"
+  queries:
+    - "Parameterized queries always"
+    - "List specific columns, not SELECT *"
+    - "EXPLAIN ANALYZE before optimizing"
+    - "Keyset pagination for large datasets"
+    - "Batch operations to prevent N+1"
+  operations:
+    - "Connection pooling required"
+    - "Version-control all migrations"
+    - "Test migrations with production-like data"
+    - "Monitor slow queries, connections, cache hit ratio"
+    - "Test backup restoration monthly"

package/bundled/ai/standards/error-codes.ai.yaml

@@ -3,8 +3,8 @@
 
 id: error-codes
 meta:
-  version: "1.1.0"
-  updated: "2026-01-05"
+  version: "1.2.0"
+  updated: "2026-03-18"
   source: core/error-code-standards.md
   description: Error code format, categories, and management
 
@@ -121,6 +121,41 @@ rules:
     instruction: Maintain centralized error code registry
     priority: recommended
 
+  - id: rfc7807-format
+    trigger: designing HTTP API error responses
+    instruction: |
+      Use RFC 7807 Problem Details format:
+      Required: type, title, status, detail, instance
+      Extension: code, errors[], requestId, timestamp
+    priority: recommended
+
+  - id: graphql-errors
+    trigger: handling GraphQL errors
+    instruction: |
+      Map error codes to extensions field:
+      - extensions.code: Application error code
+      - extensions.category: VALIDATION/BUSINESS_RULE/AUTHENTICATION/AUTHORIZATION/INTERNAL
+    priority: recommended
+
+  - id: grpc-mapping
+    trigger: handling gRPC errors
+    instruction: |
+      Map categories to gRPC status:
+      - VAL → INVALID_ARGUMENT (3)
+      - BIZ → FAILED_PRECONDITION (9)
+      - AUTH → UNAUTHENTICATED (16) / PERMISSION_DENIED (7)
+      - SYS → INTERNAL (13)
+      - NET → UNAVAILABLE (14)
+    priority: recommended
+
+  - id: retry-guidance
+    trigger: defining error retry behavior
+    instruction: |
+      Retryable: NET, AUTH token errors (200-299), SYS (maybe)
+      Not retryable: VAL, BIZ, AUTH credentials (001-099)
+      Use Idempotency-Key for non-idempotent POST operations
+    priority: recommended
+
 quick_reference:
   categories:
     columns: [Code, Category, HTTP, Use For]

package/bundled/ai/standards/git-worktree.ai.yaml

@@ -0,0 +1,77 @@
+# Git Worktree Isolation - AI Optimized
+# Source: core/git-worktree.md
+# Inspired by Superpowers using-git-worktrees (MIT)
+
+standard:
+  id: git-worktree
+  name: Git Worktree Isolation
+  description: Git Worktree 隔離開發標準
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/git-worktree.md
+    description: Git Worktree 隔離開發與生命週期管理標準
+    inspired_by: superpowers/using-git-worktrees
+
+  guidelines:
+    - "worktree 目錄必須在 .gitignore 中"
+    - "建立後跑基準測試確認環境乾淨"
+    - "完成後先合併再清理"
+    - "異常退出時確保 cleanup 被執行"
+
+  lifecycle:
+    - phase: setup
+      steps:
+        - "選擇 worktree 目錄位置（優先順序：existing → .devap/worktrees → 詢問使用者）"
+        - "執行 git check-ignore 確認目錄被忽略"
+        - "建立 worktree + 新分支"
+        - "安裝依賴（若需要）"
+    - phase: baseline
+      steps:
+        - "在 worktree 中跑基準測試"
+        - "確認測試全過（環境乾淨）"
+        - "若測試失敗，中止並報告"
+    - phase: execute
+      steps:
+        - "在隔離的 worktree 中執行任務"
+        - "任務完成後驗證"
+    - phase: merge
+      steps:
+        - "確認所有測試通過"
+        - "合併分支回主分支（--no-ff）"
+        - "處理可能的合併衝突"
+    - phase: cleanup
+      steps:
+        - "移除 worktree（git worktree remove）"
+        - "刪除分支（git branch -d）"
+        - "prune 殘留 worktree（git worktree prune）"
+
+  rules:
+    - id: GW-001
+      trigger: "worktree 目錄不在 .gitignore 中"
+      action: "自動加入 .gitignore"
+      priority: critical
+    - id: GW-002
+      trigger: "基準測試失敗"
+      action: "中止任務，報告環境問題"
+      priority: high
+    - id: GW-003
+      trigger: "異常退出"
+      action: "確保 cleanup 被執行"
+      priority: high
+    - id: GW-004
+      trigger: "合併/刪除後殘留 worktree"
+      action: "prune 殘留 worktree 引用"
+      priority: medium
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查 worktree 使用是否遵循完整生命週期：setup → baseline → execute → merge → cleanup"
+  checks:
+    - "worktree 目錄是否在 .gitignore 中"
+    - "是否執行基準測試確認環境乾淨"
+    - "完成後是否執行 cleanup"
+    - "異常退出時是否有 cleanup 機制"

package/bundled/ai/standards/logging.ai.yaml

@@ -3,8 +3,8 @@
 
 id: logging
 meta:
-  version: "1.1.0"
-  updated: "2026-01-05"
+  version: "1.2.0"
+  updated: "2026-03-18"
   source: core/logging-standards.md
   description: Logging levels, structured logging, and best practices
 
@@ -100,6 +100,25 @@ rules:
     instruction: Use async/buffered logging for performance
     priority: recommended
 
+  - id: distributed-tracing
+    trigger: logging in distributed systems
+    instruction: |
+      Include OpenTelemetry trace context:
+      - trace_id and span_id in every log entry
+      - W3C Trace Context propagation (traceparent header)
+      - Correlate logs with metrics and traces
+    priority: recommended
+
+  - id: observability-pillars
+    trigger: designing observability strategy
+    instruction: |
+      Three pillars: Logs, Metrics, Traces
+      - Logs: Discrete events with context
+      - Metrics: Aggregated measurements (counters, gauges, histograms)
+      - Traces: Request flow across services
+      Correlate all three via trace_id/span_id
+    priority: recommended
+
 quick_reference:
   level_selection:
     columns: [Question, Level]

package/bundled/ai/standards/model-selection.ai.yaml

@@ -0,0 +1,81 @@
+# AI Model Selection Strategy - AI Optimized
+# Source: core/model-selection.md
+# Inspired by Superpowers subagent-driven-development model selection (MIT)
+
+standard:
+  id: model-selection
+  name: AI Model Selection Strategy
+  description: AI 模型分級選擇策略
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/model-selection.md
+    description: 三層模型分級選擇標準
+    inspired_by: superpowers/subagent-driven-development
+
+  guidelines:
+    - "使用最便宜能勝任的模型（成本效益原則）"
+    - "根據任務複雜度信號選擇模型等級"
+    - "BLOCKED 狀態時考慮升級模型再試"
+
+  tiers:
+    - id: fast
+      description: "機械性實作 — 單一檔案、明確 spec、無需判斷"
+      signals:
+        - "修改單一檔案"
+        - "spec 完全明確，無歧義"
+        - "不需要設計判斷"
+        - "模式化的重複工作"
+      examples:
+        - "更新 package.json 版本號"
+        - "新增一個 export"
+        - "修正 typo"
+    - id: standard
+      description: "整合性實作 — 多檔案、需要判斷力"
+      signals:
+        - "修改 2-5 個檔案"
+        - "需要理解模組間關係"
+        - "需要一定設計判斷"
+      examples:
+        - "新增一個 API endpoint（含 route + handler + test）"
+        - "重構一個模組的內部結構"
+    - id: capable
+      description: "架構性工作 — 設計、審查、除錯"
+      signals:
+        - "修改 5+ 個檔案"
+        - "需要架構決策"
+        - "跨模組協調"
+        - "除錯複雜問題"
+      examples:
+        - "設計新的子系統架構"
+        - "審查大型 PR"
+        - "診斷跨服務的效能問題"
+
+  rules:
+    - id: MS-001
+      trigger: "BLOCKED 狀態且當前為 fast"
+      action: "升級至 standard 再試"
+      priority: high
+    - id: MS-002
+      trigger: "BLOCKED 狀態且當前為 standard"
+      action: "升級至 capable 再試"
+      priority: high
+    - id: MS-003
+      trigger: "BLOCKED 狀態且當前為 capable"
+      action: "標記為需要人工介入"
+      priority: critical
+    - id: MS-004
+      trigger: "任務需求不明確"
+      action: "從 standard 或更高層級開始"
+      priority: medium
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查模型選擇是否基於任務複雜度信號，而非固定使用最高等級"
+  checks:
+    - "是否根據複雜度信號選擇模型等級"
+    - "BLOCKED 時是否嘗試升級而非直接失敗"
+    - "簡單任務是否避免使用過高等級模型"