Turn Report: Deploy script preflight guard for Docker workspace snapshot

Date/Time: 2026-05-15 19:03:09 EDT

Summary

Updated scripts/deploy.ts so ./deploy now fails fast when deployment/docker/workspace-root is stale. The script now runs bun run check:docker-workspace during local prechecks and prints a clear remediation message to run sync + commit before deployment.

Changes Made

Created localWorkspaceSnapshotPrecheck() in scripts/deploy.ts.
Added preflight invocation to both deployment modes:
- localMainPrecheck()
- localBranchPrecheck()
On failure, deploy now exits with an explicit message:

Refusing deploy: deployment/docker/workspace-root is out of sync.
Run bun run sync:docker-workspace, commit updated snapshot files, then retry deploy.

Refreshed lock state to keep checks green:
- bun.lock
- deployment/docker/workspace-root/bun.lock

Context

The deployment compose stack builds from a snapshot under deployment/docker/workspace-root. If that snapshot drifts from the active workspace graph, Docker build-time bun install --frozen-lockfile fails remotely. This change catches drift locally before any remote rollout starts.

Important Implementation Details

Preflight uses spawnSync("bun", ["run", "check:docker-workspace"]) with inherited stdio for transparent output.
Failure exits with the same non-zero status, preserving script CI/shell behavior.
Guard applies to both ./deploy main and ./deploy current-branch flows.

Validation

Passed: bun run scripts/deploy.ts --help
Passed: bun run check:docker-workspace (after lock sync)

Issues, Limitations, and Mitigations

Limitation: Did not execute a full remote deploy during this turn.
Mitigation: The guard is in the local precheck path, so next real deploy run will enforce the new check automatically.

Follow-up Work

Optional defense-in-depth: run bun run check:docker-workspace on the server in remote rollout before docker compose up -d --build.
Optional CI gate: add bun run check:docker-workspace to PR checks to prevent stale snapshots reaching main.
Beads issue: islandflow-k4f.