P2: Reconcile platform assurances with later release evidence

[tomqwu]

Current Priority Decision

The Church/Basketball business milestone was accepted in #289 on 2026-09-15. Platform assurance reconciliation is active, but final closure waits for the deployment, monitoring and recovery receipts.

Execution lane: phase: platform-later. Status: active for documentation reconciliation; waiting on #265/#267/#268 for final evidence.

Completed

PR #338 reconciled current local artifact, TLS, security-scan, test and release-acceptance documentation. PR #339 added the guarded staging-acceptance procedure to README, testing, runbook, release-acceptance, roadmap, documentation-status and tool-inventory sources. Exact head 965fede3d99871679ab4a65430edc079d343cc48 passed 2,019 tests with 21 documented skips, local artifact validation and source/image security validation; make test-docs passed with 189 manual and 138 generated documents. The repository distinguishes local evidence from staging/production proof.

Remaining

As #265, #267 and #268 complete, map their exact deployed source/digest, monitoring receipt, isolated restore and approved policy evidence into the assurance matrix. Run 284.4 only against an explicitly disposable authorized target. Keep every unperformed production claim visibly unverified. Close only when the final documentation agrees with the actual evidence and #271 can consume it.

All tests and code review remain local. GitHub Actions does not run tests, and Ollama is not a code-review provider.

---

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: Medium/high: false security and operational assurances.
Start condition: ACTIVE FOR RECONCILIATION; WAITING ON #265/#267/#268 for final staging and operations evidence.

Source of Truth and Current State

• docs/SECURITY.md
• docs/RUNBOOK.md
• docs/DEPLOYMENT_GUIDE.md
• docs/DOCKER_DEVELOPMENT.md
• docs/ENVIRONMENT_SETUP.md
• docs/INDEX.md
• api/core/config.py
• api/main.py
• docker-compose.yml
• docker-entrypoint.sh

Do not retain Production-Ready/SOC2/HIPAA/GDPR-ready wording as factual certification. Correct partial fixes too: current billing guards and reset email wiring already exist; remaining acceptance is not the same as the historical defect.

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: P2: Validate production configuration after business-flow acceptance #258, P1: Prove local database correctness; defer production parity #260, P2: Build and validate the production artifact after business acceptance #265, 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: Run production release acceptance after business flows are accepted #271, P1: Reconcile every document and legacy spec with current source #277, P1: Make README, examples and public site match the product #278.
• 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. Use implemented/tested/unverified/planned status per control with source and dated evidence; a document cannot certify compliance or externally delivered alerts by itself.
2. Build a setting-to-reader-to-container-to-test matrix. Commands must match the actual artifact and distinguish local disposable checks from approved staging operations.
3. Prefer forward-compatible artifact rollback with explicit migration compatibility. Do not present alembic downgrade or restore-over-current-database as a routine safe command without a demonstrated drill.
4. One canonical current runbook with links from historical docs; no copied percentages, current test-count promises or invented hostnames/secrets.

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.

• 284.1: Remove/qualify unsupported current claims and wrong paths in a small first PR; retain historical content with clear supersession.
• 284.2: Trace every config/health/monitoring/provider statement to source and update current setup/deploy references.
• 284.3: Integrate actual artifact/alert/restore evidence from their owner issues and write operator preflight, failure, recovery and rollback procedures.
• 284.4: Run local link/config/command checks and an operator walkthrough against an explicitly disposable target before marking procedures verified.

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.

• T284-01: A current security claim without implemented control/evidence is labeled unverified rather than silently retained.
• T284-02: Every env row matches its runtime reader/default/effective container value; conflicting names fail a local consistency check.
• T284-03: Runbook failure/rollback steps preserve original data and name exactly which approved target they affect.
• T284-04: Billing/SMS/native enablement and real compliance assessment stay separate owner gates, not inferred from router presence.

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_runbook_doc.py tests/unit/test_secret_key_guard.py tests/unit/test_local_validation_policy.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

No schema work in documentation issue; link actual migrations/drill evidence from implementation owners.

Stop Conditions

Do not invent legal/compliance approval, RPO/RTO, operational recipients or production URLs. Mark missing evidence explicitly and request the needed owner decision.

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: Check factual claims against source plus actual run receipts, especially assertions of completeness, production readiness and successful external delivery.

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 #284.
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

Parent roadmap: #252. Audit baseline: 21a4a804aa57580451edded04736b1f51aef7e48 (2026-09-13).

No CI checks. All code review, formatting, lint, types, migrations, tests, security scans and artifact validation run locally. Do not add hosted validation, required CI statuses, synthetic success statuses or an Ollama code reviewer. Pages publication is separate. Record commands, environment, results, skips, limitations and reviewed head/base SHAs. Builders merge only after complete local evidence and GitHub mergeability; reviewers never merge.

This is planned work, not an implementation or production-readiness sign-off. The audit did not rerun the application/test suite, deploy, contact delivery/payment providers or validate a native release.

Findings

docs/SECURITY.md says Production-Ready and SOC 2/HIPAA/GDPR ready without supporting verification, and cites nonexistent api/core/security.py. These claims conflict with open security blockers #253-#258/#261.

docs/RUNBOOK.md treats the production configuration as operational: ENVIRONMENT is documented but not passed by production Compose; SENTRY_DSN is described as reporting even though startup only logs its presence; health/readiness both depend on the database and return raw exception text. Its dump/restore/rollback examples are not a demonstrated recovery procedure.

docker-compose.yml, Dockerfile, docker-entrypoint.sh, api/core/config.py and runtime env readers must be the source of truth, not a historical plan.

Plan

1. Immediately replace unsupported security/compliance/production certifications with dated implemented/tested/unverified controls and links to actual open blockers. Do not invent a compliance/legal assessment.
2. Build a configuration matrix for every runtime setting: canonical reader, default, production rule, Compose/entrypoint propagation, failure behavior and local test. Include provider/billing flags, signing keys, expiry, cookie security, debug flags, proxy/TLS, Redis, CORS and logging.
3. Reconcile deploy/upgrade/rollback commands with the tested artifact/migration strategy under P2: Validate production configuration after business-flow acceptance #258/P1: Prove local database correctness; defer production parity #260/P2: Build and validate the production artifact after business acceptance #265. Mark dangerous legacy downgrade/restore snippets non-operational until the drill is demonstrated.
4. Document effective service topology, worker/broker behavior, liveness/readiness, logs, alerts, recovery and data retention using P1: Make workflow notifications reliable; defer multiworker rollout #266-P2: Prove production recovery and retention after business acceptance #268 evidence. A configured DSN is not proof of delivery.
5. Add an operator acceptance record: source SHA, image digest, database version, commands, timings, logs, outcome, owner and limitations. Separate local source checks, staging drills, provider delivery, physical devices and public release.
6. Reconcile all current security/deployment/environment/Docker/SaaS/mobile support references and docs index. Archive misleading historical completion claims through the documentation ledger.

Acceptance

• No current security or operational document claims production/compliance readiness without linked evidence and scope.
• Config examples match actual readers and effective artifact settings; no real secrets appear.
• Deployment, migration, restore and rollback commands are proven on disposable authorized targets or clearly marked blocked.
• Monitoring docs distinguish implemented logging, actual error reporting and verified alert receipt.
• Recovery and retention promises match measured behavior and owner-approved policy.
• Unsupported email/SMS/billing/mobile enablement is visibly separate from the core pilot.

Validation / Dependencies

Local source/config/link tests first; authorized local operator drills only after #258/#260/#265/#266/#267/#268. Documentation correction need not wait for those implementations: state the gaps honestly now. No deployment, real data purge, provider activation or release is authorized here.

Delivery Ownership and Cross-links

Suggested owner: Security/platform documentation owner (not yet assigned). Roadmap order: 0 and final reconciliation in 3. Implement in small locally reviewed PRs; no source changes are made by filing this issue.

Coordinates #277 documentation ledger and #278 public claims; #271 is the final release-evidence consumer, not proof that these corrections already exist.

[tomqwu]

Configuration assurance receipt from PR #320: merged 6e833d446161ade845cb07cdd3987fbf948ab4e3. The maintained config matrix now lives in docs/PRODUCTION_CONFIGURATION.md; README, ROADMAP, RUNBOOK, INDEX, DOCUMENTATION_STATUS, .env.example, config/env.prod.yaml, Compose, and runtime readers were reconciled. Exact-head local suite: 1,779 passed / 21 skipped / 0 failures/errors; built-image valid and invalid startup boundaries were exercised. This does not close #284: artifact, managed Postgres, TLS/proxy, recovery, monitoring, provider, mobile/device, and release rows remain pending.

[tomqwu]

Artifact/runbook reconciliation receipt from #321

Merged source: 9a5d3acde85f51f93a390c23e48a7009a6f2d97b
Tested PR head/base: cb6a8fdb393f954a9ce2a358f5a1bc351f49d8d5 / 6e833d446161ade845cb07cdd3987fbf948ab4e3
Review: local self-review.

This advances:

• 284.2: README, production configuration, testing, tools, debug, roadmap, documentation status, and runtime configuration now match the actual one-shot migration/private datastore/read-only image contract.
• 284.3 artifact portion: RUNBOOK now identifies the exact local artifact command, retained evidence, non-destructive startup behavior, and the boundary between proven local operation and unverified staging/rollback.
• T284-01/T284-02/T284-04: documentation tests passed and provider/commercial enablement remains explicitly separate and disabled.

Evidence:

• make test-all: 1,793 passed, 21 skipped.
• make test-postgres: 8 passed.
• make test-artifact: passed for image sha256:fb00fdfbac4306eb736058572fed555efb9bc7a482d29532633972ec34b62416.
• Runbook/config/document tests are included in the final-SHA full matrix.

Keep #284 open:

• T284-03, authorized operator walkthrough, staging HTTPS, alert receipt, restore/retention policy, and tested rollback remain unverified.
• No production/compliance certification, provider activation, hosted CI, or Ollama review is claimed.

[tomqwu]

Platform assurance reconciliation receipt:

• PR Add production monitoring and sanitized probes #322 merged production liveness/readiness, optional sanitized error reporting, redacted JSON logs, release identity validation, bounded local alert transitions, and current operator/deployment/security/testing documentation.
• Validated source: 39a6dfbf7c22dc82c5e0810b00c327bdb95b9e11; merge: fd9e42755d54cc5a180c782eb39f4ae54e526888.
• Local validation: 1,814 passed, 21 skipped; PostgreSQL 16.14: 8 passed; production artifact passed with two replicas and no external-provider contact.
• Real staging monitoring, recipient acknowledgement, backup recovery, retention, and release evidence remain outstanding and must not be represented as complete.

PR: #322
Refs #267 and #268. This reconciliation issue remains open for later release evidence.

[tomqwu]

Roadmap receipt: PR #323 merged as main 0657971. Local recovery foundation now has encrypted WAL-consistent backup, isolated restore, Church/Basketball restored-state acceptance, 12/12 recovery tests, 8/8 PostgreSQL tests, and a 1,827-pass complete local suite. #268 remains open for off-site/scheduled production operations and owner-approved RPO/RTO/key custody.

[tomqwu]

Platform-assurance receipt from PR #324: the current security docs now identify exact local scanner/artifact scope, redacted failure behavior, incomplete license metadata, and separate native/deployment/provider approval. Pages publication actions are commit-pinned and no hosted validation was added. This supplies #284 security-evidence inputs but does not close the issue: production operator walkthrough, external alert receipt, deployed rollback/recovery, and final config/runbook reconciliation remain unverified.

[tomqwu]

Documentation and assurance reconciliation receipt

PR #334 merged the content-level documentation repair that the earlier inventory-only pass missed.

• docs/API.md and docs/API_QUICKSTART.md now identify removed roster_cli examples as historical and direct current REST users to the running FastAPI schema and authorization guide.
• docs/DATETIME_ARCHITECTURE.md, docs/DOCKER_DEVELOPMENT.md, and docs/ENVIRONMENT_SETUP.md now identify obsolete paths/YAML-runtime claims as historical and link maintained sources.
• docs/INDEX.md, docs/DOCUMENTATION_STATUS.md, and the ledger now agree on current versus historical ownership.
• mobile/SMOKE.md now distinguishes queued invitation delivery, local capture, direct-token testing, and externally authorized provider proof.
• Exact-head evidence: 1,985 passed / 21 skipped, 73 Playwright, 188 manual / 138 generated docs, and passing screenshot-manifest validation.

This completes the authorized local documentation reconciliation. Keep #284 open for production-only assurance: operator walkthrough, externally received alerts, deployed rollback/recovery/retention evidence, and final environment-specific config/runbook sign-off. No local suite can certify those outcomes.

[tomqwu]

Current-main security and operations evidence refresh

The committed source and exact retained artifact for main cb77a9fd295880359055e8aecc96bbb9d868c19e were scanned locally after the SendGrid callback hardening.

• make test-security: passed.
• Report: test-artifacts/security-validation/20260915T204935.370990Z-93963-08986ad3/report.json.
• Trivy 0.74.0 was run from pinned image sha256:62b1e65e8869bc4b4c6aa4fa2b21595256c7c2f6018a9d9ad61caf87187c1969.
• Exact application image: sha256:fbf8d65e4ed7a9c63dc6230e1ed25fee81a27e71c96c008ea9e9e20fdef7c217.
• Blocking findings: 0; accepted findings: 0; reported findings: 0.
• Known-secret, removed-secret, and missing-advisory-database failure drills behaved as expected.
• Docker socket was not mounted, no host scanner install occurred, and external providers were not contacted.
• Current artifact, PostgreSQL, recovery, and bounded load reports are also tied to this main SHA.

Keep #284 open. This refresh does not supply an authorized disposable-target operator walkthrough, real alert receipt, deployed rollback, owner-approved retention policy, or environment-specific production sign-off.

[tomqwu]

Loopback TLS documentation and evidence receipt

PR #338 merged as ad9c323b6c31421478e4069de1f6130e7dfeb68c.

The maintained README, testing guide, production-configuration guide, runbook, roadmap, documentation status, and release-acceptance matrix now consistently distinguish:

• verified self-signed loopback TLS behavior against the exact production image; from
• unverified external ingress, managed certificate/DNS, staging, operator receipt, deployed rollback, retention policy, and release approval.

Exact tested head 49ad866cdb9320ab2485253a50ad8446ecc0ded0 passed 2,012 tests with 21 intentional skips, all 73 Playwright cases, documentation inventory (189 manual / 138 generated), production artifact exercise, and exact-image security scan with zero findings. See PR #338 for report paths and immutable image digest.

Keep 284.4 and T284-03 open: this was an owned local rehearsal, not the required authorized disposable-target operator walkthrough or deployed rollback/recovery/retention acceptance.

[tomqwu]

Documentation reconciliation receipt (2026-09-15)

Merged PR #339 updates README.md, docs/TESTING.md, docs/RUNBOOK.md, docs/RELEASE_ACCEPTANCE.md, docs/ROADMAP.md, docs/DOCUMENTATION_STATUS.md, and docs/TOOLS.md for the guarded staging acceptance workflow. make test-docs passes with 189 manual and 138 generated documents inventoried.

The docs continue to state the truth: local validation and local artifact/security evidence are complete for this revision; staging, provider activation, production restore, pilot acceptance, and final production assurance remain unverified. Keep #284 open until #265, #267, and #268 provide their required external evidence.