othmanadi--planning-with-files/docs/attestation-locking.md

Attestation Locking and Fallback

scripts/attest-plan.sh stores a SHA-256 hash for the active task_plan.md. Hooks compare the current file hash with that stored attestation before they inject plan content into model context.

Write path

When you run sh scripts/attest-plan.sh, the script:

1. Resolves the active plan directory.
2. Hashes the active task_plan.md.
3. Writes the hash to a temporary file beside the attestation file.
4. Renames the temporary file into place.
5. Uses flock -w 5 around the rename when flock is available.

The atomic rename is the correctness guarantee. It prevents readers from seeing a partially written attestation file. The flock call is only a cooperative gate for concurrent writers on systems that provide it.

Platform behavior

Platform	flock availability	Behavior
Linux	Usually available	Atomic rename plus advisory flock guard.
macOS	Not installed by default	Atomic rename still protects correctness.
Windows Git Bash	Usually absent	Atomic rename still protects correctness.
WSL	Usually available	Same behavior as Linux.

If flock is missing, attest-plan.sh skips the advisory lock and still renames the temporary file into place. This is correct, but less coordinated for multiple writers in the same directory.

When fallback matters

The fallback only matters for legacy mode when two sessions write the same root attestation file:

./task_plan.md
./.plan-attestation

In that mode, both sessions share one plan file and one attestation file. The atomic rename keeps the attestation file valid, but it does not make the shared plan file a safe parallel workspace.

Recommended parallel workflow

Use slug-mode for parallel sessions:

./scripts/init-session.sh "Backend Refactor"
./scripts/init-session.sh "Incident Investigation"

Each slug gets its own isolated files:

.planning/2026-01-10-backend-refactor/task_plan.md
.planning/2026-01-10-backend-refactor/.attestation

.planning/2026-01-10-incident-investigation/task_plan.md
.planning/2026-01-10-incident-investigation/.attestation

Pin a terminal to one plan when needed:

export PLAN_ID=2026-01-10-backend-refactor
sh scripts/attest-plan.sh

Slug-mode avoids same-file contention by giving each session its own task_plan.md and .attestation file.