docs: advance platform build gate

tasks/plan.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Platform Operations
 
-- Status: Planned from draft revision; implementation blocked pending explicit spec approval
+- Status: Implementation plan ready for stakeholder review — implementation not authorized
 - Capability: Platform operations
 - Task list target: `tasks/todo.md`
 - Last updated: 2026-08-20
@@ -16,7 +16,7 @@ No task below is authorized merely because it appears here.
 ## Dependency graph
 
 ```text
-approve revised spec + resolve server/runtime contracts
+resolve concrete server/runtime inputs + authorize build
         |
         +--> safe config + manual release-record contract
         |        |
@@ -50,14 +50,15 @@ approve revised spec + resolve server/runtime contracts
 - Use automatic Let's Encrypt/Certbot TLS.
 - Treat structured logs/health/manual checks as MVP; add Prometheus/Grafana after MVP and before AI.
 
-## Phase 0: approve exact contracts
+## Phase 0: resolve implementation inputs and authorize the build
 
-- Approve the revised Platform Operations spec.
+- Treat the approved Platform Operations spec and ADRs 0001–0003 as the implementation baseline.
-- Resolve server/provider/capacity/user/path, image tags, resource limits, repository URLs/commands/health routes, backup endpoint/credentials/schedule, Redis AOF choice, release-record format, operator/secret escrow, and MVP-ready/observability gates.
+- Obtain the production IP/DNS state, repository URLs, actual protected environment values, ParsPack endpoint/bucket/prefix/credentials, and named operator/secret-escrow contacts.
 - Obtain the backend command contract for API, worker, migration, import, admin, liveness, readiness, and Redis-loss recovery.
 - Obtain the frontend build/static health contract.
+- Obtain explicit authorization before creating deployment implementation artifacts.
 
-Checkpoint: no implementation file exists before explicit approval and resolved inputs.
+Checkpoint: no implementation file exists before explicit build authorization and the inputs needed by its slice are resolved.
 
 ## Phase 1: configuration and Compose foundation
 
@@ -82,7 +83,7 @@ Checkpoint: manual deployment records the three SHAs, passes TLS/health/SSE chec
 - Minimally adapt Qlockify backup/upload/restore/S3-restore scripts for ZarinPal paths/services/credentials.
 - Remove Qlockify environment-file backup/restore; include PostgreSQL archive plus non-secret manifest/checksums only.
 - Add exact destination and production confirmation guards.
-- Bootstrap the server, deploy the MVP, perform one-time import/credential setup, create an encrypted remote backup, and rehearse clean restore within two hours.
+- Bootstrap the server with `first-start.sh`: migrate, import/reconcile the pinned archive, then activate public services; perform separate credential setup, encrypted remote backup, and a clean restore rehearsal within two hours.
 
 Checkpoint: every MVP acceptance criterion passes through manual health/log/disk/certificate/queue/backup checks.
 
@@ -103,9 +104,9 @@ Checkpoint: an induced failure is detected, correlated to the three-hash release
 | Dirty checkout is destroyed | Lost operator/user work | Fail on dirty/divergent state; no unconditional `git reset --hard` |
 | Server-side build differs over time | Harder reproduction | Pin base/dependency inputs in service repos, record Git hashes/local image ids/build time |
 | Migration blocks rollback | Extended outage | Expand/contract, measured locks, fresh backup, no automatic down migration |
-| Redis loss drops queue/cache | Partial analytics interruption | Optional AOF, PostgreSQL authority, idempotent reconciliation/cold-cache tests |
+| Redis loss drops queue/cache | Partial analytics interruption | AOF `everysec`, PostgreSQL authority, idempotent reconciliation/cold-cache tests |
 | SSE buffering/timeouts | Dashboard appears stuck | Exact Nginx route, buffering/compression/cache off, heartbeat/reconnect test |
-| Docker-group compromise | Host-root compromise | Dedicated key-only trusted account, restricted SSH, no daemon TCP exposure |
+| Docker-group compromise | Host-root compromise | Restricted key-only access to trusted `ubuntu` account, no daemon TCP exposure |
 | Backup leaks credentials | Wider compromise | Remove `.env` backup/restore, encrypt, separate passphrase, archive exclusion tests |
 | Backup is unusable | Data loss beyond RTO | Checksums/listing/remote verification plus clean restore rehearsal |
 | Delayed monitoring hides degradation | Slower MVP incident diagnosis | MVP health/log/operator checklist; mandatory Prometheus/Grafana before AI |

tasks/todo.md

@@ -1,18 +1,19 @@
 # Platform Operations implementation tasks
 
-- Status: Not authorized — wait for explicit approval of the revised spec
+- Status: Ready for stakeholder review — implementation not authorized
 - Canonical plan: `tasks/plan.md`
 
-## Task 0: Approve revision and resolve implementation inputs
+## Task 0: Resolve implementation inputs and preserve the implementation gate
 
-**Description:** Approve the confirmed manual Qlockify-style intent and resolve every remaining server/runtime/backup/phase-gate decision.
+**Description:** Use the approved manual Qlockify-style specification to collect the concrete values and service contracts required for later implementation while preserving the separate explicit build-authorization gate.
 
 **Acceptance criteria:**
-- [ ] Revised Platform Operations spec is explicitly approved.
+- [x] Revised Platform Operations spec is explicitly approved.
-- [ ] ADRs 0001–0003 match the approved topology, manual release, and font decisions.
+- [x] ADRs 0001–0003 match the approved topology, manual release, and font decisions.
-- [ ] Every remaining decision has a named answer/evidence.
+- [ ] Production connection values, protected secrets, repository URLs, service commands/routes, and responsible operators are recorded outside public Git where required.
+- [ ] Stakeholder explicitly authorizes creation of deployment implementation artifacts.
 
-**Verification:** Stakeholder approval plus clean documentation review.
+**Verification:** Approved specification, clean documentation review, resolved slice inputs, and explicit build authorization.
 
 **Dependencies:** None
 
@@ -61,9 +62,10 @@
 **Acceptance criteria:**
 - [ ] Migration completes before API/worker readiness.
 - [ ] Normal startup never runs import/admin; import uses one exact read-only path.
+- [ ] `first-start.sh` starts data services, migrates, imports and reconciles the pinned archive, then starts public services only after success.
 - [ ] Worker is private/event-driven and uses pinned pre-1.0 Asynq `v0.26.0`.
 
-**Verification:** Startup/failure/import-idempotency/shutdown integration tests.
+**Verification:** First-start, ordinary-startup, migration/import failure, checksum/count reconciliation, idempotent no-op, and shutdown integration tests.
 
 **Dependencies:** Task 2 and approved backend commands
 
@@ -113,11 +115,11 @@
 
 ## Task 6: Adapt Qlockify manual deploy and rollback
 
-**Description:** Modify Qlockify's deploy flow for ZarinPal paths/services and three-hash release records while removing unconditional destructive Git synchronization.
+**Description:** Modify Qlockify's deploy flow for ZarinPal paths/services and three-hash release records while keeping interactive Git pulls as a separate operator prerequisite and removing unconditional destructive Git synchronization.
 
 **Acceptance criteria:**
-- [ ] Latest `origin/main` is fast-forwarded and three hashes recorded before build.
+- [ ] Operator manually fast-forwards all three repositories to latest `origin/main`; the deployment command performs no pull and records all three hashes before build.
-- [ ] Dirty/diverged checkout, pull, build, migration, or health failure preserves the active release.
+- [ ] Dirty/diverged checkout, build, migration, or health failure preserves the active release; a manual pull failure prevents deployment from starting.
 - [ ] Previous hashes rebuild/restore within 15 minutes without automatic down migration.
 
 **Verification:** Script tests plus induced staging failures and timed rollback drill.
@@ -133,7 +135,7 @@
 **Description:** Reuse Qlockify's PostgreSQL dump, OpenSSL, rclone upload, and retention flow with ZarinPal paths/services/credentials and a non-secret manifest.
 
 **Acceptance criteria:**
-- [ ] Archive/listing/checksums/encryption/remote verification gate success.
+- [ ] Package contents, plain-SQL header/checksums, encryption, and remote verification gate success.
 - [ ] Exactly three verified encrypted local and seven remote backups are retained.
 - [ ] `.env`, secrets, Redis, TLS, CSV, credentials, logs, monitoring, font, and license are excluded.
 
@@ -164,7 +166,7 @@
 
 ## Task 9: Bootstrap and accept MVP server
 
-**Description:** Follow the reviewed bootstrap runbook, deploy manually, run one-time data/demo setup, and capture MVP evidence.
+**Description:** Follow the reviewed bootstrap runbook, run the guarded first-start migration/import/application sequence, perform separate demo setup, and capture MVP evidence.
 
 **Acceptance criteria:**
 - [ ] Access/firewall/Docker/DNS/TLS/deployment boundaries pass.