Performance Notes

Attestation SHA cache

When plan attestation is enabled, the hooks compare the approved SHA-256 hash with the current task_plan.md before injecting plan content. v2.40.0 added a small transient cache for that hash calculation.

Location

The cache lives under the first of these that resolves:

bash

$XDG_CACHE_HOME/pwf-sha/        # when XDG_CACHE_HOME is set
$HOME/.cache/pwf-sha/           # otherwise, when HOME is set
${TMPDIR:-/tmp}/pwf-sha/        # fallback only when neither is set

v2.40.0 introduced the cache under ${TMPDIR:-/tmp}/pwf-sha/. v3.0.0 moved it to the user-private path above so a world-writable /tmp can no longer be used to poison the attestation hash. Each cache entry stores the plan file mtime on the first line and the computed SHA-256 on the second line.

Keying

The cache key is the first 16 hex characters of the SHA-256 of the active plan file path (the path string, not the file contents). Each plan location gets its own entry:

text

task_plan.md
.planning/<plan-id>/task_plan.md

The stored hash is reused only when the current plan file mtime matches the cached mtime. If the file changes, the hook recomputes sha256sum or shasum -a 256 and rewrites the cache entry. In gated mode the hook always recomputes on a hit, so the completion gate never trusts a stale entry.

When it helps

The cache is most useful when:

Plan files are large.
Windows Git Bash process startup makes repeated sha256sum calls expensive.
The same attested plan fires hooks many times in one session.

When it is break-even

For small plan files, the cache may be roughly break-even. The hook still starts shell commands, reads the cache entry, and checks the mtime. On those paths, Bash process startup can dominate the actual hash cost.

Containers and CI

The cache is per-user and transient. In a container HOME is usually set (for example /root), so the cache lives at $HOME/.cache/pwf-sha/. Containers, CI jobs, and sandboxes that do not persist $HOME across restarts lose the cache between runs.

That only affects speed. A cache miss recomputes the SHA-256 from the current plan file and preserves the same attestation behavior.

Clear or avoid reuse

Clear the cache:

bash

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pwf-sha/"

There is no separate SHA-cache toggle, and overriding TMPDIR does not move the cache when HOME is set. The cache self-invalidates whenever the plan file mtime changes, so editing task_plan.md already forces a recompute. To force a clean state explicitly, remove the directory above.