Authority Doc / Public V1 Release Control

The Test And Release Gate defines the evidence that must pass before CoachMe code can merge, reach staging, or serve real users.

This page is the Public V1 authority for required pull-request checks, staging acceptance, production promotion, coverage thresholds, synthetic fixtures, release-critical journeys, web and mobile compatibility, security and defect blockers, mobile update evidence, release records, final approval, and post-deployment response.

AuthorityPull RequestStagingProductionNo WaiversPublic V1

Note

A release is approved only when every applicable required check passes and the release owner records a go decision. Urgency, disabled flags, or a known defect cannot waive a failed required check.

Scope

This authority decides when evidence is required, what blocks progress, and who approves release. Companion authorities define the detailed behavior being proved.

This Gate Owns

• Pull-request, staging, production, OTA, and native-binary gate levels.
• Required-check cadence and blocking behavior.
• Coverage thresholds and risk-based scenario requirements.
• Synthetic-fixture and staging-reset policy.
• Supported browser, OS, simulator, emulator, and physical-device evidence.
• Accessibility baseline, Arabic/RTL, dark-mode, visual, performance, and security release checks.
• Defect severity rules and the prohibition on waivers.
• Release-critical journey, evidence bundle, approval, two-hour release observation, and release disposition target.

Companion Authorities Own

• Runner and command choices: Toolchain Contract.
• Environment, migrations, backup, restore, and rollback mechanics: Environment Runbook.
• REST, event, offline, permission, privacy, and observability behavior: their named authority pages.
• Provider selection, region, terms, credentials, and launch evidence: Integration Register.
• Product scope and launch boundary: Public V1 Scope Contract.

Release Model

CoachMe releases continuously when evidence passes, while cross-surface compatibility determines whether surfaces can move independently.

Independent By Default

• API, coach web, coach mobile, and client mobile may release independently when no cross-surface dependency exists.
• There is no fixed release train. A release may proceed whenever every applicable gate passes.
• Production rollout is to all users for Public V1; progressive rollout is not required yet.
• Every releasable change begins with a pull request.

Coordinated When Dependent

• Compatibility, deprecation, and the coach/client supported-build registries follow the API Contract Standard.
• A change classified there as breaking or dependent blocks independent release and requires one coordinated plan.
• The release must prove every coach-mobile and client-mobile build that remains supported in those registries.
• Minimum-version enforcement and any critical security exception follow the API-owned compatibility contract.

Note

Promote the same immutable application artifact where the surface supports it. When app-store or native configuration requires a separate production binary, build it reproducibly from the same accepted commit, record its digest, and verify the production candidate before store release without another source change.

Gate Matrix

Each level answers a different question: is the change mergeable, is the release candidate acceptable, and did production promotion succeed?

Required checks by release stage

Stage	Required Checks	Blocking Rule
Pull Request	Format, lint, typecheck, unit, integration, contract checks, migration validation, build, coverage, documentation drift, security checks, smoke Playwright, and smoke Maestro.	Merge is blocked until every required check passes.
Staging	Complete Playwright, complete Maestro, accessibility baseline, RTL, dark mode, offline sync, migrations, performance, security, provider and operational checks, critical journey, and release evidence.	Production promotion is blocked until every staging gate passes against the immutable candidate.
Production	Deployment health, short critical-flow smoke, alert delivery, and two-hour observation.	The release remains incomplete until the production outcome is recorded.

Pull Request Gate

The pull-request gate gives fast, repeatable proof that a change is coherent enough to merge and produce a release candidate.

Static Quality

• Run the Toolchain-owned format, lint, typecheck, environment, and generated-file commands.
• Execute the complete local/CI-equivalent gate through pnpm verify.

Behavior

• Unit and integration tests.
• API and generated-client contract checks.
• Event, offline, permission, and privacy scenarios affected by the change.
• Playwright and Maestro smoke flows.

Change Safety

• Empty and upgraded seeded-database migration validation.
• Production builds for affected surfaces.
• Toolchain-owned secret detection and dependency-vulnerability checks.
• Required documentation changes.

Note

pnpm verify remains the stable local and CI-equivalent entry point. GitHub Actions owns enforcement; this page owns the pass requirement.

Staging Gate

Staging proves the complete release candidate in a production-like environment after a deterministic data reset.

1. Reset

Reset staging to the versioned synthetic-fixture baseline. Production data is never copied into staging.

Known state

2. Upgrade

Apply the release migrations, verify the upgraded seeded database, and record rollback, forward-fix, or restore posture.

Data

3. Execute

Run complete web and mobile E2E plus accessibility, visual, offline, event, security, performance, provider, and operational evidence.

Complete suites

4. Decide

Assemble the release report. Production remains blocked until every required result is green and the release owner records go.

Gate

Note

Every release uses the full staging baseline, including an API-only or web-only change. Authority-owned checks with an explicit cadence, such as infrastructure restore drills, run and block when that cadence makes them due.

Production Gate

Production receives the accepted immutable artifact, or the reproducible native production candidate defined in the Release Model, and remains under heightened observation until the release outcome is known.

Before Promotion

• Every staging result is passing.
• The release report is complete.
• The rollback, forward-fix, restore, and queue-recovery posture is recorded where applicable.
• Production backup evidence meets the Environment Runbook.
• The release owner can observe the next two hours.

After Promotion

• Verify health endpoints, deployment version, migrations, workers, queues, storage, auth, and required providers.
• Run the short production smoke path using the isolated synthetic identities defined by the Environment Runbook.
• Confirm alert delivery and watch launch dashboards for two hours.
• Record success, rollback, forward fix, or incident outcome in the release report.

Synthetic Fixtures

Repeatable evidence depends on known data, identities, clocks, permissions, and failure states.

People And Access

Coaches, clients, workspaces, relationships, support grants, unrelated tenants, ended relationships, and denied-access identities.

Coaching Work

Programs, forms, onboarding, assignments, daily tasks, progress, nutrition, media, messages, and notifications.

Technical States

API versions, migrations, events, retries, dead letters, offline operations, receipts, conflicts, provider failures, retention, export, delete, and purge.

Note

Production records, exports, media, logs, or database snapshots must never become test fixtures, even when described as anonymized.

Coverage And Risk

Numeric coverage protects the baseline; explicit scenarios protect the contracts where a missed branch could expose or lose user data.

Code coverage thresholds

Measure	Minimum	Rule
Statements	80%	The configured repository coverage project must not fall below the threshold.
Lines	80%	Generated code and approved non-executable declarations may be excluded consistently.
Functions	80%	Public behavior and domain decisions require direct coverage.
Branches	75%	Failure, denial, retry, conflict, and lifecycle branches remain explicit test targets.

Mandatory Regardless Of Percentage

Authentication, permission denial, workspace isolation, lifecycle transitions, offline replay and conflict, privacy export and deletion, migrations, media access, event/outbox transaction behavior, and support/admin access require their authority-owned positive and negative scenarios.

Supported Platforms

The compatibility gate is rolling, reviewable, and practical for the current one-developer team.

Supported browser and mobile platform matrix

Surface	Required Matrix	Evidence
Coach web	Current and previous two major versions of Chrome, Edge, Firefox, and Safari.	Playwright coverage plus targeted browser compatibility evidence.
iOS	Every major iOS version initially released within the previous five years.	Simulator matrix and critical physical smoke on iPhone 13 Pro Max.
Android	Every major Android version initially released within the previous five years.	Emulator matrix and critical physical smoke on Samsung S10+.

Note

Record the actual device and installed OS version in every release report. Review this matrix quarterly and before raising a minimum supported version. Add a broader physical or cloud-device matrix after launch when CoachMe usage data justifies it.

Accessibility, RTL, And Visual Gates

Public V1 uses a bounded accessibility baseline and automated visual proof without claiming complete WCAG conformance.

Accessibility Baseline

• Automated checks on critical coach-web screens.
• Keyboard navigation and visible focus.
• Accessible labels for interactive controls.
• Basic color contrast and non-blocking text scaling.
• One screen-reader smoke for each critical coach and client flow.

Visual Matrix

• Automated screenshots for critical screens.
• English and Arabic content.
• Left-to-right and right-to-left layout.
• Light and dark mode.
• Reviewed baselines; unexplained diffs block staging.

Note

A complete WCAG 2.2 AA audit, formal conformance claim, and broader assistive-technology matrix are Post-V1.

Performance Gate

The V1 gate detects regressions and obvious scale faults; it is not a forecast of first-year adoption.

50 Concurrent synthetic users

100 Synthetic coaches

10k Synthetic clients

<1% API error rate

Staging performance budgets

Measure	Required Budget
Coach web Core Web Vitals	LCP at or below 2.5 s; INP at or below 200 ms; CLS at or below 0.1 on critical pages.
Normal API operations under staging load	p95 at or below 500 ms; p99 at or below 1.5 s. Error rate is unexpected 5xx responses divided by completed representative requests and must remain below 1%; deliberate fault-injection requests and client-caused 4xx responses are excluded.
Physical mobile cold start	At or below 4 s on both owned devices.
Physical mobile warm resume	At or below 2 s on both owned devices.
Regression	No critical workflow more than 15% slower than its accepted staging baseline without investigation.

Note

These are staging load-test budgets. Production service objectives remain owned by Observability. Uploads, exports, media processing, and asynchronous jobs receive separate budgets based on payload and workflow.

Security And Defect Blocking

Required-check failure and known-defect severity are separate decisions; neither creates a waiver path for the other.

Always Blocks

• Secret or credential exposure detected by the Toolchain-owned scanner.
• Critical or high dependency vulnerability detected by the Toolchain-owned scanner.
• Failed authentication, authorization, or workspace-isolation evidence.
• Critical or high staging security finding.
• Any critical or high known defect.
• Any failed required check, regardless of urgency.

May Ship Only When Documented

A medium or low defect may ship only when every required check passes and the defect is outside the core coaching loop with no security, privacy, data-loss, accessibility-baseline, compatibility, or protected-contract impact.

Tests cannot be skipped, disabled, rewritten, or weakened merely to classify a failure as a known defect.

Canonical Release-Critical Journey

Every staging release proves the central coaching loop across coach web, API, worker, coach mobile where applicable, and client mobile.

1. Establish The Relationship

Coach signs in and invites a client. The client accepts, consents, and completes required onboarding forms. The coach reviews the onboarding and marks the profile READY_FOR_PROGRAMMING.

Onboard

2. Plan The Work

After the Workflow-owned readiness gate passes, the coach creates, publishes, and assigns a program containing daily tasks.

Assign

3. Execute Offline And Online

Client receives the assignment, completes daily tasks, records progress or nutrition, survives restart, and reconnects without duplication or data loss.

Execute

4. Review And Communicate

Coach sees the accepted completion and progress, then responds or sends a message.

Review

5. Prove The Boundary

An unrelated coach and client are denied access. The participating client can sign out and back in without losing accepted server state.

Protect

Note

Offboarding, export, deletion, retention, and media purge remain required staging scenarios. Backup-deletion replay follows Privacy; infrastructure backup/restore drills follow the Environment-owned cadence. These scenarios are outside the short production smoke path.

Mobile Release Gates

OTA updates and native binaries use different distribution mechanics but both remain staging-first releases.

Mobile release evidence by delivery type

Release Type	Required Evidence	Network And Compatibility Rule
Expo OTA	Runtime compatibility, OTA install, restart recovery, metered-network behavior, and rollback test.	Ordinary updates wait for Wi-Fi or unmetered access. Critical security or data-integrity updates download automatically even on a metered connection.
Native binary	Fresh install, upgrade from oldest supported version, store-build verification, and production smoke on iPhone 13 Pro Max and Samsung S10+.	Store rules govern installation. The server follows the API-owned supported-build registry and minimum-version contract.
Every mobile release	All applicable pull-request and staging gates.	No direct production publishing and no incompatible update to a native runtime.

Rollback And Alert Response

Rollback is a deliberate operator decision supported by immediate evidence, not an unobserved automatic action.

Decision Model

• Production rollback requires the release owner's manual decision.
• Application, configuration, migration, queue, and data-repair responses stay separate.
• A risky or irreversible migration has a forward-fix or restore plan before approval.
• Rollback never substitutes for audited production data repair.

Release Observation

• Observability owns alert severity, email delivery, contents, and general response targets.
• During the two-hour release-monitoring window, an attributable release-critical signal is acknowledged and dispositioned within one hour.
• The release report records the signal, decision, and resulting rollback, forward fix, or incident.

Release Evidence And Approval

Automation assembles the proof; the current sole developer records the final decision without inventing a second approver.

Automated Release Report

• Release id, commit, and immutable artifact digests. Branch names are excluded from the lifetime manifest.
• API, web, mobile, native-runtime, and generated-contract versions.
• Migration set and data-change posture.
• All required results, coverage, staging environment, and timestamps.
• Device and OS details, visual evidence, performance results, and security summary.
• Known defects, documentation changes, rollback plan, and production outcome.

Manual Decision

• The sole developer is the release owner for Public V1.
• The owner records go or no-go after reviewing the complete report.
• Self-approval is explicit; a second reviewer is not fabricated.
• When the team grows, independent high-risk review becomes revisitable.
• User-facing release notes are required only for user-visible changes.

Privacy-owned release evidence retention summary

Evidence Class	Retention
Non-identifying manifest, commit, digests, migrations, approval, outcome	Product lifetime.
Verified synthetic screenshots or videos with no real identifiers or telemetry	One year.
Detailed CI logs and failed-test artifacts	30 days under the synthetic-log maximum.
Accidental production, identifiable, or secret content	Quarantine, incident handling, and Privacy-governed deletion; never normal evidence retention.

Note

The Privacy And Retention classification and maxima override this summary.

Merge Completeness

• A pull request that changes product behavior, API contracts, workflows, permissions, privacy handling, configuration, or operations updates the corresponding authority, feature page, runbook, and release notes as applicable.
• Documentation drift is a required-check failure and blocks merge.
• All merged production code must be secure, tested, documented, migration-safe, and release-ready even when unreachable behind a disabled feature flag.

Legal And Regional Launch Boundary

Passing technical gates does not authorize real-user launch while the legal entity, privacy review, provider, or data-region decision remains unresolved.

Consumed Launch Blockers

• The Privacy And Retention legal-review gate is satisfied for the selected UAE business jurisdiction and real-user scope.
• No required Integration Register decision remains Conditional.
• No mandatory integration launch evidence remains Open or Blocked.
• Privacy notices, terms, consent, and wellness disclaimers have the approval required by the Privacy authority.

Regional Rule

• Real Public V1 users are UAE-only.
• Another GCC country requires the legal review and launch checklist defined by Privacy.
• Hosting, provider region, and cross-border admissibility follow the current Privacy outcome and Integration Register status.
• Existing Privacy and Integration change-control triggers remain binding; only an additional comprehensive legal re-review trigger list is deferred.

Note

Development, CI, staging, and synthetic testing may continue while these launch items are open. The block begins at accepting real production users.

Revisitable Decisions

Public V1 uses a strict but achievable gate for one developer. Changes require an authority update, not an undocumented exception.

Revisit After Launch Or Team Growth

• Progressive production rollout.
• Broader physical-device or cloud-device coverage.
• Independent approval for high-risk releases.
• Formal WCAG 2.2 AA audit and broader assistive-technology coverage.
• Legal re-review triggers.
• Threshold tuning using the first 30 days of real production evidence.

Never Change Through A One-Off Release

• Pull request before staging.
• Staging before production.
• Immutable artifact promotion.
• No waiver for a failed required check.
• No production data in fixtures.
• No undocumented breaking mobile/API change.
• No real-user launch while a required legal or provider decision is blocked.

Related Docs

These authorities define the behavior and evidence detail that this gate schedules, blocks, and approves.

Workflow State Map

Lifecycle states, transitions, failure outcomes, and workflow evidence.

Roles And Permissions

Positive and negative access contracts, isolation, and support/admin boundaries.

Privacy And Retention

Consent, data classes, retention, export, deletion, purge, incidents, and legal boundary.

API Contract Standard

REST behavior, generated contracts, compatibility, and deprecation.

Event And Outbox Standard

Transactional publication, retry, ordering, dead-letter, replay, and idempotency evidence.

Offline Sync Protocol

Offline mutation, replay, receipts, conflicts, restart, revocation, and purge evidence.

Environment Runbook

Promotion, migrations, backups, restore, rollback, data state, and environment health.

Toolchain Contract

Stable commands, runners, CI provider, codegen, builds, and mobile delivery tools.

Integration Register

Provider status, region, terms, failure behavior, and launch evidence.

Observability Plan

Launch signals, thresholds, dashboards, alerts, diagnostics, and post-deployment evidence.

Public V1 Scope Contract

Product scope and the first public launch boundary.

Development Readiness Review

Tracks implementation evidence and launch blockers after this authority exists.