universal-dev-standards 5.17.0 → 6.0.0

package/bundled/core/user-journey-testing.md

@@ -0,0 +1,102 @@
+# User Journey Testing Standard
+
+> **Language**: English | 繁體中文
+
+**Applicability**: Projects with multi-step, stateful user flows that span more than one user story
+**Scope**: universal
+
+---
+
+## Overview
+
+The User Journey Testing Standard defines the **TESTPLAN** format, which makes connected, sequential user journeys a first-class testing artifact. Where acceptance-criteria tests verify a single story in isolation, journey tests verify what AC tests cannot: **cross-story state continuity** — the chain of state that one step leaves behind for the next.
+
+A journey is described once in a human-readable `TESTPLAN-NNN.md` and mapped one-to-one onto automated E2E tests through shared `T-NNN` identifiers, so the plan and the executable suite never drift apart.
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| journey-test-assistant (skill) | Generates TESTPLAN and journey E2E skeletons |
+| flow-based-testing | Flow archetypes that journeys instantiate |
+| e2e-testing (option) | End-to-end execution layer journeys map onto |
+
+---
+
+## Guidelines
+
+- Every project MUST have at least one `TESTPLAN-NNN.md` documenting the main user journey.
+- TESTPLAN steps MUST be sequential and stateful — each step depends on prior state.
+- Every TESTPLAN MUST define personas before test steps.
+- TESTPLAN and automated E2E tests MUST use the same `T-NNN` identifiers.
+- Journey E2E tests MUST skip gracefully when the environment is unavailable.
+- Journey tests cover what AC tests cannot: cross-story state continuity.
+
+---
+
+## TESTPLAN Format
+
+- **File naming**: `TESTPLAN-NNN-<project-slug>.md`
+- **Location**: `test-plans/`
+
+### Required Sections
+
+| Section | Description | Format |
+|---------|-------------|--------|
+| **Personas** | Define all test actors with their role and permissions | `\| Actor \| Role \| Key Permissions \|` |
+| **Environment** | List environment prerequisites and verification commands | — |
+| **Test Groups** | `T-NNN` numbered test groups with a sequential dependency chain | — |
+| **Execution Order** | Dependency diagram showing `T-NNN → T-NNN` relationships | — |
+
+### Step Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[UI]` | Browser-based action, verify visually |
+| `[API]` | `curl` / API client verification |
+| `[CHECK]` | Expected result to confirm |
+| `[SKIP-if]` | Conditional skip with reason |
+| `★` | High-risk step requiring confirmation |
+
+### Step Format
+
+Each step declares:
+
+- **step_id** — `T-NNN-M` (group-step format)
+- **operation** — what to do, annotated with a `[MARKER]`
+- **expected_result** — what should happen
+- **precondition** — state from a previous `T-NNN` that must be satisfied
+- **depends_on** — comma-separated `T-NNN` identifiers
+
+---
+
+## Automation Mapping
+
+- **Principle**: every `T-NNN` group maps to a `describe()` block; every step maps to an `it()`.
+- **File pattern**: `*.journey.spec.ts` or `*.journey.e2e.test.ts`.
+- **Shared state**: journey tests MUST use shared `let` variables across `it()` blocks so each step builds on previous results.
+- **Skip strategy**: guard with `describe.skipIf(!BASE_URL)` for environment-dependent tests.
+
+---
+
+## Journey Categories
+
+| ID | Description | Required For |
+|----|-------------|--------------|
+| `platform-admin-journey` | Platform admin setup: login → org → project → pipeline | enterprise, saas |
+| `member-journey` | Org member: join → project access → pipeline view | enterprise, saas |
+| `dev-journey` | Developer: new project → spec → pipeline → artifact | all |
+
+---
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|-------------|----------|
+| `testplan-required` | Creating a new project | Generate `TESTPLAN-001.md` with personas, environment, and main journey steps before writing code | required |
+| `journey-before-code` | Starting project implementation | Define the user journey test plan first; journey tests act as living acceptance criteria | recommended |
+| `sequential-state` | Writing journey E2E tests | Use shared state variables (`let token, orgSlug, projectSlug`) so each step builds on previous results | required |
+| `graceful-skip` | Writing journey E2E tests | Guard with `describe.skipIf(!process.env.JOURNEY_BASE_URL)` so tests are skipped in unit CI | required |
+| `t-nnn-alignment` | Writing any E2E test | Reference `T-NNN` identifiers from TESTPLAN in test descriptions for traceability | recommended |
+| `persona-first` | Writing TESTPLAN | Define all user personas before writing any test steps | required |
+| `dependency-chain` | Writing TESTPLAN | Each test group must declare its `depends_on` list so execution order is explicit | required |

package/bundled/core/user-story-mapping.md

@@ -0,0 +1,96 @@
+# User Story Mapping Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/user-story-mapping.ai.yaml`
+> **Spec**: XSPEC-069 (cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines how teams construct and use **story maps** to plan product
+releases. It covers the three-layer story-map structure (Backbone activities,
+Walking Skeleton sub-tasks, Detail Stories), the MVP horizontal-slice rule,
+INVEST compliance per story, and Given/When/Then acceptance criteria tied to
+measurable product metrics. It prevents incomplete MVPs and ensures every story is
+testable and traceable.
+
+It is part of the **product-layer pack** (XSPEC-069), sitting between
+`prd-standards` (upstream intent) and `requirement-engineering` (downstream INVEST
+stories), with acceptance criteria tied to `product-metrics-standards`.
+
+> **Scope.** This standard defines the *story-map structure and MVP-slicing
+> discipline*. Concrete planning tooling (Miro/Jira) is an adoption choice.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Story-map three layers (backbone, walking skeleton, detail stories) | MUST |
+| REQ-002 | MVP horizontal-slice rule (no vertical-slice MVP) | MUST |
+| REQ-003 | Story INVEST compliance | MUST |
+| REQ-004 | Acceptance-criteria format (Given/When/Then, metric-tied) | MUST |
+
+### REQ-001 — Story Map Three Layers
+
+Every story map MUST be structured in three horizontal layers: (1) **Backbone**
+(top row) — user activities at the highest abstraction representing the complete
+end-to-end journey, each a verb phrase from the user's perspective; the backbone
+must represent the full journey, not only implemented features. (2) **Walking
+Skeleton** (middle row) — the minimum sub-tasks to make each backbone activity
+functional, organized vertically under each backbone item. (3) **Detail Stories**
+(bottom rows) — specific stories for variations, enhancements, and edge cases,
+prioritized vertically within each column (higher = higher priority).
+
+### REQ-002 — MVP Horizontal Slice Rule
+
+The MVP release boundary MUST be a **horizontal slice** across the story map,
+covering all backbone activities at the walking-skeleton level. An MVP covering
+only a subset of backbone activities (a **vertical slice** that perfects one
+activity while others are absent or non-functional) is PROHIBITED, because it
+cannot be evaluated end-to-end by users. **Exception**: single-activity products
+(e.g. a focused utility) are exempt if the full value proposition is delivered by
+that one activity; exceptions MUST be documented with rationale in the story map.
+
+### REQ-003 — Story INVEST Compliance
+
+Every story in the map MUST comply with the INVEST criteria from
+`requirement-engineering`: **I**ndependent, **N**egotiable, **V**aluable,
+**E**stimable, **S**mall (fits within one sprint at most; split if larger),
+**T**estable (objectively verifiable acceptance criteria exist). Stories that fail
+INVEST must be refined before entering a sprint; the assessment MUST be performed
+during backlog-refinement sessions.
+
+### REQ-004 — Acceptance Criteria Format
+
+Every story MUST have at least one acceptance criterion in **Given/When/Then**
+format, tied to a measurable product outcome from the `product-metrics-standards`
+hierarchy where applicable. Stories with criteria that cannot be objectively
+verified (e.g. "the page looks good") are non-compliant. Acceptance criteria MUST
+be written before development begins and MUST NOT be modified after it starts
+without PM and dev-lead sign-off (same revision policy as PRD changes).
+
+## Anti-Patterns
+
+- Vertical MVP slicing: perfecting one activity while other backbone activities are absent.
+- Stories without acceptance criteria entering development (no clear definition of done).
+- Backbone activities mapped to system components instead of actual user goals.
+- Story map used only for planning then discarded, not kept as a living tool.
+- Detail stories added directly without backbone and walking-skeleton context.
+
+## Integration with Existing Standards
+
+- **`prd-standards`** — PRD scope is realized as a story map and MVP slice.
+- **`requirement-engineering`** — stories follow the INVEST criteria defined there.
+- **`product-metrics-standards`** — acceptance criteria tie to a North Star driver.
+- **`acceptance-criteria-traceability`** — GWT criteria provide the AC traceability spine.
+
+## Related Specs
+
+- XSPEC-069 — UDS product-layer pack (this standard's source)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~004: three-layer map, MVP horizontal-slice rule, INVEST compliance, GWT acceptance criteria (XSPEC-069) |

package/bundled/core/verification-oracle.md

@@ -0,0 +1,167 @@
+# Verification Oracle Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/verification-oracle.ai.yaml`
+> **Spec**: XSPEC-256 (cross-project/specs/XSPEC-256-verification-oracle.md)
+
+**Scope**: universal
+
+## Overview
+
+A **test oracle** is the source of truth that decides whether software output is *correct*.
+Software without an oracle cannot be said to be "right" — you cannot even state whether it
+is right or wrong. This standard makes the **ground-truth oracle a first-class artifact**
+and turns "correct" from a one-time acceptance state into a **maintained invariant**
+re-verified on every change (DEC-077).
+
+It is the **correctness** member of the governance-gate family — alongside
+`license-compliance` (XSPEC-193, *licensing*) and `model-provenance` (XSPEC-255, *source*) —
+which all share the same shape: **registry/check → fail-closed gate → audit evidence →
+human-escalation ceiling**. The three are profiles of one mechanism over three axes:
+**licensing / provenance / correctness**.
+
+> **Scope.** This standard defines the *correctness oracle mechanism* (registry, grading,
+> gate timing, re-verification, evidence, escalation) and the acceptance evidence it
+> produces. The **oracle content (the correct answers) belongs to the customer** — it is
+> their domain, their ground truth (DEC-075 neutral mechanism / DEC-063 customer-owned
+> output). Enforcement engine wiring (e.g. VibeOps pipeline gates) is a downstream
+> adoption concern, not part of this standard.
+
+## The Oracle-ability Spectrum
+
+Not every requirement has a ready oracle. Grade each high-stakes feature by how readily its
+oracle exists — this drives cost, beachhead selection, and when a human must step in.
+
+| Tier | Oracle shape | Readiness / cost |
+|------|--------------|------------------|
+| 1 | Known-correct output of a legacy system | Most ready, cheapest (parity-provable) |
+| 2 | A batch of hand-computed / existing correct outputs | Ready (reproduce + scale) |
+| 3 | Regulation / formula (rules exist, examples missing) | Needs co-derived worked examples + sign-off (ATDD) |
+| 4 | Vague requirement (oracle must be *mined* from interviews) | Most expensive — the "translation problem" |
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Ground-truth registry as a first-class artifact, bound to AC | MUST |
+| REQ-002 | Oracle-ability grading (Tier 1–4) for every high-stakes feature | MUST |
+| REQ-003 | Fail-closed verification gate before ship | MUST |
+| REQ-004 | Sustained re-verification on every change (correctness as CI invariant) | MUST |
+| REQ-005 | Auditable verification evidence (N/N reproduced, no drift, trace) | MUST |
+| REQ-006 | Self-serve frontier ceiling — escalate when no oracle / unverifiable high-stakes | MUST |
+| REQ-007 | Oracle content sovereignty — content owned by customer, mechanism neutral | SHOULD |
+
+### REQ-001 — Ground-Truth Registry
+
+The correct answers a customer provides become a first-class artifact. Each ground-truth
+case carries an **input scenario + expected correct output**, and is **bound to the
+acceptance criterion** it proves (`acceptance-criteria-traceability`). At minimum the
+mechanism MUST support numeric and structured-output comparison, with per-field exemptions
+(e.g. `ignore_fields` for timestamps/ids). Example: a billing case "given orders + org
+state → the *correct* charge amount", not merely "the endpoint returns HTTP 200".
+
+### REQ-002 — Oracle-ability Grading
+
+Every high-stakes feature MUST be tagged with its oracle Tier (1–4, table above).
+A **Tier-4 (must-mine) feature MUST have a defined hand-off point** to an oracle-manufacturing
+flow (interview / Prototype Probe; XSPEC-252) that pulls the expensive end toward Tier 1–2.
+Beachhead selection SHOULD prefer Tier 1–2 features where the oracle is already ready.
+
+### REQ-003 — Fail-Closed Verification Gate
+
+Before a system may enter UAT/ship, it MUST **exactly reproduce every registered
+ground-truth case**. A non-reproduction MUST **block ship or escalate** — never silently
+pass (mirrors `license-compliance` blocklist and `model-provenance` denylist). The gate
+plugs into existing reviewer/QA gates and the audit logger.
+
+### REQ-004 — Sustained Re-Verification (the soul of this standard)
+
+On **every change / regeneration**, the full oracle suite MUST be re-run, making "correct"
+a **CI-grade invariant** rather than a one-time acceptance. **Drift** (was-correct, now-wrong)
+MUST be detected and **blocked**. This is the mechanization of DEC-077's "changed and still
+correct, and provably correct the whole time" — the differentiator a "generate-once, never
+re-verify" competitor cannot match.
+
+### REQ-005 — Audit Evidence
+
+Each verification run MUST emit an auditable report: *"this delivery reproduced N/N
+ground-truth cases, no drift, trace attached."* It plugs into the audit logger / hash chain,
+the `model-provenance` source evidence (XSPEC-255), and the telemetry allowlist (DEC-066).
+**This report is the outward proof of the correctness/governance moat** and a compliance
+artifact for the customer.
+
+### REQ-006 — Self-Serve Frontier Ceiling
+
+Where there is **no oracle** (correctness is not decidable) or a **high-stakes but
+unverifiable** path, the system MUST NOT let self-serve silently pass. It MUST flag
+"a human must decide / an oracle must be supplied here" and **escalate** (DEC-076 ceiling).
+Defining correctness and signing off acceptance are **human judgments** (customer / legal /
+regulator) — a product-enforced governance gate, not a consultant trap.
+
+### REQ-007 — Oracle Content Sovereignty
+
+The verification *mechanism* is domain-neutral (DEC-075); the *correct answers* are owned by
+the customer (DEC-063). Adopters SHOULD keep registries customer-scoped and isolated
+(see `model-provenance` / `license-compliance` per-customer salt patterns, DEC-064).
+
+## Principles
+
+| ID | Principle |
+|----|-----------|
+| P-1 | Oracle First — no oracle, no "correct"; grade oracle-ability before claiming correctness |
+| P-2 | Maintained Invariant — re-verify on every change; drift is a blocking event (DEC-077) |
+| P-3 | Fail-Closed — non-reproduction blocks or escalates; never silent pass |
+| P-4 | Evidence-Based — every verdict carries a reproducible trace (N/N + diff + audit id) |
+| P-5 | Human Ceiling — unverifiable high-stakes escalates to a human (DEC-076) |
+| P-6 | Content Sovereignty — mechanism neutral, correct answers owned by the customer |
+
+## Gate Timing
+
+```
+spec(SDD) → generate → [oracle verification gate]  ← REQ-003 fail-closed, pre-ship
+                              │
+        on every change ─────┤ → re-run full oracle suite  ← REQ-004 drift block
+                              ↓
+                    audit evidence report  ← REQ-005 (outward moat proof)
+                              │
+   no oracle / unverifiable ──┴──→ escalate to human  ← REQ-006 ceiling
+```
+
+## Relationship to the Governance-Gate Family
+
+| Profile | Standard | Axis | Registry/Check | Block trigger |
+|---------|----------|------|----------------|---------------|
+| Licensing | `license-compliance` (XSPEC-193) | legal | blocklist/allowlist/greylist | prohibited license |
+| Provenance | model-provenance (XSPEC-255, planned sibling) | source | model source policy | denied source |
+| **Correctness** | **`verification-oracle` (XSPEC-256)** | **correct** | **ground-truth registry** | **non-reproduction / drift** |
+
+All three: fail-closed + audit evidence + customer override telemetered + human-escalation ceiling.
+
+## Integration with Existing Standards
+
+- **`acceptance-criteria-traceability`** — oracle cases bind to AC; reproduction becomes a
+  form of AC coverage.
+- **`verification-evidence`** — the oracle report is a kind of verification evidence (N/N
+  reproduction + no-drift + trace).
+- **`test-governance`** — the oracle suite is governed test policy; the gate is a governed gate.
+- **`behavior-snapshot`** — a parity/snapshot gate is REQ-003/REQ-004 instantiated for the
+  refactor/migration case; a snapshot is itself an oracle, so the skeleton may be shared.
+
+## Related Specs
+
+- XSPEC-256 — Verification Oracle complete spec (this standard's source)
+- DEC-077 — Correctness as a maintained invariant (mother decision)
+- DEC-075 — VibeOps domain-neutral positioning (neutral mechanism)
+- DEC-076 — Self-serve customization north star (oracle = self-serve ceiling)
+- DEC-063 — Legal & compliance strategy (customer-owned output / high-stakes)
+- DEC-066 — Telemetry-driven product evolution (audit/telemetry)
+- XSPEC-193 / XSPEC-255 — sibling governance-gate profiles (licensing / provenance)
+- XSPEC-252 — Domain pack requirement translation (oracle manufacturing, Tier-4 hand-off)
+- XSPEC-188 — UAT ship-decision dashboard (business-level UAT anchors)
+- XSPEC-201 — Refactor/migration completeness (behavior-snapshot = an oracle instance)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~007: ground-truth registry, oracle-ability grading, fail-closed gate, sustained re-verification, audit evidence, self-serve ceiling, content sovereignty (XSPEC-256) |

package/bundled/core/versioning.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/versioning.md)
 
-**Version**: 1.2.0
-**Last Updated**: 2025-12-30
+**Version**: 1.5.0
+**Last Updated**: 2026-07-01
 **Applicability**: All software projects with versioned releases
 **Scope**: universal
 **Industry Standards**: Semantic Versioning 2.0.0
@@ -156,6 +156,94 @@ Format: `MAJOR.MINOR.PATCH+BUILD`
 - Use for CI/CD tracking
 - Include in artifacts but not in version comparison
 
+> **Critical: build metadata MUST NOT be used as a deployment discriminator.**
+> Because tooling ignores `+build` in precedence and comparison (above), two builds
+> differing only in build metadata (`1.2.3+abc` vs `1.2.3+def`) are **indistinguishable
+> to version-comparison tooling** — rollback targets and `semver` comparison treat them
+> as the same release. Using `+sha` to tell apart behaviorally-different deployed builds
+> is a governance bypass: the version stops being the join key for changelog / SBOM /
+> audit / rollback / SLA / CVE scope. A change that ships MUST get a real version bump or
+> a unique immutable artifact identity (see **Deployment Version Identity** below) —
+> `+sha` is **not** a substitute.
+
+---
+
+## Deployment Version Identity
+
+> Source: a recurring failure mode — multiple behaviorally-different hotfix builds
+> deployed under the same `X.Y.Z`, distinguishable only by `+sha`, so answering
+> "which build is in prod / is fix X actually deployed?" collapses into commit
+> archaeology.
+
+This section governs the identity of a **deployable unit** — whatever that unit is for the
+project (a container image, a tarball, a published package). It complements the
+[Release Process](#release-process) below, which describes one concrete single-host release
+flow; the identity rules here apply regardless of the deployment mechanism.
+
+### Core invariant
+
+**Every distinct deployable build artifact MUST carry a unique, immutable version
+identity (version proper + commit sha).** Deploying, *promoting*, or *rolling back*
+an **existing** artifact MUST NOT change its identity.
+
+- **Anchor on the artifact, not the deploy action.** A new build (different source or
+  dependencies) ⇒ new version. The *same* build moved between environments
+  (staging → prod, build-once-deploy-many), redeployed (blue-green / canary), or
+  rolled back is the **same** artifact and keeps its identity — it MUST NOT be
+  re-bumped. Re-bumping on promote/rollback makes the version number lie about what
+  is actually running. (When a rollback restores a previous artifact, it restores that
+  artifact's original identity — it does not mint a new one.)
+- **Never deploy two distinct builds under the same `X.Y.Z`.**
+
+### Enforce automatically, not by discipline
+
+The invariant SHOULD be enforced by an automatic mechanism rather than human discipline
+alone — the failure mode above *is* a forgotten manual bump. Any of these satisfies it:
+
+- **Commit-driven release automation** (`semantic-release` / `standard-version`, see
+  [Automation Tools](#automation-tools)): derives and bumps the version from commit
+  history in CI, so a human cannot forget to bump.
+- **Git-height–derived versioning** (MinVer / Nerdbank.GitVersioning / GitVersion):
+  the version is derived from git commit topology, so a collision is structurally
+  impossible. RECOMMENDED for polyglot / .NET / JVM projects (the Automation Tools
+  section is otherwise Node-centric) — see the git-height subsection under
+  [Automation Tools](#automation-tools). Note caveats for monorepos and squash-merge
+  workflows.
+- **A CI uniqueness gate**: fail the release if the computed version already exists
+  as a git tag or in the registry.
+
+### Immutable artifacts (cross-reference)
+
+A unique *number* is necessary but not sufficient — the *artifact* must also be immutable
+and content-addressed (e.g. a container image referenced by digest rather than a mutable
+tag). The concrete artifact-level requirements — pinning deployments to a content address
+and forbidding tag/version reuse — **belong with container-image-standards** and are to be
+specified there; this standard only requires that the version identity itself remain
+unique and immutable.
+
+### Build identity is observable (requirement)
+
+**A deployed service MUST expose its build identity — `version + commit sha + build time` —
+through a queryable endpoint** (a dedicated `/version`, or embedded in `/health`), so
+operators can determine exactly what is running without inspecting the binary or resorting to
+commit archaeology. Rationale: manual version numbers can collide (above), so ops needs the
+`sha` to tell apart two builds that ship under the same `X.Y.Z`.
+
+Requirements:
+
+- The exposed `sha` MUST match the deployed artifact's sha — it is **verifiable, not
+  self-reported** (derive it from the build, do not hand-type it).
+- The endpoint SHOULD be access-controlled; a public build-identity endpoint leaks internal
+  commit identity.
+- Post-release verification MUST assert the returned sha equals the deployed artifact's sha
+  (see [Phase 5: Post-release Verification](#phase-5-post-release-verification)), not merely
+  that the version number is correct.
+
+This is a deployment / observability concern: the concrete verification *mechanism* (how the
+endpoint is scraped and the assertion wired into a gate) **belongs with deployment-standards**
+(to be specified there), and **supply-chain-attestation** already provides provenance as
+the cryptographic backing for "this artifact came from this sha".
+
 ---
 
 ## Initial Development
@@ -431,8 +519,10 @@ sudo ./upgrade.sh
 # 1. Check service status
 systemctl status your-service
 
-# 2. Check application version
-curl http://localhost:PORT/api/version
+# 2. Check application build identity (version + commit sha + build time)
+#    Assert the returned sha matches the deployed artifact's sha — not just the version.
+curl http://localhost:PORT/version    # or /health, if build identity is embedded there
+# Expected: {"version": "1.2.1", "sha": "<deployed-artifact-sha>", "buildTime": "..."}
 
 # 3. Check logs for no errors
 tail -100 /path/to/app.log | grep -i error
@@ -440,7 +530,9 @@ tail -100 /path/to/app.log | grep -i error
 
 **Success Criteria**:
 - Service running normally
-- API returns correct version number
+- `/version` (or `/health`) returns the correct version number **and** a commit sha that
+  matches the deployed artifact — a matching version alone is insufficient, since two builds
+  can share one `X.Y.Z` (see [Build identity is observable](#build-identity-is-observable-requirement))
 - No fatal errors in logs
 - Functionality verification passed
 
@@ -595,6 +687,32 @@ npm install --save-dev semantic-release
 }
 ```
 
+### Git-height–derived versioning (polyglot: .NET / JVM / multi-language)
+
+The tools above are Node/npm-centric. For **.NET, JVM, or multi-language projects**, prefer
+**git-height–derived versioning**, where the version is computed automatically from the git
+tag graph plus the number of commits since the last tag ("commit height") rather than stored
+in a hand-edited file. Because the version is a deterministic function of git history,
+**two different builds cannot collide on the same version number** and no manual bump step
+can be forgotten — this is what makes it satisfy
+[Deployment Version Identity](#deployment-version-identity) structurally rather than by
+discipline.
+
+| Tool | Ecosystem | Notes |
+|------|-----------|-------|
+| **MinVer** | .NET / MSBuild | Derives the version from the nearest git tag plus commit height; no config file, no build server integration required |
+| **Nerdbank.GitVersioning** (nbgv) | .NET (also Node and others) | Reads a `version.json`; stamps version + git height + commit id into assemblies and packages |
+| **GitVersion** | Polyglot (.NET, plus a language-agnostic CLI) | Configurable versioning modes (e.g. Mainline, Continuous Delivery / Continuous Deployment) driven by branch and tag topology |
+
+**When to use which:**
+
+- **Node / npm projects** → commit-driven automation (`semantic-release` / `standard-version`, above): the bump is derived from Conventional Commits.
+- **Polyglot / .NET / JVM projects** → git-height–derived tools (MinVer / Nerdbank.GitVersioning / GitVersion): the version is derived from git tag + commit height.
+
+Both families remove the forgettable manual bump. **Caveats:** in a monorepo a single
+repo-wide commit height may not map cleanly onto per-package versions, and squash-merge
+workflows alter commit height — validate the derived version against your tagging convention.
+
 ---
 
 ## Dependency Version Ranges
@@ -638,113 +756,14 @@ npm install --save-dev semantic-release
 
 ---
 
-## Breaking Change Communication
-
-### 1. Deprecation Warnings (N-1 Version)
-
-```javascript
-// Version 1.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);
-}
-```
-
-### 2. API Versioning Strategies
-
-Choose an API versioning strategy based on your needs:
-
-| Strategy | Format | Pros | Cons |
-|----------|--------|------|------|
-| URL Path | `/api/v1/users` | Clear, easy routing | URL pollution |
-| Query Parameter | `/api/users?version=1` | Optional versioning | Cache issues |
-| Header | `Accept: application/vnd.api.v1+json` | Clean URLs | Less visible |
-| Content Negotiation | `Accept: application/vnd.api+json;version=1` | RESTful | Complex |
+## Breaking Changes & Deprecation
 
-**Recommended**: URL Path versioning for most APIs (clearest for developers).
+Breaking changes drive the **MAJOR** version increment (see [Incrementing Rules](#incrementing-rules)) — that is how SemVer signals an incompatible change to consumers. The *contract-level* details of evolving and retiring an API are owned by the standards responsible for those concerns, so each rule has a single source of truth:
 
-### 3. Deprecation Timeline
+- **API versioning strategies, the backward-compatibility checklist (what counts as a breaking change), deprecation annotations in code, and the migration-guide template** → [API Design Standards](api-design-standards.md#api-versioning-strategies)
+- **The deprecation lifecycle, minimum notice periods by API tier, `Sunset` / `Deprecation` headers, and consumer notification** → [Deprecation & Sunset Standards](deprecation-standards.md#api-deprecation)
 
-Follow this timeline when deprecating API features:
-
-```
-v1.0.0 - Feature introduced
-v1.5.0 - Deprecation warning added (minimum N-1 version)
-v2.0.0 - Feature removed (document in migration guide)
-```
-
-**Deprecation Period Guidelines**:
-
-| API Type | Minimum Deprecation Period |
-|----------|---------------------------|
-| Internal API | 1 minor version |
-| Partner API | 2 minor versions + 3 months |
-| Public API | 2 minor versions + 6 months |
-| Critical Infrastructure | 1 year minimum |
-
-### 4. Backward Compatibility Checklist
-
-Before releasing, verify these backward compatibility rules:
-
-**DO NOT break (without major version bump)**:
-- [ ] Remove public API endpoints
-- [ ] Remove required request fields
-- [ ] Add required request fields
-- [ ] Change response field types
-- [ ] Change error code meanings
-- [ ] Remove response fields consumers depend on
-
-**Safe changes (minor/patch version)**:
-- [ ] Add optional request fields
-- [ ] Add new response fields
-- [ ] Add new endpoints
-- [ ] Add new error codes
-- [ ] Improve error messages
-- [ ] Performance improvements
-
-### 5. Migration Guide (N Version)
-
-```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)**:
-```json
-{ "data": { "user": {...} } }
-```
-
-**After (v2.0)**:
-```json
-{ "user": {...} }
-```
-
-Update your code:
-```javascript
-// Before
-const user = response.data.user;
-
-// After
-const user = response.user;
-```
-```
+This standard keeps only the version-numbering rule: an incompatible change MUST ship as a MAJOR bump, and deprecation SHOULD be announced in a prior MINOR before the removing MAJOR (see [MAJOR Version](#major-version-x00) guidelines).
 
 ---
 
@@ -834,6 +853,8 @@ semver.major('2.3.1');  // 2
 - [Changelog Standards](changelog-standards.md)
 - [Git Workflow Standards](git-workflow.md)
 - [Commit Message Guide](commit-message-guide.md)
+- [API Design Standards](api-design-standards.md) — API versioning strategies, backward-compatibility rules, migration guides
+- [Deprecation & Sunset Standards](deprecation-standards.md) — deprecation lifecycle and minimum notice periods
 
 ---
 
@@ -841,6 +862,9 @@ semver.major('2.3.1');  // 2
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.5.0 | 2026-07-01 | Added: git-height–derived versioning tools (MinVer / Nerdbank.GitVersioning / GitVersion) for polyglot / .NET / JVM projects in Automation Tools (UDS #138 R2); elevated "Build identity is observable" to a requirement — deployed services MUST expose `version + commit sha + build time` via a queryable endpoint — and added a commit-sha + build-time assertion to Phase 5 Post-release Verification (UDS #138 R3) |
+| 1.4.0 | 2026-06-24 | Moved out (to single sources): API Versioning Strategies (de-duplicated), Deprecation Timeline + per-tier periods, Backward Compatibility Checklist, and the Migration Guide template — now owned by api-design-standards / deprecation-standards; versioning cross-references them (XSPEC-298 R8, UDS #126) |
+| 1.3.0 | 2026-06-23 | Added: Deployment Version Identity section; build-metadata-as-deployment-discriminator caveat (from UDS #138) |
 | 1.2.0 | 2025-12-30 | Added: API Versioning Strategies, Deprecation Timeline, Backward Compatibility Checklist |
 | 1.1.3 | 2025-12-24 | Added: Related Standards section |
 | 1.1.2 | 2025-12-11 | Improved: Upgrade package naming example to use generic placeholders instead of hardcoded project names |