P2: Build and validate the production artifact after business acceptance

[tomqwu]

Current Priority Decision

The Church/Basketball business milestone was accepted in #289 on 2026-09-15. This platform track is resumed.

Execution lane: phase: platform-later. Status: active for discovery and local artifact work; waiting for a target and authorization before deployment.

Completed

PR #338 merged the reproducible production-image validation package. PR #339 merged the guarded provider-neutral staging acceptance runner. Exact PR #339 head 965fede3d99871679ab4a65430edc079d343cc48 passed make test-all (2,019 passed, 21 documented skips, all 73 Playwright), local HTTPS artifact validation and source/image security validation with no findings. The runner refuses non-HTTPS targets, release-SHA mismatches, missing approval references and remote use without explicit opt-in; the provider-disabled image digest and rollback commands are recorded in the issue receipts.

Remaining

The owner must name a disposable staging platform/project, region and hostname and explicitly authorize deployment. Then deploy the exact candidate with paid providers disabled, record source SHA/image digest/toolchain, run the guarded migration/HTTPS/playbook/browser acceptance, prove rollback, and update #284. Do not invent a target, install or authenticate a hosting CLI, create cloud resources, or deploy before that authorization.

All validation and code review remain local. GitHub Actions does not run tests, and Ollama is not a code-review provider. This issue stays open until the deployed staging evidence satisfies its unchecked acceptance criteria.

---

Current Implementation Handoff

Prepared 2026-09-13 for a lower-cost builder at source 21a4a804aa57580451edded04736b1f51aef7e48.
No CI checks. All implementation validation and code review run locally.
Use the shared builder contract and this issue's work packages; no xhigh model or automatic model upgrade is required. This is a detailed recommendation, not a claim that a smaller model cannot make mistakes or that tests have passed.

Risk/review focus: High: release artifact and operational rollout.
Start condition: ACTIVE FOR DISCOVERY; BLOCKED FOR DEPLOYMENT. Continue local evidence work, but deploy only after the owner names the staging target and explicitly authorizes deployment.

Source of Truth and Current State

• Dockerfile
• Dockerfile.dev
• .dockerignore
• docker-compose.yml
• docker-compose.dev.yml
• docker-entrypoint.sh
• pyproject.toml
• poetry.lock
• api/main.py
• tests/unit/test_docker_packaging.py

Dockerfile runs a root Poetry install after copying source but not README.md, which pyproject declares as readme. Entrypoint migrates on every start and CMD fixes four workers; do not treat source-copy assertions as proof a clean image starts.

This handoff supersedes stale implementation statements in the background below. Preserve existing successful behavior and tests. Recheck the current branch before editing; the baseline is a source pointer, not permission to discard newer changes.

Dependencies and Ownership

• Current execution prerequisite: owner reactivates this deferred track after P1: Accept complete Church and Basketball day-to-day business flows #289. Original provider/platform dependencies are retained as future acceptance, not blockers for the current business flow.
• Coordinate, but do not wait for entire tickets to close merely to inspect/write isolated tests: P1: Make workflow notifications reliable; defer multiworker rollout #266, P2: Add production monitoring after business-flow acceptance #267, P2: Prove production recovery and retention after business acceptance #268, P2: Complete release security validation after business acceptance #269, P2: Reconcile platform assurances with later release evidence #284.
• The final commands below require P1: Repair local test entry points, coverage and isolation #281's safe local environment or an equivalently verified isolated setup. A missing dependency blocks only the slice that needs it; document that state.
• Shared source/ORM/migration changes are serialized per the master roadmap. Do not start concurrent edits to the same ownership area.

Recommended Decisions

1. Build one immutable runtime artifact from the locked source; include package metadata, templates/static assets and migrations. Keep nonroot runtime and separate build tools from runtime.
2. Recommend an explicit one-shot migration operation before starting application replicas; replicas must not race to migrate or repair schema with create_all. Validate upgrades before changing the boot contract.
3. Do not choose four workers as evidence of working SSE. Use P1: Make workflow notifications reliable; defer multiworker rollout #266's shared event transport before multiworker release, or document an owner-approved single-worker limitation rather than claim scaling.
4. Keep PostgreSQL/Redis on the private application network, authenticated health checks, environment names matching P2: Validate production configuration after business-flow acceptance #258, and TLS/trusted proxy configuration explicitly supplied by the operator.

