universal-dev-standards 5.7.2 → 5.8.0

package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml

@@ -59,9 +59,48 @@ standard:
         definition: AC has no tests
         criteria: No test case references this AC
 
+      - status: not_implemented
+        symbol: "🚫"
+        definition: AC has no corresponding implementation (feature code does not exist)
+        criteria: |
+          No business logic in src/ corresponds to this AC.
+          Distinct from uncovered: uncovered = code exists but no test; not_implemented = code does not exist.
+          Typical signals: throw NotImplementedException(), empty stub body, FEATURE_STUB: marker.
+        decision_tree: |
+          Q1: Does the corresponding code exist in src/?
+            No → not_implemented
+            Yes → Q2: Does any test reference this AC?
+              No → uncovered
+              Yes → Q3: Are all conditions in the AC tested?
+                Yes → covered
+                No → partial
+
     calculation:
-      formula: "AC Coverage % = (covered_count + partial_count × 0.5) / total_ac_count × 100"
-      note: Partial counts as 0.5 for coverage calculation
+      formula: "AC Coverage % = (covered_count + partial_count × 0.5) / (total_ac_count - not_implemented_count) × 100"
+      note: |
+        not_implemented ACs are excluded from the coverage denominator (separate dimension).
+        Partial counts as 0.5 for coverage calculation.
+        Example: 20 ACs total, 3 not_implemented, 15 covered, 2 uncovered →
+          coverage = (15 + 0) / (20 - 3) × 100 = 88.2%
+
+    ci_gate:
+      not_implemented_blocking: true
+      rule: "not_implemented_count > 0 → CI fails with [AC-NOT-IMPL] before UAT gate"
+      report_format: |
+        AC Traceability Report
+        ──────────────────────
+        🚫 NOT IMPLEMENTED (<count>) — BLOCKING
+          AC-007  OrderCancellation        src/orders/ 無對應實作
+          AC-012  RefundCalculation        src/payments/ 無對應實作
+
+        ❌ UNCOVERED (<count>) — WARNING
+          AC-003  BulkImport               test/import/ 缺測試
+
+        ✅ COVERED (<count>)
+        ⚠️  PARTIAL (<count>)
+
+        AC Coverage: <pct>% (<covered>/<implemented_total> implemented ACs)
+        Status: BLOCKED by <not_impl_count> not_implemented AC(s)
 
   quality_thresholds:
     defaults:
@@ -147,7 +186,14 @@ standard:
 
     - id: honest-status
       trigger: reporting AC coverage
-      instruction: Use honest status classification (covered/partial/uncovered); never inflate coverage
+      instruction: "Use honest status classification (covered/partial/uncovered/not_implemented); never inflate coverage"
+      priority: required
+
+    - id: not-implemented-gate
+      trigger: AC traceability matrix contains not_implemented status
+      instruction: |
+        Flag CI as BLOCKED with [AC-NOT-IMPL] message. List all not_implemented ACs.
+        not_implemented must be resolved before UAT. Exclude not_implemented from coverage denominator.
       priority: required
 
     - id: track-all-ac

package/bundled/ai/standards/behavior-snapshot.ai.yaml

@@ -0,0 +1,168 @@
+# Behavior Snapshot Standard - AI Optimized
+# Source: core/behavior-snapshot.md
+
+standard:
+  id: behavior-snapshot
+  name: Behavior Snapshot Standard
+  description: HTTP request/response golden file format for migration parity verification and refactoring characterization; defines snapshot schema, parity gate, and Gate 0 protocol
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-12"
+    source: core/behavior-snapshot.md
+    references:
+      - "XSPEC-201: Refactor/Migration Completeness Protocol"
+      - "Michael Feathers: Working Effectively with Legacy Code (characterization tests)"
+      - "Golden Master Testing pattern"
+
+  snapshot_schema:
+    description: Format of a single snapshot JSON file in .snapshots/<feature-id>/<scenario>.json
+    required_fields:
+      - name: feature_id
+        type: string
+        description: FM-NNN from feature-manifest.yaml
+      - name: scenario
+        type: string
+        description: "Scenario name (snake_case): happy_path, not_found, invalid_credentials, etc."
+      - name: request
+        type: object
+        fields:
+          method: "HTTP method (GET|POST|PUT|PATCH|DELETE)"
+          path: "URL path (no base URL)"
+          headers: "Optional request headers (omit auth tokens — use placeholder)"
+          body: "Optional request body (JSON)"
+      - name: response
+        type: object
+        fields:
+          status: "HTTP status code (integer)"
+          body: "Response body (JSON object)"
+      - name: ignore_fields
+        type: list
+        description: |
+          Fields to skip during parity comparison.
+          Use for legitimately non-deterministic values: timestamps, tokens, IDs.
+          Do NOT use to hide business logic differences.
+
+    example: |
+      {
+        "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"]
+      }
+
+  directory_structure:
+    root: ".snapshots/"
+    layout: ".snapshots/<feature-id>/<scenario>.json"
+    example: |
+      .snapshots/
+        FM-001-UserLogin/
+          happy_path.json
+          invalid_credentials.json
+        FM-007-OrderCancellation/
+          happy_path.json
+          order_not_found.json
+          MANUAL-refund_webhook.json
+    manual_prefix:
+      description: "Files prefixed MANUAL- contain manually authored snapshots (cannot be auto-recorded)"
+      examples:
+        - webhook endpoints triggered by third parties
+        - scenarios requiring specific database state
+        - background job/queue-triggered flows
+
+  ignore_fields_guidance:
+    always_ignore:
+      - created_at, updated_at, timestamp, recorded_at
+      - token, session_id, csrf_token, access_token, refresh_token
+      - request_id, trace_id, correlation_id
+    always_compare:
+      - status, code, message, error_code
+      - user_id, order_id (when using fixed test data)
+      - amount, quantity, price (business calculation results)
+      - "success, refunded, cancelled (boolean business outcomes)"
+
+  parity_gate:
+    description: CI gate comparing new system responses against recorded snapshots
+    tool: "npx tsx scripts/parity-check.ts --url <target-url> --snapshots .snapshots [--env <uat|staging>]"
+    pass_criteria: "100% of non-MANUAL snapshots must match (status + non-ignored body fields)"
+    failure_behavior:
+      uat_or_production: "Exit 1 — deployment blocked with [PARITY-BLOCK] message"
+      staging: "Exit 2 — warning only with [PARITY-WARN] message"
+    report_format: |
+      Parity Results: <passed>/<total> passed (<pct>%)
+        ✅ FM-001 / happy_path
+        ✅ FM-001 / invalid_credentials
+        ❌ [PARITY-FAIL] FM-007 / happy_path
+            body.order_status: expected "cancelled", got "pending"
+
+  gate_zero_protocol:
+    description: Characterization test gate for refactoring (XSPEC-201 Phase 1)
+    when: "--variant refactor in /vo-pipeline"
+    requirement: |
+      Characterization tests must exist and ALL pass before refactoring begins.
+      Characterization tests lock existing behavior — they do not test correctness,
+      they test that the behavior does not change during refactoring.
+    test_annotation: "@characterization or describe('characterization')"
+    enforcement: |
+      Gate 0: Run characterization tests before first refactoring commit.
+      Any failure during refactoring triggers immediate warning.
+      Gate 2: All characterization tests must pass before refactoring is considered complete.
+    anti_pattern: "Do NOT start refactoring without Gate 0 — behavior drift becomes undetectable"
+
+  rules:
+    - id: snapshot-before-migration
+      trigger: starting --variant migration pipeline
+      instruction: |
+        .snapshots/ must exist with at least one snapshot per feature before pipeline starts.
+        This is Gate 1b in the pre-flight check.
+      priority: required
+
+    - id: characterization-before-refactor
+      trigger: starting --variant refactor pipeline
+      instruction: |
+        Characterization tests must exist and pass before any refactoring begins.
+        If characterization tests don't exist, halt and prompt developer to write them.
+      priority: required
+
+    - id: ignore-fields-discipline
+      trigger: creating or reviewing snapshot ignore_fields
+      instruction: |
+        Only add fields to ignore_fields if they are legitimately non-deterministic
+        (timestamps, tokens, random IDs). Business logic fields must always be compared.
+        Overuse of ignore_fields defeats the purpose of parity testing.
+      priority: required
+
+    - id: manual-snapshots
+      trigger: snapshot cannot be auto-recorded
+      instruction: |
+        Prefix filename with MANUAL- and note why auto-recording is not possible.
+        MANUAL- snapshots must be authored by a human with full business knowledge.
+        They are excluded from auto-replay but count toward coverage reporting.
+      priority: recommended
+
+    - id: parity-100-before-uat
+      trigger: before UAT deployment in migration pipeline
+      instruction: |
+        Run parity check against all non-MANUAL snapshots.
+        100% pass rate required. Any failure blocks UAT deployment.
+        Fix parity failures before promoting — they represent behavioral divergence.
+      priority: required
+
+related_standards:
+  - feature-manifest-standard.ai.yaml
+  - acceptance-criteria-traceability.ai.yaml
+  - refactoring-standards.ai.yaml
+  - testing.ai.yaml

package/bundled/ai/standards/feature-manifest-standard.ai.yaml

@@ -0,0 +1,146 @@
+# Feature Manifest Standard - AI Optimized
+# Source: core/feature-manifest-standard.md
+
+standard:
+  id: feature-manifest-standard
+  name: Feature Manifest Standard
+  description: Machine-readable feature inventory format for migration and refactoring projects; defines FM-NNN schema, confidence scoring, and FEATURE_STUB hook protocol
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-12"
+    source: core/feature-manifest-standard.md
+    references:
+      - "XSPEC-200: Migration Feature Inventory and Completeness Gate"
+      - "XSPEC-201: Refactor/Migration Completeness Protocol"
+      - "XSPEC-199: AC not_implemented status"
+
+  manifest_schema:
+    description: Structure of feature-manifest.yaml for a migration or refactoring project
+    required_fields:
+      - name: manifest_version
+        type: string
+        value: "1.0"
+      - name: source_system
+        type: object
+        fields:
+          - language: source language (php, python, java, etc.)
+          - framework: source framework (laravel, django, spring, etc.)
+          - scan_date: ISO 8601 date
+          - scan_coverage: "<N>/<total> routes (100%)"
+      - name: features
+        type: list
+        item_schema:
+          - id: "FM-NNN (zero-padded 3 digits)"
+          - name: "PascalCase feature name"
+          - description: "Plain language description of business purpose"
+          - http_method: "GET|POST|PUT|PATCH|DELETE (null for non-HTTP)"
+          - route: "URL path or null for CLI/background"
+          - controller: "ClassName::methodName"
+          - confidence: "0.0–1.0 (see confidence_scoring)"
+          - side_effects: "list of DB_READ|DB_WRITE|EMAIL|QUEUE|HTTP_CALL|FILE"
+          - migration_risks: "list of risk labels (see migration_risks)"
+          - ac_id: "null initially; set by Planner"
+          - status: "not_implemented (initial value for all migration features)"
+
+  confidence_scoring:
+    description: How to assign confidence values during inventory
+    levels:
+      - value: 1.0
+        meaning: Feature name and business purpose are unambiguous from code
+        example: "UserLogin method in AuthController with clear JWT response"
+      - value: 0.8
+        meaning: Feature name is reasonable but business purpose requires inference
+        example: "process() method with database write — likely a form submission"
+      - value: 0.5
+        meaning: Likely an infrastructure/utility method, not a primary business feature
+        example: "HealthCheck, CorsMiddleware, LoggingFilter"
+      - value: 0.3
+        meaning: Unclear — requires human confirmation before generating AC
+        example: "handle() method with no context, generic catch-all route"
+    human_review_threshold: 0.5
+    human_review_rule: "All features with confidence < 0.5 MUST be reviewed by a human before AC generation"
+
+  migration_risks:
+    description: Risk labels for migration to target language
+    php_to_csharp:
+      - label: SESSION_HANDLING
+        description: PHP session → ASP.NET Core Session/Cookie middleware
+      - label: ORM_DIFFERENCES
+        description: Eloquent ORM → Entity Framework behavioral differences
+      - label: TIMEZONE_HANDLING
+        description: PHP timezone functions → .NET DateTimeOffset
+      - label: FILE_UPLOAD_PATH
+        description: PHP $_FILES superglobal → ASP.NET Core IFormFile
+      - label: REGEX_DIFFERENCES
+        description: PHP PCRE syntax vs .NET Regex syntax differences
+      - label: ARRAY_FUNCTIONS
+        description: PHP array_* functions → LINQ equivalents
+      - label: EXCEPTION_HIERARCHY
+        description: PHP exception hierarchy vs .NET exception hierarchy differences
+    generic:
+      - label: ASYNC_MODEL
+        description: Sync code → async/await migration required
+      - label: NULL_SEMANTICS
+        description: Null handling differences between source and target language
+      - label: STRING_ENCODING
+        description: String encoding/collation differences
+
+  feature_stub_protocol:
+    description: How to use FEATURE_STUB markers in target codebase (XSPEC-200)
+    format: "// FEATURE_STUB: <FM-ID> <FeatureName> — <AC-ID> pending"
+    example: |
+      // FEATURE_STUB: FM-007 OrderCancellation — AC-007 pending
+      public async Task<Result> CancelOrderAsync(string orderId) {
+          throw new NotImplementedException();
+      }
+    rules:
+      - "One FEATURE_STUB per FM-ID in the target codebase"
+      - "FEATURE_STUB is removed when implementation is complete and AC status updated"
+      - "FEATURE_STUB blocks CI gate (same as WARNING:STUB) — blocks main branch push and UAT/prod deploy"
+      - "FEATURE_STUB is distinct from WARNING:STUB: FEATURE_STUB = code never existed; WARNING:STUB = temp fake logic"
+
+  completeness_gate:
+    description: Pipeline gates enforced by this manifest (XSPEC-200)
+    gate_1:
+      name: Manifest Existence Gate
+      trigger: Before /vo-pipeline --variant migration starts
+      rule: "artifacts/feature-manifest.yaml must exist and .snapshots/ must exist"
+      failure_message: "Run /vo-inventory and /vo-snapshot before starting migration pipeline"
+    gate_not_implemented:
+      name: Feature Completeness Gate
+      trigger: CI before UAT deployment
+      rule: "No features in manifest may have status: not_implemented AND corresponding FEATURE_STUB in codebase"
+      failure_message: "[FEATURE-INCOMPLETE] N features still not implemented. See feature-manifest.yaml."
+
+  rules:
+    - id: manifest-before-migration
+      trigger: starting a migration pipeline
+      instruction: |
+        Require feature-manifest.yaml before generating AC or writing code.
+        All features start with status: not_implemented.
+        Planner generates AC from manifest entries.
+      priority: required
+
+    - id: confidence-review
+      trigger: feature-manifest.yaml has features with confidence < 0.5
+      instruction: |
+        Halt AC generation for low-confidence features.
+        Present list to human for review before proceeding.
+        Human must confirm feature name, purpose, and whether it's in scope.
+      priority: required
+
+    - id: stub-lifecycle
+      trigger: implementing a feature from manifest
+      instruction: |
+        When implementation is complete:
+        1. Remove FEATURE_STUB: marker from code
+        2. Update manifest status from not_implemented to implemented
+        3. Update AC traceability status from not_implemented to uncovered or covered
+      priority: required
+
+related_standards:
+  - acceptance-criteria-traceability.ai.yaml
+  - behavior-snapshot.ai.yaml
+  - spec-driven-development.ai.yaml
+  - refactoring-standards.ai.yaml

package/bundled/core/acceptance-criteria-traceability.md

@@ -83,28 +83,60 @@ Scenario: User login with valid credentials
 | **Covered** | ✅ | AC is fully tested | All conditions in AC have corresponding test assertions |
 | **Partial** | ⚠️ | AC is partially tested | Some conditions tested, but edge cases or paths missing |
 | **Uncovered** | ❌ | AC has no tests | No test case references this AC |
+| **Not Implemented** | 🚫 | AC has no corresponding implementation | Feature code does not exist (not a test gap — a code gap) |
+
+### `not_implemented` vs `uncovered` Decision Tree
+
+```
+Q1: Does the corresponding code exist in src/?
+  No → 🚫 not_implemented
+  Yes → Q2: Does any test reference this AC?
+    No → ❌ uncovered
+    Yes → Q3: Are all conditions in the AC tested?
+      Yes → ✅ covered
+      No → ⚠️ partial
+```
+
+Typical signals of `not_implemented`: `throw new NotImplementedException()`, empty stub body, `// FEATURE_STUB:` marker.
 
 ### Coverage Calculation
 
 ```
-AC Coverage % = (covered_count / total_ac_count) × 100
+AC Coverage % = (covered_count + partial_count × 0.5) / (total_ac_count - not_implemented_count) × 100
 
 Where:
   covered_count = count of AC with status "covered"
   total_ac_count = total number of AC in specification
+  not_implemented_count = count of AC with status "not_implemented" (excluded from denominator)
   partial counts as 0.5 for coverage calculation
 ```
 
 ### Example Calculation
 
 ```
-SPEC-001: 8 AC total
-  - 5 covered (✅)
-  - 2 partial (⚠️)
-  - 1 uncovered (❌)
+SPEC-001: 20 AC total
+  - 15 covered (✅)
+  - 0 partial (⚠️)
+  - 2 uncovered (❌)
+  - 3 not_implemented (🚫)
+
+Coverage = (15 + 0) / (20 - 3) × 100 = 88.2%
+Status: BLOCKED by 3 not_implemented AC(s)
+```
+
+### CI Gate for `not_implemented`
+
+`not_implemented` ACs trigger a **blocking** CI gate independent of the coverage percentage gate:
 
-Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
 ```
+[AC-NOT-IMPL] 3 AC(s) marked not_implemented:
+  🚫 AC-007  OrderCancellation
+  🚫 AC-012  RefundCalculation
+  🚫 AC-019  ExportToPDF
+All not_implemented ACs must be resolved before UAT.
+```
+
+The gate clears only when all `not_implemented` ACs are updated to `uncovered`, `partial`, or `covered`.
 
 ---
 
@@ -273,6 +305,8 @@ Generated spec MUST include:
 | Ignoring uncovered AC | Gaps in verification | Track and plan coverage for all AC |
 | AC without testability | Cannot be verified | Ensure all AC are testable |
 | Coverage without assertions | Tests run but verify nothing | Check for meaningful assertions |
+| Using `uncovered` for missing code | Hides functional completeness gap | Use `not_implemented` when code doesn't exist |
+| Including `not_implemented` in denominator | Inflates coverage metric | Exclude `not_implemented` from denominator |
 
 ---
 
@@ -291,3 +325,4 @@ Generated spec MUST include:
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2026-03-18 | Initial version — traceability matrix, coverage calculation, spec generation rules |
+| 1.1.0 | 2026-05-12 | Add `not_implemented` 4th status; update CI gate formula; add decision tree (XSPEC-199) |