docs: plan platform implementation

tasks/todo.md

@@ -0,0 +1,243 @@
+# Platform Operations implementation tasks
+
+- Status: Not authorized — wait for explicit approval of the draft spec
+- Canonical plan: `tasks/plan.md`
+
+## Task 0: Approve specification and resolve blocking decisions
+
+**Description:** Review the platform spec/ADRs and record every host, runner, version, route, capacity, backup, TLS, and ownership decision before implementation.
+
+**Acceptance criteria:**
+- [ ] `PLATFORM-OPERATIONS-SPEC.md` status is explicitly approved by the stakeholder.
+- [ ] ADR 0002 is accepted or replaced; ADR 0003 remains consistent with frontend commit `64f5ac2`.
+- [ ] All ten remaining decisions have named answers/evidence.
+
+**Verification:** Manual stakeholder approval and clean documentation diff.
+
+**Dependencies:** None
+
+**Files likely touched:** `docs/PLATFORM-OPERATIONS-SPEC.md`, `docs/decisions/0002-immutable-cross-repository-releases.md`
+
+**Estimated scope:** Small (1–2 files)
+
+## Task 1: Define release manifest and safe configuration schemas
+
+**Description:** Create machine-validated schemas/examples for exact release provenance, compatibility metadata, active/previous pointers, safe public configuration, and external secret files.
+
+**Acceptance criteria:**
+- [ ] Synthetic valid/invalid manifests prove immutable three-repository/image constraints.
+- [ ] Examples contain no secret-like values and name every required configuration input.
+- [ ] Font provenance is only frontend SHA/image digest; no injection field/path exists.
+
+**Verification:** Schema tests plus secret scan over staged files.
+
+**Dependencies:** Task 0
+
+**Files likely touched:** release/config schemas, safe examples, focused tests (maximum 5 files)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Task 2: Implement data-service Compose foundation
+
+**Description:** Add PostgreSQL/Redis pinned services, isolated data network, volumes, authentication, health checks, AOF policy, resources, and no host port publishing.
+
+**Acceptance criteria:**
+- [ ] Compose renders with pinned digests and healthy PostgreSQL/Redis.
+- [ ] Redis loss is explicitly non-authoritative and its volume is excluded from backup.
+- [ ] External/local port inspection finds no PostgreSQL/Redis host listener.
+
+**Verification:** Compose validation, health inspection, network/port policy tests.
+
+**Dependencies:** Task 1
+
+**Files likely touched:** Compose files and focused topology tests (maximum 5 files)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Task 3: Implement API, worker, and one-off lifecycle boundaries
+
+**Description:** Wire immutable backend API/worker plus migration/import/admin one-offs with health gates, profiles, locks, graceful stop, and validated configuration.
+
+**Acceptance criteria:**
+- [ ] Normal startup waits for migration but never runs import/admin automatically.
+- [ ] Worker is private/event-driven and retains pinned pre-1.0 Asynq `v0.26.0` contract.
+- [ ] Failed migration blocks candidate API/worker; import path is exact/read-only/idempotent.
+
+**Verification:** Lifecycle integration tests including failed migration and repeated import fixture.
+
+**Dependencies:** Tasks 1–2 and approved backend command/health contract
+
+**Files likely touched:** Compose lifecycle definitions, wrapper, focused tests (maximum 5 files)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Task 4: Implement frontend and font artifact health
+
+**Description:** Consume the ordinary frontend image/build context and verify static SPA plus tracked font output without copying/injecting assets in deployment.
+
+**Acceptance criteria:**
+- [ ] Candidate maps to frontend SHA/digest and serves expected font URL/MIME.
+- [ ] Missing font/license input fails frontend CI or candidate smoke.
+- [ ] Deployment files contain no font binary, license copy, private fetch, or font secret.
+
+**Verification:** Image/static health test and repository policy scan.
+
+**Dependencies:** Task 1 and approved frontend image contract at/after `64f5ac2`
+
+**Files likely touched:** frontend service definition and focused smoke/policy tests (maximum 5 files)
+
+**Estimated scope:** Small/Medium (2–4 files)
+
+## Task 5: Implement Nginx canonical TLS and routing
+
+**Description:** Add canonical host/default rejection, ACME/TLS, API/frontend separation, exact SSE proxy behavior, security headers, limits, and generic health routes.
+
+**Acceptance criteria:**
+- [ ] Only 80/443 are public; redirects/default-host behavior is exact.
+- [ ] SSE buffering/cache/compression are off and heartbeat/replay survives reconnect.
+- [ ] API never falls through to SPA; security/TLS/static-cache tests pass.
+
+**Verification:** `nginx -t`, TLS/header/routing tests, streamed timing/reconnect test.
+
+**Dependencies:** Tasks 3–4 and approved API/SSE paths/CSP
+
+**Files likely touched:** Nginx template/entrypoint and focused tests (maximum 5 files)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Checkpoint A: Runtime foundation
+
+- [ ] Tasks 1–5 pass together from a clean Compose project.
+- [ ] Only Nginx is public and all health/startup boundaries behave as specified.
+- [ ] No secret, raw data, backup, TLS key, or duplicate font/license asset is tracked.
+
+## Task 6: Implement release preflight, deploy, and rollback
+
+**Description:** Build the serialized manifest-driven operator workflow for preflight, migration, service replacement, postflight, observation, active/previous switch, and rollback.
+
+**Acceptance criteria:**
+- [ ] Deploy uses image digests only and records evidence without secrets.
+- [ ] Candidate health/migration/font failure preserves/restores prior release.
+- [ ] Application-only rollback completes within 15 minutes and never auto-runs down migration.
+
+**Verification:** Shell/unit tests plus induced staging failures and timed rollback drill.
+
+**Dependencies:** Checkpoint A
+
+**Files likely touched:** deploy/release scripts and focused tests (maximum 5 files per incremental slice)
+
+**Estimated scope:** Split into multiple Medium tasks during implementation
+
+## Task 7: Implement deployment-repository CI/CD
+
+**Description:** Validate docs/config/Compose/Nginx/scripts/policies, accept authenticated candidates, enforce protected approval/locking, and invoke the manifest-driven release.
+
+**Acceptance criteria:**
+- [ ] PR workflows validate only and cannot access production secrets/deploy.
+- [ ] Production release requires gates plus human approval and is serialized.
+- [ ] Provenance/SBOM/scan/secret results attach to the release record.
+
+**Verification:** Forge event tests with denied PR deploy, concurrent candidate events, failed gate, and approved release.
+
+**Dependencies:** Task 6 and confirmed forge/runner/registry versions
+
+**Files likely touched:** workflow plus CI-focused helpers/tests (maximum 5 files)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Task 8: Coordinate backend/frontend candidate workflows
+
+**Description:** In separately approved service-repository changes, publish one immutable tested image and send candidate metadata without direct production SSH.
+
+**Acceptance criteria:**
+- [ ] Backend gates include Go/migration/import/Asynq queue/recovery verification.
+- [ ] Frontend gates include Svelte/accessibility/RTL/build/font verification.
+- [ ] Service events cannot mutate production and use least-privilege credentials.
+
+**Verification:** Each repository's CI on PR/main plus deployment candidate receipt test.
+
+**Dependencies:** Task 7 and separate authorization in each service repository
+
+**Files likely touched:** owned service workflow/tests only; not this deployment task
+
+**Estimated scope:** Separate cross-repository tasks
+
+## Task 9: Implement observability baseline
+
+**Description:** Add bounded structured logging, private metrics/exporters/dashboards, release correlation, and symptom alerts/runbook links.
+
+**Acceptance criteria:**
+- [ ] All required RED/USE/worker/SSE/backup/TLS signals exist with bounded labels.
+- [ ] Logs rotate and contain request/release correlation but no forbidden fields.
+- [ ] Page/ticket alerts are test-fired and monitoring is not public.
+
+**Verification:** Induced staging failure located from telemetry, cardinality/redaction checks, alert delivery test.
+
+**Dependencies:** Checkpoint A and approved monitoring versions/budgets
+
+**Files likely touched:** Compose monitoring slice/config/dashboards/tests, split to <=5 files per commit
+
+**Estimated scope:** Split into multiple Medium tasks
+
+## Task 10: Implement encrypted backup and retention
+
+**Description:** Produce verified logical PostgreSQL backups, encrypt before durable storage, upload/verify remotely, retain three local/seven remote, and emit metrics.
+
+**Acceptance criteria:**
+- [ ] Archive/listing/checksums/manifest/remote verification gate success.
+- [ ] Backup contains none of the explicit exclusions.
+- [ ] Cleanup never removes the last known-good copy and uses exact validated paths.
+
+**Verification:** Backup tests against fixture DB/object store, archive exclusion inspection, failed-upload/cleanup tests.
+
+**Dependencies:** Tasks 1–3 and approved encryption/provider decisions
+
+**Files likely touched:** backup script/config/tests/docs (maximum 5 files per slice)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Task 11: Implement guarded restore and rehearsal
+
+**Description:** Validate/decrypt/trust-check an explicit backup, require all production guards, restore into an empty destination, and run application validation.
+
+**Acceptance criteria:**
+- [ ] Each absent/mismatched production factor aborts before mutation.
+- [ ] Partial/failed restore is never treated as usable or blindly retried.
+- [ ] Clean rehearsal passes tenant/session/cold-cache/worker/SSE checks within two hours.
+
+**Verification:** Destructive tests only against exact disposable fixtures, production-guard negative matrix, timed rehearsal.
+
+**Dependencies:** Task 10 and approved switch strategy
+
+**Files likely touched:** restore script/tests/docs (maximum 5 files per slice)
+
+**Estimated scope:** Medium (3–5 files)
+
+## Checkpoint B: Release and recovery
+
+- [ ] Tasks 6–11 pass in staging with release/rollback/backup/restore evidence.
+- [ ] Registry, runner, monitoring, object storage, and secrets remain least privilege/private.
+
+## Task 12: Bootstrap and accept first production-shaped server
+
+**Description:** Follow the reviewed bootstrap runbook, deploy an approved manifest, run the one-time data/demo setup, and capture every acceptance criterion.
+
+**Acceptance criteria:**
+- [ ] Access/firewall/Docker/DNS/TLS/deploy/monitoring boundaries pass.
+- [ ] Migration/import/demo accounts/tenant isolation/analytics SSE pass.
+- [ ] Encrypted remote backup and clean restore rehearsal meet RPO/RTO.
+
+**Verification:** Completed runbook evidence and stakeholder acceptance review.
+
+**Dependencies:** Checkpoint B and approved host/change window
+
+**Files likely touched:** evidence/release records only; no secret/raw runtime artifacts
+
+**Estimated scope:** Operational session
+
+## Final checkpoint
+
+- [ ] Every measurable acceptance criterion in the approved spec passes.
+- [ ] Active and previous releases are exact and rollback-ready.
+- [ ] Remaining decisions are resolved or explicitly defer launch.
+- [ ] Documentation reflects implemented reality and no implementation gate was bypassed.