universal-dev-standards 5.17.0 → 6.1.0

package/bundled/ai/standards/data-migration-testing.ai.yaml

@@ -3,10 +3,10 @@
 
 id: data-migration-testing
 meta:
-  version: "1.0.0"
-  updated: "2026-05-05"
+  version: "1.1.0"
+  updated: "2026-06-27"
   source: core/data-migration-testing.md
-  description: Database migration up/down/idempotency testing standards for schema changes
+  description: Database migration up/down/idempotency testing standards for schema changes, plus encoding-conversion and aggregate-invariant testing for cross-encoding/cross-engine migrations
 
 requirements:
   REQ-1:
@@ -63,6 +63,33 @@ requirements:
       Shared migration state between tests causes non-deterministic failures that are
       extremely difficult to diagnose.
 
+  REQ-6:
+    id: REQ-DMT-006
+    title: Encoding Conversion Test
+    rule: >
+      Migrations that cross encodings or DB engines (e.g. UTF-8 -> UTF-16/NVARCHAR,
+      VARCHAR -> NVARCHAR, or an implicit collation change) MUST include a test that
+      asserts equality at the BYTE / codepoint / normalization level — not display
+      level. Cover NFC vs NFD normalization, multi-byte boundaries, and CJK / emoji /
+      combining marks (supplementary-plane codepoints).
+    rationale: >
+      Two different byte or normalization sequences can decode to glyphs that look
+      identical, so a display-level (toBe) assertion passes while the stored bytes —
+      and downstream LIKE / unique-key / collation behavior — are silently corrupted.
+
+  REQ-7:
+    id: REQ-DMT-007
+    title: Aggregate Invariant Test
+    rule: >
+      Migrations of business-critical data MUST capture aggregate invariants
+      (COUNT(*), SUM(column), COUNT(DISTINCT key), checksum) grouped by a business
+      dimension BEFORE the migration and assert they are unchanged AFTER. Same oracle
+      as post-cutover production reconciliation, run at migration-test time.
+    rationale: >
+      Row-by-row sampling proves individual rows survived but not that the distribution
+      survived; a single wrong SUM/COUNT/DISTINCT flags drift that any sample missing
+      the affected rows would not catch.
+
 test_structure:
   isolation: "Each migration test MUST run against an isolated in-memory or temp DB"
   baseline: "Start from the schema state immediately before the migration under test"
@@ -71,6 +98,48 @@ test_structure:
     down: "Assert schema returns to pre-migration state"
     idempotency: "Apply migration twice; second apply must succeed without error"
     data: "Seed rows before migration; assert row count and values after"
+    encoding: "Assert byte/codepoint/normalization identity (Buffer compare + spread-to-codepoints + normalize), NOT display-level toBe; cover NFC/NFD, multi-byte boundaries, CJK/emoji/combining marks"
+    aggregate: "Capture COUNT/SUM/COUNT(DISTINCT)/checksum grouped by business dimension before; assert deep-equal after"
+
+cross_dialect_risks:
+  description: "SQLite -> SQL Server semantic disagreements; derive-list input for encoding/aggregate tests and the non-HTTP implicit-rule scan"
+  rows:
+    - point: Type system
+      sqlite: Dynamic typing (per-value affinity)
+      sqlserver: Static / strong typing
+      verify: Declare per-column type; scan for out-of-range / mixed-type values
+    - point: Boolean
+      sqlite: Stored as 0/1 integer
+      sqlserver: BIT
+      verify: 0/1 <-> BIT mapping; NULL boolean handling
+    - point: Date/time
+      sqlite: TEXT / REAL / INTEGER
+      sqlserver: datetime2 / datetimeoffset
+      verify: Format parse, time-zone, precision truncation
+    - point: Auto-increment PK
+      sqlite: AUTOINCREMENT
+      sqlserver: IDENTITY
+      verify: Existing id continuity; correct seed/reseed
+    - point: Case / collation
+      sqlite: LIKE case-insensitive by default / NOCASE
+      sqlserver: Determined by column collation
+      verify: Align collation; check unique-key folding collisions
+    - point: NULL ordering
+      sqlite: NULLs sort first (smallest)
+      sqlserver: Depends on configuration
+      verify: ORDER BY result-order invariant
+    - point: Float precision
+      sqlite: REAL
+      sqlserver: float / decimal
+      verify: Move money/exact values to decimal to avoid rounding error
+    - point: String concat
+      sqlite: "||"
+      sqlserver: "+ / CONCAT"
+      verify: Rewrite queries; reconcile NULL-concat semantics
+    - point: Pagination
+      sqlite: LIMIT / OFFSET
+      sqlserver: OFFSET..FETCH / TOP
+      verify: Rewrite + stable sort key for deterministic pages
 
 tooling_guidance:
   sqlite: "Use ':memory:' DSN; apply migrations via ORM migrate() or raw SQL"
@@ -89,6 +158,13 @@ anti_patterns:
   - description: >
       Writing migration tests after the fact without seeding data — misses the
       data preservation class of bugs entirely.
+  - description: >
+      Asserting string equality only on the decoded value — display-level equality
+      passes even when bytes, normalization form, or codepoints were corrupted across
+      an encoding/engine change.
+  - description: >
+      Validating a cross-engine migration with row sampling alone — distribution-level
+      drift (a wrong SUM/COUNT/DISTINCT) escapes any sample that misses the affected rows.
 
 related_standards:
   - testing

package/bundled/ai/standards/deprecation-standards.ai.yaml

@@ -3,8 +3,8 @@
 
 id: deprecation-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-03-31"
+  version: "1.1.0"
+  updated: "2026-06-24"
   source: core/deprecation-standards.md
   description: API deprecation, feature sunset, system decommission lifecycle
 
@@ -21,6 +21,14 @@ api_deprecation:
     sunset: "Sunset: Sat, 31 Dec 2026 23:59:59 GMT"
     successor: 'Link: <url>; rel="successor-version"'
   parallel_period: "≥6 months after new GA, or 3 months after last consumer migrates"
+  # Single source of truth for deprecation periods (consolidated from versioning.md,
+  # XSPEC-298 R8 / UDS #126). Sunset timeline above = default public-API cadence.
+  # Apply the LONGER of the tier minimum and parallel_period.
+  minimum_period_by_tier:
+    internal_api: "1 minor version"
+    partner_api: "2 minor versions + 3 months"
+    public_api: "2 minor versions + 6 months"
+    critical_infrastructure: "1 year minimum"
 
 notification_channels:
   - "CHANGELOG / Release Notes"

package/bundled/ai/standards/developer-memory.ai.yaml

@@ -13,8 +13,8 @@ standard:
     - "Respect noise control levels and cooldown periods"
 
   meta:
-    version: "1.0.0"
-    updated: "2026-02-07"
+    version: "1.1.0"
+    updated: "2026-06-18"
     source: core/developer-memory.md
     description: Structured system for capturing, retrieving, and surfacing developer experience insights across conversations and projects
 
@@ -115,7 +115,8 @@ standard:
       bonus_rules:
         - "3 consecutive valid: bonus +0.05"
         - "3 consecutive invalid: flag for review"
-        - "confidence < 0.2: flag for retirement"
+        - "confidence < 0.2: flag for retirement (repeatedly invalidated = noise)"
+        - "not surfaced 180+ days AND confidence < 0.5: flag for retirement (dormant + low confidence; 180d matches staleness model; UDS default, configurable)"
         - "confidence > 0.9 after 10+ uses: mark proven"
 
     review:

package/bundled/ai/standards/documentation-writing-standards.ai.yaml

@@ -3,7 +3,7 @@
 
 id: documentation-writing-standards
 meta:
-  version: "1.1.0"
+  version: "1.2.0"
   updated: "2026-03-17"
   source: core/documentation-writing-standards.md
   description: Documentation requirements based on project types (enhanced ADR, LLM writing, quality metrics, translation-friendly)

package/bundled/ai/standards/flow-based-testing.ai.yaml

@@ -3,8 +3,8 @@
 
 id: flow-based-testing
 meta:
-  version: "1.0.0"
-  updated: "2026-05-04"
+  version: "1.0.1"
+  updated: "2026-06-18"
   source: core/flow-based-testing.md
   description: Flow decomposition methodology for testing multi-step processes with branch coverage
 

package/bundled/ai/standards/forward-derivation-standards.ai.yaml

@@ -3,8 +3,8 @@
 
 id: forward-derivation
 meta:
-  version: "1.1.0"
-  updated: "2026-04-01"
+  version: "1.3.0"
+  updated: "2026-06-18"
   source: core/forward-derivation-standards.md
   description: Standards for deriving BDD, TDD, IT, E2E, ATDD, and Contract tests from approved SDD specifications
 
@@ -134,6 +134,21 @@ anti_hallucination:
     - Inventing test cases beyond AC scope
     - Fabricating edge cases not specified
 
+# Failure handling (failure -> rollback -> retry/escalate -> re-verify)
+failure_handling:
+  description: What happens when a derivation gate fails; recovery always ends by re-verifying the failed gate
+  matrix:
+    - failure: AC parse error (unsupported format)
+      action: Abort that AC, report file:line + expected GWT/bullet format, emit no skeleton, re-queue after SPEC fix
+    - failure: AC count mismatch (tests != ACs)
+      action: "[anti-hallucination] hard rollback + regenerate strict 1:1; never add/delete tests to match the count"
+    - failure: Skeleton does not parse/compile
+      action: Roll back the file and regenerate with the correct template; on a 2nd failure mark the AC [BLOCKED] and escalate
+    - failure: Human review rejection
+      action: Record the reason and regenerate only the rejected items with that feedback; never auto-approve
+    - failure: Missing @SPEC/@AC attribution
+      action: Block the transition into TDD RED and re-emit with attribution
+
 # Commands
 commands:
   - command: "/derive-bdd"
@@ -167,6 +182,15 @@ commands:
 
 # Rules for AI
 rules:
+  - id: fd-fail-gate-halts
+    instruction: A gate failure must halt progression; never enter TDD RED with an unresolved failure
+    priority: required
+  - id: fd-fail-count-hard-rollback
+    instruction: A test/AC count mismatch is a hard rollback, not a reconciliation; never add or delete tests to match the count
+    priority: required
+  - id: fd-fail-bounded-retry-escalate
+    instruction: Bound automated retries (max 2 for transient/template errors); on exhaustion mark the AC [BLOCKED] and escalate to a human
+    priority: required
   - id: approved-spec-only
     instruction: Only derive from approved specifications
     priority: required

package/bundled/ai/standards/frontend-design-standards.ai.yaml

@@ -1,17 +1,20 @@
 # Frontend Design Standards - AI Optimized
 # Source: core/frontend-design-standards.md
 # Based on: DEC-029 (awesome-design-md, MIT), DEC-030 (OpenAI Frontend Guide)
-# Version: 1.0.0
+# Version: 1.1.0
 
 id: frontend-design-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-04-13"
+  version: "1.1.0"
+  updated: "2026-07-10"
   source: core/frontend-design-standards.md
   description: |
     DESIGN.md 前端設計標準：9 段結構、語義色彩 token、字體角色、
     間距比例、UI 硬性約束與 anti-pattern 清單。
     適用所有含前端介面的專案。
+    v1.1.0 新增選填擴充：YAML frontmatter token 註冊表 +
+    {category.token} 內插語法 + components 結構化綁定
+    （借鑑 DEC-029 上游演化，Trial，不影響既有 5-token 治理收斂）。
 
 # DESIGN.md 必填 9 段結構
 design_md_sections:
@@ -78,6 +81,24 @@ design_md_sections:
     description: "AI Agent 快速讀取的設計意圖摘要"
     required_fields: [style_summary, key_constraints, tone]
 
+# 選填擴充：token 內插語法 + 結構化 components 綁定（v1.1.0，Trial）
+# 不影響上方 5-token/4-role/7-step 治理收斂；是既有 token 的機器可解析層，非新增 token 的許可證。
+optional_extensions:
+  token_interpolation:
+    status: optional_trial
+    description: "DESIGN.md 可選填 YAML frontmatter 宣告 colors/typography/rounded/spacing token 字典，正文用 {category.token} 語法引用"
+    frontmatter_keys: [colors, typography, rounded, spacing]
+    syntax: "{category.token}"
+    rule: "frontmatter 的 colors 必須對應 5 個必要語義 token；引用不存在的 category.token 視為驗證錯誤，非靜默 fallback"
+  structured_components:
+    status: optional_trial
+    description: "Section 4（Component Styling）可選填 components: 區塊，把元件綁定到 {category.token} 引用"
+    rule: "components: 區塊內每個值都必須是 {category.token} 引用，禁止直接寫 hex/px 原始值"
+  not_adopted:
+    - "不隨附 lint CLI（上游有獨立 @google/design.md npm 套件，本標準不綁定特定驗證工具）"
+    - "不做框架專屬匯出格式（React/Vue/CSS-in-JS 產生器）"
+    - "不擴增 5/4/7 token 數量（內插語法讓既有 token 可引用，不是加 token 的理由）"
+
 # 語義色彩 5 個必要 token
 semantic_color_tokens:
   required:
@@ -265,6 +286,15 @@ rules:
       禁止將首頁設計成 Dashboard Grid。
     priority: required
 
+  - id: respect-token-interpolation-if-present
+    trigger: "當 DESIGN.md 含 YAML frontmatter token 註冊表時（v1.1.0 選填擴充）"
+    instruction: |
+      解析 {category.token} 引用時一律對照 frontmatter 實際值，
+      不得憑記憶或猜測填入色值/尺寸。
+      引用不存在的 category.token 視為錯誤，向使用者回報而非靜默略過。
+      若 DESIGN.md 沒有 frontmatter，此規則不適用（擴充為選填，非強制）。
+    priority: recommended
+
 # 快速參考表
 quick_reference:
   semantic_tokens:

package/bundled/ai/standards/full-coverage-testing.ai.yaml

@@ -8,8 +8,8 @@ standard:
   description: Behavior-completeness full coverage paradigm replacing pyramid thresholds. Enforces anti-fake-test rules, STUB marker protocol, ratchet CI, and @ac traceability.
 
   meta:
-    version: "1.0.0"
-    updated: "2026-05-06"
+    version: "1.1.0"
+    updated: "2026-06-17"
     source: core/full-coverage-testing.md
     replaces: "testing pyramid thresholds (UT≥80%/IT≥70%/E2E happy-path-only)"
     xspec: "XSPEC-178"
@@ -191,6 +191,38 @@ standard:
       - "Anti-fake rules: no tautology, no business-logic mocks"
       - "STUB protocol: deployment gates on all environments"
 
+  # XSPEC-288: Migration Error-Path Completeness (axis 9 of XSPEC-284 completeness matrix)
+  # The three-path model requires an error path PER FUNCTION; this adds the migration
+  # guarantee that legacy error/degradation/fallback branches are SYSTEMATICALLY carried
+  # over, not merely sampled. Systematic-enumeration + gap-analysis layer above the
+  # XSPEC-201 error-path snapshot.
+  migration_error_path_completeness:
+    axis: "9 (error paths) of XSPEC-284 migration completeness matrix"
+    why_gap: "Per-function error path + XSPEC-201 snapshot verify only enumerated error cases. A rewrite drops scattered error branches in bulk; a passing sample does not prove no branch was missed."
+    derive: # R1 mechanized legacy exception/error-code list
+      sources:
+        catch_blocks: "grep catch/except/rescue -> every caught exception type + handler"
+        exception_hierarchy: "custom exception/error class taxonomy"
+        error_codes: "HTTP status, app error codes, error enums"
+        error_shapes: "error serializers/DTOs -> on-the-wire error contract"
+      note: "Captured list is the error-path to-verify checklist, sourced from artifacts not recall."
+    gap_analysis: # R2 systematic missing-branch oracle
+      rule: "for EACH legacy error branch verify a corresponding new-system handler; no mapping -> not_implemented (XSPEC-199) -> BLOCK"
+      output: "missing-error-branch gap report over the full derived list, not a passing sample"
+    degradation_parity: # R3
+      checklist: [external_failure_fallback, retry_policy, partial_result_handling, circuit_breaker_timeout]
+      goal: "not consistent on happy path but wildly different on failure"
+    error_response_differential: # R4
+      extends: "behavior-snapshot parity + XSPEC-284 R5 replay, applied to the ERROR response"
+      compare: [error_code, message_structure, http_status]
+    importance_ranking: "rank by production-actual trigger frequency (#134 production is the oracle); fired-in-prod branches mapped first; a high-frequency prod error branch with no mapping is a hard block"
+    gate_timing: [pre-UAT, "cutover before/after"]
+    completeness_declaration:
+      derive: "Step1 mechanized exception/error-code list"
+      oracle: "Step2 systematic gap analysis + Step4 error-response differential"
+      gate_timing: "pre-UAT + cutover before/after"
+      reuse: "XSPEC-201 error-path snapshot + three-path model; adds only systematic missing-branch analysis + error-response differential"
+
 physical_spec:
   type: custom_script
   validator:

package/bundled/ai/standards/git-worktree.ai.yaml

@@ -8,8 +8,8 @@ standard:
   description: Git Worktree 隔離開發標準
 
   meta:
-    version: "1.0.0"
-    updated: "2026-03-20"
+    version: "1.1.0"
+    updated: "2026-06-18"
     source: core/git-worktree.md
     description: Git Worktree 隔離開發與生命週期管理標準
     inspired_by: superpowers/using-git-worktrees
@@ -54,7 +54,7 @@ standard:
       priority: critical
     - id: GW-002
       trigger: "基準測試失敗"
-      action: "中止任務，報告環境問題"
+      action: "先重試至多 2 次（指數退避）以排除暫時性失敗；若持續失敗則中止任務並報告環境問題"
       priority: high
     - id: GW-003
       trigger: "異常退出"

package/bundled/ai/standards/logging.ai.yaml

@@ -3,10 +3,26 @@
 
 id: logging
 meta:
-  version: "1.3.0"
-  updated: "2026-05-26"
+  version: "1.4.0"
+  updated: "2026-06-17"
   source: core/logging-standards.md
-  description: Logging levels, structured logging, file rotation policy, and best practices
+  description: Logging levels, structured logging, mandatory events catalog, file rotation policy, and best practices
+
+# XSPEC-070 Phase 2 — skill↔standard content-coverage audit.
+# Consumed by scripts/check-skill-content-coverage.ts: the anchor skill
+# (logging-guide) MUST mention each mandatory event id below, or CONTENT-002 fires.
+# Source of truth: core/logging-standards.md "Mandatory Events" catalog (9 canonical events).
+audit:
+  mandatory_keywords:
+    - application_startup
+    - request_received
+    - validation_failure
+    - authentication_failure
+    - outbound_call_start
+    - outbound_call_complete
+    - business_event
+    - heartbeat
+    - shutdown
 
 log_levels:
   ordered:
@@ -51,6 +67,69 @@ structured_logging:
   field_naming: snake_case
   format: JSON in production
 
