universal-dev-standards 5.8.0 → 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/behavior-snapshot.ai.yaml

@@ -4,38 +4,32 @@
 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
+  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.0.0"
-    updated: "2026-05-12"
+    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: 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: |
@@ -43,8 +37,9 @@ standard:
           Use for legitimately non-deterministic values: timestamps, tokens, IDs.
           Do NOT use to hide business logic differences.
 
-    example: |
+    http_example: |
       {
+        "adapter": "http",
         "feature_id": "FM-007",
         "scenario": "happy_path",
         "request": {
@@ -64,18 +59,108 @@ standard:
         "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/
+        FM-001-UserLogin/           ← http adapter
           happy_path.json
           invalid_credentials.json
-        FM-007-OrderCancellation/
+        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:
@@ -161,6 +246,25 @@ standard:
         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

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: