universal-dev-standards 5.17.0 → 6.1.0

package/bundled/core/accessibility-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/accessibility-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-29
+**Version**: 1.1.0
+**Last Updated**: 2026-06-18
 **Applicability**: All software projects with user interfaces
 **Scope**: universal
 **Industry Standards**: WCAG 2.1/2.2, WAI-ARIA 1.2, Section 508
@@ -213,8 +213,11 @@ This standard defines comprehensive guidelines for creating accessible software
 
 ```javascript
 // ✅ Good: Session timeout warning
-const TIMEOUT_WARNING = 5 * 60 * 1000; // 5 minutes before timeout
-const SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+// A warning + a way to extend the session is REQUIRED by WCAG 2.2.1 (Timing
+// Adjustable). The specific durations are UDS defaults and are configurable:
+// 30 min idle aligns with NIST SP 800-63B AAL2 reauthentication guidance.
+const TIMEOUT_WARNING = 5 * 60 * 1000; // 5 min warning before timeout
+const SESSION_TIMEOUT = 30 * 60 * 1000; // 30 min idle (UDS default; configurable)
 
 setTimeout(() => {
   const extend = confirm('Your session will expire in 5 minutes. Extend?');
@@ -909,6 +912,7 @@ The a11y gate contributes to the Release Readiness Sign-off as:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-06-18 | Added: source + configurable note for session-timeout durations (WCAG 2.2.1 Timing Adjustable; NIST SP 800-63B AAL2) (XSPEC-292 T8) |
 | 1.0.0 | 2026-01-29 | Initial release: WCAG 2.1 coverage, POUR principles, ARIA guidelines, keyboard navigation, forms, testing |
 
 ---

package/bundled/core/ai-friendly-architecture.md

@@ -5,7 +5,7 @@
 **Version**: 1.0.0
 **Last Updated**: 2026-01-21
 **Applicability**: All software projects collaborating with AI assistants
-**Scope**: partial
+**Scope**: universal
 **Industry Standards**: None (Emerging AI collaboration practice)
 
 ---

package/bundled/core/ai-response-navigation.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/ai-response-navigation.md) | [简体中文](../locales/zh-CN/core/ai-response-navigation.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-25
+**Version**: 1.1.0
+**Last Updated**: 2026-06-10
 **Applicability**: All projects using AI-assisted development
 **Scope**: universal
 **Industry Standards**: None (Emerging AI tool practice)
@@ -69,6 +69,32 @@ Adjust the number of options based on context complexity:
 
 When a next-step suggestion corresponds to a known slash command, reference it using `` `/command` `` format so users can copy and execute directly. Use natural language descriptions for steps without corresponding commands.
 
+### Rule 6: Model Tier Annotation（Optional）
+
+When a next-step option clearly maps to a specific complexity tier, you MAY annotate it with a model tier hint. This annotation is **strictly optional** — existing skills do not need to be updated retroactively; new and revised skills are encouraged to adopt it.
+
+**Notation**: append `〔model: Fast〕`, `〔model: Standard〕`, or `〔model: Capable〕` after the option description.
+
+**Tier selection**: use the complexity signals from the [model-selection](model-selection.md) standard:
+- `Fast` — single file, unambiguous spec, no design judgment
+- `Standard` — 2–5 files, inter-module understanding needed
+- `Capable` — 5+ files, architectural decisions, cross-system correctness
+
+**Localized notation**:
+- 繁體中文：`〔模型：Fast〕` / `〔模型：Standard〕` / `〔模型：Capable〕`
+- 简体中文：`〔模型：Fast〕` / `〔模型：Standard〕` / `〔模型：Capable〕`
+
+Tier names are **vendor-neutral**. Each tool or platform maps these tiers to its available models independently.
+
+**Example** (task completed, with tier annotations):
+
+```markdown
+> **Suggested next steps:**
+> - Run `/derive bdd` to extract BDD scenarios `〔model: Fast〕` — format conversion only
+> - Run `/checkin` for quality gate verification ⭐ **Recommended** `〔model: Standard〕` — inter-module judgment required
+> - Run `/sdd` for integrated architecture design `〔model: Capable〕` — cross-system impact analysis
+```
+
 ---
 
 ## Contextual Templates
@@ -209,7 +235,7 @@ Each tool's integration layer is responsible for rendering the Navigation Footer
 > **Suggested next steps:**
 > - Run `/test` to write tests for the new feature
 > - Run `/commit` to commit changes ⭐ **Recommended** — changes are complete and verified
-> - Run `/review` for self-review
+> - Run `/code-review` for self-review
 ```
 
 ### Example 2: Asking the User a Design Question
@@ -257,6 +283,7 @@ Each tool's integration layer is responsible for rendering the Navigation Footer
 | R3 | Match template to response type |
 | R4 | 1–5 options, adapt to context |
 | R5 | Use `/command` format when applicable |
+| R6 | *(Optional)* Append `〔model: Fast\|Standard\|Capable〕` when tier is clear |
 
 | Exempt | Not Exempt |
 |--------|------------|
@@ -280,6 +307,7 @@ Each tool's integration layer is responsible for rendering the Navigation Footer
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-06-10 | Add R6 optional model tier annotation (`〔model: Fast\|Standard\|Capable〕`); vendor-neutral; no forced changes to existing skills |
 | 1.0.0 | 2026-03-25 | Initial release |
 
 ---

package/bundled/core/anti-sycophancy-prompting.md

@@ -181,4 +181,4 @@ Then give your honest recommendation.
 ## Related Standards
 
 - [anti-hallucination.md](anti-hallucination.md) — Prevents fabrication; complements anti-sycophancy
-- [agent-epistemic-calibration.md](agent-epistemic-calibration.md) — Epistemic humility in agent design (where applicable)
+- [agent-epistemic-calibration.md](anti-hallucination.md) — Epistemic humility in agent design (where applicable)

package/bundled/core/api-design-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/api-design-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-18
+**Version**: 1.1.0
+**Last Updated**: 2026-06-24
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: OpenAPI 3.x, JSON:API 1.1, Google API Design Guide, RFC 7231 (HTTP Semantics)
@@ -165,12 +165,14 @@ https://api.example.com/v2/users
 
 ### Version Lifecycle
 
