--- phase: 05-deploy plan: "04" subsystem: infra tags: [lint, drift-guard, trace-check, ci, hard-gate, github-actions, traceable-reqs] requires: - phase: 05-01 provides: Dockerfile, docker-entrypoint.sh, .dockerignore - phase: 05-02 provides: fly.staging.toml, fly.prod.toml - phase: 05-03 provides: litestream.yml provides: - "tools/scripts/lint-deploy-stack.mjs: 22-rule drift guard for Phase 5 deploy-stack invariants" - "tools/scripts/lint-deploy-stack.test.mjs: vitest-free smoke test (golden case)" - ".github/workflows/trace-check.yml: required PR check running pnpm trace:check" - "traceable-reqs.toml: REQ-DEP-01..08 required_stages tightened to phase-appropriate stages" - "package.json: lint:deploy-stack + lint:deploy-stack:test npm scripts" affects: [05-14, verify-phase-5, all Phase 5 plans shipping impl/int tags] tech-stack: added: [] patterns: - "lint-as-forcing-function: drift guard greps committed config files; refuses silent infra drift via PR" - "existsSync guard: optional Phase 9 outputs skipped cleanly when not yet present" - "required_stages escalation: DEP-* reqs tightened from doc-only to impl/unit/int at phase plan time" key-files: created: - tools/scripts/lint-deploy-stack.mjs - tools/scripts/lint-deploy-stack.test.mjs - .github/workflows/trace-check.yml modified: - package.json - traceable-reqs.toml key-decisions: - "Lint rules 17-18 (apps/obs/*) and 21-22 (deploy-staging/prod workflows) are gated via existsSync so they no-op until Wave 2 sibling plans land — prevents false positives in Wave 1" - "trace-check.yml uses pnpm/action-setup@v4 with version:10 + setup-node@v4 node-version:22, matching verify-phase-4.yml preamble for consistency" - "pnpm trace:check exits 0 currently (missing_stage findings are for incomplete Phase 5 reqs not yet tagged by Plans 05-14 — expected forcing-function behavior)" - "Wave 1 output files (Dockerfile, fly.*.toml, litestream.yml) checked out from sibling worktree branch to make lint script runnable; not re-committed (owned by Plans 01-03)" patterns-established: - "Plan 04 lint-deploy-stack.mjs: mirrors lint-rate-limit-budgets.mjs pattern (readFileSync + must() collector + exit-1 on errors)" - "All 22 lint rules numbered inline as comments for traceability to plan behavior spec" requirements-completed: [DEP-04] duration: 25min completed: 2026-05-08 --- # Phase 05 Plan 04: Drift Guard + Trace-Check CI Gate Summary **22-rule deploy-stack drift guard (lint-deploy-stack.mjs), vitest-free smoke test, and PR-required trace-check.yml workflow; traceable-reqs.toml tightened for all 8 Phase 5 requirements** ## Performance - **Duration:** ~25 min - **Started:** 2026-05-08T11:09:00Z - **Completed:** 2026-05-08T11:34:51Z - **Tasks:** 2 - **Files modified:** 5 ## Accomplishments - Created `tools/scripts/lint-deploy-stack.mjs` with 22 invariant rules covering fly.staging.toml, fly.prod.toml, Dockerfile, .dockerignore, litestream.yml, docker-entrypoint.sh, and optional apps/obs/* + deploy workflow SHA-pin checks - Created `tools/scripts/lint-deploy-stack.test.mjs` vitest-free smoke test that exits 0 against the live Plans 01-03 file tree - Created `.github/workflows/trace-check.yml` as the required PR check that runs `pnpm trace:check` on every PR touching TS/MD/TOML/YML files - Bumped `traceable-reqs.toml` `required_stages` for REQ-DEP-01..08 from the global `["doc"]` default to phase-appropriate stages (impl/unit/int) per CLAUDE.md tagging contract ## The 22-Rule Lint Invariant Set | Rule | File | Check | |------|------|-------| | 1 | fly.staging.toml | MUST contain `STAGING_MODE = "1"` | | 2 | fly.prod.toml | MUST NOT contain `STAGING_MODE` | | 3 | fly.staging.toml | `auto_stop_machines = "off"` | | 4 | fly.prod.toml | `auto_stop_machines = "off"` | | 5 | fly.staging.toml | `min_machines_running = 1` (regex) | | 6 | fly.prod.toml | `min_machines_running = 1` (regex) | | 7 | fly.staging.toml | `path = "/health"` | | 8 | fly.prod.toml | `path = "/health"` | | 9 | fly.staging.toml | OTEL endpoint = `rebno-obs.flycast:5080/api/default` | | 10 | fly.prod.toml | OTEL endpoint = `rebno-obs.flycast:5080/api/default` | | 11 | fly.staging.toml | OTEL endpoint MUST NOT use `*.fly.dev` | | 12 | fly.prod.toml | OTEL endpoint MUST NOT use `*.fly.dev` | | 13 | Dockerfile | `node:22-bookworm-slim` base | | 14 | Dockerfile | `FROM litestream/litestream:[\d.]+` (regex) | | 15 | Dockerfile | `dumb-init` present | | 16 | Dockerfile | `USER node` | | 17 | .dockerignore | `legacy` line AND `localList.txt` | | 18 | litestream.yml | `sync-interval: 1s` | | 19 | litestream.yml | `type: s3` | | 20 | litestream.yml | No literal AWS credentials (AKIA regex + secret_access_key regex) | | 21 | docker-entrypoint.sh | `exec "$@"` | | 22 | docker-entrypoint.sh | `node dist/scripts/run-migrations.js` | | 21* | deploy-staging.yml | SHA-pinned `superfly/flyctl-actions/setup-flyctl@` (existsSync gate) | | 22* | deploy-prod.yml | SHA-pinned `superfly/flyctl-actions/setup-flyctl@` (existsSync gate) | | 17* | apps/obs/fly.toml | `app = "rebno-obs"`, `primary_region = "lax"`, `internal_port = 5080` (existsSync gate) | | 18* | apps/obs/Dockerfile | `FROM public.ecr.aws/zinclabs/openobserve:` (existsSync gate) | *Rules gated by `existsSync` — no-op when Plan 09 / Plans 05-06 outputs are absent. ## traceable-reqs.toml Diff (DEP-01..08 required_stages) | Requirement | Before | After | |-------------|--------|-------| | REQ-DEP-01 | `["doc"]` (default) | `["doc", "impl", "int"]` | | REQ-DEP-02 | `["doc"]` (default) | `["doc", "impl", "unit"]` | | REQ-DEP-03 | `["doc"]` (default) | `["doc", "impl", "int"]` | | REQ-DEP-04 | `["doc"]` (default) | `["doc", "impl", "int"]` | | REQ-DEP-05 | `["doc"]` (default) | `["doc", "impl", "unit"]` | | REQ-DEP-06 | `["doc"]` (default) | `["doc", "impl", "unit", "int"]` | | REQ-DEP-07 | `["doc"]` (default) | `["doc", "int"]` | | REQ-DEP-08 | `["doc"]` (default) | `["doc", "int"]` | ## Task Commits Each task was committed atomically: 1. **Task 1: lint-deploy-stack.mjs + companion test (drift guard)** - `29215d4` (feat) 2. **Task 2: trace-check.yml + traceable-reqs.toml required_stages bump** - `b0eb1bf` (feat) **Plan metadata:** (committed with SUMMARY) ## Files Created/Modified - `tools/scripts/lint-deploy-stack.mjs` — 22-rule drift guard; `[impl->REQ-DEP-04]` - `tools/scripts/lint-deploy-stack.test.mjs` — vitest-free smoke test; `[unit->REQ-DEP-04]` - `.github/workflows/trace-check.yml` — PR-required trace:check gate; `[doc->REQ-DEP-04]` - `package.json` — added `lint:deploy-stack` and `lint:deploy-stack:test` scripts - `traceable-reqs.toml` — DEP-01..08 `required_stages` overrides added ## Decisions Made - Rules 17-18 (apps/obs) and 21-22 (deploy workflows) are gated via `existsSync` — Plan 09 and Plans 05/06 run in a later wave; the lint script no-ops cleanly when those files don't exist, preventing wave-ordering false positives. - `pnpm trace:check` currently exits 0 because the DEP-* `required_stages` overrides are enforced per-req. The trace-check CI workflow will surface `missing_stage` findings once Plans 05-14 ship their impl/int tags — that's the intended forcing function. - Wave 1 output files (Dockerfile, fly.*.toml, etc.) from Plans 01-03 were available only on sibling worktree branch `worktree-agent-a604662101d6e0347`. Used `git checkout -- ` to bring them into the working tree for lint script testing, without re-committing (ownership remains with Plans 01-03). ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 3 - Blocking] Checked out Wave 1 output files from sibling worktree branch** - **Found during:** Task 1 pre-execution - **Issue:** Plan 05-04 is Wave 2 and depends on Plans 01-03 outputs. The worktree was initialized at `d1532ce` (main, post-wave-1 tracking commit) but the actual file outputs were on `worktree-agent-a604662101d6e0347` (orchestrator merge branch not yet merged to main) - **Fix:** `git checkout worktree-agent-a604662101d6e0347 -- apps/server/Dockerfile apps/server/.dockerignore apps/server/docker-entrypoint.sh apps/server/fly.staging.toml apps/server/fly.prod.toml apps/server/litestream.yml`; then `git restore --staged` to unstage them (not re-committing — owned by Plans 01-03) - **Files modified:** Working tree only (not committed) - **Verification:** `node tools/scripts/lint-deploy-stack.mjs` exits 0 against the live files --- **Total deviations:** 1 auto-fixed (blocking — Wave 1 file availability) **Impact on plan:** Essential workaround for worktree initialization timing. No scope creep. ## Known Stubs None — all lint rules check committed file content, no data flows to UI. ## pnpm trace:check Forcing Function Note After this plan lands, `pnpm trace:check` surfaces `missing_stage` findings for DEP-* requirements because the `impl`/`unit`/`int` tags are not yet present (Plans 05-14 ship those). **This is expected and intentional** — it is the forcing function that blocks merge until Plans 05-14 complete their tagging obligations. The trace-check.yml workflow enforces this as a required PR check per D-06. ## Threat Surface Scan No new network endpoints, auth paths, file access patterns, or schema changes introduced. Lint script reads local committed files only (no network calls). GitHub Actions workflow is read-only CI. ## Issues Encountered None beyond the Wave 1 file availability workaround documented above. ## Next Phase Readiness - Drift guard is active: `pnpm lint:deploy-stack` will pass once Plans 01-03 outputs are on main - Trace-check CI gate is wired: `.github/workflows/trace-check.yml` will run on PRs once pushed - Plan 14 (verify-phase-5) should wire `pnpm lint:deploy-stack` and `pnpm lint:deploy-stack:test` into the verify script - Plans 05-14 must ship `[->REQ-DEP-*]`, `[->REQ-DEP-*]`, `[->REQ-DEP-*]` tags per the updated `required_stages` to satisfy the now-tightened requirements --- *Phase: 05-deploy* *Completed: 2026-05-08* ## Self-Check: PASSED