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

package/bundled/ai/standards/pipeline-integration-standards.ai.yaml

@@ -0,0 +1,184 @@
+# Pipeline Integration Standards - AI Optimized
+# Source: core/pipeline-integration-standards.md
+
+standard:
+  id: pipeline-integration
+  name: Pipeline Integration
+  description: Configuration contract, stage model, and context classification for automated development pipelines
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-18"
+    source: core/pipeline-integration-standards.md
+    references:
+      - "ISO/IEC 12207 (Software Lifecycle Processes)"
+      - "ISO/IEC 15504 SPICE (Process Assessment)"
+      - "Continuous Delivery (Jez Humble)"
+      - "DORA Metrics"
+
+  configuration_contract:
+    description: >
+      Projects using automated pipelines declare pipeline preferences via standard toggles.
+      All toggles default to OFF (manual mode).
+
+    toggles:
+      - name: autoSpecGeneration
+        type: boolean
+        default: false
+        description: Automatically generate SDD specs from PRD/user stories
+        when_on: Pipeline generates spec draft, submits for review
+        when_off: Manual spec creation required
+
+      - name: autoDerive
+        type: boolean
+        default: false
+        description: Automatically derive BDD/TDD/ATDD from approved specs
+        when_on: Pipeline runs derivation after spec approval
+        when_off: Manual derivation via commands
+
+      - name: autoTDD
+        type: boolean
+        default: false
+        description: Automatically enter TDD RED phase after derivation
+        when_on: Pipeline sets RED state and creates test skeleton
+        when_off: Developer manually enters TDD
+
+      - name: autoCheckin
+        type: boolean
+        default: false
+        description: Automatically commit when all quality gates pass
+        when_on: Pipeline commits after all gates pass
+        when_off: Developer manually commits
+
+      - name: autoBatch
+        type: boolean
+        default: false
+        description: Automatically batch pending changes before commit
+        when_on: Pipeline accumulates changes and merges at threshold
+        when_off: Each change committed individually
+
+    reading_rules:
+      - Fail-safe defaults — all toggles default to OFF
+      - Explicit declaration — never assume toggle state without reading config
+      - Runtime override — CLI flags may override file-based config
+      - Validation — validate configuration values before execution
+
+  pipeline_stages:
+    description: Standard 6-stage pipeline model
+    stages:
+      - stage: PLAN
+        input: PRD, user stories, requirements
+        output: Structured requirements document
+        gate: Requirements reviewed
+
+      - stage: SPEC
+        input: Requirements
+        output: SDD specification with AC
+        gate: Spec approved
+
+      - stage: DERIVE
+        input: Approved spec
+        output: BDD scenarios, TDD skeletons, ATDD tables
+        gate: 1:1 AC mapping verified
+
+      - stage: BUILD
+        input: Test skeletons + spec
+        output: Implementation code
+        gate: Tests pass (RED→GREEN)
+
+      - stage: REVIEW
+        input: Implementation + tests
+        output: Review feedback
+        gate: Review approved
+
+      - stage: CHECKIN
+        input: Approved changes
+        output: Committed code
+        gate: All quality gates pass
+
+  context_classification:
+    types:
+      - type: greenfield
+        description: New project or feature with no existing code
+        scenario: Starting a new module, service, or product
+        strategy:
+          plan: Full requirements
+          spec: Complete SDD
+          derive: Full derivation
+          build: TDD from scratch
+          review: Full review
+          checkin: Standard checkin
+
+      - type: brownfield
+        description: Existing codebase requiring modification
+        scenario: Adding features to legacy code, refactoring
+        strategy:
+          plan: Impact analysis first
+          spec: Delta SDD (changes only)
+          derive: Targeted derivation
+          build: Modify existing + new tests
+          review: Focused review on changes
+          checkin: Standard checkin
+
+      - type: adhoc
+        description: Small, isolated changes
+        scenario: Bug fixes, configuration changes, hotfixes
+        strategy:
+          plan: Quick assessment
+          spec: Optional (for significant changes)
+          derive: Skip (unless complex)
+          build: Direct fix
+          review: Quick review
+          checkin: Standard checkin
+
+    detection_signals:
+      - signal: file_count
+        greenfield: 0 or minimal files
+        brownfield: Established codebase
+        adhoc: N/A
+      - signal: change_scope
+        greenfield: New directory/module
+        brownfield: Modifications to existing files
+        adhoc: 1-3 files changed
+      - signal: test_coverage
+        greenfield: No existing tests
+        brownfield: Existing test suite
+        adhoc: Existing tests cover area
+
+  rules:
+    - id: read-config-first
+      trigger: starting pipeline execution
+      instruction: Read all toggles from configuration before executing any stage
+      priority: required
+
+    - id: fail-safe-defaults
+      trigger: toggle not found in configuration
+      instruction: Default all unset toggles to OFF (manual mode)
+      priority: required
+
+    - id: enforce-stage-gates
+      trigger: completing a pipeline stage
+      instruction: Verify quality gate passes before progressing to next stage
+      priority: required
+
+    - id: context-awareness
+      trigger: starting pipeline execution
+      instruction: Detect or read context type and adapt stage strategy accordingly
+      priority: required
+
+    - id: log-decisions
+      trigger: skipping or executing a stage
+      instruction: Log which stages were executed, skipped, and why
+      priority: recommended
+
+    - id: validate-config
+      trigger: reading configuration
+      instruction: Validate toggle types (boolean), context enum, and unknown keys
+      priority: required
+
+related_standards:
+  - spec-driven-development.md
+  - forward-derivation-standards.md
+  - checkin-standards.md
+  - change-batching-standards.md
+  - acceptance-criteria-traceability.md

package/bundled/ai/standards/systematic-debugging.ai.yaml

@@ -0,0 +1,73 @@
+# Systematic Debugging Workflow - AI Optimized
+# Source: core/systematic-debugging.md
+# Inspired by Superpowers systematic-debugging (MIT)
+
+standard:
+  id: systematic-debugging
+  name: Systematic Debugging Workflow
+  description: 系統化除錯工作流，借鑑 Superpowers 四階段法
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/systematic-debugging.md
+    description: 系統化除錯工作流標準
+    inspired_by: superpowers/systematic-debugging
+
+  guidelines:
+    - "遵循四階段鐵律：Root Cause → Pattern Analysis → Hypothesis Testing → Fix Implementation"
+    - "禁止跳過根因分析直接修復"
+    - "連續 3 次修復失敗必須質疑架構設計（3-Strike Rule）"
+    - "在元件邊界加診斷觀測定位故障層"
+    - "從錯誤症狀反向追蹤到源頭（backward tracing）"
+
+  phases:
+    - name: root_cause
+      description: "根因調查 — 分析錯誤訊息 + 變更追蹤"
+      actions:
+        - "仔細閱讀錯誤訊息，定位精確出錯位置"
+        - "追蹤最近變更記錄（git log / git diff）"
+        - "在元件邊界加 console.log / 斷點觀測"
+        - "記錄觀測結果，形成初步假設"
+    - name: pattern_analysis
+      description: "模式分析 — 比對同類成功案例"
+      actions:
+        - "搜尋類似功能的成功實作"
+        - "比對差異點"
+        - "檢查是否遺漏前置條件"
+    - name: hypothesis_testing
+      description: "假設測試 — 最小化修改驗證"
+      actions:
+        - "用最小化修改驗證假設"
+        - "每次只改一個變數"
+        - "記錄每次嘗試的假設與結果"
+    - name: fix_implementation
+      description: "修復實作 — 確認根因後再修復"
+      actions:
+        - "確認根因後才實作修復"
+        - "修復後執行完整測試"
+        - "確認不引入新問題"
+
+  rules:
+    - id: SD-001
+      trigger: "連續修復失敗 3 次"
+      action: "停止猜測，質疑架構設計"
+      priority: critical
+    - id: SD-002
+      trigger: "出現 'quick fix'、'just try'、'should work now' 等字眼"
+      action: "停止，回到 Phase 1 根因分析"
+      priority: high
+    - id: SD-003
+      trigger: "多元件交互錯誤"
+      action: "在每個元件邊界加診斷觀測"
+      priority: medium
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查除錯過程是否遵循四階段工作流：root_cause → pattern_analysis → hypothesis_testing → fix_implementation"
+  checks:
+    - "根因分析是否在修復嘗試之前完成"
+    - "是否記錄每次假設與驗證結果"
+    - "連續失敗 3 次是否觸發架構審查"

