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

package/bundled/core/anti-sycophancy-prompting.md

@@ -0,0 +1,184 @@
+# Anti-Sycophancy Prompting Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/anti-sycophancy-prompting.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-04-15
+**Applicability**: All AI agent implementations and LLM prompt design
+**Scope**: universal
+**Industry Standards**: None (UDS original, informed by RLHF sycophancy research)
+
+---
+
+## Purpose
+
+This standard defines techniques and rules for designing prompts that elicit genuine, critical responses from LLMs rather than sycophantic agreement with the user's implied preferences.
+
+Sycophancy in LLMs originates from RLHF training objectives where human raters prefer agreeable responses, causing models to optimize for user satisfaction over accuracy.
+
+---
+
+## Core Techniques
+
+### 1. Socratic Critique Framework (REQ-1)
+
+Reframe the task from "evaluate my idea" to "attack my idea" to eliminate the incentive for sycophancy.
+
+| DO | DO NOT |
+|----|--------|
+| ✅ Ask for the 3 most fatal objections to the idea | ❌ Ask "is this a good idea?" |
+| ✅ Require each objection to be technically grounded | ❌ Allow vague positive framing |
+| ✅ Prohibit positive opening phrases | ❌ Accept "Great idea, but..." patterns |
+
+**Prompt Template**:
+```
+Do not evaluate whether this is good or bad.
+List the 3 most fatal objections to: [idea]
+Each objection must be technically grounded and non-trivial to dismiss.
+```
+
+---
+
+### 2. Anchor Prevention Protocol (REQ-2)
+
+Obtain the LLM's independent judgment before revealing the user's position, preventing anchoring bias.
+
+| Step | Action |
+|------|--------|
+| 1 | Ask for neutral comparison without revealing preference |
+| 2 | Receive independent judgment |
+| 3 | Reveal user's position |
+| 4 | Require explicit technical justification if model changes stance |
+
+**Workflow**:
+```
+Round 1: "Compare [A] vs [B] for [context]. Which is better?"
+→ Wait for independent judgment
+
+Round 2: "I prefer [A]. Does this change your assessment? Why?"
+→ Model must justify any position change with technical facts
+```
+
+---
+
+### 3. Symmetric Dual-Column Output (REQ-3)
+
+Use format constraints to force balanced presentation of opposing viewpoints.
+
+**Required Format**:
+```
+| Arguments FOR the decision | Arguments AGAINST the decision |
+|---------------------------|-------------------------------|
+| [Equal weight content]    | [Equal weight content]        |
+
+Net Recommendation: [Must take a clear stance, may recommend against]
+```
+
+**Rules**:
+- Both columns must have similar length (< 20% difference)
+- Net recommendation must be explicit and may be negative
+- Model cannot escape the format by padding one side
+
+---
+
+### 4. Confidence and Uncertainty Labeling (REQ-4)
+
+Require confidence scores on all recommendations to surface uncertainty.
+
+**Format**:
+```
+Recommendation: [specific action]
+Confidence: [1-5] — [reason for uncertainty]
+Unknown: [what information would change this assessment]
+```
+
+**Confidence Scale**:
+
+| Level | Meaning |
+|-------|---------|
+| 5 | Validated at similar scale, high certainty |
+| 4 | Industry standard with sufficient documentation |
+| 3 | Reasonable inference, PoC recommended |
+| 2 | Uncertain, Spike strongly recommended |
+| 1 | Highly uncertain, not recommended for direct adoption |
+
+**Rules**:
+- Confidence < 3 must include "More information needed before confirming"
+- All major claims require confidence labeling
+- Uncertainty must be actionable (specify what information resolves it)
+
+---
+
+### 5. Sycophancy Detection Heuristics (REQ-5)
+
+Heuristics for identifying sycophantic responses, usable in automated post-processing.
+
+| Signal Type | Detection Rule |
+|-------------|---------------|
+| Positive opener | Response starts with agreeable phrase within first 50 tokens (e.g., "great", "interesting", "certainly", "of course") |
+| Position flip | Model reverses stance after user reveals preference without new technical evidence |
+| Risk minimization | Pattern: "While there are some minor issues, overall..." without specifying the issues |
+| Missing quantification | Major recommendation lacks confidence score or specific metrics |
+
+**Trigger**: If 2+ signals detected → invoke re-evaluation with explicit Red Team framing.
+
+---
+
+## Prohibited Behaviors
+
+| Prohibited | Correct Action |
+|-----------|----------------|
+| Opening critique with positive affirmation | Start directly with the analysis |
+| Reversing stance without new technical evidence | Maintain position or cite specific new information |
+| Describing risks as "minor" without evidence | Quantify risk or explain why it is bounded |
+| Providing major recommendations without confidence | Always include confidence (1-5) and uncertainty statement |
+
+---
+
+## Integration with Agent Prompts
+
+When applying to AI agents:
+
+| Agent Type | Apply Rules |
+|------------|-------------|
+| Code Review Agent | REQ-1 (Socratic) + REQ-3 (Dual-column) + REQ-5 (Detection) |
+| Architecture Advisor Agent | REQ-2 (Anchor Prevention) + REQ-4 (Confidence) + REQ-5 (Detection) |
+| Bug Analysis Agent | REQ-1 (Socratic) + REQ-4 (Confidence) |
+| General Consultation Agent | REQ-3 (Dual-column) + REQ-4 (Confidence) |
+
+---
+
+## Complete Anti-Sycophancy Prompt Template
+
+```
+You are a domain expert with no emotional investment in my satisfaction.
+Your role is to identify flaws in my thinking, not to make me feel good.
+
+Rules:
+- Do NOT open with positive phrases (good, interesting, nice, certainly)
+- Every recommendation must include a confidence level (1-5) and what you are uncertain about
+- If my direction is wrong, say so directly
+
+My question: [question]
+
+First, list the incorrect assumptions I may be holding about this problem.
+Then give your honest recommendation.
+```
+
+---
+
+## Checklist
+
+- [ ] Prompt does not invite agreement ("is this good?")
+- [ ] Positive opening phrases explicitly prohibited
+- [ ] Model's independent stance obtained before revealing user preference (if applicable)
+- [ ] Dual-column format enforced for evaluation tasks
+- [ ] Confidence levels required on major recommendations
+- [ ] Sycophancy detection applied to output before presenting to user
+
+---
+
+## Related Standards
+
+- [anti-hallucination.md](anti-hallucination.md) — Prevents fabrication; complements anti-sycophancy
+- [agent-epistemic-calibration.md](agent-epistemic-calibration.md) — Epistemic humility in agent design (where applicable)

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