universal-dev-standards 5.7.3 → 5.8.0

package/bundled/core/behavior-snapshot.md

@@ -0,0 +1,239 @@
+# Behavior Snapshot Standard
+
+> **Language**: English | 繁體中文
+
+**Applicability**: Migration and refactoring projects requiring behavioral parity verification
+**Scope**: universal (HTTP-based systems)
+
+---
+
+## Overview
+
+The Behavior Snapshot Standard defines a golden-file format for recording HTTP request/response pairs from an existing system. These snapshots serve two purposes:
+
+1. **Migration parity baseline** — verify the new system reproduces the same behavior as the old system
+2. **Refactoring characterization** — lock existing behavior before changing code (Gate 0 protocol)
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| XSPEC-201 | Refactor/Migration Completeness Protocol |
+| Michael Feathers: *Working Effectively with Legacy Code* | Characterization test concept |
+| Golden Master Testing | Pattern for recording and replaying expected outputs |
+
+---
+
+## Snapshot File Format
+
+### Location
+
+```
+.snapshots/<feature-id>/<scenario>.json
+```
+
+### Schema
+
+```json
+{
+  "feature_id": "FM-007",
+  "scenario": "happy_path",
+  "request": {
+    "method": "POST",
+    "path": "/api/orders/123/cancel",
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "body": {
+      "reason": "customer_request"
+    }
+  },
+  "response": {
+    "status": 200,
+    "body": {
+      "success": true,
+      "order_status": "cancelled",
+      "refund_initiated": true
+    }
+  },
+  "ignore_fields": ["refund_id", "cancelled_at"]
+}
+```
+
+### Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `feature_id` | Yes | `FM-NNN` from feature-manifest.yaml |
+| `scenario` | Yes | `snake_case` scenario name (`happy_path`, `not_found`, etc.) |
+| `request.method` | Yes | HTTP method |
+| `request.path` | Yes | URL path without base URL |
+| `request.headers` | No | Headers needed for the request (no real auth tokens) |
+| `request.body` | No | Request body (JSON) |
+| `response.status` | Yes | Expected HTTP status code |
+| `response.body` | Yes | Expected response body (fields to compare) |
+| `ignore_fields` | No | Fields to skip during comparison (see guidance below) |
+
+---
+
+## Directory Structure
+
+```
+.snapshots/
+  FM-001-UserLogin/
+    happy_path.json
+    invalid_credentials.json
+    account_locked.json
+  FM-007-OrderCancellation/
+    happy_path.json
+    order_not_found.json
+    order_already_cancelled.json
+    MANUAL-refund_webhook.json     ← manually authored
+```
+
+### MANUAL- Prefix
+
+Files prefixed `MANUAL-` contain snapshots that cannot be automatically recorded:
+- Webhook endpoints triggered by third parties
+- Scenarios requiring specific, hard-to-reproduce database state
+- Background job / queue-triggered flows (non-HTTP entry points)
+
+`MANUAL-` files are excluded from automated replay but are counted in coverage reporting.
+
+---
+
+## `ignore_fields` Guidance
+
+### Always Ignore (Non-Deterministic)
+
+| Field Pattern | Reason |
+|--------------|--------|
+| `created_at`, `updated_at`, `timestamp` | Changes every request |
+| `token`, `session_id`, `csrf_token` | Cryptographically random |
+| `request_id`, `trace_id`, `correlation_id` | Random UUID |
+
+### Always Compare (Business Logic)
+
+| Field Pattern | Reason |
+|--------------|--------|
+| `status`, `code`, `message`, `error_code` | Core business outcome |
+| `order_status`, `payment_status` | State machine result |
+| `amount`, `quantity`, `price` | Calculated business value |
+| `success`, `refunded`, `cancelled` | Boolean business outcome |
+| `user_id`, `order_id` (with fixed test data) | Referential integrity |
+
+**Rule**: `ignore_fields` is for legitimately non-deterministic values. Using it to hide business logic differences defeats the purpose of parity testing.
+
+---
+
+## Parity Check Tool
+
+Run `scripts/parity-check.ts` to replay all snapshots against a target system:
+
+```bash
+npx tsx scripts/parity-check.ts --url http://new-system:8080 [--snapshots .snapshots] [--env uat|staging]
+```
+
+### Output
+
+```
+🔄 Parity Check — 119 snapshots against http://new-system:8080
+
+  ✅ FM-001 / happy_path
+  ✅ FM-001 / invalid_credentials
+  ❌ [PARITY-FAIL] FM-007 / happy_path
+      body.order_status: expected "cancelled", got "pending"
+      body.refund_initiated: expected true, got false
+
+─────────────────────────────────
+Parity Results: 118/119 passed (99.2%)
+
+❌ 1 parity check(s) failed.
+[PARITY-BLOCK] UAT/production deployment blocked. Fix parity failures first.
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All snapshots pass |
+| 1 | Failures found + `--env uat` or `production` → deployment blocked |
+| 2 | Failures found + `--env staging` → warning only |
+
+---
+
+## Gate 0: Characterization Test Protocol (Refactoring)
+
+Before starting any refactoring, characterization tests must exist and pass.
+
+### What Are Characterization Tests?
+
+Characterization tests record what the existing code *actually does* — not what it *should* do. They lock observable behavior before changes begin. If a characterization test fails during refactoring, it signals unintended behavior change.
+
+```typescript
+describe('characterization: OrderService.cancelOrder', () => {
+  // @characterization
+  it('returns status cancelled and sets refund_initiated=true for valid order', async () => {
+    const result = await orderService.cancelOrder('test-order-123', 'customer_request');
+    expect(result.order_status).toBe('cancelled');
+    expect(result.refund_initiated).toBe(true);
+  });
+});
+```
+
+### Gate 0 Enforcement
+
+1. **Before first refactoring commit**: Run `npm test -- --grep characterization`
+   - Any failure → STOP. Fix the existing code before changing it.
+2. **During refactoring**: Every commit re-runs characterization tests
+   - Any failure → immediate warning of behavior drift
+3. **Gate 2 (completion)**: All characterization tests pass → refactoring complete
+
+### Anti-Pattern Warning
+
+> Never start refactoring without Gate 0. Once you start changing code, it becomes impossible to tell whether a test failure is "I broke something" or "the test was wrong about old behavior."
+
+---
+
+## Integration with Migration Pipeline
+
+### Gate 1 Pre-Flight (`--variant migration`)
+
+Before `/vo-pipeline --variant migration`:
+1. `artifacts/feature-manifest.yaml` must exist
+2. `.snapshots/` must contain at least one snapshot per feature
+
+### Parity Gate (Before UAT)
+
+After all features are implemented, run parity check:
+- 100% pass rate required (excluding `MANUAL-` files)
+- Any failure blocks UAT promotion
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Impact | Correct Approach |
+|--------------|--------|------------------|
+| Overusing `ignore_fields` | Business logic differences hidden | Only ignore non-deterministic fields |
+| Skipping MANUAL snapshots | Untested webhook/background behavior | Author MANUAL snapshots before UAT |
+| Recording snapshots from broken system | Wrong baseline | Verify old system behavior before recording |
+| Characterization tests without `@characterization` | Gate 0 can't find them | Always annotate with `@characterization` |
+| Starting refactoring before Gate 0 | Behavior drift undetectable | Run characterization tests first, always |
+
+---
+
+## Related Standards
+
+- [Feature Manifest Standard](feature-manifest-standard.md) — FM-NNN schema for manifest features
+- [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) — `not_implemented` AC status
+- [Refactoring Standards](refactoring-standards.md) — Characterization test requirements
+- [Testing Standards](testing-standards.md) — Test implementation standards
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-05-12 | Initial version — snapshot schema, parity gate, Gate 0 characterization protocol (XSPEC-201) |

package/bundled/core/feature-manifest-standard.md

@@ -0,0 +1,213 @@
+# Feature Manifest Standard
+
+> **Language**: English | 繁體中文
+
+**Applicability**: Migration and refactoring projects where an existing system is being ported or restructured
+**Scope**: universal (language-agnostic manifest format)
+
+---
+
+## Overview
+
+The Feature Manifest Standard defines a machine-readable format (`feature-manifest.yaml`) for cataloguing all features of an existing system before migration or refactoring begins. It provides a structured bridge between the legacy system's capabilities and the new system's acceptance criteria, enabling tools (VibeOps `/vo-pipeline --variant migration`) to enforce completeness gates automatically.
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| XSPEC-200 | Migration Feature Inventory and Completeness Gate |
+| XSPEC-201 | Refactor/Migration Completeness Protocol |
+| XSPEC-199 | AC `not_implemented` status extension |
+
+---
+
+## When to Use
+
+Use `feature-manifest.yaml` when:
+- Migrating a system from one language/framework to another (e.g., PHP → C# .NET)
+- Porting a legacy system to a new architecture
+- Starting a major refactoring where existing behavior must be preserved
+
+**Do not use** for greenfield development — the manifest is a reflection of an existing system, not a design document.
+
+---
+
+## Feature Manifest Format
+
+### File Location
+
+```
+artifacts/feature-manifest.yaml
+```
+
+### Top-Level Structure
+
+```yaml
+manifest_version: "1.0"
+source_system:
+  language: php
+  framework: laravel
+  scan_date: "2026-05-12"
+  scan_coverage: "47/47 routes (100%)"
+
+features:
+  - id: FM-001
+    name: UserLogin
+    # ... (see Feature Entry below)
+```
+
+### Feature Entry Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | `FM-NNN` (zero-padded) |
+| `name` | string | Yes | PascalCase business feature name |
+| `description` | string | Yes | Plain language description of business purpose |
+| `http_method` | string | No | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`; `null` for CLI/background |
+| `route` | string | No | URL path; `null` for CLI/background |
+| `controller` | string | Yes | `ClassName::methodName` |
+| `confidence` | float | Yes | 0.0–1.0 (see Confidence Scoring) |
+| `side_effects` | list | Yes | `DB_READ`, `DB_WRITE`, `EMAIL`, `QUEUE`, `HTTP_CALL`, `FILE` |
+| `migration_risks` | list | No | Risk labels (see Migration Risks) |
+| `ac_id` | string | No | `null` initially; set by Planner after manifest creation |
+| `status` | string | Yes | Always `not_implemented` initially |
+
+### Complete Feature Entry Example
+
+```yaml
+features:
+  - id: FM-007
+    name: OrderCancellation
+    description: 取消訂單並觸發退款流程
+    http_method: POST
+    route: /api/orders/{id}/cancel
+    controller: OrderController::cancel
+    confidence: 0.9
+    side_effects:
+      - DB_WRITE
+      - QUEUE
+    migration_risks:
+      - ORM_DIFFERENCES
+    ac_id: null
+    status: not_implemented
+```
+
+---
+
+## Confidence Scoring
+
+| Value | Meaning | Action |
+|-------|---------|--------|
+| 1.0 | Feature name and business purpose are unambiguous | Proceed to AC generation |
+| 0.8 | Feature name is reasonable, purpose requires inference | Proceed with note |
+| 0.5 | Likely infrastructure/utility, not primary business feature | Flag for human review |
+| 0.3 | Unclear — cannot determine business purpose | **Halt; human must confirm** |
+
+**Rule**: All features with `confidence < 0.5` must be reviewed by a human before Planner generates AC.
+
+---
+
+## Migration Risks
+
+### PHP → C# .NET
+
+| Label | Description |
+|-------|-------------|
+| `SESSION_HANDLING` | PHP `$_SESSION` → ASP.NET Core Session/Cookie middleware |
+| `ORM_DIFFERENCES` | Eloquent ORM vs Entity Framework behavioral differences |
+| `TIMEZONE_HANDLING` | PHP timezone functions → .NET `DateTimeOffset` |
+| `FILE_UPLOAD_PATH` | PHP `$_FILES` → ASP.NET Core `IFormFile` |
+| `REGEX_DIFFERENCES` | PHP PCRE syntax vs .NET `System.Text.RegularExpressions` |
+| `ARRAY_FUNCTIONS` | PHP `array_*` functions → LINQ equivalents |
+| `EXCEPTION_HIERARCHY` | PHP exception hierarchy vs .NET exception hierarchy |
+
+### Generic
+
+| Label | Description |
+|-------|-------------|
+| `ASYNC_MODEL` | Sync code → async/await migration |
+| `NULL_SEMANTICS` | Null handling differences |
+| `STRING_ENCODING` | String encoding/collation differences |
+
+---
+
+## FEATURE_STUB Marker Protocol
+
+When implementing features from the manifest in the target codebase, use `FEATURE_STUB:` markers as placeholders:
+
+### Format
+
+```
+// FEATURE_STUB: <FM-ID> <FeatureName> — <AC-ID> pending
+```
+
+### Example (C#)
+
+```csharp
+// FEATURE_STUB: FM-007 OrderCancellation — AC-007 pending
+public async Task<Result<OrderDto>> CancelOrderAsync(string orderId, CancellationReason reason)
+{
+    throw new NotImplementedException();
+}
+```
+
+### FEATURE_STUB vs WARNING:STUB
+
+| Marker | Semantic | When to Use |
+|--------|----------|-------------|
+| `// WARNING: STUB` | Temporary fake logic (code runs but behavior is wrong) | Placeholder with incorrect business logic |
+| `// FEATURE_STUB:` | Feature not yet implemented (no logic at all) | Feature from manifest that hasn't been coded yet |
+
+**Both markers block CI** (main branch push and UAT/production deployment).
+
+### Lifecycle
+
+1. Feature added to manifest with `status: not_implemented`
+2. Developer adds `FEATURE_STUB:` placeholder in target code
+3. Developer implements the feature, removes `FEATURE_STUB:` marker
+4. Update manifest `status` → `implemented`
+5. Update AC traceability `status` → `uncovered` or `covered`
+
+---
+
+## Completeness Gates
+
+### Gate 1 (Pre-Pipeline)
+
+Before `/vo-pipeline --variant migration` starts:
+- `artifacts/feature-manifest.yaml` must exist
+- `.snapshots/` directory must exist with at least one JSON file
+
+### Feature Completeness Gate (Pre-UAT)
+
+CI blocks UAT deployment if:
+- Any feature in manifest has `status: not_implemented` AND
+- Corresponding `FEATURE_STUB:` exists in codebase
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Impact | Correct Approach |
+|--------------|--------|------------------|
+| Starting migration without manifest | Feature gaps discovered in UAT | Always generate manifest first |
+| Skipping low-confidence features | Silent functional omissions | Review and confirm all features |
+| Using `uncovered` instead of `not_implemented` | CI doesn't block on missing features | Use `not_implemented` when code doesn't exist |
+| Not removing `FEATURE_STUB:` after implementation | False "incomplete" signal in CI | Always clean up markers after implementation |
+
+---
+
+## Related Standards
+
+- [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) — `not_implemented` AC status
+- [Behavior Snapshot Standard](behavior-snapshot.md) — HTTP parity baseline recording
+- [Refactoring Standards](refactoring-standards.md) — Characterization tests for refactoring
+- [Spec-Driven Development](spec-driven-development.md) — AC generation workflow
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-05-12 | Initial version — FM-NNN schema, confidence scoring, FEATURE_STUB protocol (XSPEC-200) |

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.7.3
-translation_version: 5.7.3
-last_synced: 2026-05-08
+source_version: 5.8.0
+translation_version: 5.8.0
+last_synced: 2026-05-12
 status: current
 ---
 
@@ -17,6 +17,15 @@ status: current
 
 ## [Unreleased]
 
+## [5.8.0] - 2026-05-12
+
+### 新增
+- **`feature-manifest-standard`**（`ai/standards/feature-manifest-standard.ai.yaml`、`core/feature-manifest-standard.md`）：新增标准，定义迁移/重构项目的 FM-NNN 机器可读功能清单格式。含信心评分、迁移风险标签（PHP→C#）、`FEATURE_STUB:` 标记协议与 Gate 1 完整性闸门。（XSPEC-200）
+- **`behavior-snapshot`**（`ai/standards/behavior-snapshot.ai.yaml`、`core/behavior-snapshot.md`）：新增标准，定义 HTTP 金文件快照格式，用于迁移等价性验证与重构特征化测试。含快照结构、`ignore_fields` 指引、parity gate exit codes 与 Gate 0 特征化测试协议。（XSPEC-201）
+
+### 变更
+- **`acceptance-criteria-traceability`**：新增第 4 个 AC 状态 `not_implemented`（🚫）——区分「代码不存在」与 `uncovered`（代码存在但无测试）。更新覆盖率公式（分母排除 `not_implemented`）。新增 CI blocking gate：`not_implemented_count > 0` → blocking（独立于覆盖率 % gate）。新增状态分类决策树。（XSPEC-199）
+
 ## [5.7.3] - 2026-05-08
 
 ### 修复

package/bundled/locales/zh-CN/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 5.7.3 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.8.0 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.7.3
-translation_version: 5.7.3
-last_synced: 2026-05-08
+source_version: 5.8.0
+translation_version: 5.8.0
+last_synced: 2026-05-12
 status: current
 ---
 
@@ -17,6 +17,15 @@ status: current
 
 ## [Unreleased]
 
+## [5.8.0] - 2026-05-12
+
+### 新增
+- **`feature-manifest-standard`**（`ai/standards/feature-manifest-standard.ai.yaml`、`core/feature-manifest-standard.md`）：新增標準，定義移植/重構專案的 FM-NNN 機器可讀功能盤點格式。含信心評分、移植風險標籤（PHP→C#）、`FEATURE_STUB:` 標記協議與 Gate 1 完整性閘門。（XSPEC-200）
+- **`behavior-snapshot`**（`ai/standards/behavior-snapshot.ai.yaml`、`core/behavior-snapshot.md`）：新增標準，定義 HTTP 金文件快照格式，用於移植同等性驗證與重構特徵化測試。含快照結構、`ignore_fields` 指引、parity gate exit codes 與 Gate 0 特徵化測試協議。（XSPEC-201）
+
+### 修改
+- **`acceptance-criteria-traceability`**：新增第 4 個 AC 狀態 `not_implemented`（🚫）——區分「程式碼不存在」與 `uncovered`（程式碼存在但無測試）。更新覆蓋率公式（分母排除 `not_implemented`）。新增 CI blocking gate：`not_implemented_count > 0` → blocking（獨立於覆蓋率 % gate）。新增狀態分類決策樹。（XSPEC-199）
+
 ## [5.7.3] - 2026-05-08
 
 ### 修復

package/bundled/locales/zh-TW/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 5.7.3 | **發布日期**: 2026-04-13 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.8.0 | **發布日期**: 2026-04-13 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。