package/bundled/ai/standards/verification-evidence.ai.yaml

@@ -0,0 +1,84 @@
+# Verification Evidence Standard - AI Optimized
+# Source: core/verification-evidence.md
+# Inspired by Superpowers verification-before-completion (MIT)
+
+standard:
+  id: verification-evidence
+  name: Verification Evidence Standard
+  description: 驗證證據標準，強化 anti-hallucination
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/verification-evidence.md
+    description: 驗證證據標準 — Iron Law: 無驗證證據不可聲稱完成
+    inspired_by: superpowers/verification-before-completion
+
+  guidelines:
+    - "Iron Law：無驗證證據 = 不可聲稱完成"
+    - "每次驗證必須記錄 command + exitCode + output + timestamp"
+    - "回歸測試必須展示 RED → GREEN 循環"
+    - "代理報告 success ≠ 實際 success，需獨立驗證"
+    - "驗證輸出截斷至合理長度（2000 字元）但保留關鍵資訊"
+
+  evidence_format:
+    fields:
+      - name: command
+        type: string
+        required: true
+        description: "實際執行的驗證指令"
+      - name: exit_code
+        type: number
+        required: true
+        description: "指令退出碼（0 = 成功）"
+      - name: output
+        type: string
+        required: true
+        description: "驗證輸出（截斷至 2000 字元）"
+      - name: timestamp
+        type: string
+        required: true
+        description: "執行時間（ISO 8601 格式）"
+
+  red_green_cycle:
+    description: "回歸測試的 RED → GREEN 驗證"
+    steps:
+      - "RED: 在修復前執行測試，確認測試確實失敗"
+      - "修復問題"
+      - "GREEN: 再次執行測試，確認測試通過"
+      - "記錄 RED 和 GREEN 兩個階段的證據"
+
+  trust_rules:
+    - "代理聲稱「已完成」→ 檢查 verification_evidence 是否存在"
+    - "verification_evidence 為空 → 標記為未驗證"
+    - "exit_code ≠ 0 → 標記為驗證失敗"
+    - "多個驗證步驟 → 所有步驟都必須通過"
+
+  rules:
+    - id: VE-001
+      trigger: "代理回報 success 但無 verification_evidence"
+      action: "降級為 done_with_concerns"
+      priority: critical
+    - id: VE-002
+      trigger: "exit_code ≠ 0"
+      action: "標記驗證失敗，啟動 fix loop"
+      priority: high
+    - id: VE-003
+      trigger: "Bug fix 無 RED-GREEN 循環"
+      action: "要求提供 RED 和 GREEN 兩階段證據"
+      priority: high
+    - id: VE-004
+      trigger: "驗證輸出超過 2000 字元"
+      action: "截斷但保留錯誤訊息與摘要行"
+      priority: medium
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查任務完成是否附帶驗證證據（command + exit_code + output + timestamp）"
+  checks:
+    - "完成聲明是否附帶 verification_evidence"
+    - "evidence 是否包含所有必填欄位"
+    - "exit_code 是否為 0（成功）"
+    - "Bug fix 是否有 RED → GREEN 循環證據"

package/bundled/ai/standards/workflow-enforcement.ai.yaml

@@ -0,0 +1,253 @@
+# Workflow Enforcement Standards - AI Optimized
+# Source: core/workflow-enforcement.md
+
+id: workflow-enforcement
+meta:
+  version: "1.0.0"
+  updated: "2026-03-19"
+  source: core/workflow-enforcement.md
+  description: Machine-enforceable workflow gates that prevent phase skipping in development methodologies
+
+enforcement_modes:
+  enforce:
+    description: Block phase transition, show guidance to correct phase
+    behavior: AI refuses to proceed and explains which prerequisite is missing
+    default: true
+
+  suggest:
+    description: Show warning but allow override with user confirmation
+    behavior: AI warns about skipped prerequisites but proceeds if user insists
+
+  off:
+    description: No enforcement checks
+    behavior: AI follows workflow steps without gate checks
+
+config_location: ".uds/config.yaml"
+config_key: "workflow.enforcement_mode"
+
+gates:
+  sdd:
+    description: Spec-Driven Development phase gates
+    phases:
+      - phase: discuss
+        prerequisites: []
+        note: Entry point, no prerequisites
+
+      - phase: create
+        prerequisites:
+          - check: orphan_specs
+            command: "ls docs/specs/SPEC-*.md 2>/dev/null"
+            condition: warn_if_non_terminal_specs_exist
+            on_fail: warn_and_offer_cleanup
+            blocking: false
+
+      - phase: review
+        prerequisites:
+          - check: spec_exists
+            command: "ls docs/specs/SPEC-*.md"
+            condition: at_least_one_spec_exists
+            on_fail: guide_to_create
+            blocking: true
+          - check: spec_status_draft
+            command: "grep -m1 '^status:' docs/specs/SPEC-XXX.md"
+            condition: status_is_draft
+            on_fail: guide_to_create
+            blocking: true
+
+      - phase: approve
+        prerequisites:
+          - check: spec_in_review
+            condition: status_is_review
+            on_fail: guide_to_review
+            blocking: true
+          - check: review_comments_addressed
+            condition: no_unresolved_comments
+            on_fail: guide_to_resolve_comments
+            blocking: true
+
+      - phase: implement
+        prerequisites:
+          - check: spec_exists
+            command: "ls docs/specs/SPEC-*.md"
+            condition: at_least_one_spec_exists
+            on_fail: guide_to_create
+            blocking: true
+          - check: spec_approved
+            condition: status_is_approved
+            on_fail: guide_to_approve
+            blocking: true
+          - check: workflow_state
+            command: "ls .workflow-state/sdd-*.yaml 2>/dev/null"
+            condition: check_for_resumable_state
+            on_fail: start_fresh
+            blocking: false
+
+      - phase: verify
+        prerequisites:
+          - check: implementation_exists
+            condition: spec_has_implementation_commits
+            on_fail: guide_to_implement
+            blocking: true
+          - check: ac_coverage
+            condition: all_ac_have_code_and_tests
+            on_fail: list_incomplete_acs
+            blocking: true
+
+  tdd:
+    description: Test-Driven Development phase gates
+    phases:
+      - phase: red
+        prerequisites:
+          - check: feature_defined
+            condition: user_has_described_behavior
+            on_fail: ask_for_behavior_description
+            blocking: true
+          - check: sdd_spec_if_applicable
+            condition: if_sdd_project_spec_exists_and_approved
+            on_fail: guide_to_sdd
+            blocking: false
+
+      - phase: green
+        prerequisites:
+          - check: failing_test_exists
+            command: "npm test 2>&1 | grep -E 'FAIL|failing'"
+            condition: at_least_one_test_failing
+            on_fail: guide_to_red_phase
+            blocking: true
+
+      - phase: refactor
+        prerequisites:
+          - check: all_tests_passing
+            command: "npm test"
+            condition: zero_test_failures
+            on_fail: guide_to_green_phase
+            blocking: true
+
+  bdd:
+    description: Behavior-Driven Development phase gates
+    phases:
+      - phase: discovery
+        prerequisites:
+          - check: behavior_identified
+            condition: user_has_identified_behavior
+            on_fail: ask_for_behavior
+            blocking: true
+
+      - phase: formulation
+        prerequisites:
+          - check: examples_collected
+            condition: discovery_produced_examples
+            on_fail: guide_to_discovery
+            blocking: true
+
+      - phase: automation
+        prerequisites:
+          - check: feature_file_exists
+            command: "ls tests/features/*.feature 2>/dev/null"
+            condition: at_least_one_feature_file
+            on_fail: guide_to_formulation
+            blocking: true
+          - check: gherkin_format
+            condition: scenarios_use_given_when_then
+            on_fail: fix_scenario_format
+            blocking: true
+
+      - phase: living_docs
+        prerequisites:
+          - check: steps_implemented
+            condition: step_definitions_exist
+            on_fail: guide_to_automation
+            blocking: true
+          - check: scenarios_passing
+            condition: all_scenarios_pass
+            on_fail: fix_failing_scenarios
+            blocking: true
+
+  commit:
+    description: Commit workflow gates
+    phases:
+      - phase: commit
+        prerequisites:
+          - check: staged_changes
+            command: "git diff --cached --stat"
+            condition: has_staged_changes
+            on_fail: guide_to_git_add
+            blocking: true
+          - check: no_merge_conflicts
+            condition: no_conflict_markers_in_staged
+            on_fail: resolve_conflicts
+            blocking: true
+          - check: tests_pass
+            condition: tests_passing_for_feat_fix
+            on_fail: fix_tests
+            blocking: true
+          - check: spec_reference
+            condition: feat_fix_should_reference_spec
+            on_fail: suggest_spec_reference
+            blocking: false
+
+rules:
+  - id: enforce-phase-order
+    trigger: AI assistant receives a workflow phase command
+    instruction: >
+      Before executing any workflow phase (SDD, TDD, BDD), check the
+      phase gate prerequisites defined in this standard. If any blocking
+      prerequisite fails, STOP execution, explain what is missing, and
+      guide the user to the correct prerequisite phase. Non-blocking
+      prerequisites generate warnings but allow proceeding.
+    priority: required
+
+  - id: respect-enforcement-mode
+    trigger: checking workflow gates
+    instruction: >
+      Read the project's enforcement mode from .uds/config.yaml
+      (workflow.enforcement_mode). If 'enforce' (default), block on
+      failed prerequisites. If 'suggest', warn but allow override.
+      If 'off', skip all checks.
+    priority: required
+
+  - id: guide-dont-block
+    trigger: prerequisite check fails
+    instruction: >
+      When a prerequisite fails, provide actionable guidance:
+      1. Explain WHAT is missing (e.g., "No approved spec found")
+      2. Explain WHY it matters (e.g., "SDD requires approved specs before implementation")
+      3. Show HOW to fix it (e.g., "Run /sdd approve SPEC-XXX.md first")
+      Never just say "blocked" — always provide the path forward.
+    priority: required
+
+  - id: resume-existing-workflow
+    trigger: workflow command invoked with existing state
+    instruction: >
+      Before starting a fresh workflow, check .workflow-state/ for
+      existing state files. If an active workflow exists for the same
+      spec or feature, offer to resume instead of starting fresh.
+    priority: required
+
+  - id: feat-commit-spec-suggestion
+    trigger: committing a feat or fix type change
+    instruction: >
+      When generating a feat or fix commit message, check if active
+      specs exist in docs/specs/. If yes, suggest adding Refs: SPEC-XXX
+      to the commit footer. If no specs exist and the change is
+      significant (>3 files changed or new API), suggest creating a
+      spec via /sdd. This is advisory, not blocking.
+    priority: recommended
+
+quick_reference:
+  enforcement_modes:
+    columns: [Mode, Behavior, Config Value]
+    rows:
+      - [Enforce, "Block + Guide", "enforce"]
+      - [Suggest, "Warn + Allow", "suggest"]
+      - [Off, "No checks", "off"]
+
+  phase_gates:
+    columns: [Workflow, Phase, Key Prerequisite]
+    rows:
+      - [SDD, implement, "Spec must be Approved"]
+      - [SDD, verify, "All ACs must have code + tests"]
+      - [TDD, green, "At least one failing test"]
+      - [TDD, refactor, "All tests passing"]
+      - [BDD, automation, ".feature file must exist"]
+      - [Commit, feat/fix, "Suggest spec reference"]