# CI cadence — local construction, final project integration, release

Current maintained-branch policy: [ADR-020](docs-adr-020-maintained-dev-main-delivery.md), explicitly requested 2026-10-06, supersedes the phase branch lifecycle below for future work. Develop on `dev`, integrate to protected `main` through a PR, and retain/synchronize dev after merge. For existing clean delivery or dev, use `bash scripts/git-flow.sh finish --base origin/main --pr NUMBER --required "Quick verification"`; every security/current-head/base/check guard still applies. Historical phase evidence and incomplete runtime/release obligations remain preserved. The phase commands below describe the earlier construction batch.

[ADR-018](docs-adr-018-project-batch-delivery.md) changes cadence on 2026-10-05 by explicit user request. Current local changes are not GitHub activation. Required main protection was last verified as Quick verification on 2026-09-30; this edit does not remove it. Historical G01-FLOW activation included draft runs and per-phase merges; those are superseded only after the workflow rollout.

## Level 1 — each microtask, local and specific

Run required task acceptance and relevant risk checks before its implementation commit. Docs/process: links, task/dependency consistency, changed templates/rules, whitespace and secret-surface checks. Go: changed package/consumers' actual tests, formatting, compilation and relevant vet. SQL/PostGIS/migrations: real DB schema/upgrade/transaction tests. Authentication/privacy/price precision/idempotency/jobs: positive and adversarial/failure cases; concurrency/race where relevant. OpenAPI/sqlc: affected contract vectors and generation drift. Infra: syntax plus smoke of the changed control. Android/iOS work after G09-LOCAL: affected module/Room/permissions/offline tests, without unrelated backend load campaigns.

Risk class `critical` includes identity/replay/authorization, precise prices/units, observation immutability/consensus, PII/media, transactions/migrations/jobs, backups and destructive-operation controls. `standard` covers ordinary noncritical logic; `docs` is nonexecutable documentation. A workflow/migration/script disguised as documentation is classified by behavior. Failures block the corresponding commit/integration; retrying away flakiness is not a fix.

## Level 2 — at the end of all authorized project construction phases

During construction, do not create phase PRs or inspect remote checks to decide whether the next source phase can start. Commit/push isolated phase branches as authorized; current push workflows target main only. Finish each phase with specialized local acceptance and a versioned evidence checkpoint, then start its dependent branch from the exact tested head. LOCAL_DONE / INTEGRATION_PENDING does not mean merged or certified. Immediate Level 1 checks remain required.

At final closure, prepare one cumulative PR to main, preserving phase/task commits. No bookkeeping-only follow-up PR. Run end acceptance once; preserve the user-directed end Android manual batch and iOS archive. Required Quick verification (`make quick-verify`) is the bounded integration gate, not full release certification. Local quick runs once through `finish` after required remote checks pass, avoiding repeated aggregate runs on pending CI. Unknown/missing/failed/skipped/cancelled results and stale heads/bases refuse merge.

All three ordinary workflows keep main pushes and PR events opened/synchronize/reopened/ready_for_review. Jobs run only on non-draft PRs or main pushes. Draft jobs may report skipped, which is NOT accepted gate evidence; the controller explicitly rejects drafts. Ready-for-review must trigger a real run, without a path filter on required quick. Subsequent commits rerun checks. Main-only pushes preserve final post-merge verification; backup phase pushes do not run CI. `backend.yml` and `ci.yml` remain path-selected supplemental signals on the final PR, with read-only permissions and per-ref concurrency to cancel superseded runs.

Quick keeps the existing contract/manifest selection, changed-file secret review, Go format/build/vet and short behavioral tests; sqlc/OpenAPI checks follow changed inputs. Compile-only is labeled as such. It does not replace immediate PostGIS/auth/privacy risk checks. No broad PostGIS/load/restore/device campaign for an unrelated docs edit. Source-wide dependency certification belongs to Level 3, but known vulnerable additions/failures must be addressed immediately.

Production workers never wait with 150/300 second sleeps or repeatedly poll a pending draft. Finalization is a bounded snapshot: finish exits CI_PENDING/failure instead of looping. Work on other authorized scope if available; otherwise report the pending action truthfully. A base merge/code/config change requires affected revalidation. Review configured protection and actual PR head/base/workflow identity at final closure; GitHub merge-ref evidence must correspond to that pair.

## Level 3 — full matrix on an immutable release candidate

Real-production backend candidate: after G24-ANDROID-COMMERCIAL (Android/backend scope, ADR-016) and all required backend extension/phase fixes are merged, P09 selects a clean checkout of a pinned commit. Run the union of full unit/static/coverage, real PostGIS/race/migration upgrade, OpenAPI/compatibility/golden, auth/privacy/evidence/moderation E2E, dependency/secret/image scans, image/startup, deployed edge/cache/TLS, fault/load, encrypted off-host restore and privacy-deletion replay checks. Include the existing Android regression baseline needed to preserve the shipped app. Record expected jobs and external-environment checks up front; a missing result prevents certification.

Reuse previously collected expensive specialized evidence only when it demonstrably covers the same artifact/config/environment and unchanged relevant inputs. Do not rerun a 30-minute load or restore exercise because a documentation field changed, but never label evidence for one binary as certification of a different one. A code/config change invalidates affected candidate evidence; a changed release SHA requires reconciliation of the full matrix before approval.

Full workflows are manual release-candidate dispatch and stable version tag verification, never every ordinary PR/push. A manual run must explicitly select/verify the intended candidate SHA after all required phase merges. No candidate/stable tags merely to trigger early full CI. A stable tag points to the certified SHA; any tag-triggered checks must pass before release publication/deploy. No automatic production deploy follows phase merges. Historical G18 retains its incomplete Android/iOS matrix; iOS is deferred until explicit resumption. G24 has the complete commercial Android functional/device/performance matrix before scoped actual G09; public P10 pilot and P11 releases require appropriate separate checks.

The full entry point grows as modules and environment checks are implemented. During P01, its harness proves selection and failure behavior against available foundation checks; absent future suites remain explicit outstanding work. Only the complete P09 expected-result manifest can certify G09. A tool exiting zero with only the initial foundation subset cannot satisfy the release gate.

## Rollout and evidence

Local policy/helpers/tests can be used in the isolated branch now. GitHub YAML behavior starts only after authorized integration; this change does not cancel existing jobs or claim remote settings were edited. Preserve the required Quick verification context. Draft skipping must never be used to bypass protection: the final PR is ready and its current real required run must succeed. Validate existing required names before rollout; a disappearing required check blocks merge, not justification for admin bypass.

Harnesses: `bash scripts/tests/test-project-batch-flow.sh`, `bash scripts/tests/test-git-flow.sh`, `python3 scripts/tests/test-ci-cadence.py`. They exercise checkpoint ancestry/staleness, worktree isolation, dry-run/no remote calls, draft/check refusal and workflow event conditions. Synthetic tests do not prove live GitHub activation or real production acceptance.

State: task/phase LOCAL_DONE / INTEGRATION_PENDING → final batch INTEGRATED → wiki PENDING/SYNCED separately → candidate RELEASE_CERTIFIED only after its complete matrix. Record tested behavior SHA/tree and real commands in phase evidence; post-merge records ride the next useful commit. No duplicate aggregate run or recursive record-only PR.