OthmanAdi/planning-with-files / skills/i18n/planning-with-files-zh
planning-with-files-zh
Verified用于多步骤 AI 代理工作的持久化文件规划系统。将 task_plan.md、findings.md 和 progress.md 保存在磁盘上,生命周期钩子会注入选定的项目规划上下文。自动恢复只读取项目规划文件。只有显式运行 session-catchup.py --metadata 才会检查本机同项目的会话元数据;--replay 可输出有长度限制且由 nonce 框定的同项目摘录。可选门禁仅在宿主支持时请求继续,绝不执行 Markdown 中声明的命令。本技能没有网络上传路径。适用于研究或需要 5 次以上工具调用的工作。触发词:任务规划、项目计划、制定计划、分解任务、多步骤规划、进度跟踪、文件规划、帮我规划、拆解项目
scripts/attest-plan.sh
View on GitHub#!/bin/sh
# planning-with-files: lock the current task_plan.md content with a SHA-256 attestation.
#
# Use after you finalise (or intentionally edit) a plan. The hooks then refuse
# to inject plan content into the model context if the file diverges from the
# attested hash, surfacing a "[PLAN TAMPERED]" warning instead.
#
# Resolution:
# 1. --target root or <plan-id> → root or named plan under $PWF_PLAN_ROOT (default: cwd)
# 2. $PLAN_ID env var → ./.planning/$PLAN_ID/
# 3. ./.planning/.active_plan
# 4. Newest ./.planning/<dir>/ by mtime
# 5. Current directory when it is .planning/<valid-slug>/
# 6. Legacy ./task_plan.md at project root
#
# Usage:
# sh scripts/attest-plan.sh # attest the active plan
# sh scripts/attest-plan.sh --show # print the stored hash
# sh scripts/attest-plan.sh --clear # remove the attestation (re-open the plan)
# sh scripts/attest-plan.sh --target root # attest the legacy root plan
# sh scripts/attest-plan.sh --target <plan-id> # attest one named plan
set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# An echoed selector must not forge output: a newline or an escape sequence
# in PLAN_ID could otherwise print a fake status line.
printable() {
# The sed step covers C1 controls, which are two bytes in UTF-8.
c1_lead="$(printf '\302')"
c1_low="$(printf '\200')"
c1_high="$(printf '\237')"
printf '%s' "$1" | LC_ALL=C tr '\000-\037\177' '?' \
| LC_ALL=C sed "s/${c1_lead}[${c1_low}-${c1_high}]/?/g"
}
pwf_plan_root_is_accepted() {
case "${PWF_PLAN_ROOT:-}" in
\\\\*|//*|[A-Za-z]:[!\\/]*) return 1 ;;
/*|[A-Za-z]:[\\/]*) ;;
*) return 1 ;;
esac
[ -d "${PWF_PLAN_ROOT}" ]
}
resolve_from_slug_cwd() {
slug_cwd="$(pwd -P 2>/dev/null)" || return 1
planning_dir="${slug_cwd%/*}"
[ "${planning_dir##*/}" = ".planning" ] || return 1
plan_id="${slug_cwd##*/}"
slug_is_valid "${plan_id}" || return 1
[ -f "${slug_cwd}/task_plan.md" ] || return 1
printf "%s\n" "${slug_cwd}/task_plan.md"
}
resolve_plan_file() {
if [ -n "${target:-}" ]; then
if [ "${target}" = "root" ]; then
target_root="."
if [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Match the shared resolver's supported absolute local pins.
# A valid project-root junction is intentional, so resolve it.
pwf_plan_root_is_accepted || return 1
target_root="$(cd "${PWF_PLAN_ROOT}" 2>/dev/null && pwd -P)" || return 1
fi
[ ! -L "${target_root}/task_plan.md" ] || return 1
[ -f "${target_root}/task_plan.md" ] || return 1
printf "%s\n" "${target_root}/task_plan.md"
return 0
fi
slug_is_valid "${target}" || return 1
# Reuse the binding, project-pin and containment rules. A flag replaces
# PLAN_ID for this call only; it does not change the shared pointer.
[ -f "${RESOLVER}" ] || return 1
target_dir="$(PLAN_ID="${target}" sh "${RESOLVER}" 2>/dev/null)" || return 1
[ -n "${target_dir}" ] || return 1
# Use the shell's physical path spelling: native Windows backslashes
# make sha256sum prefix its output with an escaped-filename marker.
target_dir="$(cd "${target_dir}" 2>/dev/null && pwd -P)" || return 1
[ ! -L "${target_dir}/task_plan.md" ] || return 1
[ -f "${target_dir}/task_plan.md" ] || return 1
printf "%s\n" "${target_dir}/task_plan.md"
return 0
fi
plan_dir=""
if [ -f "${RESOLVER}" ]; then
plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "$plan_dir" ] && [ "$(sh "${RESOLVER}" --check-ambiguity 2>/dev/null)" = "PWF_PLAN_AMBIGUOUS_V1" ]; then
return 2
fi
fi
if [ -n "${plan_dir}" ] && [ -f "${plan_dir}/task_plan.md" ]; then
printf "%s\n" "${plan_dir}/task_plan.md"
return 0
fi
# Explicit selectors are bindings, not hints. If the shared resolver
# rejected one, do not attest a different plan through a cwd fallback.
if [ -n "${PWF_PLAN_ROOT:-}" ] || [ -n "${PLAN_ID:-}" ]; then
return 1
fi
# An absolute script path does not change the invoking shell's cwd. When
# that cwd is a slug plan directory, keep slug-mode storage semantics
# instead of misclassifying its task_plan.md as a legacy root plan.
slug_plan_file="$(resolve_from_slug_cwd)" || slug_plan_file=""
if [ -n "${slug_plan_file}" ]; then
printf "%s\n" "${slug_plan_file}"
return 0
fi
if [ -f "./task_plan.md" ]; then
printf "%s\n" "./task_plan.md"
return 0
fi
return 1
}
attestation_path_for() {
plan_file="$1"
plan_dir="$(dirname "${plan_file}")"
if [ "${target:-}" = "root" ]; then
printf "%s\n" "${plan_dir}/.plan-attestation"
elif [ "${plan_dir}" = "." ]; then
# Legacy mode: store at project root.
printf "%s\n" "./.plan-attestation"
else
printf "%s\n" "${plan_dir}/.attestation"
fi
}
compute_hash() {
target="$1"
if command -v sha256sum >/dev/null 2>&1; then
# GNU sha256sum prefixes the hash with a backslash when the path holds
# one, which a native Windows PWF_PLAN_ROOT does.
sha256sum "${target}" | awk '{ sub(/^\\/, "", $1); print $1 }'
elif command -v shasum >/dev/null 2>&1; then
shasum -a 256 "${target}" | awk '{print $1}'
else
printf "ERROR: no sha256 utility available\n" >&2
return 1
fi
}
mode="attest"
target=""
usage_error() {
printf "Usage: %s [--show|--clear|--enable-checkbox-only|--checkbox-only] [--target root|<plan-id>]\n" "$0" >&2
exit 2
}
case "${1:-}" in
--clear|--show)
[ "$#" -eq 1 ] || usage_error
mode="${1#--}"
shift ;;
--enable-checkbox-only|--checkbox-only)
mode="${1#--}"
shift ;;
esac
if [ "${1:-}" = "--target" ]; then
[ "$#" -eq 2 ] && [ -n "$2" ] || usage_error
target="$2"
shift 2
fi
[ "$#" -eq 0 ] || usage_error
plan_file="$(resolve_plan_file)"
resolve_status=$?
if [ "${resolve_status}" -ne 0 ]; then
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ "${resolve_status}" -eq 2 ]; then
printf "[plan-attest] Multiple plans are available. Set PLAN_ID=<slug>; nothing was attested.\n" >&2
elif [ -n "${target:-}" ]; then
printf "[plan-attest] --target %s did not resolve to a plan. An explicit target is a binding: nothing was attested and no other plan was substituted.\n" "$(printable "${target}")" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ] && ! pwf_plan_root_is_accepted; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "$(printable "${PWF_PLAN_ROOT}")" >&2
elif [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "$(printable "${PLAN_ID}")" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "$(printable "${PWF_PLAN_ROOT}")" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
fi
attestation_file="$(attestation_path_for "${plan_file}")"
checkbox_state() {
command -v python3 >/dev/null 2>&1 || {
printf '[plan-attest] Checkbox enrollment requires POSIX Python 3.\n' >&2
return 1
}
python3 -I - "$1" "${plan_file}" "${attestation_file##*/}" <<'PWF_CHECKBOX_PY'
# Private cache records contain byte offsets and filesystem identities, never plan text.
import hashlib
import json
import os
import re
import secrets
import stat
import sys
from contextlib import ExitStack
mode, plan_path, attest = sys.argv[1:]
def refuse(reason):
raise ValueError(reason)
def run(stack):
if os.name != "posix" or not hasattr(os, "O_NOFOLLOW") or os.open not in os.supports_dir_fd:
refuse("Checkbox enrollment requires POSIX Python 3 with no-follow file descriptors.")
dirs = os.O_DIRECTORY | os.O_RDONLY | os.O_NOFOLLOW
def directory(path):
fd = os.open("/", dirs)
stack.callback(os.close, fd)
for part in os.path.abspath(path).split("/"):
if part:
fd = os.open(part, dirs, dir_fd=fd)
stack.callback(os.close, fd)
return fd
parent_path = os.path.abspath(os.path.dirname(plan_path))
parent = os.open(".", dirs) if os.path.dirname(plan_path) == "." else directory(parent_path)
if os.path.dirname(plan_path) == ".":
stack.callback(os.close, parent)
# macOS exposes /var through /private/var. Canonicalize the home path
# before opening each component; never follow links inside the cache.
home = directory(os.path.realpath(os.path.expanduser("~")))
cache_name = ".pwf-checkbox-v1"
if mode == "enable-checkbox-only":
try:
os.mkdir(cache_name, 0o700, dir_fd=home)
except FileExistsError:
pass
try:
cache = os.open(cache_name, dirs, dir_fd=home)
except FileNotFoundError:
if mode == "forget":
return
refuse("No checkbox enrollment. Review the plan and use --enable-checkbox-only.")
stack.callback(os.close, cache)
attrs = os.fstat(cache)
if attrs.st_uid != os.geteuid() or attrs.st_mode & 0o077:
refuse("Checkbox cache must be an owner-only directory.")
key = hashlib.sha256(os.fsencode(os.path.join(parent_path, attest))).hexdigest()
def read_file(fd, name, private=False):
flags = os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW
with os.fdopen(os.open(name, flags, dir_fd=fd), "rb") as stream:
info = os.fstat(stream.fileno())
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
refuse("Expected a regular, singly linked file.")
if private and (info.st_uid != os.geteuid() or info.st_mode & 0o077):
refuse("Unsafe permissions on checkbox enrollment.")
data = stream.read()
after = os.fstat(stream.fileno())
if (info.st_size, info.st_ctime_ns) != (after.st_size, after.st_ctime_ns):
refuse("File changed during read. Retry.")
return data, info
def identity(info):
return [info.st_dev, info.st_ino, info.st_ctime_ns]
def generation(info, digest):
# Rename may change ctime. These values survive publishing the staged
# inode and distinguish a fresh strict attestation of identical bytes.
return [info.st_dev, info.st_ino, info.st_mtime_ns, digest.decode("ascii").strip()]
def stage(fd, data):
tmp = ".pwf-" + secrets.token_hex(16)
writer = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=fd)
def cleanup():
try:
os.unlink(tmp, dir_fd=fd)
except FileNotFoundError:
pass
stack.callback(cleanup)
with os.fdopen(writer, "wb") as output:
output.write(data)
output.flush()
info = os.fstat(output.fileno())
return tmp, info
record = None
try:
raw, _ = read_file(cache, key, private=True)
record = json.loads(raw)
if not isinstance(record, dict) or record.get("format") != "pwf-checkbox-1":
refuse("Unrecognized checkbox metadata.")
except FileNotFoundError:
pass
if mode == "forget":
if record is not None:
os.unlink(key, dir_fd=cache)
return
snapshot, plan_info = read_file(parent, "task_plan.md")
try:
stored, digest_info = read_file(parent, attest)
if not re.fullmatch(rb"[0-9a-f]{64}(?:\r?\n)?", stored):
refuse("Refusing to replace an unrecognized attestation file.")
except FileNotFoundError:
stored = digest_info = None
digest = hashlib.sha256(snapshot).hexdigest().encode("ascii") + b"\n"
boxes = {}
# Only standalone, flush-left "- [ ]" and "* [ ]" with one ASCII space
# after the bullet are eligible. Indented tasks stay under strict approval.
# A list-shaped line inside a Markdown code fence is example text.
fence = None
comment = False
offset = 0
for line in snapshot.split(b"\n"):
# A UTF-8 BOM is ignored by Markdown only at the document start.
# Keep offsets into the original byte string for digest reconstruction.
bom = 3 if offset == 0 and line.startswith(b"\xef\xbb\xbf") else 0
content = line[bom:]
marker = re.match(rb" {0,3}(?:[-*+][ ]{1,4}|[0-9]{1,9}[.)][ ]{1,4})?(`{3,}|~{3,})(.*)", content)
if fence is not None:
closing = re.fullmatch(rb" {0,3}(`{3,}|~{3,})[ \t]*\r?", content)
if closing and closing[1].startswith(fence):
fence = None
elif comment:
if b"-->" in content:
comment = False
if content.partition(b"-->")[2].strip():
refuse("Ambiguous HTML after comment. Review the plan manually.")
elif marker and (marker[1].startswith(b"~") or b"`" not in marker[2]):
fence = marker[1]
elif b"<!--" in content:
prefix, _, tail = content.partition(b"<!--")
if prefix.strip():
refuse("Ambiguous HTML comment. Review the plan manually.")
comment = b"-->" not in tail
if not comment and tail.partition(b"-->")[2].strip():
refuse("Ambiguous HTML after comment. Review the plan manually.")
else:
if re.match(rb"^[ \t]*(?:[-*+]|[0-9]{1,9}[.)])?[ \t]*<(?:/?[a-zA-Z]|[!?])", content):
refuse("Raw HTML blocks require manual re-attestation.")
box = re.match(rb"[-*] \[([ x])\](?=[ \t]|\r?$)", content)
if box:
boxes[offset + bom + box.start(1)] = box[1]
offset += len(line) + 1
def check_plan_generation():
current = os.stat("task_plan.md", dir_fd=parent, follow_symlinks=False)
if identity(current) != identity(plan_info):
refuse("Plan changed during attestation. Retry.")
previous = None
if record and digest_info:
selected = generation(digest_info, stored)
previous = next((entry for entry in record.get("generations", [])
if entry["id"] == selected), None)
if mode == "checkbox-only":
if previous is None:
refuse("No current checkbox enrollment. Review the plan and use --enable-checkbox-only.")
prior = bytearray(snapshot)
for offset in previous["unchecked"]:
if boxes.get(offset) == b"x":
prior[offset] = ord(" ")
if hashlib.sha256(prior).hexdigest().encode("ascii") != stored.rstrip(b"\r\n"):
refuse("Changes exceed checkbox-only scope.")
if digest.rstrip() == stored.rstrip():
check_plan_generation()
print("[plan-attest] Plan already matches attestation.")
return
check_plan_generation()
digest_tmp, staged = stage(parent, digest)
candidate = {"id": generation(staged, digest),
"unchecked": [pos for pos, value in boxes.items() if value == b" "]}
entries = [previous, candidate] if previous else [candidate]
intent = {"format": "pwf-checkbox-1", "generations": entries}
cache_tmp, _ = stage(cache, json.dumps(intent).encode("ascii"))
# Until the digest rename, its previous generation remains authoritative.
# Afterwards the candidate record is already usable, even across a retry.
os.replace(cache_tmp, key, src_dir_fd=cache, dst_dir_fd=cache)
check_plan_generation()
os.replace(digest_tmp, attest, src_dir_fd=parent, dst_dir_fd=parent)
current, written = read_file(parent, attest)
if generation(written, current) != candidate["id"]:
refuse("Attestation changed before verification.")
check_plan_generation()
print("[plan-attest] Attested selected plan with checkbox enrollment.")
try:
with ExitStack() as stack:
run(stack)
except (OSError, ValueError, KeyError, TypeError) as error:
sys.exit("[plan-attest] " + str(error))
PWF_CHECKBOX_PY
}
if [ "${mode}" != show ]; then
# Create in a private directory, then atomically claim the shared name
# with link(2). Never open an existing lock (which might be a link or FIFO).
writer_dir="$(dirname "${attestation_file}")"
case "${mode}" in
checkbox-only|enable-checkbox-only)
project_root="$(cd "${PWF_PLAN_ROOT:-.}" && pwd -P)" || exit 1
expected_slug="${writer_dir##*/}"
case "${target:-}" in
root) expected_slug="" ;;
"") expected_slug="${PLAN_ID:-${expected_slug}}" ;;
*) expected_slug="${target}" ;;
esac
cd -P "${writer_dir}" || exit 1
selected_dir="$(pwd -P)" || exit 1
if [ "${selected_dir}" != "${project_root}" ]; then
slug_is_valid "${expected_slug}" && [ "${selected_dir}" = "${project_root}/.planning/${expected_slug}" ] || exit 1
elif [ -n "${target:-${PLAN_ID:-}}" ] && [ "${target:-}" != root ]; then
exit 1
fi
writer_dir=.
plan_file=./task_plan.md
attestation_file="./${attestation_file##*/}"
;;
esac
writer_name="${attestation_file##*/}.writer-lock"
staging="$(mktemp -d "${writer_dir}/.pwf-writer.XXXXXXXX")" || exit 1
claim="${staging}/${writer_name}"
: > "${claim}" || exit 1
trap 'rm -f "${claim}"; rmdir "${staging}"' EXIT
attempts=0
lock_path="${writer_dir}/${writer_name}"
owner="${staging##*/}"
if ln "${claim}" "${staging}/probe" 2>/dev/null && [ "${claim}" -ef "${staging}/probe" ]; then
lock_type=link
else
case "$(uname -s)" in
MINGW*|MSYS*|CYGWIN*)
lock_type=windows
if command -v pwsh >/dev/null 2>&1; then windows_shell=pwsh
elif command -v powershell.exe >/dev/null 2>&1; then windows_shell=powershell.exe
else printf '[plan-attest] Native PowerShell is required for this volume.\n' >&2; exit 1
fi
native_lock="$(cygpath -aw "${lock_path}")" || exit 1 ;;
*) lock_type=directory ;;
esac
fi
rm -f "${staging}/probe"
claim_writer() {
case "${lock_type}" in
link) ln "${claim}" "${writer_dir}/" 2>/dev/null ;;
directory)
# On POSIX mkdir is exclusive, including on volumes without hard links.
(umask 077; mkdir "${lock_path}") 2>/dev/null || return 1
mkdir "${lock_path}/${owner}" || return 1 ;;
windows)
PWF_CLAIM_PATH="${native_lock}" PWF_CLAIM_OWNER="${owner}" \
"${windows_shell}" -NoProfile -NonInteractive -Command '
$ErrorActionPreference = "Stop"
try {
$s = [IO.File]::Open($env:PWF_CLAIM_PATH, "CreateNew", "Write", "None")
try {
$data = [Text.Encoding]::ASCII.GetBytes($env:PWF_CLAIM_OWNER)
$s.Write($data, 0, $data.Length)
} finally { $s.Dispose() }
} catch { exit 1 }' ;;
esac
}
until claim_writer; do
attempts=$((attempts + 1))
if [ "${attempts}" -ge 50 ]; then
printf '[plan-attest] Cannot acquire attestation writer lock.\n' >&2
exit 1
fi
sleep 0.1
done
release_writer() {
case "${lock_type}" in
link) [ "${claim}" -ef "${lock_path}" ] && rm -f "${lock_path}" ;;
directory) rmdir "${lock_path}/${owner}" && rmdir "${lock_path}" ;;
windows)
if [ -f "${lock_path}" ] && [ ! -L "${lock_path}" ] &&
[ "$(cat "${lock_path}")" = "${owner}" ]; then rm -f "${lock_path}"; fi ;;
esac
rm -f "${claim}"
rmdir "${staging}"
}
trap release_writer EXIT
trap 'exit 1' HUP INT TERM
case "${mode}" in
checkbox-only|enable-checkbox-only)
checkbox_state "${mode}"
exit "$?" ;;
esac
fi
case "${mode}" in
show)
if [ -f "${attestation_file}" ]; then
printf "Plan: %s\n" "${plan_file}"
printf "Attestation: %s\n" "${attestation_file}"
printf "SHA-256: %s\n" "$(cat "${attestation_file}")"
# Nonce (security A1.4): if init-session generated a per-plan nonce
# next to the attestation, surface it. Informational only here; the
# hooks consume it to build collision-proof BEGIN/END delimiters.
nonce_file="$(dirname "${attestation_file}")/.nonce"
if [ -f "${nonce_file}" ]; then
printf "Nonce: %s\n" "$(tr -d '\r\n[:space:]' < "${nonce_file}" 2>/dev/null)"
fi
else
printf "[plan-attest] No attestation set for %s.\n" "${plan_file}"
exit 1
fi
;;
clear)
if [ -f "${attestation_file}" ]; then
rm -f "${attestation_file}" || exit 1
printf "[plan-attest] Cleared attestation for %s.\n" "${plan_file}"
else
printf "[plan-attest] No attestation to clear.\n"
fi
if [ -d "${HOME:-}/.pwf-checkbox-v1" ]; then
checkbox_state forget || printf '[plan-attest] Optional checkbox cache cleanup was unavailable.\n' >&2
fi
;;
attest)
printf "Plan: %s\n" "${plan_file}"
printf "Attestation: %s\n" "${attestation_file}"
hash_val="$(compute_hash "${plan_file}")" || exit 1
# v2.40: protect the write with an advisory flock when available so
# concurrent legacy-mode sessions (no PLAN_ID, both at the same project
# root) cannot corrupt the .plan-attestation file mid-write. Atomic
# rename of a temp file is the real guarantee on POSIX; flock is the
# cooperative gate around the rename for slow-disk writes.
#
# Note: legacy single-file mode is inherently racey across concurrent
# sessions because both can edit task_plan.md without coordination. The
# canonical parallel-session pattern is slug-mode under
# .planning/<slug>/, where each session pins PLAN_ID and gets its own
# .attestation file. We surface a hint when concurrent activity is
# detected.
if [ -f "${attestation_file}" ]; then
mtime_now="$(date +%s 2>/dev/null || echo 0)"
mtime_prev="$(stat -c '%Y' "${attestation_file}" 2>/dev/null \
|| stat -f '%m' "${attestation_file}" 2>/dev/null \
|| echo 0)"
age=$((mtime_now - mtime_prev))
if [ "${age}" -ge 0 ] && [ "${age}" -lt 30 ] 2>/dev/null; then
# If we're in legacy mode (root .plan-attestation) and another
# session just wrote, warn. Slug-mode files in .planning/<slug>/
# are per-session by construction; no need to warn there.
case "${attestation_file}" in
*./.plan-attestation|*/.plan-attestation)
case "${attestation_file}" in
*./.planning/*) : ;; # slug-mode, ignore
*)
printf "[plan-attest] Note: %s was modified %ss ago by another process.\n" \
"${attestation_file}" "${age}" >&2
printf "[plan-attest] For parallel sessions, prefer slug-mode (init-session.sh <name>) so each session gets its own .attestation file.\n" >&2
;;
esac
;;
esac
fi
fi
tmp_file="${attestation_file}.tmp.$$"
printf "%s\n" "${hash_val}" > "${tmp_file}" 2>/dev/null || {
printf "[plan-attest] Failed to write %s\n" "${tmp_file}" >&2
exit 1
}
mv_ok=1
if command -v flock >/dev/null 2>&1; then
# Advisory lock around the rename. lock_dir is the dir containing
# the target file. The {} subshell pattern keeps the lock scoped to
# the mv call.
lock_dir="$(dirname "${attestation_file}")"
(
flock -w 5 9 || true
mv -f "${tmp_file}" "${attestation_file}"
) 9>"${lock_dir}/.attestation.lock" 2>/dev/null || mv_ok=0
rm -f "${lock_dir}/.attestation.lock" 2>/dev/null
else
mv -f "${tmp_file}" "${attestation_file}" 2>/dev/null || mv_ok=0
fi
# Integrity gap fix (security A2.1): a failed atomic rename must not be
# allowed to silently leave a stale attestation when the target already
# existed. The old fallback only wrote when the file was absent, so a
# cross-device or permission-denied mv on an existing attestation left
# the OLD hash in place with a success exit. On mv failure we re-write
# the intended hash through a second atomic rename (never a bare
# redirect onto the live file, which would expose torn reads to
# concurrent verifiers), then verify the on-disk content.
if [ "${mv_ok}" -eq 0 ] || [ ! -f "${attestation_file}" ]; then
fb_tmp="${attestation_file}.fb.$$"
printf "%s\n" "${hash_val}" > "${fb_tmp}" 2>/dev/null \
&& mv -f "${fb_tmp}" "${attestation_file}" 2>/dev/null || {
rm -f "${fb_tmp}" "${tmp_file}" 2>/dev/null
printf "[plan-attest] Failed to write attestation %s\n" "${attestation_file}" >&2
exit 1
}
fi
rm -f "${tmp_file}" 2>/dev/null
# Read-back verification. Both write paths above are atomic renames, so
# a concurrent verifier always reads a complete 64-hex hash — either our
# own or an identical one from a peer attesting the same plan content.
# A mismatch here therefore means our intended hash genuinely did not
# land (stale content, failed write); fail loudly with a nonzero exit so
# callers never trust a stale attestation.
stored_hash="$(tr -d '\r\n[:space:]' < "${attestation_file}" 2>/dev/null)"
if [ "${stored_hash}" != "${hash_val}" ]; then
printf "[plan-attest] Attestation write verification FAILED for %s\n" "${attestation_file}" >&2
printf "[plan-attest] Expected %s, found %s. The plan is NOT attested.\n" "${hash_val}" "${stored_hash}" >&2
exit 1
fi
short_hash="$(printf "%s" "${hash_val}" | cut -c1-12)"
printf "[plan-attest] Locked %s\n" "${plan_file}"
printf "[plan-attest] SHA-256: %s... (stored in %s)\n" "${short_hash}" "${attestation_file}"
printf "[plan-attest] Hooks will block injection if the file is modified without re-running this command.\n"
;;
esac
exit 0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |