universal-dev-standards 5.1.0-beta.6 → 5.1.0-beta.7

package/bundled/core/capability-declaration.md

@@ -0,0 +1,59 @@
+# Capability Declaration Standard
+
+> **Source**: XSPEC-037 | **Borrowed from**: claude-code-book Ch.3
+
+## Overview
+
+The Capability Declaration Standard mandates that all tools, adapters, and agents explicitly declare their safety properties. **All properties default to the most conservative (Fail-Closed) values** — a developer who forgets to declare capabilities gets safe behavior, not dangerous behavior.
+
+Borrowed from claude-code-book's `buildTool` factory design, where `isConcurrencySafe()` and `isReadOnly()` default to `false`, requiring explicit opt-in for performance optimizations.
+
+## Fail-Closed Defaults
+
+```typescript
+const FAIL_CLOSED_DEFAULTS: CapabilityDeclaration = {
+  isConcurrencySafe: false,       // Cannot run in parallel
+  isReadOnly: false,              // Assumed to have side effects
+  requiresUserConfirmation: true, // Must confirm before execution
+  trustLevel: "untrusted",        // Maximum sandbox restrictions
+};
+```
+
+## CapabilityDeclaration Interface
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `isConcurrencySafe` | boolean | **false** | Safe to run in parallel with other operations |
+| `isReadOnly` | boolean | **false** | Makes no persistent state changes |
+| `requiresUserConfirmation` | boolean | **true** | Requires explicit user approval before execution |
+| `trustLevel` | enum | **untrusted** | Sandbox isolation level |
+
+## Trust Levels
+
+| Level | Description | Sandbox |
+|-------|-------------|---------|
+| `trusted` | Built-in or audited plugin | No restrictions |
+| `sandboxed` | Third-party tool | Restricted execution environment |
+| `untrusted` | Unknown source | Maximum restrictions (default) |
+
+## Well-Known Declarations
+
+| Tool | isConcurrencySafe | isReadOnly | requiresConfirmation | trustLevel |
+|------|-------------------|------------|---------------------|------------|
+| GrepTool | ✅ true | ✅ true | ❌ false | trusted |
+| GlobTool | ✅ true | ✅ true | ❌ false | trusted |
+| FileReadTool | ✅ true | ✅ true | ❌ false | trusted |
+| FileEditTool | ❌ false | ❌ false | ✅ true | trusted |
+| BashTool | ❌ false | ❌ false | ✅ true | sandboxed |
+
+## Enforcement
+
+- **Missing declaration**: Use `FAIL_CLOSED_DEFAULTS` + log `[WARN] Capability not declared for: {name}`
+- **False claim detection**: If declared `isReadOnly: true` but performs writes → log `CAPABILITY_MISMATCH` event, revert to Fail-Closed
+- **Concurrency**: Only components with `isConcurrencySafe: true` may be batched into parallel execution
+
+## References
+
+- AI-optimized: [ai/standards/capability-declaration.ai.yaml](../ai/standards/capability-declaration.ai.yaml)
+- XSPEC-037: Cross-project specification
+- Borrowed from: [claude-code-book](https://github.com/lintsinghua/claude-code-book) Ch.3 `buildTool` Fail-Closed factory

package/bundled/core/circuit-breaker.md

@@ -0,0 +1,58 @@
+# Circuit Breaker Standard
+
+> **Source**: XSPEC-036 | **Borrowed from**: claude-code-book Ch.2
+
+## Overview
+
+The Circuit Breaker pattern protects Agent systems from API stampedes caused by repeated failures. After `failureThreshold` consecutive failures, the breaker opens and immediately rejects all requests — no waiting for timeout. After a cooldown period, it allows one probe call to test recovery.
+
+Real-world data: Before introducing circuit breakers, claude-code-book measured ~250K wasted API calls per day across 1,279 sessions with >50 consecutive failures each (max: 3,272 consecutive failures).
+
+## States
+
+```
+CLOSED ──(N consecutive failures)──→ OPEN
+OPEN   ──(cooldownMs elapsed)──→ HALF_OPEN
+HALF_OPEN ──(probe success)──→ CLOSED
+HALF_OPEN ──(probe failure)──→ OPEN
+```
+
+| State | Behavior |
+|-------|----------|
+| **CLOSED** | Normal operation, requests forwarded |
+| **OPEN** | All requests rejected immediately with `CircuitOpenError` |
+| **HALF_OPEN** | One probe request allowed; success → CLOSED, failure → OPEN |
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `failureThreshold` | 3 | Consecutive failures before opening |
+| `cooldownMs` | 30000 | OPEN → HALF_OPEN wait time (ms) |
+| `successThreshold` | 1 | Probe successes needed to close |
+
+## Interface
+
+```typescript
+interface CircuitBreaker {
+  readonly name: string;
+  readonly state: "CLOSED" | "HALF_OPEN" | "OPEN";
+  execute<T>(fn: () => Promise<T>): Promise<T>; // throws CircuitOpenError when OPEN
+  getState(): CircuitBreakerState;
+  reset(): void; // admin manual reset
+}
+```
+
+## Applicable Scenarios
+
+- DevAP Fix Loop retries
+- DevAP LLM API call protection
+- VibeOps Feedback Loop retries
+- VibeOps FLARE retrieval retries
+- Any component using retry with external dependencies
+
+## References
+
+- AI-optimized: [ai/standards/circuit-breaker.ai.yaml](../ai/standards/circuit-breaker.ai.yaml)
+- XSPEC-036: Cross-project specification
+- Borrowed from: [claude-code-book](https://github.com/lintsinghua/claude-code-book) Ch.2 `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES`

package/bundled/core/developer-memory.md

@@ -329,7 +329,35 @@ Multiple pitfalls → Pattern → Mental Model
 
 ---
 
-## 5. Noise Control
+## 5. Memory Verification Principle（記憶是線索，非結論）
+
+> 借鑑 lintsinghua/claude-code-book 記憶驗證原則。
+
+記憶提供方向，但**不能直接作為事實使用**。使用記憶前須獨立驗證：
+
+| 記憶內容 | 驗證方法 | 衝突時處理 |
+|---------|---------|-----------|
+| 檔案路徑 | 確認檔案仍存在（Glob/Read） | 標記記憶為 `needs-revision` |
+| 函式名稱/API flag | 確認仍存在（Grep/文件） | 標記記憶為 `needs-revision` |
+| 架構快照/Repo 狀態 | 優先信任 `git log`/原始碼 | 更新記憶為當前狀態 |
+| 套件版本/相依 | 確認 package.json/lockfile | 以實際版本為準 |
+
+### 禁止行為
+
+- 直接引用記憶中的具體 API/路徑/函式名稱推薦給使用者，未先驗證
+- 宣稱「根據記憶，X 存在」而未執行獨立確認
+- 因記憶內容與現況衝突時，選擇信任記憶而非當前觀察
+
+### 記憶用途場景
+
+記憶適合提供：
+- **搜尋方向**：「這類問題上次在 X 模組找到答案」
+- **模式線索**：「這個錯誤模式對應已知 pitfall MEM-2026-0042」
+- **決策背景**：「此設計決策的歷史背景是...」
+
+---
+
+## 6. Noise Control
 
 ### Push Levels
 

package/bundled/core/dual-phase-output.md

@@ -0,0 +1,56 @@
+# Dual-Phase LLM Output Standard
+
+> **Source**: XSPEC-035 | **Borrowed from**: claude-code-book Ch.7 AutoCompact
+
+## Overview
+
+The Dual-Phase LLM Output pattern requires LLM review agents to produce two XML blocks in a single response: an `<analysis>` thinking scratchpad (discarded after processing) and a `<summary>` structured conclusion (retained). This lets the model reason thoroughly while preventing thinking processes from accumulating in the conversation context.
+
+## Problem
+
+Review agents (Judge, Evaluator, Guardian) typically generate 2000–5000 token responses, with 50–70% being reasoning that accumulates in conversation history. In repeated review scenarios (Fix Loop 3× retries), this wastes 3000–10500 tokens per task.
+
+## Format
+
+```xml
+<analysis>
+[Reasoning scratchpad — DISCARDED after processing]
+- Step-by-step evaluation
+- Edge case considerations
+- Alternative comparisons
+</analysis>
+
+<summary>
+decision: approved | rejected | needs_revision
+confidence: high | medium | low
+findings:
+  - [type] description
+next_action: [recommended follow-up action]
+</summary>
+```
+
+## Post-Processing Rules
+
+1. Extract `<summary>` content → persist to context
+2. Discard `<analysis>` content → never write to conversation history
+3. If `<summary>` tag missing → fallback: treat full response as summary, log `[WARN] dual-phase format missing`
+
+## Extension Fields
+
+Applications may add fields inside `<summary>` but must not remove core fields:
+- **Security (Guardian)**: `severity: critical | high | medium | low`, `cwe_ids: [CWE-NNN]`
+- **Quality (Evaluator)**: `test_coverage: number`, `tech_debt_score: number`
+
+## Token Impact
+
+| Scenario | Savings |
+|----------|---------|
+| Single review | 1000–3500 tokens |
+| Fix Loop (3× retries) | 3000–10500 tokens |
+| VibeOps pipeline (evaluator + guardian) | 2000–7000 tokens per run |
+
+## References
+
+- AI-optimized: [ai/standards/dual-phase-output.ai.yaml](../ai/standards/dual-phase-output.ai.yaml)
+- XSPEC-035: Cross-project specification
+- Borrowed from: [claude-code-book](https://github.com/lintsinghua/claude-code-book) Ch.7 `formatCompactSummary`

package/bundled/core/failure-source-taxonomy.md

@@ -0,0 +1,72 @@
+# Failure Source Taxonomy Standard
+
+> **Source**: XSPEC-045 | **Borrowed from**: ultraworkers/claw-code ROADMAP Phase 2 Failure Taxonomy
+
+## Overview
+
+The Failure Source Taxonomy adds a `failureSource` (why) dimension on top of the existing `TaskStatus` (what). Structured failure sources allow the downstream recovery mechanism (Recovery Recipe Registry, XSPEC-046) to precisely match strategies, avoiding the application of the same retry logic to fundamentally different failure types.
+
+## 8 Failure Sources
+
+| Source | Description | Recommended Recovery |
+|--------|-------------|---------------------|
+| `prompt_delivery` | Prompt not delivered to LLM (API 4xx, empty response, parse error) | retry or model_switch |
+| `model_degradation` | LLM quality degrades (repetitive output, irrelevant response) | model_switch |
+| `branch_divergence` | Working branch falls behind base branch | rebase_and_retry |
+| `compilation` | Compile or type-check errors (tsc, cargo, go build) | fix_loop |
+| `test_failure` | Test failures (unit / integration / system / e2e) | fix_loop |
+| `tool_failure` | Tool layer failure (MCP server unresponsive, plugin load failure) | circuit_breaker then retry |
+| `policy_violation` | Safety/governance policy block (Guardian deny, SafetyHook) | human_checkpoint |
+| `resource_exhaustion` | Resource exhausted (token budget exceeded, timeout, USD budget) | degraded_mode or human_checkpoint |
+
+## Priority Rules
+
+When multiple failure sources coexist, apply:
+
+1. `branch_divergence` > `compilation` — divergence is usually the root cause of compilation failures
+2. `policy_violation` > others — security takes precedence, do not attempt bypass
+3. `resource_exhaustion` > others — retrying when resources are exhausted is meaningless
+4. Otherwise: use the first detected source
+
+## Types
+
+```typescript
+type FailureSource =
+  | "prompt_delivery"
+  | "model_degradation"
+  | "branch_divergence"
+  | "compilation"
+  | "test_failure"
+  | "tool_failure"
+  | "policy_violation"
+  | "resource_exhaustion";
+
+interface FailureDetail {
+  source: FailureSource;
+  raw_error: string;
+  detected_by: string;  // quality-gate / claude-adapter / safety-hook / branch-drift
+  timestamp: string;    // ISO 8601
+}
+```
+
+## Guidelines
+
+- All failure results should carry `failureSource` to enable precise recovery strategy matching
+- `failureSource` is an **optional** field — must not break existing code without this field
+- Select the most fundamental source as `failureSource` in a single failure event
+- `failureSource` should be set by the component that detects the failure
+- DevAP and VibeOps each define `FailureSource` type independently (AGPL isolation)
+
+## Applicable Scenarios
+
+- DevAP QualityGate failure result enrichment
+- VibeOps PipelineRunner `agent:error` event payload
+- Recovery Recipe Registry (XSPEC-046) match key
+- Telemetry failure analytics dimension
+
+## References
+
+- AI-optimized: [ai/standards/failure-source-taxonomy.ai.yaml](../ai/standards/failure-source-taxonomy.ai.yaml)
+- XSPEC-045: Cross-project specification
+- Depends on: Recovery Recipe Registry (XSPEC-046)
+- Borrowed from: [ultraworkers/claw-code](https://github.com/ultraworkers/claw-code) ROADMAP Phase 2 Failure Taxonomy