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