+# When you MUST write a log entry (XSPEC-234 / closes #108).
+# Compliant formatting but silent-at-the-critical-moment logging is excluded.
+mandatory_events:
+  - id: application_startup
+    when: After process boot, before accepting requests
+    level: INFO
+    must_log: [app_name, version, git_sha, environment, hostname, pid, listening_endpoints]
+    must_not_log: [secrets, full_connection_strings]
+    rationale: Lifecycle blind spot; confirms which build/config is actually live
+  - id: request_received
+    when: First time HTTP middleware sees a request
+    level: INFO/DEBUG
+    must_log: [method, path, source_ip, request_id]
+    must_not_log: [request_body, auth_headers]
+    rationale: Establishes request_id correlation from the edge inward
+  - id: validation_failure
+    when: schema / ModelState / DTO validation rejects
+    level: WARN
+    must_log: [request_id, path, missing_fields, payload_shape]
+    must_not_log: [field_values, pii]
+    rationale: Framework rejects before handler; payload otherwise never logged (incident #2)
+  - id: authentication_failure
+    when: login / token verification fails
+    level: WARN
+    must_log: [uid_attempted, source_ip, failure_reason]
+    must_not_log: [password, token_value]
+    rationale: 'Account or password error alone is un-investigable without uid/IP (incident #3)'
+  - id: outbound_call_start
+    when: An outbound HTTP/RPC call is initiated
+    level: INFO
+    must_log: [target_url_host_path, request_id_propagated, timeout_ms]
+    must_not_log: [credentials, bearer_tokens]
+    rationale: A send-failed error must leave a trace that the call was even attempted
+  - id: outbound_call_complete
+    when: An external call returns or fails
+    level: INFO/WARN/ERROR
+    must_log: [status_code_or_failure_phase, elapsed_ms, retries]
+    must_not_log: [response_body_with_pii]
+    rationale: Distinguish dns/tcp/tls/http failure phase for diagnosis
+  - id: business_event
+    when: A state-changing business operation completes
+    level: INFO
+    must_log: [operation_name, actor, target_ids, outcome]
+    must_not_log: [full_record_payload, pii]
+    rationale: Audit trail of what changed and by whom
+  - id: heartbeat
+    when: Long-running background service, at least once per 60 seconds
+    level: INFO
+    must_log: [service_name, queue_depth, items_processed_since_last_heartbeat]
+    must_not_log: []
+    rationale: Detect silent/0-byte background worker; enables silence detection (incident #4)
+  - id: shutdown
+    when: Process exits (graceful or fatal)
+    level: INFO/ERROR
+    must_log: [app_name, signal_or_reason, uptime_seconds, pending_work_count]
+    must_not_log: []
+    rationale: Lifecycle blind spot; reveals crash vs graceful and lost in-flight work
+
+mandatory_events_follow_on_rules:
+  access_log_separation: Health-probe/liveness traffic MUST NOT pollute business-event log (separate sink)
+  silence_detection_sla: Alert after N minutes with no events, N <= 2x heartbeat interval
+  request_id_discoverability: Error responses to client SHOULD carry request_id for support correlation
+
 sensitive_data:
   never_log:
     - passwords
@@ -80,6 +159,19 @@ rules:
     instruction: Use structured JSON logging with required fields
     priority: required
 
+  - id: mandatory-events
+    trigger: implementing startup/shutdown, request handling, validation, auth, outbound calls, background services
+    instruction: |
+      Emit the mandatory events catalog entries (see mandatory_events):
+      application_startup, request_received, validation_failure,
+      authentication_failure, outbound_call_start, outbound_call_complete,
+      business_event, heartbeat, shutdown. A log that follows every formatting
+      rule but never fires at the critical moment is excluded. Validation rejects
+      MUST log payload_shape (keys only, not values); auth failures MUST log
+      uid+source_ip (never password/token); background services MUST heartbeat
+      so silence is detectable.
+    priority: required
+
   - id: include-context
     trigger: logging operations
     instruction: Include request_id or trace_id for correlation
@@ -185,9 +277,11 @@ quick_reference:
 
 enforcement:
   hook_type: PostToolUse
+  trigger: PostToolUse
   matcher:
     tool: Write
     path: "src/**/*.ts"
   script_ref: "scripts/hooks/check-logging-standard.js"
+  hook_script: "scripts/hooks/check-logging-standard.js"
   severity: warning
   timeout_ms: 500

package/bundled/ai/standards/mock-boundary.ai.yaml

@@ -3,14 +3,17 @@
 
 id: mock-boundary
 meta:
-  version: "1.1.0"
-  updated: "2026-05-13"
+  version: "1.2.0"
+  updated: "2026-07-01"
   source: core/mock-boundary.md
   description: >
     Rules defining what can and cannot be mocked to prevent hollow tests —
     tests that pass while the real system is broken.
     v1.1.0: Added Level 1/Level 2 mock layer distinction and external
     dependency testability matrix template (XSPEC-204).
+    v1.2.0: Added injectable background execution as a seam (parallel to clock
+    injection) — allowed background-runner seam, no-poll/sleep rule, and the
+    poll/sleep-for-background-result anti-pattern (issue #143).
 
 # ─────────────────────────────────────────────────────────
 # Mock Levels (v1.1.0)
@@ -150,6 +153,31 @@ allowed:
       // 1. The DB layer has its own integration tests
       // 2. The service test focuses on service logic (not DB behavior)
 
+  - category: In-Process Background Execution (via injectable runner)
+    description: >
+      Fire-and-forget dispatch — Task.Run, unawaited promises, setTimeout,
+      goroutines, thread-pool/executor submission, asyncio.create_task
+    reason: >
+      Background dispatch is a seam, exactly like the system clock. Inject a
+      runner so the test can drive the work to deterministic, awaited completion
+      and assert on success/exception/retry — instead of polling or sleeping.
+    implementation: >
+      Abstract dispatch behind a small interface (e.g. IBackgroundTaskRunner /
+      BackgroundDispatcher). Production keeps true fire-and-forget semantics;
+      the test double runs the work inline and tracks the Task/promise, exposing
+      a handle the test can await before asserting.
+    example: |
+      // Production: real fire-and-forget — returns immediately, work runs detached
+      class FireAndForgetDispatcher implements BackgroundDispatcher {
+        dispatch(work: () => Promise<void>): void { void work() }
+      }
+      // Test: inline + tracked so the test can await deterministic completion
+      class DeterministicDispatcher implements BackgroundDispatcher {
+        private tasks: Promise<void>[] = []
+        dispatch(work: () => Promise<void>): void { this.tasks.push(work()) }
+        async settle(): Promise<void> { await Promise.all(this.tasks) }
+      }
+
 # ─────────────────────────────────────────────────────────
 # Forbidden Mocks
 # ─────────────────────────────────────────────────────────
@@ -253,6 +281,15 @@ anti_patterns:
     description: DB mock returns hardcoded data, hiding query logic errors
     problem: Schema migrations, wrong predicates, missing joins — all invisible
 
+  - name: Poll/Sleep for Background Result
+    description: >
+      Sleeping or polling to wait for in-process fire-and-forget work
+      (Task.Run, unawaited promise, setTimeout, goroutine) to finish
+    problem: >
+      The race is still there — the timeout only hides it most of the time while
+      slowing the whole suite; on a shared runner it leaks flakiness into other
+      MRs' CI. Same class of anti-pattern as depending on wall-clock time.
+
 # ─────────────────────────────────────────────────────────
 # Rules
 # ─────────────────────────────────────────────────────────
@@ -297,6 +334,15 @@ rules:
       If any hollow test indicator triggers, rewrite the mocking strategy.
     priority: required
 
+  - id: no-poll-sleep-for-background-work
+    trigger: test asserts a fire-and-forget side effect (Task.Run, unawaited promise, setTimeout, goroutine, executor)
+    instruction: >
+      Never poll or sleep to wait for in-process background work. Inject a
+      deterministic runner (e.g. IBackgroundTaskRunner / BackgroundDispatcher)
+      whose test double runs the work inline and tracks the Task/promise; await
+      the tracked task, then assert on success, exception, or retry.
+    priority: required
+
   - id: level-2-stub-server-rules
     trigger: UAT environment lacks a real external service (SMS, payment, IdP)
     instruction: >