Skip to content

OthmanAdi/planning-with-files / skills/planning-with-files

planning-with-files

Verified

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

FileKindSize
SKILL.mdskill md41.0 KB
evals/planning-with-files.eval.yamlconfig4.8 KB
examples.mdmarkdown4.4 KB
plan-inventory.mdmarkdown9.3 KB
reference.mdmarkdown8.3 KB
scripts/attest-plan.ps1script27.4 KB
scripts/attest-plan.shscript27.4 KB
scripts/check-complete.ps1script12.8 KB
scripts/check-complete.shexecutablescript13.6 KB
scripts/gate-stop.shscript1.4 KB
scripts/init-session.ps1script19.5 KB
scripts/init-session.shexecutablescript15.4 KB
scripts/inject-plan.pyscript66.1 KB
scripts/inject-plan.shscript63.5 KB
scripts/ledger-append.ps1script6.7 KB
scripts/ledger-append.shscript11.9 KB
scripts/ledger-summary.ps1script6.7 KB
scripts/ledger-summary.shscript7.8 KB
scripts/phase-status.ps1script10.2 KB
scripts/phase-status.shscript7.4 KB
scripts/plan-doctor.shexecutablescript9.0 KB
scripts/resolve-plan-dir.ps1executablescript11.5 KB
scripts/resolve-plan-dir.shexecutablescript15.3 KB
scripts/session-catchup.pyexecutablescript36.4 KB
scripts/set-active-plan.ps1executablescript42.7 KB
scripts/set-active-plan.shexecutablescript38.6 KB
scripts/skill-hook.shexecutablescript19.3 KB
templates/analytics_findings.mdmarkdown1.8 KB
templates/analytics_task_plan.mdmarkdown2.5 KB
templates/findings.mdmarkdown1.1 KB
templates/loop.mdmarkdown2.1 KB
templates/progress.mdmarkdown1.5 KB
templates/task_plan.mdmarkdown2.2 KB
templates/task_plan_autonomous.mdmarkdown3.2 KB

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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall