universal-dev-standards 5.1.1 → 5.3.0

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

@@ -0,0 +1,105 @@
+id: push-standards
+meta:
+  version: "1.0.0"
+  updated: "2026-04-23"
+  source: skills/push/SKILL.md
+  description: "Git push safety gates, protected branch detection, force-push guardrails, and push receipt audit trail"
+
+config:
+  protected_branches:
+    default: ["main", "master", "release/*", "hotfix/*"]
+    description: "Branches requiring explicit confirmation before push"
+
+  push_gates:
+    default: ["lint", "test"]
+    optional: ["ac-coverage", "type-check", "security-scan"]
+    description: "Quality gates to run before pushing"
+
+  receipt:
+    output:
+      default: "console"
+      choices: ["console", "file", "both"]
+    file_path: "~/.uds/push-history.jsonl"
+
+  auto_pr:
+    default: true
+    description: "Prompt to create PR after pushing to non-protected branch"
+
+  repo_mode:
+    default: "team"
+    choices: ["team", "single-owner"]
+    description: "single-owner skips PR prompts and reduces collaboration guardrails"
+
+rules:
+  - id: detect-protected-branch
+    trigger: "executing /push"
+    priority: required
+    instruction: |
+      Before pushing, detect the target branch name.
+      If the target matches any protected_branches pattern:
+      1. Display a warning with the branch name
+      2. Show what commits will be pushed
+      3. Require explicit user confirmation before proceeding
+      4. If user does not confirm, abort without pushing
+
+  - id: force-push-guardrail
+    trigger: "push with --force flag detected"
+    priority: required
+    instruction: |
+      When force push is detected:
+      1. Calculate commits that will be overwritten on remote
+      2. Show the count and authors of overwritten commits
+      3. Require the user to type a confirmation string (e.g., "yes, force push")
+      4. Record force_push: true in the push receipt
+
+  - id: pre-push-gates
+    trigger: "before executing git push"
+    priority: required
+    instruction: |
+      Run all configured push_gates in sequence:
+      - lint: run project lint command (from uds.project.yaml or detected)
+      - test: run project test command
+      If any gate fails: abort push, display which gate failed, suggest fix.
+      If --skip-gates flag: run push without gates, mark gates_skipped: true in receipt.
+
+  - id: push-receipt
+    trigger: "after successful push"
+    priority: required
+    instruction: |
+      Output a structured push receipt containing:
+      - branch: target branch name
+      - commit_sha: HEAD commit SHA (short)
+      - gates_passed: list of gates that ran and passed
+      - gates_skipped: boolean
+      - force_push: boolean
+      - timestamp: ISO 8601 format
+      If receipt.output includes "file": append to ~/.uds/push-history.jsonl as JSON line.
+
+  - id: pr-integration
+    trigger: "after successful push to non-protected branch"
+    priority: suggested
+    instruction: |
+      If auto_pr is true AND repo_mode is "team":
+      Check if an open PR exists for this branch on the remote.
+      If no open PR: prompt user whether to run pr-automation-assistant.
+      If user confirms: invoke pr-automation-assistant.
+      If auto_pr is false OR repo_mode is "single-owner": skip this step.
+
+  - id: single-owner-mode
+    trigger: "repo_mode: single-owner is configured"
+    priority: recommended
+    instruction: |
+      In single-owner mode, skip all collaboration-specific steps:
+      - No PR prompts
+      - Reduced force-push warnings (still warn, but no confirmation text required)
+      Protected branch detection remains active.
+
+schema:
+  push_receipt:
+    branch: string
+    commit_sha: string
+    gates_passed: "string[]"
+    gates_skipped: boolean
+    force_push: boolean
+    timestamp: "ISO 8601 string"
+    target_remote: string

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

@@ -0,0 +1,68 @@
+# Rollback Standards (AI-Optimized v1)
+# Source: core/rollback-standards.md
+
+standard:
+  id: rollback-standards
+  name: Rollback Standards
+  description: Rollback trigger conditions, auto vs manual decisions, and error budget integration
+  guidelines:
+    - "Define rollback triggers with measurable thresholds — never subjective 'it looks bad'"
+    - "Auto-rollback on error rate > 2× baseline sustained 5 minutes"
+    - "Assisted rollback when SLO violated but non-critical"
+    - "Manual rollback for latency degradation within SLO bounds"
+    - "Error budget < 10% automatically escalates assisted to auto-rollback"
+    - "Every rollback event must be logged and trigger incident response flow"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-26"
+    source: core/rollback-standards.md
+    parent: deployment-standards.ai.yaml
+
+trigger_conditions:
+  auto_rollback:
+    error_rate: ">2× baseline sustained 5min"
+    health_check_failures: "3 consecutive"
+    p99_latency: ">5× baseline sustained 3min"
+  assisted_rollback:
+    slo_violated: "non-critical path"
+    error_budget_remaining: "<10%"
+  manual_rollback:
+    latency_degraded: "within SLO bounds"
+    cosmetic_issues: "user-visible but non-functional"
+
+severity_matrix:
+  P0: {trigger: auto, timeline: "<2min", notify: "all-hands"}
+  P1: {trigger: auto, timeline: "<5min", notify: "on-call"}
+  P2: {trigger: assisted, timeline: "<15min", notify: "team-lead"}
+  P3: {trigger: manual, timeline: "<1hr", notify: "developer"}
+
+error_budget_integration:
+  threshold: "10% remaining"
+  escalation: "assisted → auto"
+  incident_event: true
+  pause_deploys: "when budget exhausted"
+
+rollback_methods:
+  blue_green: {time: "<30s", risk: low, prerequisite: "dual-slot infrastructure"}
+  feature_flag: {time: "<5s", risk: minimal, prerequisite: "flag system in place"}
+  dns_switch: {time: "60-120s", risk: medium, prerequisite: "multi-region setup"}
+  code_revert: {time: "minutes", risk: medium, prerequisite: "clean git history"}
+  database_restore: {time: "hours", risk: high, prerequisite: "backup verified"}
+
+checklist:
+  pre_rollback:
+    - "Confirm rollback target version is healthy"
+    - "Verify database migration is backward compatible"
+    - "Notify stakeholders of rollback"
+  post_rollback:
+    - "Confirm health checks pass at target version"
+    - "Write rollback event to deployment log"
+    - "Open incident ticket for root cause analysis"
+    - "Update error budget tracking"
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: "test -f rollback.sh && grep -q 'set -euo pipefail' rollback.sh"
+    rule: "rollback_script_configured"

package/bundled/core/agent-behavior-discipline.md

