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

package/bundled/core/error-code-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/error-code-standards.md)
 
-**Version**: 1.1.0
-**Last Updated**: 2026-01-05
+**Version**: 1.2.0
+**Last Updated**: 2026-03-18
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: RFC 7807, RFC 9457
@@ -285,6 +285,228 @@ function validateEmail(email: string) {
 }
 ```
 
+## API Error Serialization
+
+### RFC 7807 / RFC 9457 Problem Details
+
+For HTTP APIs, use the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) Problem Details format as the standard error envelope:
+
+```json
+{
+  "type": "https://api.example.com/errors/auth-val-001",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "Email field is required for registration",
+  "instance": "/api/register",
+  "code": "AUTH_VAL_001",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Email is required",
+      "code": "AUTH_VAL_001"
+    }
+  ],
+  "requestId": "req_abc123",
+  "timestamp": "2026-03-18T10:30:00Z"
+}
+```
+
+**Required Fields (RFC 7807):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | URI | Reference to error documentation |
+| `title` | string | Short, human-readable summary |
+| `status` | integer | HTTP status code |
+| `detail` | string | Human-readable explanation |
+| `instance` | string | URI of the request that caused the error |
+
+**Extension Fields (Recommended):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | string | Application error code (PREFIX_CATEGORY_NUMBER) |
+| `errors` | array | Detailed field-level errors |
+| `requestId` | string | Correlation ID for tracing |
+| `timestamp` | string | ISO 8601 timestamp |
+
+### REST JSON Error Response
+
+Standard REST error response combining internal error codes with RFC 7807:
+
+```json
+// Single error
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "Request validation failed",
+  "errors": [
+    {
+      "code": "AUTH_VAL_001",
+      "field": "email",
+      "message": "Email is required",
+      "pointer": "/data/attributes/email"
+    }
+  ]
+}
+
+// Multiple errors
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "Multiple validation errors occurred",
+  "errors": [
+    {
+      "code": "AUTH_VAL_001",
+      "field": "email",
+      "message": "Email is required",
+      "pointer": "/data/attributes/email"
+    },
+    {
+      "code": "AUTH_VAL_201",
+      "field": "password",
+      "message": "Password must be at least 8 characters",
+      "pointer": "/data/attributes/password"
+    }
+  ]
+}
+```
+
+### GraphQL Error Handling
+
+GraphQL uses a different error model. Map application error codes into the `extensions` field:
+
+```json
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "Email is required",
+      "locations": [{ "line": 2, "column": 3 }],
+      "path": ["createUser"],
+      "extensions": {
+        "code": "AUTH_VAL_001",
+        "category": "VALIDATION",
+        "field": "email",
+        "httpStatus": 400,
+        "timestamp": "2026-03-18T10:30:00Z"
+      }
+    }
+  ]
+}
+```
+
+**GraphQL Error Categories:**
+
+| Category | Maps To | Use For |
+|----------|---------|---------|
+| `VALIDATION` | VAL | Input validation failures |
+| `BUSINESS_RULE` | BIZ | Business logic violations |
+| `AUTHENTICATION` | AUTH (001-099) | Authentication failures |
+| `AUTHORIZATION` | AUTH (100-199) | Permission failures |
+| `INTERNAL` | SYS | Server-side errors |
+| `NETWORK` | NET | Upstream service failures |
+
+### gRPC Error Handling
+
+Map application error codes to gRPC status codes and include details via metadata:
+
+```protobuf
+// Error detail message
+message ErrorDetail {
+  string code = 1;          // "AUTH_VAL_001"
+  string message = 2;       // Human-readable message
+  string field = 3;         // Affected field
+  string documentation = 4; // Link to error docs
+}
+```
+
+**gRPC Status Code Mapping:**
+
+| Category | gRPC Status | Code |
+|----------|-------------|------|
+| VAL | `INVALID_ARGUMENT` | 3 |
+| BIZ | `FAILED_PRECONDITION` | 9 |
+| AUTH (001-099) | `UNAUTHENTICATED` | 16 |
+| AUTH (100-199) | `PERMISSION_DENIED` | 7 |
+| SYS | `INTERNAL` | 13 |
+| NET | `UNAVAILABLE` | 14 |
+
+```go
+// Go example
+import "google.golang.org/grpc/status"
+import "google.golang.org/grpc/codes"
+
+st := status.New(codes.InvalidArgument, "Validation failed")
+st, _ = st.WithDetails(&errdetails.BadRequest{
+    FieldViolations: []*errdetails.BadRequest_FieldViolation{
+        {Field: "email", Description: "AUTH_VAL_001: Email is required"},
+    },
+})
+return st.Err()
+```
+
+## Retry and Idempotency
+
+### Retry Guidance
+
+| Category | Retryable | Strategy |
+|----------|-----------|----------|
+| VAL | No | Fix input and resubmit |
+| BIZ | No | Resolve business condition |
+| AUTH (001-099) | No | Re-authenticate |
+| AUTH (200-299) | Yes | Refresh token, then retry |
+| SYS | Maybe | Retry with exponential backoff |
+| NET | Yes | Retry with exponential backoff |
+
+### Retry Response Headers
+
+```http
+HTTP/1.1 503 Service Unavailable
+Retry-After: 30
+X-RateLimit-Reset: 1679961600
+```
+
+Include retry guidance in error responses:
+
+```json
+{
+  "type": "https://api.example.com/errors/rate-limit",
+  "title": "Rate Limit Exceeded",
+  "status": 429,
+  "detail": "Too many requests",
+  "code": "API_NET_429",
+  "retryable": true,
+  "retryAfter": 30
+}
+```
+
+### Idempotency Keys
+
+For non-idempotent operations (POST), require `Idempotency-Key` header:
+
+```http
+POST /api/payments HTTP/1.1
+Idempotency-Key: key_abc123def456
+Content-Type: application/json
+
+{"amount": 100, "currency": "USD"}
+```
+
+**Idempotency Rules:**
+
+| Verb | Idempotent | Key Required |
+|------|-----------|-------------|
+| GET | Yes | No |
+| PUT | Yes | No |
+| DELETE | Yes | No |
+| PATCH | No | Recommended |
+| POST | No | Required for critical operations |
+
+---
+
 ## Documentation Requirements
 
 ### Error Code Documentation
@@ -366,6 +588,7 @@ AUTH_VAL_001
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-03-18 | Added: API Error Serialization (RFC 7807 Problem Details, REST, GraphQL, gRPC), Retry and Idempotency guidance |
 | 1.1.0 | 2026-01-05 | Added: References section with RFC 7807, RFC 9457, HTTP status codes, and Microsoft REST API Guidelines |
 | 1.0.0 | 2025-12-30 | Initial error code standards |
 
@@ -377,6 +600,9 @@ AUTH_VAL_001
 - [RFC 9457 - Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc9457) - Updated RFC 7807 (2023)
 - [HTTP Status Codes (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - HTTP status code reference
 - [Microsoft REST API Guidelines - Errors](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors) - Industry best practices
+- [GraphQL Spec - Errors](https://spec.graphql.org/October2021/#sec-Errors) - GraphQL error format specification
+- [gRPC Status Codes](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) - gRPC error handling reference
+- [Google API Design Guide - Errors](https://cloud.google.com/apis/design/errors) - Google's API error design patterns
 
 ---
 

package/bundled/core/forward-derivation-standards.md

@@ -1,7 +1,7 @@
 # Forward Derivation Standards | 正向推演標準
 
-**Version**: 1.1.0
-**Last Updated**: 2026-01-25
+**Version**: 1.2.0
+**Last Updated**: 2026-03-18
 **Applicability**: All projects using Spec-Driven Development
 **Scope**: uds-specific
 **Industry Standards**: JSON Schema 2020-12
@@ -525,6 +525,57 @@ spec-review → forward-derivation → discovery
 
 ---
 
+## Pipeline Integration
+
+### Automated TDD Transition
+
+When forward derivation is triggered by an automated pipeline (see [Pipeline Integration Standards](pipeline-integration-standards.md)), the following rules apply for transitioning into the TDD cycle:
+
+#### Auto-TDD Entry Rules
+
+| Rule | Description |
+|------|-------------|
+| **Derivation completeness** | All derivation outputs (BDD, TDD, ATDD) must be generated before entering TDD |
+| **RED state initialization** | Pipeline sets TDD state to RED after generating test skeletons |
+| **Test skeleton validation** | Generated test files must compile/parse without errors before entering RED |
+| **AC count verification** | Verify output test count matches AC count before transitioning |
+
+#### Pipeline Hooks
+
+Derivation steps can be automatically triggered by pipeline events:
+
+| Hook | Trigger | Action |
+|------|---------|--------|
+| `on-spec-approved` | Spec status changes to "approved" | Start derivation pipeline |
+| `on-derivation-complete` | All derivation outputs generated | Transition to TDD RED phase |
+| `on-tdd-green` | All derived tests pass | Trigger review stage |
+
+#### Auto-TDD Entry Workflow
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ Spec Approved│───▶│  Derive All  │───▶│ Verify Count │───▶│  TDD RED     │
+│ (hook)       │    │  BDD+TDD+ATDD│    │ AC = Tests   │    │  (auto-set)  │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+```
+
+1. **Spec Approval**: Pipeline detects spec approval (via hook or polling)
+2. **Full Derivation**: Pipeline runs `/derive-all` with project-configured language/framework
+3. **Count Verification**: Pipeline verifies output count matches AC count (anti-hallucination)
+4. **RED State**: Pipeline sets TDD state to RED; test skeletons exist but assertions are [TODO]
+
+#### Integration with Pipeline Stages
+
+Forward derivation maps to the **DERIVE** stage in the [Pipeline Integration Standards](pipeline-integration-standards.md) 6-stage model:
+
+| Pipeline Stage | Forward Derivation Role |
+|---------------|------------------------|
+| SPEC | Input: approved specification |
+| **DERIVE** | Execute: parse AC → generate BDD/TDD/ATDD outputs |
+| BUILD | Output: test skeletons feed into TDD RED→GREEN cycle |
+
+---
+
 ## Anti-Patterns to Avoid
 
 ### Generation Anti-Patterns