-| Phase | Duration | Action |
-|-------|----------|--------|
+An API version moves through four states. The **durations** — the parallel-support window and the deprecation notice period — are the single responsibility of [Deprecation & Sunset Standards](deprecation-standards.md#api-deprecation); this table defines only the states and the API-contract action in each, so the timing numbers live in exactly one place.
+
+| Phase | State | API-Contract Action |
+|-------|-------|---------------------|
 | **Current** | Active development | Full support, new features |
-| **Supported** | 6-12 months after successor | Bug fixes, security patches only |
-| **Deprecated** | 3-6 months notice | Sunset header, migration guide |
-| **Retired** | After deprecation period | Return 410 Gone with migration info |
+| **Supported** | Maintained in parallel with successor | Bug fixes, security patches only |
+| **Deprecated** | Retirement announced | `Deprecation` / `Sunset` headers, migration guide published |
+| **Retired** | Removed | Return `410 Gone` with migration info |
 
 ### Deprecation Headers
 
@@ -180,6 +182,88 @@ Deprecation: true
 Link: <https://api.example.com/v2/docs>; rel="successor-version"
 ```
 
+> The full deprecation **process** (the staged Sunset timeline) and the **minimum notice
+> period per API tier** are governed by [Deprecation & Sunset Standards](deprecation-standards.md#api-deprecation).
+> This standard owns the API-contract surface below: how a version is deprecated in code,
+> what counts as a breaking change, and how to document the migration.
+
+### Deprecating an API Version
+
+Signal deprecation through SemVer and in the API itself, then follow the deprecation lifecycle. The version progression mirrors [Semantic Versioning](versioning.md#incrementing-rules):
+
+```
+v1.0.0 — Version introduced
+v1.5.0 — Deprecation announced (no later than the N-1 minor before removal)
+v2.0.0 — Version removed (breaking change → MAJOR bump)
+```
+
+Mark deprecated code so callers see the warning well before the removal release:
+
+```javascript
+// v1.5.0 — add deprecation warning
+/**
+ * @deprecated Use authenticateV2() instead. Will be removed in v2.0.0
+ */
+function authenticate(username, password) {
+  console.warn('[DEPRECATED] authenticate() will be removed in v2.0.0. Use authenticateV2()');
+  return authenticateV2(username, password);
+}
+```
+
+### Backward Compatibility Checklist
+
+Before releasing, classify every change. Anything in the first list is **breaking** and requires a MAJOR version bump (see [Semantic Versioning](versioning.md#incrementing-rules)); anything in the second list is backward-compatible and ships in a MINOR or PATCH release.
+
+**Breaking — never without a MAJOR version bump:**
+- [ ] Remove a public API endpoint
+- [ ] Remove a required request field
+- [ ] Add a required request field
+- [ ] Change a response field's type
+- [ ] Change the meaning of an error code
+- [ ] Remove a response field consumers depend on
+
+**Backward-compatible — safe in a MINOR or PATCH release:**
+- [ ] Add an optional request field
+- [ ] Add a new response field
+- [ ] Add a new endpoint
+- [ ] Add a new error code
+- [ ] Improve an error message
+- [ ] Performance improvement
+
+### API Migration Guide
+
+When a MAJOR version ships breaking changes, publish a migration guide that maps each old usage to its replacement:
+
+````markdown
+# Migration Guide: v1.x to v2.0
+
+## Breaking Changes
+
+### 1. authenticate() removed
+
+**Before (v1.x)**:
+```javascript
+const token = await authenticate('user', 'pass');
+```
+
+**After (v2.0)**:
+```javascript
+const token = await authenticateV2({ username: 'user', password: 'pass' });
+```
+
+### 2. API response format changed
+
+**Before (v1.x)**: `{ "data": { "user": {...} } }`
+**After (v2.0)**: `{ "user": {...} }`
+
+```javascript
+// Before
+const user = response.data.user;
+// After
+const user = response.user;
+```
+````
+
 ---
 
 ## Request/Response Standards
@@ -917,6 +1001,7 @@ Error   → { type, title, status, detail, errors, traceId }
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-06-24 | Added: Deprecating an API Version, Backward Compatibility Checklist, and API Migration Guide (consolidated from versioning.md); Version Lifecycle now defers all period numbers to deprecation-standards as the single source of truth (XSPEC-298 R8, UDS #126) |
 | 1.0.0 | 2026-03-18 | Initial release |
 
 ---

package/bundled/core/audit-trail.md

@@ -0,0 +1,119 @@
+# Audit Trail Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/audit-trail.ai.yaml`
+> **Spec**: XSPEC-066 (cross-project/specs/XSPEC-066-uds-compliance-audit-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines the requirements for creating, storing, and managing
+**immutable audit trails** across systems that handle sensitive data, financial
+transactions, access-control changes, and compliance-relevant operations. It
+covers mandatory event types, the audit-record schema, tamper-evidence
+requirements, retention periods, query/export capabilities, and SIEM integration.
+It is designed to satisfy SOC 2, ISO 27001, GDPR, and financial regulatory
+requirements.
+
+It is part of the **compliance & audit pack** (XSPEC-066) and the
+audit-trail member is the core carrier of EU AI Act auditability (DEC-041) and of
+the VibeOps Governance Agent intervention record (DEC-042). It composes with the
+governance-gate family — `license-compliance` (XSPEC-193), `verification-oracle`
+(XSPEC-256), and `model-provenance` (XSPEC-255) — whose gate verdicts are written
+into an audit trail conforming to this standard.
+
+> **Scope.** This standard defines *what* must be audited, the *record schema*,
+> and the *immutability / retention / access* rules. The concrete storage engine
+> (S3 Object Lock, append-only DB, hash-chain library) and the SIEM product are
+> adoption choices, not part of this standard.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Mandatory auditable event types (auth, authz, data access, config, financial, compliance) | MUST |
+| REQ-002 | Audit-record schema (mandatory + recommended fields) | MUST |
+| REQ-003 | Immutability and tamper evidence (append-only + hash chain) | MUST |
+| REQ-004 | Audit-log retention periods by category | MUST |
+| REQ-005 | Query and export capability (filterable, exportable, query-of-query logged) | MUST |
+| REQ-006 | SIEM integration and alerting | SHOULD |
+
+### REQ-001 — Mandatory Auditable Event Types
+
+Systems MUST capture audit records, without exception, for: (1) **Authentication**
+— login success/failure, logout, MFA events, password changes; (2)
+**Authorization** — access granted/denied, privilege escalation, role changes; (3)
+**Data access** — read/write/delete of TIER-1 and TIER-2 PII (see
+`pii-classification`), bulk data exports; (4) **Configuration changes** — system
+settings, security-policy changes, user/role management; (5) **Financial
+transactions** — payment processing, refunds, balance changes; (6)
+**Compliance-relevant actions** — consent changes, data-erasure requests, legal
+holds.
+
+### REQ-002 — Audit Record Schema
+
+Every audit record MUST contain: `event_id` (UUID v4), `event_type` (enumerated
+string), `timestamp` (ISO 8601 UTC with milliseconds), `actor_id` (user or
+service account), `actor_ip` (for user actions), `resource_type`, `resource_id`,
+`action`, `outcome` (success/failure), and `environment` (production/staging). It
+SHOULD also include `session_id`, `request_id` for correlation, before/after
+state for mutations, and geographic region.
+
+### REQ-003 — Immutability and Tamper Evidence
+
+Audit logs MUST be written to an **append-only** store that prevents modification
+or deletion by application-level principals. Each record MUST include a
+cryptographic hash of the previous record (**chaining**) to detect tampering.
+Write access to the audit store MUST be restricted to the audit service only — no
+engineer or application service should have direct write access. Log integrity
+MUST be verifiable on demand.
+
+### REQ-004 — Audit Log Retention Periods
+
+Audit logs MUST be retained according to these minimums by category:
+authentication/authorization — 1 year hot, 6 years cold (SOC 2 / ISO 27001);
+financial transactions — 7 years (financial regulations); PII access — 3 years;
+configuration changes — 3 years; all other audit events — 1 year. Deletion of
+audit records before their retention period expires is **PROHIBITED**. Logs
+approaching expiry MUST be automatically archived to cold storage.
+
+### REQ-005 — Audit Log Query and Export Capability
+
+The audit system MUST support filtering by `event_type`, `actor_id`,
+`resource_id`, time range, and `outcome`. Results MUST be exportable in JSON and
+CSV. Queries returning PII MUST themselves be logged as audit events
+(query-of-query). Audit data MUST be accessible to authorized compliance/security
+teams within 4 hours of a request, and to regulators within 24 hours.
+
+### REQ-006 — SIEM Integration and Alerting
+
+Audit logs SHOULD be forwarded in real time to a SIEM system. The SIEM SHOULD
+have automated detection rules for brute-force login patterns (>5 failures in
+5 min), privilege escalation outside business hours, bulk PII exports (>1000
+records in 1 hour), and access from new geographic regions. Alerts SHOULD trigger
+on-call notification for high-severity detections.
+
+## Integration with Existing Standards
+
+- **`pii-classification`** — data-access auditing keys on the PII tier of the
+  fields touched (TIER-1/TIER-2 reads are mandatory audit events).
+- **`logging-standards`** — audit records are a distinct, immutable class above
+  ordinary application logs; PII masking from `pii-classification` still applies.
+- **`license-compliance` / `verification-oracle` / `model-provenance`** —
+  governance-gate verdicts (block/override) are written into the audit trail.
+- **`execution-history`** — general execution records are not a substitute for a
+  compliance-grade, tamper-evident audit trail.
+
+## Related Specs
+
+- XSPEC-066 — UDS compliance & audit pack (this standard's source)
+- DEC-041 — EU AI Act 2026 compliance (audit trail as auditability carrier)
+- DEC-042 — Guardian / Governance Agent pattern (intervention auditability)
+- DEC-020 — VibeOps commercial dual license (license-compliance auditing)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~006: event types, record schema, immutability/tamper evidence, retention, query/export, SIEM integration (XSPEC-066) |

package/bundled/core/behavior-snapshot.md

@@ -104,13 +104,32 @@ Files prefixed `MANUAL-` contain snapshots that cannot be automatically recorded
 
 ## `ignore_fields` Guidance
 
-### Always Ignore (Non-Deterministic)
+> **Core principle — ignore the _value_, keep the _format_ assertion.** A field being non-deterministic means its *value* changes between runs; it does **not** mean the field's *shape* may change freely. The naive use of `ignore_fields` drops the whole field from comparison, which also stops asserting its format — so a serializer that silently turns an ISO-8601 timestamp into a Unix epoch, drops the timezone, or changes UUID casing/version passes unnoticed. **Ignore the value; still assert the format.**
 
-| Field Pattern | Reason |
-|--------------|--------|
-| `created_at`, `updated_at`, `timestamp` | Changes every request |
-| `token`, `session_id`, `csrf_token` | Cryptographically random |
-| `request_id`, `trace_id`, `correlation_id` | Random UUID |
+### Ignore Value vs. Ignore Format
+
+| Field | Naive: whole-field ignore | Recommended: ignore value, assert format |
+|-------|---------------------------|-------------------------------------------|
+| `created_at` | not compared at all | value ignored; assert it is still ISO-8601 with the same fractional-second precision and the same timezone representation |
+| `trace_id` | not compared at all | value ignored; assert it still matches the UUID version and canonical 8-4-4-4-12 shape |
+| `token` | not compared at all | value ignored; assert length, charset, and prefix |
+
+### Non-Deterministic Fields: Ignore Value, Assert Format
+
+| Field Pattern | Ignore (the value) | Still assert (format / shape) |
+|--------------|--------------------|-------------------------------|
+| `created_at`, `updated_at`, `timestamp` | the instant | ISO-8601 vs. epoch vs. custom; fractional-second precision (number of digits); timezone representation (`Z` vs `+00:00` vs offset) |
+| `token`, `session_id`, `csrf_token` | the random bytes | length, charset, prefix |
+| `request_id`, `trace_id`, `correlation_id` | the random UUID | UUID version + canonical 8-4-4-4-12 shape and casing |
+
+**Timestamp example.** A migrated endpoint returns `created_at`:
+
+```text
+old system: "2026-05-12T08:30:00Z"
+new system: "2026-05-12T08:30:00.000+00:00"
+```
+
+Both decode to the same instant, so a whole-field ignore — and even a value comparison after parsing to a date — passes. But the **serialized format drifted**: fractional seconds appeared and the timezone representation changed from `Z` to `+00:00`. Clients that string-match, or parse with a strict format, break in production. Asserting the format pattern (e.g. `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$`) catches this; ignoring the whole field hides it.
 
 ### Always Compare (Business Logic)
 
@@ -122,7 +141,71 @@ Files prefixed `MANUAL-` contain snapshots that cannot be automatically recorded
 | `success`, `refunded`, `cancelled` | Boolean business outcome |
 | `user_id`, `order_id` (with fixed test data) | Referential integrity |
 
-**Rule**: `ignore_fields` is for legitimately non-deterministic values. Using it to hide business logic differences defeats the purpose of parity testing.
+### Whole-Field Ignore (Exception — Requires Justification)
+
+Dropping a field from comparison entirely — no value **and** no format assertion — is an **exception**, not the default. Reserve it for fields whose format is genuinely unspecified or irrelevant (e.g. an opaque vendor blob), and document the reason inline.
+
+> ⚠️ **Risk**: whole-field ignore masks **format drift**. A timestamp that changes precision or timezone, a UUID that changes version, or a number that gains or loses a trailing zero will pass silently — the exact class of bug parity testing exists to catch.
+
+**Rule**: `ignore_fields` is for legitimately non-deterministic *values*. Ignore the value while still asserting the field's format/shape. Using it to drop business-logic fields — or to silence format drift on non-deterministic fields — defeats the purpose of parity testing.
+
+---
+
+## Serialization-Format Parity
+
+A differential oracle that compares only **deserialized objects** silently normalizes serialization-level differences away: it parses both responses into maps/objects and compares those, so any divergence that disappears on parse is invisible. To catch serialization bugs, the oracle must compare at a granularity that preserves the serialized form — either compare the **raw serialized string**, or explicitly assert the JSON shape.
+
+### What a Parsed-Object Compare Hides
+
+| Serialization divergence | Hidden when you compare parsed objects? |
+|--------------------------|------------------------------------------|
+| `1` vs `1.0` (number format) | Yes — both parse to the number `1` |
+| `null` vs a missing key | Yes — both read as absent/null |
+| `true` vs `1` vs `"true"` | Often — after type coercion |
+| Key ordering | Yes — object keys are unordered |
+| Leading zeros / scientific notation | Yes — normalized on parse |
+| Whitespace and Unicode escaping (`\/`, `\uXXXX`) | Yes — lost on parse |
+
+### Two Strategies
+
+1. **Raw-string comparison** — compare the exact serialized string. Strongest fidelity; use it when the wire format is part of the contract (public APIs, cached payloads, signed bodies).
+2. **Explicit JSON-shape assertions** — when raw compare is too strict (e.g. legitimately non-deterministic values), assert the shape explicitly:
+   - **key presence and order** (when order is contractual)
+   - **number format**: `1` vs `1.0`, leading zeros, scientific notation
+   - **`null` vs absent key** (an omitted field is not the same as an explicit `null`)
+   - **boolean/string type**: `true` vs `"true"` vs `1`
+
+### Cross-Language Rewrites Change the Serializer
+
+When a system is rewritten in another language, the serializer changes — and serializers differ in their **defaults**. The oracle must assert these explicitly, because nothing else will. Common PHP `json_encode` ↔ C# `System.Text.Json` default differences:
+
+| Concern | PHP `json_encode` (default) | C# `System.Text.Json` (default) |
+|---------|------------------------------|----------------------------------|
+| Number trailing zeros | `(float) 1.0` emits `1`; `JSON_PRESERVE_ZERO_FRACTION` is needed to keep `1.0` | `double` `1.0` serializes as `1`; `decimal` preserves scale |
+| Date / time | no native date type — app-defined (often a custom string or epoch) | `DateTime`/`DateTimeOffset` → ISO-8601 (round-trip "O"), e.g. `2026-05-12T08:30:00+00:00` |
+| Timezone | app-defined | `DateTimeOffset` keeps the offset; `DateTime.Kind` decides `Z` vs offset |
+| `null` properties | included as `"k":null` | included by default; omitted only with `DefaultIgnoreCondition.WhenWritingNull` |
+| Key ordering | insertion order (associative array) | property-declaration / reflection order |
+| Slash and Unicode escaping | escapes `/` and non-ASCII unless `JSON_UNESCAPED_SLASHES` / `JSON_UNESCAPED_UNICODE` | does not escape `/`; escapes non-ASCII per the configured encoder |
+
+### Asserting the Serialized Shape (TypeScript)
+
+```typescript
+// Beyond value parity: assert the serialized form, not just the parsed object.
+function assertSerializationParity(oldRaw: string, newRaw: string): void {
+  // 1. Strongest: exact serialized string (after stripping only ignored *values*).
+  if (oldRaw === newRaw) return;
+
+  // 2. Otherwise assert shape explicitly on the raw text, not on JSON.parse():
+  //    number format — a "1.0" in old must not silently become "1" in new
+  const numberShape = (s: string) => s.match(/:\s*-?\d+(\.\d+)?([eE][+-]?\d+)?/g) ?? [];
+  expect(numberShape(newRaw)).toEqual(numberShape(oldRaw));
+
+  //    null vs missing — an explicit "key":null must not disappear
+  expect(/"refund_id"\s*:\s*null/.test(newRaw))
+    .toBe(/"refund_id"\s*:\s*null/.test(oldRaw));
+}
+```
 
 ---
 
@@ -218,6 +301,8 @@ After all features are implemented, run parity check:
 | Overusing `ignore_fields` | Business logic differences hidden | Only ignore non-deterministic fields |
 | Skipping MANUAL snapshots | Untested webhook/background behavior | Author MANUAL snapshots before UAT |
 | Recording snapshots from broken system | Wrong baseline | Verify old system behavior before recording |
+| Comparing only the deserialized object | Serialization-format bugs (number format, `null` vs missing key, key order, type coercion) are normalized away on parse | Compare the raw serialized string, or assert the JSON shape explicitly (see Serialization-Format Parity) |
+| Whole-field `ignore_fields` on a non-deterministic field | Masks the field's **format** drift (timestamp precision/timezone, UUID version) | Ignore the value but still assert the format/shape (see `ignore_fields` Guidance) |
 | Characterization tests without `@characterization` | Gate 0 can't find them | Always annotate with `@characterization` |
 | Starting refactoring before Gate 0 | Behavior drift undetectable | Run characterization tests first, always |
 
@@ -229,6 +314,7 @@ After all features are implemented, run parity check:
 - [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) — `not_implemented` AC status
 - [Refactoring Standards](refactoring-standards.md) — Characterization test requirements
 - [Testing Standards](testing-standards.md) — Test implementation standards
+- [Data Migration Testing](data-migration-testing.md) — same "don't compare what merely *looks* equal" principle, applied at the DB storage layer (byte/codepoint encoding) rather than the oracle/serialization layer
 
 ---
 
@@ -237,3 +323,4 @@ After all features are implemented, run parity check:
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2026-05-12 | Initial version — snapshot schema, parity gate, Gate 0 characterization protocol (XSPEC-201) |
+| 1.1.0 | 2026-06-28 | Comparison-fidelity additions (XSPEC-306) — `ignore_fields` rewritten to "ignore value, assert format"; new Serialization-Format Parity section (raw vs. JSON-shape assertions, PHP↔C# serializer defaults); 2 format-masking anti-patterns; cross-ref to data-migration-testing |

package/bundled/core/browser-compatibility-standards.md

@@ -2,10 +2,11 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/browser-compatibility-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-05-05
+**Version**: 1.0.2
+**Last Updated**: 2026-06-18
 **Applicability**: Frontend projects (web apps, progressive web apps, web components)
 **Scope**: universal
+**Owning Spec**: XSPEC-293 (orthogonal to XSPEC-209 route coverage)
 **Industry Standards**: Browserslist, W3C WebDriver, WebDriver BiDi
 **References**: [caniuse.com](https://caniuse.com/), [Playwright browser support matrix](https://playwright.dev/docs/browsers)
 
@@ -27,6 +28,16 @@ Browser compatibility issues are among the most user-visible defects, yet they a
 | **Tier-2** (Partial support) | Best-effort; major flows must work | ≥ 95% pass — WARN if below, FAIL if < 90% |
 | **Tier-3** (Best effort) | Not officially supported; defects logged but not blocking | Advisory only |
 
+> **Tier-2 `≥95%` / `<90%` thresholds — basis & configurability**: these are UDS
+> defaults, configurable per project. Tier-2 is "best-effort, major flows must
+> work", so the gate tolerates a small tail of non-critical failures: `≥95%` =
+> healthy (WARN below, to prompt triage); `<90%` = material regression (FAIL).
+> Tune them to your target-market browser coverage — e.g. derive the Tier-2
+> browser set and the pass bar from your Browserslist market-share config
+> (`> 0.5%` etc.). **Exception**: when the failing Tier-2 cases are all
+> non-critical flows (logged as Tier-3-style defects), a release owner may
+> override the WARN/FAIL with a recorded justification.
+
 ---
 
 ## Default Browser Matrix
@@ -209,6 +220,8 @@ last 2 ChromeAndroid versions
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.0.2 | 2026-06-18 | Added: basis + configurability + exception note for Tier-2 95%/90% thresholds (XSPEC-292 T8 / XSPEC-293 AC-293-2) |
+| 1.0.1 | 2026-06-18 | Added: Owning Spec pointer → XSPEC-293 (XSPEC-291 §11) |
 | 1.0.0 | 2026-05-05 | Initial release: Tier-1/2/3 matrix, Playwright config, cloud testing, release gate criteria |
 
 ---

package/bundled/core/checkin-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/checkin-standards.md)
 
-**Version**: 1.6.0
-**Last Updated**: 2026-04-20
+**Version**: 1.8.0
+**Last Updated**: 2026-07-09
 **Applicability**: All software projects using version control
 **Scope**: partial
 **Industry Standards**: SWEBOK v4.0 Chapter 6
@@ -96,7 +96,7 @@ pytest --cov=src tests/
 ```
 
 **Verification**:
-- Run all test suites locally
+- Run all relevant tests locally (see "All relevant tests pass" above — directly exercised code plus tests affected by the change, via test impact analysis tooling if the project has it); when scope is unclear, or the change touches shared/core paths, run the full suite instead
 - Review test coverage report
 - Ensure new code paths are tested
 
@@ -151,6 +151,12 @@ describe('Regression: [BUG-ID or description]', () => {
   - Cyclomatic complexity ≤10
   - No duplicated code blocks
 
+  > Thresholds are UDS defaults, configurable per project. Cyclomatic complexity
+  > ≤10 follows McCabe's original guidance (McCabe, 1976) — the value most
+  > linters (ESLint `complexity`, SonarQube) default to; the method-length and
+  > nesting limits are common style-guide defaults aimed at readability, not
+  > hard rules. Tune them to your language/team.
+
 - [ ] **Security checked**
   - No hardcoded secrets (passwords, API keys)
   - No SQL injection vulnerabilities
@@ -1005,6 +1011,7 @@ git commit -m "feat(module-c): add export to CSV feature"
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.7.0 | 2026-06-18 | Added: source + configurable note for code-smell thresholds (McCabe 1976 cyclomatic complexity; linter defaults) (XSPEC-292 T8) |
 | 1.5.0 | 2026-03-18 | Added: AC coverage verification, batch threshold trigger, automated check-in rules |
 | 1.4.0 | 2026-01-16 | Added: Bug Fix Testing Evaluation section with decision matrix |
 | 1.3.0 | 2026-01-05 | Added: SWEBOK v4.0 Chapter 6 (Software Configuration Management) to References |

package/bundled/core/code-review-checklist.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/code-review-checklist.md)
 
-**Version**: 1.3.0
-**Last Updated**: 2026-01-12
+**Version**: 1.4.0
+**Last Updated**: 2026-06-18
 **Applicability**: All software projects with code review processes
 **Scope**: universal
 **Industry Standards**: SWEBOK v4.0 Chapter 10
@@ -476,6 +476,13 @@ jobs:
 | 200-500 lines | 1 day | 2 days |
 | > 500 lines | 🚨 Consider splitting | 3+ days |
 
+> **Sources & configurability**: the size tiers reflect the empirically observed
+> drop in review effectiveness past ~200–400 changed lines (SmartBear/Cisco code
+> review study; [Google engineering practices](https://google.github.io/eng-practices/review/)).
+> The response-time targets are UDS defaults — replace them with your team's
+> review SLA. **Exception**: generated or vendored bulk changes (lockfiles,
+> migrations, snapshots) are reviewed by spot-check, not by line count.
+
 ### Reviewer Availability
 
 - Set "review hours" in team calendar
@@ -657,6 +664,7 @@ Comment Prefixes:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.4.0 | 2026-06-18 | Added: source + configurability note for PR-size/response-time thresholds (SmartBear/Cisco study, Google practices) + bulk-change exception (XSPEC-292 T8) |
 | 1.3.0 | 2026-01-12 | Added: Comprehensive Refactoring PRs section with pre-review checklist, review focus areas, large refactoring guidelines, red flags, and best practices |
 | 1.2.0 | 2026-01-05 | Added: SWEBOK v4.0 Chapter 10 (Software Quality) to References |
 | 1.1.0 | 2025-12-22 | Added: Alternative text labels section for review comments (Chinese label support) |