"Docs-ship race — shared staging dir between deploy.yml and release.yml docs jobs; fixed by a single ship script with per-run staging + flock'd swap"

§1

1. Both docs jobs MUST ship through one implementation, tools/docs-site/ship.sh - the duplicated inline snippet is how the shared-staging race was born, and TASK-IMP-074's rules-to-channels principle applies to the shippers themselves.
2. Staging MUST be per-run unique (docs.new.${GITHUB_RUN_ID}.${GITHUB_RUN_ATTEMPT}, local$$ fallback): no shipper can ever name, and therefore never delete, another's in-flight staging.
3. The swap (rm -rf docs && mv <stage> docs) MUST run under a remote flock on ~/cyberos/apps/console/.docs-ship.lock: swaps serialize, the docs-absent window stays single-threaded and sub-second, last writer wins (all writers build the same main, so content is equivalent).
4. Abandoned staging dirs MUST be swept without endangering live ones: the flock'd section removes docs.new* entries untouched for 2h+ only - an in-flight extract continuously refreshes its dir mtime and completes in seconds. This also retires the legacy shared docs.new name on its first post-fix ship.
5. Transport invariants inherited unchanged: tar streamed over ssh (no runner tgz, no VPS /tmp - the scp era shipped a truncated archive), set -euo pipefail, size echo for the deploy log.

Lean profile: one script + two call-site swaps; the race, the fix, and the sweep semantics are all machine-verified in-session by a two-racer simulation of the exact remote command shape.

§5 (run 2026-07-13)

• bash -n ship.sh PASS; both workflows YAML-parse post-edit. PASS
• Two-racer simulation (exact remote command shape, tiny payloads, shared console dir): both exit 0, final docs = last swap's content, no cannot-stat. PASS (pre-fix design loses one racer by construction - observed live in #127)
• Sweep semantics: pre-seeded stale docs.new (3h) swept; fresh foreign docs.new.other.0 survived. PASS
• flock present in util-linux (verified in the ubuntu sandbox; the VPS is ubuntu - if ever absent, the step fails loud at "command not found", not silently).
• Testing pass 2026-07-13 (post gate-1 "approve all"): two-racer simulation re-run green (both exit 0, last swap wins, sweep semantics intact); ship.sh bash -n + both workflows YAML re-verified.

§9

• The docs-absent window during the swap (sub-second, now serialized) is accepted, as it was pre-fix. A symlink-flip scheme (docs -> release dir, atomic ln -sfn) would remove it entirely; adopt only if a monitoring blip ever attributes to it.
• deploy.yml's docs job and release.yml's docs job still both exist by design (TASK-DOCS-003: tags refresh the site too); deduplicating the JOBS is out of scope - this task dedupes the shipper.

§10

End of TASK-IMP-079.