@@ -626,6 +677,7 @@ spec-review → forward-derivation → discovery
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-03-18 | Added: Pipeline Integration section — auto-TDD transition, pipeline hooks, auto-TDD entry workflow |
 | 1.1.0 | 2026-01-25 | Added: Contract output (contract.json), Schema output (schema.json), /derive-contracts command for verification artifact generation |
 | 1.0.0 | 2026-01-19 | Initial release |
 

package/bundled/core/git-worktree.md

@@ -0,0 +1,131 @@
+# Git Worktree Isolation
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/git-worktree.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-20
+**Applicability**: All projects using Git for version control
+**Scope**: universal
+**Inspired by**: [Superpowers](https://github.com/obra/superpowers) — using-git-worktrees (MIT)
+
+---
+
+## Purpose
+
+Define a lifecycle for using Git worktrees to isolate development work, ensuring clean environments, safe merging, and proper cleanup. Worktrees allow parallel work on multiple branches without stashing or switching.
+
+定義 Git Worktree 的完整生命週期管理標準，確保環境乾淨、安全合併與適當清理。Worktree 允許在多個分支上並行工作，無需 stash 或切換。
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| Worktree | A linked working copy of a Git repository at a different branch |
+| Baseline Test | A test run on a fresh worktree to verify the environment is clean |
+| Worktree Directory | The filesystem path where the worktree is created |
+
+---
+
+## Core Principle — Isolation with Accountability
+
+> **Every worktree must start clean (baseline test), work in isolation, and end with either a merge or explicit cleanup.**
+
+每個 worktree 必須以乾淨狀態開始（基準測試）、在隔離環境中工作、以合併或明確清理結束。
+
+---
+
+## Lifecycle Phases
+
+### Phase 1: Setup（建立）
+
+1. **Choose worktree location** — priority order:
+   - Existing configured path
+   - `.devap/worktrees/` or similar project-local directory
+   - Ask the user
+2. **Verify `.gitignore`** — run `git check-ignore` to confirm the worktree directory is ignored
+3. **Create the worktree** — `git worktree add <path> -b <branch-name>`
+4. **Install dependencies** — run package manager install if needed
+
+```bash
+# Example setup
+git worktree add .worktrees/feature-auth -b feature/auth
+cd .worktrees/feature-auth
+pnpm install  # or npm install, pip install, etc.
+```
+
+### Phase 2: Baseline（基準驗證）
+
+1. **Run the test suite** in the fresh worktree
+2. **Confirm all tests pass** — this verifies the environment is clean
+3. **If tests fail** — abort and report the environment issue (do not proceed)
+
+```bash
+# Baseline verification
+pnpm test  # Must pass before any work begins
+```
+
+基準測試失敗代表環境有問題，必須中止並報告。
+
+### Phase 3: Execute（執行）
+
+1. Work in the isolated worktree as a normal development environment
+2. Make commits as usual
+3. Run tests after changes
+
+### Phase 4: Merge（合併）
+
+1. **Verify all tests pass** in the worktree
+2. **Merge back** — use `--no-ff` to preserve branch history
+3. **Handle conflicts** if they arise
+
+```bash
+git checkout main
+git merge --no-ff feature/auth
+```
+
+### Phase 5: Cleanup（清理）
+
+1. **Remove the worktree** — `git worktree remove <path>`
+2. **Delete the branch** — `git branch -d <branch-name>`
+3. **Prune stale worktrees** — `git worktree prune`
+
+```bash
+git worktree remove .worktrees/feature-auth
+git branch -d feature/auth
+git worktree prune
+```
+
+**Important**: Cleanup must happen even on abnormal exits. Use try/finally patterns or cleanup hooks.
+
+清理必須在異常退出時也執行，使用 try/finally 或清理 hook。
+
+---
+
+## Rules
+
+| ID | Trigger | Action | Priority |
+|----|---------|--------|----------|
+| GW-001 | Worktree directory not in `.gitignore` | Automatically add to `.gitignore` | Critical |
+| GW-002 | Baseline tests fail | Abort task, report environment issue | High |
+| GW-003 | Abnormal exit during worktree operation | Ensure cleanup is executed | High |
+| GW-004 | Worktree exists after branch merge/delete | Prune stale worktree references | Medium |
+
+---
+
+## Best Practices
+
+| Practice | Rationale |
+|----------|-----------|
+| Use a consistent worktree directory (e.g., `.worktrees/`) | Easy to `.gitignore` and locate |
+| Always run baseline tests | Prevents false failures from environment issues |
+| Use `--no-ff` for merges | Preserves branch topology in history |
+| Clean up immediately after merge | Prevents stale worktree accumulation |
+
+---
+
+## References
+
+- **Superpowers**: [using-git-worktrees](https://github.com/obra/superpowers) (MIT)
+- **Git Documentation**: [git-worktree](https://git-scm.com/docs/git-worktree)

package/bundled/core/model-selection.md

@@ -0,0 +1,153 @@
+# AI Model Selection Strategy
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/model-selection.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-20
+**Applicability**: AI-assisted development with multiple model tiers
+**Scope**: universal
+**Inspired by**: [Superpowers](https://github.com/obra/superpowers) — subagent-driven-development (MIT)
+
+---
+
+## Purpose
+
+Define a cost-effective strategy for selecting AI model tiers based on task complexity signals. Use the cheapest model that can handle the job, and escalate only when necessary.
+
+定義基於任務複雜度的 AI 模型分級選擇策略。使用能勝任的最便宜模型，僅在必要時升級。
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| Model Tier | A classification level representing model capability and cost |
+| Complexity Signal | Observable characteristics of a task that indicate required capability |
+| Escalation | Upgrading to a higher-tier model after a lower tier fails |
+
+---
+
+## Core Principle — Cost Efficiency
+
+> **Always start with the cheapest model tier that matches the task's complexity signals.**
+
+始終使用與任務複雜度匹配的最便宜模型。
+
+---
+
+## Three-Tier Model Classification
+
+### Tier 1: Fast（快速層）
+
+**Purpose**: Mechanical implementation — single file, clear spec, no judgment needed.
+
+機械性實作 — 單一檔案、明確規格、無需判斷。
+
+**Complexity Signals**:
+- Modifies a single file
+- Specification is completely unambiguous
+- No design judgment required
+- Repetitive, pattern-based work
+
+**Examples**:
+- Update `package.json` version number
+- Add a new export statement
+- Fix a typo
+- Rename a variable across a file
+
+### Tier 2: Standard（標準層）
+
+**Purpose**: Integration work — multiple files, requires judgment.
+
+整合性實作 — 多檔案、需要判斷力。
+
+**Complexity Signals**:
+- Modifies 2–5 files
+- Requires understanding inter-module relationships
+- Needs some design judgment
+- Cross-cutting but within a bounded context
+
+**Examples**:
+- Add an API endpoint (route + handler + test)
+- Refactor a module's internal structure
+- Implement a feature with database migration
+- Write integration tests for a subsystem
+
+### Tier 3: Capable（能力層）
+
+**Purpose**: Architectural work — design, review, complex debugging.
+
+架構性工作 — 設計、審查、複雜除錯。
+
+**Complexity Signals**:
+- Modifies 5+ files
+- Requires architectural decisions
+- Cross-module coordination
+- Complex debugging or performance analysis
+- Ambiguous requirements needing interpretation
+
+**Examples**:
+- Design a new subsystem architecture
+- Review a large pull request
+- Diagnose cross-service performance issues
+- Refactor a major component with many dependents
+
+---
+
+## Selection Decision Flow
+
+```
+Analyze task complexity signals
+  ├── Single file, clear spec, no judgment? → Tier 1 (Fast)
+  ├── 2-5 files, some judgment needed?      → Tier 2 (Standard)
+  └── 5+ files, architectural decisions?    → Tier 3 (Capable)
+```
+
+---
+
+## Escalation Rules
+
+When a model tier fails (returns `BLOCKED`), escalate to the next tier:
+
+| Current Tier | On BLOCKED | Action |
+|-------------|-----------|--------|
+| Fast | → Standard | Re-dispatch with Standard tier |
+| Standard | → Capable | Re-dispatch with Capable tier |
+| Capable | → Human | Flag for human intervention |
+
+### Escalation is Not Retry
+
+Escalation means using a more capable model, not repeating the same action. The higher-tier model receives:
+- The original task
+- The lower-tier model's output and failure reason
+- Additional context if available
+
+升級不是重試。更高層級的模型會收到原始任務、低層級的輸出與失敗原因。
+
+---
+
+## Rules
+
+| ID | Trigger | Action | Priority |
+|----|---------|--------|----------|
+| MS-001 | BLOCKED at Fast tier | Escalate to Standard | High |
+| MS-002 | BLOCKED at Standard tier | Escalate to Capable | High |
+| MS-003 | BLOCKED at Capable tier | Flag for human intervention | Critical |
+| MS-004 | Task has ambiguous requirements | Start at Standard or higher | Medium |
+
+---
+
+## Cost Optimization Tips
+
+1. **Batch simple tasks** — send multiple Fast-tier tasks in one session
+2. **Pre-classify tasks** — use task metadata to auto-select tiers
+3. **Track escalation rates** — high escalation from Fast → Standard may indicate poor task decomposition
+4. **Review Capable usage** — ensure Capable-tier tasks genuinely need that level
+
+---
+
+## References
+
+- **Superpowers**: [subagent-driven-development](https://github.com/obra/superpowers) (MIT)
+- **Cost-Effective AI**: Principle of using the minimum capability needed