Small Work Packages

Each item is one reviewable slice, not permission for one giant PR. Add the failing regression first; finish code, tests and affected docs for that slice together. Leave this issue open until all packages and original acceptance criteria are satisfied or explicitly revised by the owner.

• 265.1: Add failing packaging/entrypoint tests, repair the smallest metadata/install issue and run a fresh local container build.
• 265.2: Separate migration execution from app startup and test upgrade failure, process signals and readiness in a disposable stack.
• 265.3: Exercise the built image with production settings and PostgreSQL: login, static assets, basic roster, publish, export and worker/broker connectivity.
• 265.4: Record source SHA/image digest/base/toolchain versions, scan report, migration outcome and authorized staging smoke; update P2: Reconcile platform assurances with later release evidence #284 runbook.

Required Regression Cases

These are specifications for tests to add/retain, not claimed execution results. Each new negative case must assert unchanged unauthorized state and zero forbidden side effects.

• T265-01: Clean build without repository bind mount -> imports api/web, renders real assets and exposes intended app entry points.
• T265-02: Migration failure -> application never becomes ready; starting two replicas cannot run competing migrations.
• T265-03: Nonroot container stops gracefully on SIGTERM; no secret file appears in image layers or build output.
• T265-04: Private datastore ports are not publicly published; authenticated Redis health works; image identity matches the tested digest.

Local Commands and Evidence

Existing targeted commands (paths checked against the audit source; run only after the stated safe preflight):

poetry run pytest tests/unit/test_docker_packaging.py tests/unit/test_secret_key_guard.py tests/api/test_readiness.py -q

Also run the shared formatting/lint/touched-type/unit/full-suite and local review protocol from #252 for the final pushed revision. Add new targeted tests to these commands when implemented. Run API and browser tiers in separate processes. Native, PostgreSQL, image, provider and operator drills require their explicit environment; an unavailable tool/target is blocked/not run, never a pass.

Schema and Compatibility

Use #260's migration history unchanged unless an explicit upgrade defect is fixed. Application rollback must remain compatible with the migrated schema; downgrade is not an automatic rollback strategy.

Stop Conditions

No Docker daemon -> runtime slice blocked, not passed. No staging target/region/operator approval -> stop before deployment. Never delete shared volumes to obtain a clean build.

After two failed focused repair attempts without new diagnostic evidence, stop the affected package and post the exact failure, commands, suspected boundary and needed decision. Do not silently broaden scope, weaken tests or upgrade models. A fresh local reviewer checks: Inspect actual image contents and runtime process/DB behavior, not only Dockerfile text; compare tested and deployed digests.

Completion Receipt

• Work-package and regression IDs above map to changed files and actual results.
• Commands, versions, dates, pass/fail/skip/not-run counts, logs/screenshots and tested head/base SHAs are linked.
• A separate local review records findings and resolution; self-review is labeled if used and is not misrepresented as independent review.
• Affected docs/README/playbooks/screenshots and dependency/roadmap status are reconciled, not left as unnamed follow-ups.
• If implementation is authorized through PR/merge, GitHub reports mergeable and the shared local-evidence requirements are met; reviewer agents never merge.
• No hosted CI check, status attestation, Ollama reviewer, live provider action, deployment, real-data purge or store submission was introduced by implication.

Copyable Builder Prompt

First read this issue's Current Priority Decision and #289. Run only its NOW slice.
If this issue is deferred, report that state instead of starting the older package list.
Implement the next ready work package in tomqwu/SignUpFlow issue #265.
Read its Current Implementation Handoff and #252 Builder Handoff Contract first.
Inspect current source and preserve newer/unrelated changes. Start with the
package's failing regression, then complete code, local tests, local review and
affected docs/assets together. Do not skip acceptance or invent passing evidence.
No CI checks or Ollama code review. Do not deploy, activate providers, purge real
data or submit to stores. Stop and report unmet prerequisites or policy decisions.
Record the package/test IDs and exact reviewed/tested source SHAs before claiming done.

---

Earlier Audit and Acceptance Context

Current policy (2026-09-13)

No CI checks. Everything is validated locally. This includes code review,
formatting, lint, type checks, migrations, all test tiers, security scans,
artifact checks and mobile validation. Do not add hosted jobs, required CI
statuses, synthetic success checks or an Ollama reviewer. GitHub is for source,
PRs, issues and publication, not validation.

Record commands, environment, results, limitations and reviewed head/base SHAs.
Builders merge only with completed local evidence and GitHub mergeability;
reviewer agents never merge. Real staging/provider/device acceptance remains
required where applicable, driven by authorized local operator tools.
Historical evidence and older comments do not override this policy.

Parent roadmap: #252

Priority: P1, blocks core production pilot. Phase: C. Suggested owner: Platform/release. Original estimate (superseded; re-estimate remaining work): 4-6 engineering days.

Historical audit evidence (recheck against current source)

Dockerfile:40 installs the root Poetry project without copying the README declared by pyproject.toml:6; only api is listed as a package although api.main imports web. These packaging risks were not verified with a clean Docker build in this audit. docker-compose.yml publishes PostgreSQL/Redis ports, requires a Redis password but probes it without authentication, omits ENVIRONMENT, and starts no active worker service. docker-entrypoint.sh migrates on every container start. GitHub shows only a github-pages environment, not a verified backend staging deployment.

Source baseline: GitHub main 214e3f3f17a582d5f9b2063be6872ea2b1d25714, audited 2026-09-09. Infrastructure/provider claims marked unverified require actual staging evidence.

Implementation plan

1. Resolve the owner's hosting region/provider, budget, external hostname and rollback operator, then document one supported topology with managed or private PostgreSQL/Redis and TLS termination.
2. Build from a clean checkout using a pinned compatible Python/Poetry toolchain. Correct project/README/web template/static packaging and smoke-test imports/assets from the actual image, not the source tree.
3. Fix authenticated Redis readiness with a genuine successful PING check; keep database/broker ports private and wire the canonical production environment and broker settings.
4. Run migrations in a controlled once-per-deploy step, provision secrets through the hosting system, and restrict the running app's DB privileges.
5. Run artifact builds and smoke validation locally, retaining immutable image tags/digests. Promote the same tested image into staging and later production; record source SHA and migration revision.
6. Exercise rolling restart, graceful shutdown, failed migration and rollback to a known previous image without destructive automatic database downgrade.

Acceptance criteria

• A fresh clone produces an image that boots against fresh PostgreSQL, serves API/web/templates/static assets and exposes correct probes.
• Missing secrets/invalid configuration prevent readiness; no data-store ports are publicly exposed.
• Staging serves HTTPS with production cookie/security settings and no test bypass flags.
• The deployment records an immutable image digest, source SHA and migration version, and a tested rollback path.
• Local artifact checks have retained results for the exact source SHA and image digest.

Dependencies

#258, #260, #259

Validation

Clean Docker build and container smoke, staging login/invite/solve/publish journeys, migration failure drill and rolling restart. Store deployment logs/results without secrets.

Whole-repository audit scope (2026-09-13)

Baseline: 21a4a804aa57580451edded04736b1f51aef7e48. This addendum assigns full-scope follow-through; it is not a new test pass or production sign-off. No CI checks; all review and validation runs locally.

Review both Dockerfiles, both Compose files, .dockerignore, docker-entrypoint.sh, pyproject/lock and packaging metadata as one artifact contract. Verify README/root package metadata and web/templates/static assets are actually present in a clean build; source-existence tests alone are insufficient. Validate effective production env, private datastore exposure, Redis authentication/health checks, worker topology, migrations-on-boot/concurrent starts and immutable artifact rollback. #283 handles stale binary/demo tooling; #284 documents only proven commands. Record build source/digest and authorized staging evidence; do not deploy from this issue plan alone.

Keep evidence and disposition synchronized with master roadmap #252 and documentation ledger #277. Close only after the remaining acceptance criteria have linked local results; a planning/audit note is not completion.

[tomqwu]

Local production-artifact completion receipt

Merged in #321 at 9a5d3acde85f51f93a390c23e48a7009a6f2d97b.

Reviewed/tested PR head: cb6a8fdb393f954a9ce2a358f5a1bc351f49d8d5
Reviewed base: 6e833d446161ade845cb07cdd3987fbf948ab4e3
Review type: local self-review, explicitly not an independent reviewer.

Work packages

• 265.1 complete locally: clean locked image build; runtime contains API, web templates/static assets, Alembic metadata, and no build toolchain.
• 265.2 complete locally: migrations run once before replicas; failed/unmigrated startup remains unready; two replicas do not migrate; nonroot process exits cleanly on SIGTERM.
• 265.3 complete locally: image ran against PostgreSQL 16.14 and authenticated Redis 7.4.11; two replicas passed login/static/health/HSTS plus basketball create/invite/solve/publish/export.
• 265.4 locally complete except authorized staging: source, image, toolchain, lock/Dockerfile inputs, layer scan, migration outcome, and runtime results are retained. Staging was not run because no target or operator authorization exists.

Required regressions

• T265-01 passed: fresh image imports and serves the real API/web/static surfaces without a source bind mount.
• T265-02 passed: explicit migration succeeds; app startup against an unmigrated database exits 3 and does not create alembic_version; replicas start only after migration.
• T265-03 passed: runtime is UID 999/nonroot, app root is read-only, SIGTERM exits 0, final image/history/build output and all 10 saved layers contain no known in-process secret values or .env files.
• T265-04 passed: PostgreSQL/Redis publish no host ports; Redis PING is authenticated; tested image ID/digest is sha256:fb00fdfbac4306eb736058572fed555efb9bc7a482d29532633972ec34b62416.

Exact local evidence

• make test-all: 1,793 passed, 21 skipped, 0 failed/errors. test-artifacts/local-validation/20260915T020546.402533Z-68054-ed504bd0/report.json
• make test-postgres: 8 passed. test-artifacts/postgres-validation/2026-09-15T020532.140380-0000-67940-4df47cc4/report.json
• make test-artifact: passed. test-artifacts/artifact-validation/20260915T020446.920965Z-67750-a2ed41ad/report.json
• Black, Ruff, touched-module mypy, and git diff --check: passed.
• Initial local artifact attempts exposed production file logging and scan-environment defects; both were fixed and the exact final head was rebuilt/retested.

Deliberately not claimed

• Staging HTTPS, managed services, image promotion, and rollback were not run.
• External providers were disabled and not contacted.
• No hosted CI check, Ollama review, deployment, or provider activation was introduced.

Keep this issue open. Local artifact acceptance is complete, but the staging and tested rollback acceptance criteria still need an authorized target and operator evidence.

[tomqwu]

Current-main artifact refresh

After PR #337, the production artifact was rebuilt and exercised from exact main cb77a9fd295880359055e8aecc96bbb9d868c19e.

• make test-artifact: passed.
• Report: test-artifacts/artifact-validation/20260915T204739.531422Z-92487-264e40f3/report.json.
• Retained image: signupflow-artifact:cb77a9fd2958-264e40f3.
• Image ID/digest: sha256:fbf8d65e4ed7a9c63dc6230e1ed25fee81a27e71c96c008ea9e9e20fdef7c217.
• PostgreSQL 16.14 and authenticated Redis 7.4.11 ran on private, unpublished ports.
• Explicit migration passed; unmigrated startup failed closed with exit 3.
• Two nonroot, read-only replicas passed health, static assets, browser login, HSTS, basketball solve/publish/export, and graceful shutdown.
• Required-file, layer, build-output, environment-file, and known-secret scans passed.
• External providers were disabled and not contacted.

make test-postgres also passed 10/10 at the same source SHA; report: test-artifacts/postgres-validation/2026-09-15T204813.715061-0000-92841-432c997c/report.json.

Keep #265 open. This is owned local artifact evidence, not authorized staging HTTPS, promoted-image identity, managed-service behavior, or a deployed rollback drill.

[tomqwu]

Business milestone accepted; platform track resumed

Issue #289 is closed after explicit owner acceptance at current main cb77a9fd295880359055e8aecc96bbb9d868c19e. The roadmap now advances to the deferred platform/release gates in dependency order.

Next gate: #265 authorized staging artifact acceptance.

Current GitHub deployment inventory:

• environments: github-pages only;
• repository variables: none;
• application deployments: none;
• Actions secret names: OLLAMA_API_KEY only, unrelated to application deployment or code review;
• no staging hostname, platform project, region, managed PostgreSQL/Redis target, or operator identity is configured.

The exact local image, PostgreSQL, recovery, load, security, full-suite, and mobile receipts remain linked in the child issues. No staging deployment can be performed or claimed until the owner names a disposable target and explicitly authorizes its use.

[tomqwu]

Staging target discovery

Read-only host inspection found no configured application deployment path:

• no installed Railway, Fly, Render, DigitalOcean, Google Cloud, AWS, Kubernetes, or Heroku CLI;
• no corresponding user configuration directories;
• GitHub has only the github-pages environment and Pages deployment history;
• no repository deployment variables or application deployment secrets are configured.

No CLI was installed, no account login was attempted, and no environment was created. #265 remains waiting for an owner-selected disposable staging platform/project/region/hostname and explicit deployment authorization. External providers will remain disabled.

[tomqwu]

Local TLS artifact slice merged

PR #338 merged as ad9c323b6c31421478e4069de1f6130e7dfeb68c after GitHub reported exact head 49ad866cdb9320ab2485253a50ad8446ecc0ded0 as MERGEABLE and CLEAN.

Exact-head local evidence:

• make test-all: 2,012 passed / 21 skipped / 0 failures or errors, including all 73 Playwright tests.
• Suite report: test-artifacts/local-validation/20260915T215417.607325Z-18916-b7873465/report.json; tracked_tree_clean=true.
• make test-artifact: passed; report test-artifacts/artifact-validation/20260915T215319.575130Z-18464-0566350d/report.json.
• Retained exact image: sha256:5029cf4e9e36c70650d4b3f47be6924c89a2ee7976d638ce717a43df224c2af8.
• The owned proxy negotiated TLS 1.3 / TLS_AES_256_GCM_SHA384, completed browser login/dashboard, verified Secure/HttpOnly/SameSite cookies, rejected a foreign-origin write with 403, and proved the session cookie was not sent over plain HTTP.
• make test-security: passed against the same source/image with 0 blocking, accepted, or reported findings; report test-artifacts/security-validation/20260915T215340.586927Z-18610-588c5b1e/report.json.
• Ephemeral TLS private material was deleted; external providers were disabled and not contacted.
• Local self-review found no issues and is not represented as independent review.

This advances the local portion of 265.4 and T265-04, but does not satisfy the unchecked staging criteria. No target was supplied and the report says staging was not run. Keep #265 open for an owner-selected, explicitly authorized disposable staging target, external ingress/managed TLS, deployed digest and migration identity, and a tested deployed rollback path.

[tomqwu]

Progress receipt (2026-09-15)

Merged PR #339 (82e715749060b9bbd2eb7ce5659d5accd8625d0b), adding a guarded, provider-neutral staging acceptance runner.

Evidence for exact source 965fede3d99871679ab4a65430edc079d343cc48:

• make test-all: 2,019 passed, 21 skipped, 0 failed/errors; all 73 Playwright tests passed.
• make test-artifact: passed for retained image signupflow-artifact:965fede3d998-d42c4cce; migrations, loopback TLS 1.3, two replicas, browser login, and a published scheduling workflow passed.
• make test-security: passed with no findings.
• New runner refuses non-HTTPS targets, release-SHA mismatch, missing approval references, and any remote use without --allow-authorized-remote; it checks /health and /ready before writing data and exercises every discovered playbook plus a browser session.

Still open: no disposable staging platform/project, region, hostname, or explicit deployment authorization has been supplied. Therefore staging was not contacted, #265.4 is not complete, and no deployment/provider configuration was changed.