universal-dev-standards 5.7.3 → 5.10.0

package/bundled/ai/language-packs/README.md

@@ -0,0 +1,55 @@
+# UDS Language Packs
+
+Language packs provide migration risk labels for specific source→target language pairs.
+They extend the core `feature-manifest-standard` without polluting the core standard.
+
+## Naming Convention
+
+```
+language-pack-<source>-to-<target>.ai.yaml
+```
+
+Examples:
+- `language-pack-php-to-csharp.ai.yaml`
+- `language-pack-java-to-go.ai.yaml`
+- `language-pack-python-to-rust.ai.yaml`
+
+## Available Language Packs
+
+| Pack | Source | Target | Labels |
+|------|--------|--------|--------|
+| [language-pack-php-to-csharp.ai.yaml](language-pack-php-to-csharp.ai.yaml) | PHP | C# (ASP.NET Core) | SESSION_HANDLING, ORM_DIFFERENCES, TIMEZONE_HANDLING, FILE_UPLOAD_PATH, REGEX_DIFFERENCES, ARRAY_FUNCTIONS, EXCEPTION_HIERARCHY |
+
+## Usage
+
+Reference language pack risk labels in `feature-manifest.yaml` alongside generic labels:
+
+```yaml
+features:
+  - id: FM-001
+    name: UserLogin
+    migration_risks:
+      - SESSION_HANDLING   # from language-pack-php-to-csharp
+      - NULL_SEMANTICS     # from generic risks (feature-manifest-standard)
+      - ASYNC_MODEL        # from generic risks
+```
+
+## Generic vs Language Pack Labels
+
+| Type | Source | When to use |
+|------|--------|-------------|
+| Generic | `feature-manifest-standard.migration_risks.generic` | All migration projects |
+| Language Pack | `ai/language-packs/<pack>.ai.yaml` | Specific source→target pairs |
+
+## Creating a New Language Pack
+
+1. Copy the structure from an existing pack
+2. Replace `source`, `target`, and `migration_risks` with the new pair's specifics
+3. Each risk label should have: `label`, `description`, `details` (optional but recommended)
+4. Submit via pull request to UDS with evidence from real migration projects
+
+## Architecture Decision
+
+Language packs were separated from the core `feature-manifest-standard` in UDS v1.1.0
+(XSPEC-203) to keep the core standard language-agnostic. See `ai/standards/feature-manifest-standard.ai.yaml`
+`migration_risks.language_packs` for the extension point declaration.

package/bundled/ai/language-packs/language-pack-php-to-csharp.ai.yaml

@@ -0,0 +1,83 @@
+# Language Pack: PHP → C# (ASP.NET Core) Migration Risks
+# Migrated from: feature-manifest-standard v1.0.0 core standard
+# Use with: feature-manifest.yaml features[].migration_risks
+
+language_pack:
+  id: php-to-csharp
+  source: php
+  target: csharp
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-13"
+    description: PHP to C# (ASP.NET Core) migration risk labels
+    migrated_from: "feature-manifest-standard v1.0.0 migration_risks.php_to_csharp"
+    references:
+      - "XSPEC-203: Language Pack Architecture"
+
+  migration_risks:
+    - label: SESSION_HANDLING
+      description: PHP session → ASP.NET Core Session/Cookie middleware differences
+      details: |
+        PHP sessions are file-backed by default and rely on PHPSESSID cookie.
+        ASP.NET Core uses IDistributedCache (Redis/SQL) backed sessions.
+        Check: session_start(), $_SESSION usage → ISession / IDistributedCache
+
+    - label: ORM_DIFFERENCES
+      description: Eloquent ORM → Entity Framework behavioral differences (lazy loading, conventions)
+      details: |
+        Eloquent uses ActiveRecord pattern; EF Core uses DataMapper/Unit of Work.
+        Lazy loading is opt-in in EF Core (vs default in Eloquent).
+        Check: Model relationships, ->with() eager loading, timestamps conventions
+
+    - label: TIMEZONE_HANDLING
+      description: PHP timezone functions → .NET DateTimeOffset handling
+      details: |
+        PHP date() and strtotime() are timezone-sensitive via date_default_timezone_set().
+        .NET uses DateTimeOffset for timezone-aware datetimes; DateTime is ambiguous.
+        Check: date(), strtotime(), Carbon usage → DateTimeOffset, TimeZoneInfo
+
+    - label: FILE_UPLOAD_PATH
+      description: PHP $_FILES superglobal → ASP.NET Core IFormFile interface
+      details: |
+        PHP uses $_FILES superglobal with move_uploaded_file().
+        ASP.NET Core uses IFormFile with CopyToAsync() and streaming.
+        Check: $_FILES, move_uploaded_file(), file validation logic
+
+    - label: REGEX_DIFFERENCES
+      description: PHP PCRE syntax vs .NET Regex syntax differences
+      details: |
+        PHP uses PCRE with delimiters (e.g., '/pattern/i'); .NET has no delimiters.
+        Named groups: PHP (?P<name>) vs .NET (?<name>).
+        Unicode properties and some PCRE extensions differ.
+        Check: preg_match(), preg_replace(), preg_split() usage
+
+    - label: ARRAY_FUNCTIONS
+      description: PHP array_* functions → LINQ equivalents
+      details: |
+        PHP array functions are procedural; .NET uses LINQ extension methods.
+        array_map() → .Select(); array_filter() → .Where(); array_reduce() → .Aggregate()
+        array_unique() → .Distinct(); usort() → .OrderBy()
+        Check: array_map, array_filter, array_reduce, usort, array_column usage
+
+    - label: EXCEPTION_HIERARCHY
+      description: PHP exception hierarchy vs .NET exception hierarchy differences
+      details: |
+        PHP: Exception → RuntimeException → InvalidArgumentException etc.
+        .NET: Exception → SystemException / ApplicationException → specific types
+        PHP allows catching multiple types with | (PHP 8+); .NET uses catch blocks.
+        Check: try/catch blocks, custom exception classes, exception type mapping
+
+  usage_example: |
+    # In feature-manifest.yaml:
+    features:
+      - id: FM-001
+        name: UserLogin
+        migration_risks:
+          - SESSION_HANDLING    # from this language pack
+          - NULL_SEMANTICS      # from generic risks (feature-manifest-standard)
+
+      - id: FM-007
+        name: OrderCancellation
+        migration_risks:
+          - ORM_DIFFERENCES     # from this language pack
+          - ASYNC_MODEL         # from generic risks

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,272 @@
+# Behavior Snapshot Standard - AI Optimized
+# Source: core/behavior-snapshot.md
+
+standard:
+  id: behavior-snapshot
+  name: Behavior Snapshot Standard
+  description: Multi-modal golden file format for migration parity verification and refactoring characterization; supports HTTP, CLI, File, and Event adapters; defines snapshot schema, parity gate, and Gate 0 protocol
+
+  meta:
+    version: "1.1.0"
+    updated: "2026-05-13"
+    source: core/behavior-snapshot.md
+    references:
+      - "XSPEC-201: Refactor/Migration Completeness Protocol"
+      - "XSPEC-203: Language Pack Architecture (multi-modal adapter extension)"
+      - "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: adapter
+        type: string
+        description: "Snapshot adapter type: http (default) | cli | file | event"
+        default: "http"
+        backward_compat: "Omitting adapter field is equivalent to adapter: http — existing snapshots remain valid"
+      - 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: 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.
+
+    http_example: |
+      {
+        "adapter": "http",
+        "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"]
+      }
+
+  adapters:
+    description: Adapter schemas for different software interaction types. Choose based on how the feature interacts with the outside world.
+
+    http:
+      description: HTTP request/response adapter — for web services and REST APIs (default)
+      fields:
+        request:
+          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)"
+        response:
+          status: "HTTP status code (integer)"
+          body: "Response body (JSON object)"
+      when_to_use: "Feature is triggered by HTTP request and returns HTTP response"
+
+    cli:
+      description: CLI tool adapter — for command-line tools, scripts, and batch processors
+      fields:
+        args: "Command arguments array (excluding the program name itself)"
+        stdin: "Standard input string (null if the command reads no stdin)"
+        stdout: "Expected standard output string"
+        stderr: "Expected standard error string (empty string if none expected)"
+        exit_code: "Expected exit code (integer: 0 = success)"
+      when_to_use: "Feature is invoked via command-line arguments and produces stdout/stderr output"
+      example: |
+        {
+          "adapter": "cli",
+          "feature_id": "FM-012",
+          "scenario": "convert_csv_to_json",
+          "args": ["convert", "--input", "data.csv", "--format", "json"],
+          "stdin": null,
+          "stdout": "{\"rows\": 42, \"status\": \"ok\"}",
+          "stderr": "",
+          "exit_code": 0,
+          "ignore_fields": []
+        }
+
+    file:
+      description: File I/O adapter — for batch processors, report generators, and data pipelines
+      fields:
+        input_files: "List of input file descriptors: {path, content_hash}"
+        output_files: "List of expected output file descriptors: {path, content_hash}"
+      content_hash_format: "sha256:<hex> — use fixtures for deterministic input; capture hash from reference run for expected output"
+      when_to_use: "Feature reads input files and produces output files (no HTTP or CLI interaction)"
+      example: |
+        {
+          "adapter": "file",
+          "feature_id": "FM-015",
+          "scenario": "generate_monthly_report",
+          "input_files": [
+            { "path": "fixtures/sales_2026_04.csv", "content_hash": "sha256:abc123" }
+          ],
+          "output_files": [
+            { "path": "output/report_2026_04.pdf", "content_hash": "sha256:def456" }
+          ],
+          "ignore_fields": []
+        }
+
+    event:
+      description: Event/message adapter — for event-driven systems, message queues, and daemons
+      fields:
+        trigger: "The triggering event or message: {type, queue/topic, payload}"
+        expected_state_changes: "List of expected database/state changes: {entity, field, from, to}"
+        expected_side_effects: "List of expected side effects using standard labels: EMAIL_SENT, QUEUE_MESSAGE_PUBLISHED, FILE_WRITTEN, HTTP_CALL_MADE"
+      when_to_use: "Feature is triggered by an event/message and produces state changes or side effects"
+      example: |
+        {
+          "adapter": "event",
+          "feature_id": "FM-020",
+          "scenario": "order_placed_triggers_inventory_deduction",
+          "trigger": {
+            "type": "message",
+            "queue": "orders.placed",
+            "payload": { "order_id": "ORD-001", "product_id": "PROD-007", "quantity": 1 }
+          },
+          "expected_state_changes": [
+            { "entity": "inventory", "field": "quantity", "from": 10, "to": 9 }
+          ],
+          "expected_side_effects": ["EMAIL_SENT", "QUEUE_MESSAGE_PUBLISHED"],
+          "ignore_fields": ["processed_at", "message_id"]
+        }
+
+  directory_structure:
+    root: ".snapshots/"
+    layout: ".snapshots/<feature-id>/<scenario>.json"
+    example: |
+      .snapshots/
+        FM-001-UserLogin/           ← http adapter
+          happy_path.json
+          invalid_credentials.json
+        FM-007-OrderCancellation/   ← http adapter
+          happy_path.json
+          order_not_found.json
+          MANUAL-refund_webhook.json
+        FM-012-ConvertCsv/          ← cli adapter
+          convert_csv_to_json.json
+          missing_input_file.json
+        FM-015-MonthlyReport/       ← file adapter
+          generate_monthly_report.json
+        FM-020-InventoryDeduction/  ← event adapter
+          order_placed_triggers_inventory_deduction.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
+
+    - id: adapter-selection
+      trigger: creating a behavior snapshot
+      instruction: |
+        Select the adapter matching the feature's interaction type.
+        Use http ONLY for actual HTTP endpoint features.
+        Use cli for command-line tool features.
+        Use file for batch I/O and report generation features.
+        Use event for message-driven and daemon features.
+        When in doubt about which adapter to use, refer to the adapters section's when_to_use fields.
+      priority: required
+
+    - id: backward-compatibility
+      trigger: reading existing snapshot files without adapter field
+      instruction: |
+        Treat snapshot files missing the adapter field as adapter=http.
+        Do NOT require migration of existing snapshot files to add adapter field.
+        New snapshots should always include the adapter field explicitly.
+      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/deployment-standards.ai.yaml

@@ -12,10 +12,13 @@ standard:
     - "Automate build, test, deploy, and rollback"
 
   meta:
-    version: "1.0.0"
-    updated: "2026-02-09"
+    version: "1.1.0"
+    updated: "2026-05-13"
     source: core/deployment-standards.md
-    description: Safe deployment strategies, feature flags, rollback, environment parity, and DORA metrics
+    description: >
+      Safe deployment strategies, feature flags, rollback, environment parity, and DORA metrics.
+      v1.1.0: Added environment stratification responsibility matrix and stub server CI/CD
+      lifecycle rules (XSPEC-204).
 
   principles:
     core:
@@ -125,6 +128,108 @@ checklist:
     medium_term_24hr: ["Batch jobs successful", "Data consistency verified", "No memory leaks"]
     long_term_1wk: ["Flag cleanup scheduled", "Retrospective completed", "Docs updated"]
 
+# ─────────────────────────────────────────────────────────
+# Environment Stratification Responsibility Matrix (v1.1.0)
+# ─────────────────────────────────────────────────────────
+environment_stratification_matrix:
+  rule: >
+    Projects with external dependencies MUST build an environment stratification
+    responsibility matrix at test-planning time (not at release candidate review).
+    This matrix answers: "Which test flows can be fully verified in which environment?"
+  when_required: "Any project with external service dependencies (SMS, payment, IdP, messaging, etc.)"
+  where: "docs/testing/environment-stratification-matrix.md or in the test plan"
+
+  template: |
+    ## Environment Stratification Responsibility Matrix
+
+    | Flow / Feature         | local UAT        | Remote UAT       | PRD                |
+    |------------------------|:----------------:|:----------------:|:------------------:|
+    | Auth / Login           | ✅ stub IdP      | ✅ Keycloak/AD   | ✅ Enterprise IdP  |
+    | SMS Sending            | ⚠️ L2-stub       | ❌ / ⚠️          | ✅ Real + billing  |
+    | Payment / Purchase     | ⚠️ L2-stub       | ⚠️ network-dep   | ✅ Real + reconcile|
+    | User / Dept Management | ✅               | ✅ cross-machine  | ✅                 |
+    | Background Jobs        | ✅ in-process    | ✅               | ✅                 |
+
+    Legend:
+    ✅ Full E2E verification possible
+    ⚠️ Flow passes through stub/mock — real-world dimensions NOT verified
+    ❌ Cannot test in this environment layer
+
+    ### PRD-only verification items (must plan PRD smoke test coverage)
+    - SMS billing correctness
+    - Payment real debit + bank reconciliation
+    - Enterprise AD group sync behavior
+
+  mandatory_rule: >
+    This matrix MUST be reviewed at test planning stage alongside
+    acceptance-criteria-traceability. It is NOT acceptable to discover
+    PRD-only verification items for the first time during release candidate review.
+
+# ─────────────────────────────────────────────────────────
+# Stub Server CI/CD Lifecycle Rules (v1.1.0)
+# ─────────────────────────────────────────────────────────
+stub_server_cicd_rules:
+  rationale: >
+    Production CI/CD artifacts commonly exclude stub server directories for valid
+    security reasons (e.g., MockSoap/, tests/stub-server/ excluded from build.ps1).
+    Without explicit rules, this creates an undocumented "UAT cannot test X" situation
+    that is discovered too late in the release cycle.
+
+  build_time:
+    rules:
+      - "Production artifact MUST exclude all stub server code directories"
+      - "Exclusion rule MUST be documented in docs/uat/STUB-EXCLUSION-RATIONALE.md"
+      - "CI build verification step MUST confirm stub directories are absent from artifact"
+    example_ps1: |
+      # build.ps1 — explicit exclusion with documentation comment
+      # Stub server excluded from production artifact (see docs/uat/STUB-EXCLUSION-RATIONALE.md)
+      # Consequence: UAT machine cannot run SMS/MMS flow without sidecar deployment (see Option A below)
+      $exclude = @("MockSoap", "tests/stub-server", "test-fixtures")
+
+  uat_deployment:
+    rule: "Choose Option A or Option B; document the choice; do NOT leave it undocumented"
+    options:
+      option_a_sidecar_deploy:
+        name: "Sidecar Deployment (Recommended)"
+        description: >
+          Stub server deployed as separate process to UAT machine;
+          application configured via env var to reach the stub endpoint.
+        benefit: "Decoupled from app artifact; independently updatable"
+        example_github_actions: |
+          deploy-stub-server:
+            environment: uat
+            steps:
+              - name: Deploy stub server to UAT
+                run: |
+                  ssh uat-machine "cd /opt/stub-server && pm2 start server.js --name stub-server"
+              - name: Configure app to use stub
+                run: echo "SMS_ENDPOINT=http://uat-machine:9999/soap" >> $GITHUB_ENV
+        example_gitlab_ci: |
+          deploy-stub-server:
+            stage: deploy
+            environment: uat
+            script:
+              - ssh uat-machine "pm2 start tests/stub-server/server.js --name stub-server"
+            only: [uat-branch, tags]
+
+      option_b_prd_smoke_deferral:
+        name: "PRD Smoke Deferral"
+        description: >
+          Document which flows cannot be tested in UAT; explicitly mark them as
+          PRD-smoke-only items. These items must appear in the environment stratification matrix.
+        requirement: "Must be reflected as ❌ in environment stratification matrix with PRD smoke plan"
+
+  prd_prohibitions:
+    - "MUST NOT deploy or run stub servers in PRD environment"
+    - "MUST NOT include stub server code in PRD artifact"
+    - "MUST NOT allow network access to stub server endpoints from PRD"
+
+  forbidden_state: >
+    It is NEVER acceptable to have "no stub server AND no real service AND no documented
+    deferral" for a testable flow. Every flow must be either:
+    (a) fully testable in UAT via real service or Level 2 stub server, OR
+    (b) explicitly documented as PRD-smoke-only with a smoke test plan.
+
 physical_spec:
   type: custom_script
   validator: