Most architecture standards die the same way: they become prose nobody maintains. Three months later the source has been renamed and reshaped while the standard still describes a system that no longer exists — and CI never notices, until the drift detonates in a customer environment.
BitzOrcas inverts this: the production-readiness contract is encoded as machine-readable JSON manifests and compile-time gate tests rather than promises. Source declarations answer what the system implements, manifests define which surfaces may ship, and architecture tests continuously prove that both still agree. If either side changes without the other, the gate fails before merge — so every contributor and every Consumer is held to the same rules.
What governance owns
| Concern | Page |
|---|---|
| The full quality-gate contract — CI matrix, test layers, status-code semantics, AOT/reflection/T-SQL gates, completion definitions | Quality gates |
| Manifest-driven production readiness — the surface-to-manifest mapping and the ratchets | Production readiness |
| The productized intake contract for a new module, adapter, background job, or endpoint | Extension intake |
The compile-time AppModule typed-marker system and the converged module set | Module governance |
| The per-module Ready / Out-of-Scope matrix and what “Ready” means | Readiness matrix |
| Framework/Profile/Host industry-neutrality rules and ownership boundaries | Industry-neutral surfaces |
Governance manifests
The manifests live in the source repository at docs/architecture/00-governance/manifests/ and are the machine-readable source of truth. The full table — with scope and purpose for each — is in Commercial GA gate. Highlights:
0008-error-catalog.json— the 1,968-entry strong-typed error catalog (see Defining errors)0013-runtime-license-policy-catalog.json— the shared runtime license policies and static combination boundary (see Runtime License)0002-production-adapter-readiness.json— the adapter readiness guard with five risk tiers0004-template-upgrade-map.json— the template version upgrade map (consumed by bitz-upgrade)
These numbers are not hand-maintained here: architecture tests such as ProductionReadinessNamingTests force every manifest to declare "scope": "production-readiness" and lock its naming structure. When source expands while a manifest lags, the build fails at the cheapest possible moment instead of inside a customer environment.
The decision record
Architectural decisions — why a choice was made, what alternatives were rejected, what is superseded — are recorded as ADRs. See Architecture decisions for the index and lifecycle.
What governance deliberately excludes
Internal process state (sprint ledgers, orchestrator tracking) and transitional migration notes stay in the source repository. They are not reader-facing documentation.
Chapter Navigation
- 01/07
Quality gates
The verify-all flow, CI matrix, test layers, API status-code contract, data-consistency test matrix, AOT/reflection/T-SQL gates, and the template completion definition that gate a BitzOrcas merge.
- 02/07
Production readiness
The manifest-driven production-readiness model — the surface-to-manifest mapping, the legacy ledger ratchet, and the adapter readiness guard that fails closed in Production/Staging.
- 03/07
Extension intake
The productized intake contract for a new module, adapter, background job, or endpoint — capabilities EXT-1 through EXT-8, default semantics, mandatory Operations visibility, and the fixed verification block.
- 04/07
Module governance
The compile-time AppModule system, the distinct current sets of 36 typed markers and 36 handbooks, the central legacy boundary, and the ledger ratchet governing module identity and dependencies.
- 05/07
Module readiness matrix
The current 36 Platform roots, their Ready / Out-of-Scope status, ProductionDepth semantics, and repository-wide persistence closure.
- 06/07
Industry-neutral surfaces
The ownership rules that keep Framework, generic Profiles, and Hosts vertical-free, the template adoption contract, and the AssignedLawyerId to AssignedOwnerId migration.
- 07/07
External Standards Reference List
The master list of external standards referenced by the platform and its manual: ProblemDetails (RFC 9457), HTTP QUERY (RFC 10008), the OAuth token family, TOTP, CSV and more — each with the authoritative link, source-code locations, and adoption mode.