universal-dev-standards 5.16.0 → 6.0.0

package/bundled/core/full-coverage-testing.md

@@ -160,6 +160,74 @@ CI reports AC coverage rate. If more than 20% of ACs lack `@ac`-tagged tests, a
 
 ---
 
+## Migration Error-Path Completeness (XSPEC-288)
+
+> Part of the [XSPEC-284](https://github.com/AsiaOstrich/universal-dev-standards) 9-axis migration completeness matrix (**axis ⑨ — error paths**). The three-path model above requires an error path **per function**; this section adds the **migration-specific** guarantee that legacy's error/degradation/fallback branches are **systematically** carried over — not merely sampled.
+
+### Why the three-path model alone is not enough for a migration
+
+The per-function error-path requirement and XSPEC-201's error-path snapshot only verify the error cases **you thought to enumerate**. In a rewrite the happy path is migrated because it has an explicit requirement, while error branches — scattered across `try/catch` layers, custom exception hierarchies, specific error codes, and degradation fallbacks — are **silently dropped in bulk**. A passing error-path sample does not prove **no branch was missed** (same blind-spot class as #134, occurring on the error-path layer). This section is the **systematic-enumeration + gap-analysis** layer above the snapshot mechanism.
+
+### Step 1 — Mechanized legacy exception / error-code list (derive, R1)
+
+Enumerate the legacy error surface **mechanically**, not from memory:
+
+| Source | Yields |
+|--------|--------|
+| `catch` / `except` / `rescue` blocks (grep) | every caught exception type + handler |
+| Custom exception / error class hierarchy | the declared error taxonomy |
+| Error/status codes (HTTP status, app error codes, error enums) | the response-code surface |
+| Error response shapes (serializers, error DTOs) | the on-the-wire error contract |
+
+The captured list is the **error-path to-verify checklist** — sourced from artifacts, not human recall.
+
+### Step 2 — Systematic missing-branch gap analysis (oracle, R2)
+
+For **each** legacy error branch from Step 1, verify the new system has a corresponding handler. A branch with no mapping is marked `not_implemented` (XSPEC-199) and **blocks**. The output is a **"missing error branch" gap report** over the full derived list — not a sample that happened to pass.
+
+```markdown
+## Error-Path Gap Report — <module>
+
+| Legacy branch (error type / code) | New-system handler | Status |
+|-----------------------------------|--------------------|--------|
+| PaymentDeclinedException → 402 | PaymentService.handleDecline | MAPPED |
+| GatewayTimeout → retry+fallback | (none found) | not_implemented — BLOCK |
+| ValidationError → 422 + field list | InputValidator | MAPPED |
+
+**Branches: N total · M mapped · K not_implemented (block if K>0)**
+```
+
+### Step 3 — Degradation / fallback parity (R3)
+
+Legacy degradation modes (fallback on external-service failure, retry, partial results) are easy to drop because they only run when something fails. Verify the new system preserves the corresponding degradation behavior, so the system is not "consistent on the happy path, wildly different on failure":
+
+- [ ] External-service-failure **fallback** behavior matches legacy
+- [ ] **Retry** policy (count, backoff, give-up) matches legacy
+- [ ] **Partial-result** handling matches legacy (returns what it can vs all-or-nothing)
+- [ ] **Circuit-breaker / timeout** degradation matches legacy
+
+### Step 4 — Error-response differential (oracle, R4)
+
+Extend [behavior-snapshot](behavior-snapshot.md) parity and XSPEC-284 R5 replay to cover the **error response**, not just the happy-path response. Compare new vs legacy on:
+
+- **Error code** (HTTP status, app error code)
+- **Message structure** (error DTO shape, field-level errors)
+- **HTTP status** mapping per error class
+
+This makes implicit error-path divergence self-report at cutover, the same way the happy-path snapshot does.
+
+**Gate timing**: pre-UAT (gap analysis + degradation parity) + cutover before/after (error-response differential).
+
+### Importance ranking (scope guidance)
+
+Not every legacy error branch must map at equal priority. Rank by **production-actual trigger frequency** (echoes #134 "production is the oracle"): branches that have actually fired in production logs are mapped first; never-fired latent branches are lower priority but still listed. A high-frequency production error branch with no new-system mapping is a hard block.
+
+### Completeness declaration (matrix alignment)
+
+Axis ⑨ is satisfied when this section declares all three: **derive** (Step 1 mechanized exception/error-code list), **oracle** (Step 2 systematic gap analysis + Step 4 error-response differential), and **gate timing** (pre-UAT + cutover before/after). Reuse XSPEC-201 error-path snapshot + the three-path model above — this section adds only systematic missing-branch analysis and the error-response differential, it does not rebuild a test framework.
+
+---
+
 ## Migration from Pyramid Model
 
 If your project previously used pyramid thresholds:
@@ -180,7 +248,11 @@ The ratchet starts at your current coverage. From that point on, it can only inc
 - `unit-testing.ai.yaml` — Unit test scope and organization
 - `integration-testing.ai.yaml` — Integration test patterns
 - `deployment-standards.ai.yaml` — Deploy gate requirements
+- `flaky-test-management.md` — Intermittent-failure handling: a test that flakes is **not** a passing test. Before a coverage figure counts toward a gate, intermittent failures MUST be quarantined / retry-budgeted / root-caused per that standard — otherwise "full coverage" hides non-deterministic gaps.
+- `behavior-snapshot.md` — Error-response differential oracle (Migration Error-Path Completeness, axis ⑨)
+- `migration-assistant` skill — Legacy exception/error-code derive + degradation parity (XSPEC-288)
 - XSPEC-178 — Full specification and implementation phases
+- XSPEC-288 — Migration Error-Path Completeness (axis ⑨ of XSPEC-284 matrix)
 
 
 **Scope**: universal

package/bundled/core/git-worktree.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/git-worktree.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-20
+**Version**: 1.1.0
+**Last Updated**: 2026-06-18
 **Applicability**: All projects using Git for version control
 **Scope**: universal
 **Inspired by**: [Superpowers](https://github.com/obra/superpowers) — using-git-worktrees (MIT)
@@ -59,7 +59,7 @@ pnpm install  # or npm install, pip install, etc.
 
 1. **Run the test suite** in the fresh worktree
 2. **Confirm all tests pass** — this verifies the environment is clean
-3. **If tests fail** — abort and report the environment issue (do not proceed)
+3. **If tests fail** — retry up to 2× with backoff to rule out transient flakes/timeouts; if they still fail, abort and report the environment issue (do not proceed)
 
 ```bash
 # Baseline verification
@@ -108,7 +108,7 @@ git worktree prune
 | ID | Trigger | Action | Priority |
 |----|---------|--------|----------|
 | GW-001 | Worktree directory not in `.gitignore` | Automatically add to `.gitignore` | Critical |
-| GW-002 | Baseline tests fail | Abort task, report environment issue | High |
+| GW-002 | Baseline tests fail | Retry up to 2× (exponential backoff) for transient failures; if persistent, abort task and report environment issue | High |
 | GW-003 | Abnormal exit during worktree operation | Ensure cleanup is executed | High |
 | GW-004 | Worktree exists after branch merge/delete | Prune stale worktree references | Medium |
 

package/bundled/core/guides/performance-guide.md

@@ -1,6 +1,6 @@
 # Performance Guide
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/performance-guide.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/performance-guide.md) | [简体中文](../../locales/zh-CN/core/guides/performance-guide.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-29

package/bundled/core/guides/security-guide.md

@@ -1,6 +1,6 @@
 # Security Guide
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/security-guide.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/security-guide.md) | [简体中文](../../locales/zh-CN/core/guides/security-guide.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-29

package/bundled/core/health-check-standards.md

@@ -12,7 +12,7 @@
 - **Readiness 僅檢關鍵依賴**：非關鍵依賴不納入，避免邊緣故障造成服務被下線
 - **慢啟動用 startup probe**：啟動完成後交棒給 liveness
 - **結構化 JSON 回應**：含 `status` / `dependencies` / `timestamp` / `version`
-- **作為 observability signal**：連續 fail 觸發 incident
+- **作為 observability signal**：連續 fail（達 probe threshold）依 [alerting-standards](alerting-standards.md) 觸發告警——由 alerting 定義觸發時機、嚴重性對映與路由（`HC-001 HEALTH_CHECK_FAILED` 為 alert 來源之一），health-check 只負責 emit signal、不自行決定通知對象
 
 ## Probe Types
 
@@ -68,7 +68,7 @@
 - AI-optimized: [ai/standards/health-check-standards.ai.yaml](../ai/standards/health-check-standards.ai.yaml)
 - XSPEC-067: DEC-043 Wave 1 Reliability Pack 跨專案規格
 - DEC-043: UDS 覆蓋完整性路線圖（驅動來源）
-- Related: `deployment-standards`, `circuit-breaker`, observability-standards (XSPEC-063 規劃中)
+- Related: `deployment-standards`, `circuit-breaker`, `alerting-standards`（probe 連續失敗 → 告警觸發與路由）, observability-standards (XSPEC-063 規劃中)
 - Industry: Kubernetes probes, Microsoft eShop health checks, Google SRE Book Ch.6
 
 

package/bundled/core/iac-design-principles.md

@@ -0,0 +1,97 @@
+# Infrastructure as Code Design Principles
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/iac-design-principles.ai.yaml`
+> **Spec**: XSPEC-065 (cross-project/specs/XSPEC-065-uds-infrastructure-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines the four foundational principles for Infrastructure as Code
+(IaC) authoring: **reproducible, immutable, idempotent, and versioned**. It covers
+state management requirements (remote state with locking), drift detection
+categories, and CI/CD integration. It is designed to ensure infrastructure
+changes are traceable, reversible, and safe to apply repeatedly without unintended
+side effects.
+
+It is part of the **IaC pack** (XSPEC-065) and is the tool-agnostic foundation
+that `container-image-standards` and `secret-management-standards` build on
+(images and secret backends are themselves versioned, reproducible
+infrastructure).
+
+> **Scope.** This standard defines the *authoring principles*, *state-management*
+> rules, and the *drift-handling taxonomy*. The specific IaC tool (Terraform /
+> Pulumi / CloudFormation) and backend are adoption choices, not part of this
+> standard.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | IaC four principles (reproducible, immutable, idempotent, versioned) | MUST |
+| REQ-002 | State management (remote backend, locking, encryption, no local state in VCS) | MUST |
+| REQ-003 | Drift detection (plan on PR; three-category classification) | MUST |
+
+### REQ-001 — IaC Four Principles
+
+All infrastructure definitions MUST adhere to four foundational principles:
+(1) **Reproducible** — given the same inputs and state, applying IaC produces
+identical infrastructure; (2) **Immutable** — infrastructure changes are applied
+by replacing resources, not mutating them in-place; blue/green or rolling
+replacement patterns are preferred over in-place mutations; (3) **Idempotent** —
+applying the same IaC configuration multiple times produces the same result
+without error or unintended side effects; (4) **Versioned** — all IaC definitions
+are stored in version control with meaningful commit messages; no infrastructure
+change is made outside the VCS workflow.
+
+### REQ-002 — State Management
+
+IaC state MUST be stored in a remote backend with locking enabled to prevent
+concurrent modifications. Local state files MUST NOT be committed to version
+control or used in CI/CD pipelines. Recommended backends: Terraform Cloud /
+S3+DynamoDB (Terraform), Pulumi Service / S3 (Pulumi), CloudFormation native
+stack state. State access MUST be restricted to authorized principals via IAM or
+equivalent. State encryption at rest is REQUIRED.
+
+### REQ-003 — Drift Detection
+
+Teams MUST run `plan` (or equivalent) in CI on every pull request to detect
+configuration drift. Drift outcomes MUST be classified into one of three
+categories and handled accordingly: (1) **rollback-to-code** — actual infra
+deviates from code due to a manual change; revert actual to match code on next
+apply; (2) **update-code-from-actual** — actual reflects an intentional change not
+yet codified; update IaC to match, then apply; (3) **manual-reconcile** — drift
+requires human judgment (e.g., data volume changes); escalate to the infra owner
+with a documented decision. Drift reports SHOULD be published to a team channel on
+a scheduled cadence (e.g., daily).
+
+## Anti-Patterns
+
+- Committing local state files (`terraform.tfstate`) to version control.
+- Applying mutable in-place changes (e.g., sed-patching running VMs) instead of replacing resources.
+- Making manual console changes without updating the corresponding IaC definition.
+- Using no remote locking, allowing concurrent applies that corrupt state.
+- Pinning to `latest` provider or module versions, breaking reproducibility.
+
+## Integration with Existing Standards
+
+- **`container-image-standards`** — container images are versioned, reproducible
+  artifacts produced under the same principles.
+- **`secret-management-standards`** — secret backends (Vault/KMS) are managed as
+  access-controlled infrastructure with remote state.
+- **`deployment-standards` / `cd-deployment-strategies`** — immutable replacement
+  (REQ-001) underpins blue/green and rolling deployment patterns.
+- **`no-cicd-deployment`** — even without a CI/CD platform, the four principles and
+  state-management rules still apply to scripted infrastructure changes.
+
+## Related Specs
+
+- XSPEC-065 — UDS infrastructure (IaC) pack (this standard's source)
+- DEC-043 — UDS coverage completeness roadmap (Wave 4 scope)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~003: IaC four principles, state management, drift detection (XSPEC-065) |

package/bundled/core/incident-response.md

@@ -0,0 +1,119 @@
+# Incident Response Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/incident-response.ai.yaml`
+> **Spec**: XSPEC-063 (cross-project/specs/XSPEC-063-uds-sre-standards-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines the end-to-end **incident response lifecycle**: severity
+classification, response-time SLAs, roles and responsibilities, communication
+protocols, escalation paths, and blameless postmortem requirements. It is
+designed to reduce MTTR, ensure consistent stakeholder communication during
+incidents, and drive systemic reliability improvements through structured
+postmortems.
+
+It is part of the **SRE/operations pack** (XSPEC-063) and is the incident-handling
+member alongside `slo-sli` (error-budget triggers) and `runbook` (executable
+recovery steps). It composes with `virtual-organization-standards` — a SEV-1
+incident spins up the incident virtual organization (IC, Communications Lead,
+Operations Lead) — and feeds the proactive reliability ownership described in
+XSPEC-251 (Operator).
+
+> **Scope.** This standard defines *how incidents are classified, coordinated,
+> communicated, and learned from*. The paging tool (PagerDuty, Opsgenie), the
+> status-page product, and the ticketing system are adoption choices, not part of
+> this standard.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Severity classification (4-level SEV scale with response SLAs) | MUST |
+| REQ-002 | Incident Commander role (assigned within 10 min for SEV-1/2) | MUST |
+| REQ-003 | Stakeholder communication protocol (defined cadence + status page) | MUST |
+| REQ-004 | Blameless postmortem requirements (5 Whys, action items tracked) | MUST |
+| REQ-005 | On-call rotation and handoff (≥2 engineers, written handoff) | MUST |
+| REQ-006 | Incident retrospective metrics (MTTD/MTTR reviewed monthly) | SHOULD |
+
+### REQ-001 — Severity Classification
+
+Every incident MUST be classified at declaration using a 4-level severity scale.
+**SEV-1** (Critical): complete service outage or data breach affecting all users,
+response within 15 minutes, C-suite notification. **SEV-2** (High): major feature
+unavailable or significant performance degradation affecting >25% of users,
+response within 30 minutes. **SEV-3** (Medium): minor feature unavailable or
+degradation affecting <25% of users, response within 4 hours. **SEV-4** (Low):
+cosmetic issue or very minor impact, response within 24 hours.
+
+### REQ-002 — Incident Commander Role
+
+Every SEV-1 and SEV-2 incident MUST have a designated Incident Commander (IC)
+assigned within 10 minutes of declaration. The IC is responsible for coordinating
+the response bridge, assigning roles (scribe, comms lead, technical leads),
+driving the timeline, making go/no-go decisions on fixes, and initiating the
+postmortem. The IC does NOT directly troubleshoot — their sole focus is
+coordination.
+
+### REQ-003 — Stakeholder Communication Protocol
+
+During SEV-1/SEV-2 incidents, stakeholder updates MUST be sent on a defined
+cadence: initial notification within 15 minutes of declaration, updates every
+30 minutes until resolution, and an immediate update on any severity change or
+major development. Updates MUST include current status, known impact, what is
+being done, and the next update time. The status page MUST be updated
+simultaneously with internal communications.
+
+### REQ-004 — Blameless Postmortem Requirements
+
+Every SEV-1 incident MUST have a blameless postmortem completed within 5 business
+days; SEV-2 incidents within 10 business days. Postmortems MUST be blameless —
+focusing on systemic causes, not individual mistakes. Required sections: timeline,
+impact, root cause (5 Whys), contributing factors, action items with owners and
+due dates, and lessons learned. Action items MUST be tracked to completion.
+
+### REQ-005 — On-Call Rotation and Handoff
+
+Every production service MUST have a documented on-call rotation with at least 2
+engineers. Rotation schedules MUST be published at least 2 weeks in advance.
+On-call handoff MUST include a written summary of active incidents, recent
+incidents still under investigation, known flaky alerts, upcoming planned
+maintenance, and any service-health concerns. Handoff MUST be acknowledged by the
+incoming on-call.
+
+### REQ-006 — Incident Retrospective Metrics
+
+Teams SHOULD track and review incident metrics monthly: MTTD (Mean Time To
+Detect), MTTR (Mean Time To Resolve), incident frequency by severity, repeat
+incidents (same root cause within 90 days), and postmortem action-item completion
+rate. These metrics SHOULD be reviewed in monthly reliability reviews with
+engineering leadership.
+
+## Integration with Existing Standards
+
+- **`runbook`** — the IC and on-call engineers execute typed runbooks during the
+  mitigate phase; SEV runbooks are drilled per the `runbook` cadence.
+- **`slo-sli`** — error-budget burn often triggers incident declaration; SLO
+  impact is summarized in the postmortem.
+- **`postmortem-standards`** — REQ-004 aligns with the blameless postmortem
+  template; this standard sets the trigger and timelines.
+- **`virtual-organization-standards`** — SEV-1 incidents instantiate the incident
+  virtual organization (IC, Communications Lead, Operations Lead).
+- **`alerting-standards`** — alerts initiate detection and severity assessment.
+- **`execution-history`** — automated mitigation actions are recorded as execution
+  history.
+
+## Related Specs
+
+- XSPEC-063 — UDS SRE/operations pack (this standard's source)
+- XSPEC-251 — Operator proactive reliability (proactive ownership upstream of incidents)
+- DEC-041 — EU AI Act 2026 compliance (auditability requires postmortems)
+- DEC-042 — Guardian / Governance Agent pattern (agent-driven runbook execution)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~006: severity classification, incident commander, communication protocol, blameless postmortem, on-call rotation/handoff, retrospective metrics (XSPEC-063) |

package/bundled/core/license-compliance.md

@@ -4,6 +4,8 @@
 > **AI-optimized version**: `ai/standards/license-compliance.ai.yaml`
 > **Agent Spec**: ASPEC-001 (cross-project/aspec/ASPEC-001-license-compliance-agent.md)
 
+**Scope**: universal
+
 ## Overview
 
 Comprehensive license compliance for AI-augmented development, covering both general OSS practice (Tier 1) and AI-specific rules for AI-generated code (Tier 2).

package/bundled/core/logging-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/logging-standards.md)
 
-**Version**: 1.3.0
-**Last Updated**: 2026-05-26
+**Version**: 1.4.0
+**Last Updated**: 2026-06-17
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: RFC 5424, OpenTelemetry, W3C Trace Context
@@ -15,6 +15,81 @@
 
 This document defines logging standards for consistent, structured, and actionable application logs across all environments.
 
+## Mandatory Events
+
+> **Closes** UDS issue [#108](https://github.com/AsiaOstrich/universal-dev-standards/issues/108) (XSPEC-234). The rest of this standard defines **how** to write a log entry (level / fields / PII mask / rotation). This section defines **when you MUST write one** — excluding "compliant on paper but materially silent" logging.
+
+Logging that follows every formatting rule but **never fires at the moment that matters** is worse than useless: it gives false confidence during an incident. The events below are the canonical moments where a log entry is **mandatory**. Each declares `when` / `must_log` / `must_NOT_log` / `level` / `rationale`.
+
+### Why this exists (real incidents)
+
+A PHP→.NET migration burned 2 days diagnosing "send failed, no log", because **four layers were all silent**:
+
+1. **Load-balancer marks backend DOWN** (503) on health-probe timeout — backend logged only probe noise, zero business events.
+2. **Framework validation reject** (e.g. ModelState / DTO 501) — the rejecting framework returned before any handler ran, so the **payload was never logged**.
+3. **Auth failure** logged only "Account or password error" — **no uid, no source IP** → un-investigable.
+4. **Background worker alive but log file 0 bytes** — no mechanism detected the silence.
+
+None of these were caught by the formatting rules alone. Mandatory events close that gap.
+
+### Catalog (9 canonical events)
+
+| id | when | level | Core required fields (`must_log`) | `must_NOT_log` |
+|----|------|-------|-----------------------------------|----------------|
+| `application_startup` | After process boot, **before** accepting requests | INFO | app_name, version, git_sha, environment, hostname, pid, listening_endpoints | secrets, full connection strings |
+| `request_received` | First time HTTP middleware sees a request | INFO / DEBUG | method, path, source_ip, request_id | request body, auth headers |
+| `validation_failure` | schema / ModelState / DTO validation rejects | WARN | request_id, path, missing_fields[], payload_shape (keys only) | field **values**, PII |
+| `authentication_failure` | login / token verification fails | WARN | uid (attempted), source_ip, failure_reason | password, token value |
+| `outbound_call_start` | An outbound HTTP/RPC call is initiated | INFO | target_url (host+path), request_id propagated, timeout_ms | credentials, bearer tokens |
+| `outbound_call_complete` | An external call returns or fails | INFO / WARN / ERROR | status_code **or** failure_phase (dns/tcp/tls/http), elapsed_ms, retries | response body with PII |
+| `business_event` | A state-changing business operation completes | INFO | operation_name, actor, target ids, outcome | full record payload, PII |
+| `heartbeat` | Long-running background service, ≥ 1× / 60 s | INFO | service_name, queue_depth, items_processed_since_last_heartbeat | — |
+| `shutdown` | Process exits (graceful or fatal) | INFO / ERROR | app_name, signal/reason, uptime_seconds, pending_work_count | — |
+
+Each event's `rationale` ties back to a real failure mode: `validation_failure` ⇒ incident #2 (un-logged payload); `authentication_failure` field requirements ⇒ incident #3 (no uid/IP); `heartbeat` + silence detection ⇒ incident #4 (0-byte log); `application_startup`/`shutdown` ⇒ lifecycle blind spots; `outbound_call_*` ⇒ "send failed" with no trace of the call.
+
+### Scenarios
+
+#### Scenario: Validation failure must produce a log
+
+- **GIVEN** an API endpoint receives a payload missing a `[Required]` field
+- **WHEN** the framework auto-rejects (e.g. 400/501) before the handler runs
+- **THEN** a WARN log MUST be written with `request_id`, `path`, `missing_fields[]`, `payload_shape` (keys only)
+- **AND** a post-mortem can reconstruct the failure cause directly from the log
+
+#### Scenario: Background service must heartbeat
+
+- **GIVEN** a worker process is running
+- **WHEN** no INFO/WARN/ERROR is written within 60 s
+- **THEN** a `heartbeat` log MUST be written with current queue depth and items processed
+- **AND** if no heartbeat appears for ≥ 2× the interval (≥ 120 s), the silence detector MUST alert
+
+### Compliant startup log example
+
+```json
+{
+  "timestamp": "2026-06-17T08:00:00.000Z",
+  "level": "INFO",
+  "message": "application_startup",
+  "event": "application_startup",
+  "app_name": "payment-service",
+  "version": "2.3.1",
+  "git_sha": "a1b2c3d",
+  "environment": "production",
+  "hostname": "pod-abc123",
+  "pid": 4711,
+  "listening_endpoints": ["0.0.0.0:8080", "0.0.0.0:9090/metrics"]
+}
+```
+
+### Follow-on rules
+
+1. **Access-log separation** — health-probe / liveness traffic MUST NOT pollute the business-event log. Route probes to a separate sink/file so they cannot drown out or rotate away business events (see incident #1).
+2. **Log-silence detection SLA** — a service SHOULD alert after N minutes with no events, with N ≤ 2× the `heartbeat` interval. Absence of expected logs is itself an alertable condition (see the "Absence of Expected Logs" alert pattern below).
+3. **OPS-facing log discoverability** — error responses returned to the client SHOULD carry the `request_id`, so support can correlate a user-reported failure to backend logs without round-trips for log access.
+
+> **Cross-ref**: `heartbeat` / silence detection complement the [Log File Rotation Policy](#log-file-rotation-policy) (a 0-byte / silently-dropping log is the same blind spot from two directions) and migration-assistant's Background Job / Side-Effect Completeness (these events are the observable "has-fired" evidence).
+
 ## Log Levels
 
 ### Standard Log Levels
@@ -754,6 +829,7 @@ App cannot continue?         → FATAL
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.4.0 | 2026-06-17 | Added: Mandatory Events catalog — 9 canonical "when you MUST log" events (when/must_log/must_NOT_log/level/rationale), validation-failure + heartbeat scenarios, compliant startup example, follow-on rules (access-log separation, silence-detection SLA, request_id discoverability) (XSPEC-234 / closes issue #108) |
 | 1.3.0 | 2026-05-26 | Added: Log File Rotation Policy — mandatory dual-trigger (time + size) rotation with hostile-default warning, recipes for .NET/Python/Java/Node, ops SOP (XSPEC-232 / closes issue #111) |
 | 1.2.0 | 2026-01-24 | Added: OpenTelemetry Semantic Conventions, Observability Three Pillars Integration, Log-based Alerting, Advanced Correlation Patterns |
 | 1.1.0 | 2026-01-05 | Added: References section with OWASP, RFC 5424, OpenTelemetry, and 12 Factor App |

package/bundled/core/mock-boundary.md

@@ -1,7 +1,7 @@
 # Mock Boundary Standards
 
-**Version**: 1.0.0
-**Last Updated**: 2026-05-04
+**Version**: 1.1.0
+**Last Updated**: 2026-07-01
 **Applicability**: All software projects with unit and integration tests
 **Scope**: universal
 **Industry Standards**: ISTQB Foundation (Test Doubles), xUnit Patterns (Gerard Meszaros)
@@ -46,6 +46,7 @@ vi.mock('node:fs/promises', ...)                  // I/O replaced
 | Environment variables | `process.env.NODE_ENV`, `process.env.LICENSE_KEY` | Enables config variation |
 | File system (unit tests only) | `fs.readFile`, `fs.writeFile` | Avoids I/O in fast unit tests |
 | Cross-module boundaries (with IT counterpart) | Other modules' public APIs | Isolates unit under test |
+| In-process background execution (via injectable runner) | `Task.Run`, unawaited promises, `setTimeout`, goroutines, thread-pool dispatch | Injecting a runner seam lets tests await deterministic completion, eliminating the race |
 
 ---
 
@@ -60,6 +61,46 @@ vi.mock('node:fs/promises', ...)                  // I/O replaced
 
 ---
 
+## Injectable Background Execution
+
+Fire-and-forget background work (a `Task.Run`, an unawaited promise, a `setTimeout`, a goroutine, a `java.util.concurrent` executor submission, or `asyncio.create_task`) is a **seam**, exactly like the system clock. Just as you inject a clock instead of reading wall-clock time, you inject the background dispatcher instead of spawning work directly. This lets a test drive the work to a **deterministic, awaited completion** and assert on its outcome (success, exception, or retry) — no polling, no sleeping, no race.
+
+Abstract the dispatch behind a small interface (e.g. `IBackgroundTaskRunner` / `BackgroundDispatcher`), then provide two implementations:
+
+- **Production**: preserves true fire-and-forget semantics — dispatch returns immediately and the work runs detached.
+- **Test**: runs the work **inline** and **tracks the underlying Task/promise**, exposing a handle the test can `await` so completion (and any failure) is observable.
+
+Language-neutral sketch (TypeScript pseudo-code):
+
+```typescript
+// Seam — injected wherever background work is dispatched
+interface BackgroundDispatcher {
+  dispatch(work: () => Promise<void>): void
+}
+
+// Production: real fire-and-forget — returns immediately, work runs detached
+class FireAndForgetDispatcher implements BackgroundDispatcher {
+  dispatch(work: () => Promise<void>): void {
+    void work() // intentionally not awaited
+  }
+}
+
+// Test: inline execution + tracked tasks so tests can await completion
+class DeterministicDispatcher implements BackgroundDispatcher {
+  private readonly tasks: Promise<void>[] = []
+  dispatch(work: () => Promise<void>): void {
+    this.tasks.push(work()) // start inline, keep the handle
+  }
+  async settle(): Promise<void> {
+    await Promise.all(this.tasks) // test awaits deterministic completion
+  }
+}
+```
+
+The test injects `DeterministicDispatcher`, exercises the code under test, then `await dispatcher.settle()` before asserting on the result — the background side effect is now fully observable and deterministic.
+
+---
+
 ## Hollow Test Detection
 
 Before submitting a test file, check:
@@ -78,6 +119,7 @@ Before submitting a test file, check:
 - **Orphan Mock**: Cross-module mock with no integration test counterpart
 - **Security Bypass Mock**: Auth/permission logic replaced with pass-through stub
 - **Database Mock Cascade**: DB returns hardcoded data, hiding real query errors
+- **Poll/Sleep for Background Result**: Sleeping or polling to wait for fire-and-forget work to finish. The race is still there — the timeout merely hides it most of the time while slowing the whole suite and, on a shared runner, leaking flakiness into other MRs' CI. Inject a deterministic runner and await the tracked task instead.
 
 ---
 
@@ -90,6 +132,7 @@ Before submitting a test file, check:
 | IT counterpart | Mocking cross-module boundary | Ensure corresponding IT exists |
 | No security mock | Test involves auth/permissions | Use real test user + real token |
 | Hollow review | Mock count ≥ import count | Add output-value assertion |
+| No poll/sleep for background work | Test asserts a fire-and-forget side effect | Inject deterministic runner; await the tracked task |
 
 ---
 
@@ -98,3 +141,12 @@ Before submitting a test file, check:
 - **testing**: Mock boundary rules apply to all test levels in the testing pyramid
 - **test-completeness-dimensions**: Dimension 8 (AI Test Quality) references these rules
 - **flow-based-testing**: Flow tests must follow mock boundary rules
+
+---
+
+## Version History
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0.0 | 2026-05-04 | Initial standard: hollow test problem, CAN/CANNOT mock tables, detection, anti-patterns, rules summary |
+| 1.1.0 | 2026-07-01 | Added injectable background execution as a seam (parallel to clock injection): CAN-mock row, `Injectable Background Execution` section, `Poll/Sleep for Background Result` anti-pattern, and no-poll/sleep rule (issue #143) |