@@ -0,0 +1,178 @@
+# Agent Behavior Discipline
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/agent-behavior-discipline.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-04-24
+**Applicability**: All AI agent implementations using UDS-compliant harnesses
+**Scope**: universal
+**Industry Standards**: Informed by Karpathy 2026-01 observations + andrej-karpathy-skills (MIT)
+
+---
+
+## Purpose
+
+This standard defines four behavioral disciplines for AI agents that elevate performance from "functional" to "excellent". These disciplines address the most common failure modes observed in production LLM coding agents:
+
+1. **Executing on wrong assumptions** — agent proceeds without confirming direction
+2. **Over-engineering** — agent writes 200 lines when 50 would suffice
+3. **Scope creep** — agent "helpfully" modifies unrelated code
+4. **Goalless loops** — agent iterates without a defined stopping condition
+
+The disciplines are designed to be stackable with existing UDS standards (`anti-hallucination`, `anti-sycophancy-prompting`, `test-driven-development`) and enforceable at the harness level (DevAP `DisciplineConfig`).
+
+---
+
+## Principle 1: Ask — Surface Assumptions Before Executing
+
+### Rule
+
+Before any non-trivial task, explicitly state all assumptions and wait for confirmation.
+
+### When to Apply
+
+| Condition | Action |
+|-----------|--------|
+| Ambiguous requirements or multiple valid interpretations | Use Disclosure Format (below) |
+| Confidence score < 0.7 | Pause and ask |
+| Architecture changes or multi-file modifications | Always disclose |
+| Single-file trivial change (confidence ≥ 0.9, < 5 lines) | May skip confirmation |
+
+### Disclosure Format
+
+```
+My assumptions: [explicit list]
+Approach considered: [A] vs [B] — choosing A because [reason]
+If my understanding is incorrect, please redirect before I proceed.
+```
+
+### Why This Matters
+
+Karpathy observed: *"Models make wrong assumptions, don't seek clarification, and are a little too sycophantic."* A wrong direction costs more tokens to undo than the upfront 3-second check would have taken.
+
+---
+
+## Principle 2: Simple — Minimum Code, Nothing Speculative
+
+### Rule
+
+Solve with the least code required. Never add unrequested functionality.
+
+### Three Strikes Rule (DRY Threshold)
+
+Abstract only when identical logic appears **3 or more times**. A single-use helper is always a premature abstraction.
+
+### DO / DO NOT
+
+| DO | DO NOT |
+|----|--------|
+| ✅ Write only what the task requires | ❌ Add features "that might be needed later" |
+| ✅ Rewrite when a significantly shorter solution exists | ❌ Create single-use abstractions |
+| ✅ Inline logic used only once | ❌ Add speculative configuration hooks |
+| ✅ Skip error handling for impossible scenarios | ❌ Add defensive code for internal invariants |
+
+### Why This Matters
+
+Karpathy observed: *"It will implement 1000 lines of bloated code, and when challenged, immediately cuts it to 100."* If it can be 50 lines, it should be 50 lines from the start.
+
+---
+
+## Principle 3: Precision — Touch Only What the Task Requires
+
+### Rule
+
+Scope modifications to the declared minimum set of files and lines. Clean up only your own mess.
+
+### Scope Declaration Format
+
+Before any edit, output:
+```
+Modifying: [file list]
+Not touching: [related but out-of-scope areas]
+Out-of-scope observation (action deferred): [optional — verbal only, no edit]
+```
+
+### DO / DO NOT
+
+| DO | DO NOT |
+|----|--------|
+| ✅ Match existing local code style | ❌ Improve unrelated code "while I'm here" |
+| ✅ Flag pre-existing issues verbally | ❌ Remove dead code you didn't create |
+| ✅ Remove only imports orphaned by YOUR change | ❌ Rename symbols not in your task scope |
+| ✅ Declare scope before starting | ❌ Format unrelated code to match your preferences |
+
+### Why This Matters
+
+Karpathy observed agents that *"alter code it doesn't understand, and then things break"*. Precision prevents untraceable side effects and keeps diffs reviewable.
+
+---
+
+## Principle 4: Test — Define Success Criteria, Loop Until Verified
+
+### Rule
+
+Transform every task into a measurable, verifiable success criterion before implementation.
+
+### TDD Flow
+
+```
+Define success criterion → Write failing test (Red) → Implement (Green) → Refactor → Verify
+```
+
+### Vague Criteria Escalation
+
+If the task uses subjective language ("make it better", "improve search quality"):
+> "What specific metric or observable outcome defines success here?"
+
+Never proceed with a subjective stopping condition.
+
+### Autonomous Loop Protocol
+
+| Parameter | Value |
+|-----------|-------|
+| max_retries | 5 (default; configurable via DisciplineConfig) |
+| Per-iteration logging | Record `failureSource` (see failure-source-taxonomy) |
+| On stuck (same error fingerprint) | Escalate to human with failureSource summary |
+
+### Why This Matters
+
+Karpathy's strongest principle: *"LLMs excel at looping toward specific goals — provide success criteria rather than directives."* Without a verifiable goal, an autonomous agent loop has no natural stopping point.
+
+---
+
+## Integration with Other UDS Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `anti-hallucination` | Ask principle: disclose when uncertain rather than guessing |
+| `anti-sycophancy-prompting` | Ask principle: don't assume, push back when warranted |
+| `test-driven-development` | Test principle: TDD is the operational implementation |
+| `change-batching-standards` | Precision principle: scope limits reinforce batching logic |
+| `failure-source-taxonomy` | Test principle: loop protocol uses failureSource taxonomy |
+| `recovery-recipe-registry` | Test principle: max_retries maps to recovery recipe escalation |
+
+---
+
+## Enforcement at Harness Level (DevAP)
+
+`DisciplineConfig` in DevAP `src/types.ts`:
+
+```typescript
+interface DisciplineConfig {
+  ask_threshold: number;           // Confidence below this triggers Ask disclosure (default: 0.6)
+  max_loop_retries: number;        // Autonomous loop ceiling (default: 5)
+  precision_scope: 'strict' | 'relaxed'; // strict = always declare scope
+}
+```
+
+The `assumptionCheckGate()` in `src/orchestrator.ts` evaluates task complexity against `ask_threshold` before dispatching to the agent.
+
+---
+
+## 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/core/cd-deployment-strategies.md

@@ -0,0 +1,121 @@
+# CD Deployment Strategies（CD 部署策略）
+
+## 概述
+
+本標準定義四種主要部署策略的選用矩陣：Blue-Green、Canary、Rolling、Recreate。幫助團隊根據流量規模、風險容忍度和基礎設施成本，做出一致且有據可查的策略選擇。
+
+---
+
+## 核心原則
+
+- **三維決策**：根據流量規模 × 風險容忍度 × 基礎設施成本選擇策略
+- **禁止直接推產**：任何變更都必須先通過 staging 環境驗證
+- **零停機目標**：除非為內部工具或開發環境，否則應追求零停機部署
+
+---
+
+## 策略選用矩陣
+
+| 策略 | 流量規模 | 風險容忍度 | 基礎設施成本 | 停機時間 | 回滾時間 |
+|------|---------|----------|------------|---------|---------|
+| Blue-Green | 高 | 低 | 高 | 零 | < 30 秒 |
+| Canary | 中至高 | 中 | 中 | 零 | < 2 分鐘 |
+| Rolling | 任意 | 中 | 低 | 極少 | 數分鐘 |
+| Recreate | 低 | 高 | 極低 | 數秒至數分鐘 | 數分鐘 |
+
+---
+
+## 各策略詳細說明
+
+### Blue-Green
+
+**適用場景**：有狀態服務、資料庫相容性變更、高 SLA API
+
+**運作方式**：
+- 維護兩個完全相同的環境（Blue = 現有線上版，Green = 新版本）
+- 完整部署並驗證 Green 環境後，切換 Load Balancer 流量
+- 問題發生時立即切回 Blue
+
+**前置條件**：雙環境基礎設施、Load Balancer、健康檢查
+
+---
+
+### Canary
+
+**適用場景**：功能驗證、A/B 測試、高風險變更
+
+**流量漸進比例**：1% → 5% → 25% → 50% → 100%
+
+**運作方式**：
+- 先將少量流量導向新版本
+- 監控指標，符合自動晉升規則則繼續擴大
+- 發現問題立即縮回 0%
+
+**前置條件**：流量切分機制、可觀測性、自動晉升規則
+
+---
+
+### Rolling
+
+**適用場景**：無狀態服務、標準更新、批次工作者
+
+**運作方式**：
+- 依序更新每個實例，更新前進行健康檢查
+- 允許新舊版本短暫共存
+- 資源效率最佳，但回滾需時較長
+
+**前置條件**：多個服務實例、健康檢查
+
+---
+
+### Recreate
+
+**適用場景**：開發/測試環境、內部工具、單一實例服務
+
+**運作方式**：
+- 停止所有現有實例，部署新版本，重新啟動
+- 最簡單，但有停機時間
+
+**前置條件**：無（最低門檻）
+
+---
+
+## 決策樹
+
+```
+Q1: 需要零停機時間？
+  → 否 → Recreate
+  → 是 → Q2
+
+Q2: 流量 > 10k req/min？
+  → 是 → Q3（Blue-Green 或 Canary）
+  → 否 → Rolling
+
+Q3: 變更屬於高風險？
+  → 是 → Canary
+  → 否 → Q4
+
+Q4: 基礎設施預算有限？
+  → 是 → Rolling
+  → 否 → Blue-Green
+```
+
+---
+
+## 無 CI/CD 環境的替代做法
+
+| 策略 | 替代方案 |
+|------|---------|
+| Blue-Green | 參見 no-cicd-deployment.ai.yaml 的 Shell Script 實作 |
+| Canary | 使用 Nginx `split_clients` 或 HAProxy 做流量切分 |
+| Rolling | 使用順序式 rsync + 健康檢查迴圈 |
+| Recreate | 最簡單 — 停止、部署、啟動 |
+
+---
+
+## 相關標準
+
+- [deployment-standards.md](deployment-standards.md) — 部署基礎原則
+- [rollback-standards.md](rollback-standards.md) — 回滾觸發條件矩陣
+- [no-cicd-deployment.md](no-cicd-deployment.md) — 無 CI/CD 部署策略
+- AI 格式：[../ai/standards/cd-deployment-strategies.ai.yaml](../ai/standards/cd-deployment-strategies.ai.yaml)

package/bundled/core/no-cicd-deployment.md

@@ -0,0 +1,205 @@
+# No-CI/CD Deployment Strategy
+
+> **補充**: 本文件補充 `deployment-standards.md`，專注於無 CI/CD 平台（GitHub Actions / GitLab CI）環境下的可靠部署設計。
+
+## 核心三層架構
+
+```
+Layer 1: 防止錯誤部署
+  └─ set -euo pipefail、版本 tag 強制、deploy.lock
+
+Layer 2: 驗證部署正確
+  └─ Smoke Test、健康檢查、版本號比對、自動 rollback
+
+Layer 3: 快速回復能力
+  └─ Blue-Green 切換、< 30 秒 rollback
+```
+
+## Layer 1：防止錯誤部署
+
+### Shell 腳本強制執行
+
+所有部署腳本必須以下列標頭開始：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- `set -e`：任何命令失敗立即退出
+- `set -u`：引用未定義變數視為錯誤
+- `set -o pipefail`：管線中任何命令失敗都會傳播錯誤
+
+### 強制部署順序
+
+```bash
+echo "[1/4] 執行測試..."
+npm test
+
+echo "[2/4] 建置產物..."
+npm run build
+
+echo "[3/4] 推送到伺服器..."
+rsync -avz --delete ./dist/ user@server:/app/
+
+echo "[4/4] 驗證部署..."
+./verify.sh || { echo "驗證失敗，執行 rollback..."; ./rollback.sh; exit 1; }
+```
+
+### deploy.lock 防並發
+
+```bash
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ 部署進行中（PID: $(cat $LOCK_FILE)），請等待完成"
+  exit 1
+fi
+
+echo $$ > "$LOCK_FILE"
+```
+
+### 版本 Tag 強制
+
+```bash
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ 當前 commit 沒有版本 tag，請先執行："
+  echo "   git tag v$(cat VERSION) && git push --tags"
+  exit 1
+fi
+```
+
+## Layer 2：驗證部署正確
+
+### Smoke Test 腳本 (verify.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-https://example.com/health}"
+EXPECTED_VERSION=$(cat VERSION)
+MAX_RETRIES=3
+RETRY_INTERVAL=5
+
+for i in $(seq 1 $MAX_RETRIES); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "健康檢查失敗 ($i/$MAX_RETRIES)，等待 ${RETRY_INTERVAL}s..."
+  sleep $RETRY_INTERVAL
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ 版本不符！預期 $EXPECTED_VERSION，實際 $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ 版本驗證通過：$ACTUAL_VERSION"
+```
+
+### 健康檢查端點規格
+
+應用程式必須提供 `/health` 端點，回應格式：
+
+```json
+{
+  "status": "ok",
+  "version": "1.2.3",
+  "timestamp": "2026-04-26T10:00:00Z"
+}
+```
+
+## Layer 3：快速回復能力
+
+### Blue-Green 架構
+
+```
+[Nginx]
+  │
+  ├─── Blue (port 3001) ← 穩定版（當前 active）
+  └─── Green (port 3002) ← 新版（部署目標）
+```
+
+**Nginx 配置**：
+
+```nginx
+upstream app {
+  server 127.0.0.1:3001;  # blue
+  # server 127.0.0.1:3002;  # green（切換時啟用此行並停用上一行）
+}
+
+server {
+  listen 80;
+  location / {
+    proxy_pass http://app;
+  }
+}
+```
+
+### Rollback 腳本 (rollback.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current)
+if [[ "$CURRENT" == *"green"* ]]; then
+  TARGET="/app/blue"
+else
+  TARGET="/app/green"
+fi
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ 已切回 $TARGET（$(date -u +%Y-%m-%dT%H:%M:%SZ)）"
+
+# 記錄 rollback 事件
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### 完整 Makefile
+
+```makefile
+.PHONY: deploy rollback verify
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current: $$(readlink /app/current)"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool
+```
+
+## Deployment Log 格式
+
+每次部署（成功或失敗）都必須寫入 JSON Lines 格式的日誌：
+
+```json
+{"timestamp":"2026-04-26T10:00:00Z","version":"1.2.3","git_commit":"abc1234","operator":"albert","result":"success","duration_seconds":45,"slot":"green"}
+{"timestamp":"2026-04-26T11:30:00Z","version":"1.2.4","git_commit":"def5678","operator":"albert","result":"failure","duration_seconds":12,"slot":"green","error":"version_mismatch"}
+```
+
+## 適用場景
+
+| 場景 | 建議 |
+|------|------|
+| 個人 VPS / 小型專案 | Layer 1 + Layer 2（無需 Blue-Green） |
+| 自架伺服器（多人團隊） | 三層全套 + deploy.lock |
+| Air-gapped 環境 | 三層全套 + 本地 artifact registry |
+| 容器化部署 | 搭配 `docker compose` 執行 |
+
+## 相關標準
+
+- `deployment-standards.ai.yaml` — 有 CI/CD 平台的部署策略（本文件的補充前提）
+- `health-check-standards.ai.yaml` — /health 端點設計規範
+- `circuit-breaker.ai.yaml` — 斷路器整合（進階場景）