OthmanAdi/planning-with-files / .pi/skills/planning-with-files
planning-with-files
FlaggedPersistent 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.
scripts/set-active-plan.sh
View on GitHub#!/bin/sh
# List saved named plans, show the shared pointer, change that pointer, or
# archive and restore named plans (a rename into .planning/.archive, #355).
# Usage: set-active-plan.sh [--list [--archived]|-l|--verify-root|PLAN_ID]
# set-active-plan.sh --list --json [--archived] [--limit N] [--offset N]
# set-active-plan.sh --archive <id> [--yes] | --restore <id> [--yes]
# Operates on the current project; listing never binds a host or injects data.
# Archive and restore preview without --yes, never copy, and never delete.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
ARCHIVE_ROOT="${PLAN_ROOT}/.archive"
PWF_ROOT_PIN=""
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Sets CANON_OUT to the canonical absolute path on success; returns 1 on a
# full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
# Setting a variable instead of printing keeps hot callers out of a subshell,
# which costs a process on Windows.
canonicalize_into() {
target="$1"
CANON_OUT=""
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
CANON_OUT="${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
CANON_OUT="${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { CANON_OUT="${out}"; return 0; }
fi
return 1
}
canonicalize() {
canonicalize_into "$1" || return 1
printf "%s\n" "${CANON_OUT}"
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
if canonicalize_into "${PWF_ROOT_PIN:-.}"; then ROOT_REAL="${CANON_OUT}"; else ROOT_REAL=""; fi
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
if canonicalize_into "${check_target}"; then cand_real="${CANON_OUT}"; else cand_real=""; fi
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk -v output="${2:-text}" '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (primary_count > 1) malformed = 1
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""; primary_count = 0
}
{
line = $0
if (NR == 1 && output == "json") sub(/^\357\273\277/, "", line)
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
primary_count++
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
if (primary == "") primary = line
} else if (phase && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*/) {
malformed = 1
}
}
END {
finish()
if (output == "json") {
state = total == 0 ? "empty" : ((malformed || total != complete + in_progress + pending) ? "malformed" : "parsed")
printf "{\"status\":\"%s\",\"total\":%d,\"complete\":%d,\"in_progress\":%d,\"pending\":%d}", state, total, complete, in_progress, pending
} else printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && can_open "${_plan_file}" || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.' \
'Archive a finished plan with --archive <id> (preview first; nothing is deleted).'
fi
_archived="$(archived_count)"
[ "${_archived}" -eq 0 ] || printf '%s\n' "${_archived} archived plan(s): --list --archived"
}
# Archive and restore (#355): a finished plan moves to .planning/.archive/<id>
# with one rename and comes back the same way. Dot-prefixed names are never
# plans on any route, so an archived plan is invisible to every resolver and
# the remaining named plans select automatically again.
fail() { printf '%s\n' "Error: $1" >&2; exit 1; }
is_real_dir() { [ -d "$1" ] && [ ! -L "$1" ] && is_within_root "$1"; }
# A plan that may move: a real contained directory with a regular task_plan.md.
is_real_plan_dir() { is_real_dir "$1" && [ -f "$1/task_plan.md" ] && [ ! -L "$1/task_plan.md" ]; }
device_of() { stat -c %d "$1" 2>/dev/null || stat -f %d "$1" 2>/dev/null; }
# A plan ID must match its directory entry exactly. A case-insensitive
# filesystem finds alpha for ALPHA and Win32 drops a trailing dot, which
# would archive under another name and slip past the guards below.
has_exact_entry() {
for _he_entry in "$1"/*; do
[ "${_he_entry##*/}" = "$2" ] && return 0
done
return 1
}
# True when a slug names the source directory itself ($2), not merely the
# same string: the resolver would select alpha for ALPHA or alpha. there.
names_source() { slug_is_valid "$1" && [ "${PLAN_ROOT}/$1" -ef "$2" ]; }
# The pointer read the way the resolver reads it: BOM stripped, all
# whitespace removed, then a valid slug that names the source directory.
pointer_names_source() {
! pointer_is_unsafe && [ -f "${ACTIVE_FILE}" ] && can_open "${ACTIVE_FILE}" || return 1
_pn_id="$(tr -d '[:space:]' < "${ACTIVE_FILE}")"
_pn_bom="$(printf '\357\273\277')"
case "${_pn_id}" in "${_pn_bom}"*) _pn_id="${_pn_id#"${_pn_bom}"}" ;; esac
names_source "${_pn_id}" "$1"
}
# Archived plans with the listing filters, counted with builtins only.
archived_count() {
_ac_n=0
if is_real_dir "${ARCHIVE_ROOT}"; then
for _ac_dir in "${ARCHIVE_ROOT}"/*; do
[ -d "${_ac_dir}" ] && [ ! -L "${_ac_dir}" ] || continue
slug_is_valid "${_ac_dir##*/}" || continue
[ -f "${_ac_dir}/task_plan.md" ] && [ ! -L "${_ac_dir}/task_plan.md" ] || continue
_ac_n=$((_ac_n + 1))
done
fi
printf '%s' "${_ac_n}"
}
list_archived() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_real_dir "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_found=0
if is_real_dir "${ARCHIVE_ROOT}"; then
for _dir in "${ARCHIVE_ROOT}"/*; do
_id="${_dir##*/}"
slug_is_valid "${_id}" && is_real_plan_dir "${_dir}" && can_open "${_dir}/task_plan.md" || continue
_status="$(phase_status "${_dir}/task_plan.md")" || continue
[ "${_found}" -eq 1 ] || printf '%s\n' 'Archived plans:'
printf '%s\n' "- ${_id} - ${_status}"
_found=1
done
fi
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No archived plans found.'
else
printf '%s\n' 'Restore with --restore <id>.'
fi
}
# Every check runs before anything is touched; a failure changes nothing.
# $1 archive|restore, $2 plan id, $3 1 to apply (otherwise preview).
move_plan() {
_mp_op="$1"; _mp_id="$2"; _mp_apply="$3"
slug_is_valid "${_mp_id}" || fail 'invalid plan ID. Use a named directory under .planning.'
[ -d "${PLAN_ROOT}" ] || fail "planning directory not found: ${PLAN_ROOT}"
is_real_dir "${PLAN_ROOT}" || fail 'planning directory is outside the project, is a link, or cannot be verified.'
if [ "${_mp_op}" = archive ]; then
_mp_src="${PLAN_ROOT}/${_mp_id}"; _mp_parent="${ARCHIVE_ROOT}"
is_real_plan_dir "${_mp_src}" && has_exact_entry "${PLAN_ROOT}" "${_mp_id}" ||
fail "no plan to archive at ${_mp_src} (needs a real directory inside the project with a regular task_plan.md)."
! names_source "${PLAN_ID:-}" "${_mp_src}" || fail 'PLAN_ID selects this plan in the current environment; unset it before archiving.'
if [ -e "${ARCHIVE_ROOT}" ] || [ -L "${ARCHIVE_ROOT}" ]; then
is_real_dir "${ARCHIVE_ROOT}" || fail "archive directory is not a real directory inside the project: ${ARCHIVE_ROOT}"
fi
else
_mp_src="${ARCHIVE_ROOT}/${_mp_id}"; _mp_parent="${PLAN_ROOT}"
is_real_dir "${ARCHIVE_ROOT}" || fail "no archive directory inside the project at ${ARCHIVE_ROOT}"
is_real_plan_dir "${_mp_src}" && has_exact_entry "${ARCHIVE_ROOT}" "${_mp_id}" ||
fail "no archived plan at ${_mp_src} (needs a real directory inside the project with a regular task_plan.md)."
fi
_mp_dest="${_mp_parent}/${_mp_id}"
if [ -e "${_mp_dest}" ] || [ -L "${_mp_dest}" ]; then
_mp_remedy=restore; [ "${_mp_op}" = archive ] || _mp_remedy=archive
fail "${_mp_dest} already exists; ${_mp_remedy} or rename it first."
fi
# One rename only: never a copy across filesystems, never a partial tree.
_mp_dev_parent="${_mp_parent}"; [ -d "${_mp_parent}" ] || _mp_dev_parent="${PLAN_ROOT}"
_mp_dev_src="$(device_of "${_mp_src}")" || _mp_dev_src=''
_mp_dev_dest="$(device_of "${_mp_dev_parent}")" || _mp_dev_dest=''
[ -n "${_mp_dev_src}" ] && [ "${_mp_dev_src}" = "${_mp_dev_dest}" ] ||
fail "${_mp_src} and ${_mp_dev_parent} are not on the same filesystem; a plan is only renamed, never copied."
# Decided before the move: afterwards the source no longer exists.
_mp_names_pointer=0
if [ "${_mp_op}" = archive ] && pointer_names_source "${_mp_src}"; then
_mp_names_pointer=1
fi
if [ "${_mp_apply}" != 1 ]; then
_mp_status="$(phase_status "${_mp_src}/task_plan.md")" || fail "cannot read ${_mp_src}/task_plan.md"
_mp_complete="${_mp_status%%/*}"; _mp_total="${_mp_status#*/}"; _mp_total="${_mp_total%% *}"
if [ "${_mp_op}" = archive ]; then
printf '%s\n' "Would archive plan: ${_mp_id} (${_mp_status})" " from: ${_mp_src}" " to: ${_mp_dest}"
if [ "${_mp_total}" -eq 0 ] || [ "${_mp_complete}" -ne "${_mp_total}" ]; then
printf '%s\n' ' Note: not all phases are complete.'
fi
[ "${_mp_names_pointer}" -eq 0 ] || printf '%s\n' ' The shared default (.active_plan) names this plan and will be cleared.'
printf '%s\n' "The plan is moved, never deleted. Restore with: set-active-plan.sh --restore ${_mp_id}"
else
printf '%s\n' "Would restore plan: ${_mp_id} (${_mp_status})" " from: ${_mp_src}" " to: ${_mp_dest}" \
'The plan is moved, never deleted.'
fi
printf '%s\n' 'Run again with --yes to apply.'
return 0
fi
_mp_made_archive=0
if [ "${_mp_op}" = archive ] && [ ! -d "${ARCHIVE_ROOT}" ]; then
mkdir -- "${ARCHIVE_ROOT}" 2>/dev/null || fail "could not create ${ARCHIVE_ROOT}"
_mp_made_archive=1
is_real_dir "${ARCHIVE_ROOT}" || fail "archive directory cannot be verified after creation: ${ARCHIVE_ROOT}"
fi
if ! mv -- "${_mp_src}" "${_mp_dest}"; then
# A failed call leaves no .archive it created: rmdir removes only an
# empty directory, so anything with content is never touched.
[ "${_mp_made_archive}" -eq 0 ] || rmdir -- "${ARCHIVE_ROOT}" 2>/dev/null || :
fail "could not move ${_mp_src} to ${_mp_dest}"
fi
if [ -e "${_mp_src}" ] || [ ! -f "${_mp_dest}/task_plan.md" ]; then
# mv descends into a directory another process created meanwhile.
[ ! -f "${_mp_dest}/${_mp_id}/task_plan.md" ] ||
fail "${_mp_dest} appeared concurrently and the plan now sits at ${_mp_dest}/${_mp_id}; move it by hand."
fail "move did not complete as expected; inspect ${_mp_src} and ${_mp_dest}."
fi
if [ "${_mp_op}" = archive ]; then
printf '%s\n' "Archived plan: ${_mp_id}" " to: ${_mp_dest}"
if [ "${_mp_names_pointer}" -eq 1 ]; then
if rm -f -- "${ACTIVE_FILE}"; then
printf '%s\n' ' Cleared the shared default (.active_plan), which named this plan.'
else
printf '%s\n' "Warning: could not remove ${ACTIVE_FILE}; it still names the archived plan." >&2
fi
fi
printf '%s\n' "Restore with: set-active-plan.sh --restore ${_mp_id}"
else
printf '%s\n' "Restored plan: ${_mp_id}" " to: ${_mp_dest}" \
"To make it the default: set-active-plan.sh ${_mp_id} To pin a session: PLAN_ID=${_mp_id}"
fi
}
# [ -r ] consults permission bits only. On Windows a file that another
# process holds open without sharing passes that test and still fails to
# open, which left awk's error where JSON belonged. A real open decides.
# `true`, not `:`: a redirection error on a special builtin exits a POSIX
# shell (sh, dash) under set -e instead of returning.
can_open() { { true < "$1"; } 2>/dev/null; }
# JSON is an explicit read-only listing mode. Keep all of its work outside the
# existing text/selection paths, including interpreter and resolver discovery.
# The helpers below set a variable instead of printing, so a candidate costs
# no subshell of its own: each one is a process on Git Bash (#356).
json_quote() {
case "$1" in
*[\"\\[:cntrl:]]*)
JSON_QUOTED=$(printf '%s' "$1" | LC_ALL=C awk '
BEGIN { printf "\""; for (i=1; i<32; i++) escape[sprintf("%c",i)] = sprintf("\\u%04x",i) }
{ if (NR>1) printf "\\n"; for (i=1; i<=length($0); i++) {
c=substr($0,i,1)
if (c=="\\") printf "\\\\"
else if (c=="\"") printf "\\\""
else if (c in escape) printf "%s",escape[c]
else printf "%s",c
}} END { printf "\"" }
') ;;
*) JSON_QUOTED="\"$1\"" ;;
esac
}
json_string() {
json_quote "$1"
printf '%s' "$JSON_QUOTED"
}
# One stat call for modification time and size. The flavor that worked first
# is kept, so BSD stat does not pay for a failed GNU attempt on every file.
file_stat() {
_fs_out=''
if [ "${STAT_FLAVOR:-gnu}" = gnu ]; then
_fs_out=$(stat -c '%Y %s' "$1" 2>/dev/null) && STAT_FLAVOR=gnu || _fs_out=''
fi
if [ -z "$_fs_out" ] && [ "${STAT_FLAVOR:-bsd}" = bsd ]; then
_fs_out=$(stat -f '%m %z' "$1" 2>/dev/null) && STAT_FLAVOR=bsd || _fs_out=''
fi
FILE_MTIME=${_fs_out%% *}; FILE_BYTES=${_fs_out#* }
[ -n "$_fs_out" ] || FILE_BYTES=''
}
file_metadata() {
_jf_path="$1"; _jf_display="$2"; _jf_state=missing; _jf_mtime=null; _jf_bytes=''
if [ -L "$_jf_path" ]; then _jf_state=excluded
elif [ -e "$_jf_path" ]; then
if [ ! -f "$_jf_path" ] || ! is_within_root "$_jf_path"; then _jf_state=excluded
elif ! can_open "$_jf_path"; then _jf_state=unreadable
else
_jf_state=readable
file_stat "$_jf_path"; _jf_mtime=$FILE_MTIME; _jf_bytes=$FILE_BYTES
case "$_jf_mtime" in ''|*[!0-9]*) _jf_mtime=null ;; esac
fi
fi
json_quote "$_jf_display"
FILE_META="{\"path\":${JSON_QUOTED},\"status\":\"${_jf_state}\",\"modified_at\":${_jf_mtime}}"
}
JSON_PHASES_UNAVAILABLE='{"status":"unavailable","total":0,"complete":0,"in_progress":0,"pending":0}'
# $2 is the size already read for this file, if any.
json_phases() {
_jp_file="$1"; JSON_PHASES=$JSON_PHASES_UNAVAILABLE
if [ -L "$_jp_file" ] || [ ! -f "$_jp_file" ] || ! can_open "$_jp_file" || ! is_within_root "$_jp_file"; then
return
fi
_jp_bytes=${2:-}
if [ -z "$_jp_bytes" ]; then file_stat "$_jp_file"; _jp_bytes=$FILE_BYTES; fi
case "$_jp_bytes" in ''|*[!0-9]*) _jp_bytes=262145 ;; esac
if [ "$_jp_bytes" -gt 262144 ]; then
JSON_PHASES='{"status":"too_large","total":0,"complete":0,"in_progress":0,"pending":0}'; return
fi
# The file can still lock or vanish between the open test and the parse;
# a failed or empty parse must not leave a hole in the document.
_jp_out=$(phase_status "$_jp_file" json 2>/dev/null) || _jp_out=''
case "$_jp_out" in '{"status":"'*'}') JSON_PHASES=$_jp_out ;; esac
}
json_candidate() {
_jc_dir="$1"; _jc_display="$2"; _jc_id="$3"; _jc_kind="$4"
if [ "$_jc_kind" = root ]; then _jc_id_json=null; else json_quote "$_jc_id"; _jc_id_json=$JSON_QUOTED; fi
JSON_CANDIDATE="{\"kind\":\"${_jc_kind}\",\"plan_id\":${_jc_id_json},\"ownership\":\"unknown\",\"files\":{"
_jc_comma=''; _jc_plan_bytes=''
for _jc_pair in task_plan:task_plan.md findings:findings.md progress:progress.md; do
_jc_key=${_jc_pair%%:*}; _jc_name=${_jc_pair#*:}
file_metadata "$_jc_dir/$_jc_name" "$_jc_display/$_jc_name"
[ "$_jc_key" != task_plan ] || _jc_plan_bytes=$_jf_bytes
JSON_CANDIDATE="${JSON_CANDIDATE}${_jc_comma}\"${_jc_key}\":${FILE_META}"
_jc_comma=,
done
json_phases "$_jc_dir/task_plan.md" "$_jc_plan_bytes"
JSON_CANDIDATE="${JSON_CANDIDATE}},\"phases\":${JSON_PHASES}}"
}
json_selection() {
_js_status=unknown; _js_id=null
# Listing scope stays cwd. Do not inspect another pinned project's plans.
if [ -n "${PWF_PLAN_ROOT:-}" ]; then
case "$PWF_PLAN_ROOT" in
\\\\*|//*|[A-Za-z]:[!\\/]*|[!/]*)
case "$PWF_PLAN_ROOT" in [A-Za-z]:[\\/]*) : ;; *) printf '{"status":"rejected","plan_id":null}'; return ;; esac ;;
esac
if [ ! -d "$PWF_PLAN_ROOT" ]; then printf '{"status":"rejected","plan_id":null}'; return; fi
_js_pin=$(canonicalize "$PWF_PLAN_ROOT") || _js_pin=''
norm_slashes "$_js_pin"; _js_pin="$NORM_OUT"
if [ "$_js_pin" != "$JSON_PHYSICAL_ROOT" ] && ! [ "$PWF_PLAN_ROOT" -ef . ] 2>/dev/null; then printf '{"status":"outside_scope","plan_id":null}'; return; fi
fi
if [ -L "$PLAN_ROOT" ] || { [ -d "$PLAN_ROOT" ] && ! is_within_root "$PLAN_ROOT"; }; then
_js_status=unknown
[ -z "${PLAN_ID:-}" ] || _js_status=rejected
printf '{"status":"%s","plan_id":null}' "$_js_status"; return
fi
_js_resolver="$(dirname "$0")/resolve-plan-dir.sh"
if [ -z "${PLAN_ID:-}" ] && [ -f "$ACTIVE_FILE" ]; then
_js_pointer_bytes=$(stat -c %s "$ACTIVE_FILE" 2>/dev/null || stat -f %z "$ACTIVE_FILE" 2>/dev/null) || _js_pointer_bytes=9999
if [ "$_js_pointer_bytes" -gt 256 ]; then printf '{"status":"unknown","plan_id":null}'; return; fi
fi
if [ -f "$_js_resolver" ]; then
_js_dir=$(sh "$_js_resolver" 2>/dev/null) || _js_dir=''
if [ -n "$_js_dir" ]; then
norm_slashes "$_js_dir"; _js_dir="$NORM_OUT"
_js_status=selected; _js_id=$(json_string "${_js_dir##*/}")
elif [ "$(sh "$_js_resolver" --check-ambiguity 2>/dev/null)" = PWF_PLAN_AMBIGUOUS_V1 ]; then _js_status=ambiguous
elif [ -n "${PLAN_ID:-}" ]; then _js_status=rejected
elif [ -f task_plan.md ] && [ ! -L task_plan.md ] && is_within_root task_plan.md; then _js_status=legacy_root
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then _js_status=rejected
else _js_status=none
fi
fi
printf '{"status":"%s","plan_id":%s}' "$_js_status" "$_js_id"
}
json_add_candidate() {
if [ "$JSON_INDEX" -lt "$JSON_OFFSET" ]; then JSON_INDEX=$((JSON_INDEX + 1)); return 0; fi
if [ "$JSON_RETURNED" -ge "$JSON_LIMIT" ]; then JSON_TRUNCATED=true; JSON_NEXT=$JSON_INDEX; return 1; fi
json_candidate "$1" "$2" "$3" "$4"; _ja_row=$JSON_CANDIDATE
# list_plans_json runs under LC_ALL=C, so the length is in bytes.
_ja_size=${#_ja_row}
if [ $((JSON_USED + _ja_size + 1)) -gt "$JSON_BUDGET" ]; then
JSON_TRUNCATED=true; JSON_NEXT=$JSON_INDEX
if [ "$JSON_RETURNED" -eq 0 ]; then
JSON_SKIPPED=$((JSON_SKIPPED + 1)); JSON_NEXT=$((JSON_INDEX + 1))
fi
return 1
fi
JSON_ROWS="${JSON_ROWS}${JSON_COMMA}${_ja_row}"; JSON_COMMA=,
JSON_USED=$((JSON_USED + _ja_size + 1)); JSON_RETURNED=$((JSON_RETURNED + 1)); JSON_INDEX=$((JSON_INDEX + 1))
}
list_plans_json() {
JSON_PHYSICAL_ROOT=$(canonicalize .) || { printf '{"schema_version":1,"error":"unresolved_project_root"}\n'; return 1; }
norm_slashes "$JSON_PHYSICAL_ROOT"; JSON_PHYSICAL_ROOT=$NORM_OUT
JSON_PROJECT=$JSON_PHYSICAL_ROOT
# cygpath converts through the ANSI code page under LC_ALL=C or LANG=C,
# mangling every non-ASCII path; pin a UTF-8 locale for that one call.
if [ -x /usr/bin/cygpath.exe ]; then JSON_PROJECT=$(LC_ALL=C.UTF-8 /usr/bin/cygpath.exe -am "$JSON_PROJECT"); fi
# Slugs are ASCII. C locale gives the same ordering as PS ordinal, and
# the root and named candidates must parse under the same locale.
LC_ALL=C; export LC_ALL
_jl_pointer=null; _jl_pointer_state=missing
if [ -L "$ACTIVE_FILE" ]; then _jl_pointer_state=excluded
elif [ -e "$ACTIVE_FILE" ]; then
_jl_pointer_state=invalid
if [ -f "$ACTIVE_FILE" ] && [ -r "$ACTIVE_FILE" ] && is_within_root "$ACTIVE_FILE"; then
_jl_bytes=$(stat -c %s "$ACTIVE_FILE" 2>/dev/null || stat -f %z "$ACTIVE_FILE" 2>/dev/null) || _jl_bytes=9999
if [ "$_jl_bytes" -le 256 ]; then
_jl_active=$(current_active)
if [ -n "$_jl_active" ]; then
_jl_pointer=$(json_string "$_jl_active"); _jl_pointer_state=dangling
if [ ! -L "$PLAN_ROOT/$_jl_active" ] && [ ! -L "$PLAN_ROOT/$_jl_active/task_plan.md" ] && [ -f "$PLAN_ROOT/$_jl_active/task_plan.md" ] && is_within_root "$PLAN_ROOT/$_jl_active/task_plan.md"; then _jl_pointer_state=present; fi
fi
fi
fi
fi
_jl_header="{\"schema_version\":1,\"scope\":{\"project_root\":$(json_string "$JSON_PROJECT"),\"source\":\"cwd\"},\"shared_default\":{\"plan_id\":${_jl_pointer},\"status\":\"${_jl_pointer_state}\"},\"selection\":$(json_selection),\"host_session\":null,\"archived_count\":$(archived_count),\"candidates\":["
_jl_header_size=$(printf '%s' "$_jl_header" | LC_ALL=C wc -c)
JSON_BUDGET=$((16383 - _jl_header_size - 512))
JSON_ROWS=''; JSON_COMMA=''; JSON_INDEX=0; JSON_RETURNED=0; JSON_USED=0; JSON_SKIPPED=0; JSON_NEXT=null; JSON_TRUNCATED=false
if [ "$JSON_BUDGET" -lt 0 ]; then printf '{"schema_version":1,"error":"project_path_exceeds_output_limit"}\n'; return 1; fi
# --archived lists .planning/.archive with the same filters and no root candidate.
_jl_scan="$PLAN_ROOT"; _jl_kind=named; _jl_rel=.planning
if [ "$JSON_ARCHIVED" = 1 ]; then _jl_scan="$ARCHIVE_ROOT"; _jl_kind=archived; _jl_rel=.planning/.archive; fi
_jl_continue=1
if [ "$JSON_ARCHIVED" != 1 ] && { [ -e task_plan.md ] || [ -L task_plan.md ] || [ -e findings.md ] || [ -e progress.md ]; }; then
json_add_candidate . "$JSON_PROJECT" '' root || _jl_continue=0
fi
if [ "$_jl_continue" = 1 ] && [ -d "$_jl_scan" ]; then
if [ -L "$PLAN_ROOT" ] || [ -L "$_jl_scan" ] || ! is_within_root "$_jl_scan"; then JSON_SKIPPED=$((JSON_SKIPPED + 1))
else
for _jl_dir in "$_jl_scan"/*; do
[ -d "$_jl_dir" ] || [ -L "$_jl_dir" ] || continue
_jl_id=${_jl_dir##*/}; slug_is_valid "$_jl_id" || continue
if [ -L "$_jl_dir" ] || [ -L "$_jl_dir/task_plan.md" ] || ! is_within_root "$_jl_dir"; then JSON_SKIPPED=$((JSON_SKIPPED + 1)); continue; fi
[ -f "$_jl_dir/task_plan.md" ] || continue
json_add_candidate "$_jl_dir" "$JSON_PROJECT/$_jl_rel/$_jl_id" "$_jl_id" "$_jl_kind" || break
done
fi
fi
printf '%s%s],"limits":{"limit":%s,"offset":%s,"returned":%s,"truncated":%s,"next_offset":%s,"skipped":%s},"warnings":[' "$_jl_header" "$JSON_ROWS" "$JSON_LIMIT" "$JSON_OFFSET" "$JSON_RETURNED" "$JSON_TRUNCATED" "$JSON_NEXT" "$JSON_SKIPPED"
[ "$JSON_SKIPPED" -eq 0 ] || printf '"linked_unsafe_or_oversized_entries_skipped"'
printf ']}\n'
}
case "${1:-}:${2:-}" in
--list:--json|-l:--json)
shift 2; JSON_LIMIT=20; JSON_OFFSET=0; JSON_ARCHIVED=0
while [ "$#" -gt 0 ]; do
if [ "$1" = --archived ]; then JSON_ARCHIVED=1; shift; continue; fi
[ "$#" -ge 2 ] || { printf '%s\n' 'Error: a listing option needs an integer value.' >&2; exit 1; }
case "$2" in ''|*[!0-9]*|0[0-9]*) printf '%s\n' 'Error: listing bounds must be decimal integers.' >&2; exit 1 ;; esac
[ "${#2}" -le 6 ] || { printf '%s\n' 'Error: listing bound is too large.' >&2; exit 1; }
case "$1" in --limit) JSON_LIMIT=$2 ;; --offset) JSON_OFFSET=$2 ;; *) printf '%s\n' 'Error: unknown JSON listing option.' >&2; exit 1 ;; esac
shift 2
done
[ "$JSON_LIMIT" -ge 1 ] && [ "$JSON_LIMIT" -le 100 ] || { printf '%s\n' 'Error: limit must be between 1 and 100.' >&2; exit 1; }
list_plans_json; exit $? ;;
--list:--archived|-l:--archived)
[ "$#" -eq 2 ] || { printf '%s\n' 'Error: --list --archived takes no other option; JSON is --list --json --archived.' >&2; exit 1; }
list_archived; exit $? ;;
--archive:*|--restore:*)
move_op="${1#--}"; move_apply=0
case "${2:-}" in ''|-*) printf '%s\n' "Error: --${move_op} needs a plan ID: --${move_op} <id> [--yes]" >&2; exit 1 ;; esac
if [ "$#" -eq 3 ] && [ "$3" = --yes ]; then move_apply=1
elif [ "$#" -ne 2 ]; then printf '%s\n' "Error: --${move_op} takes a plan ID and optionally --yes, nothing else." >&2; exit 1
fi
move_plan "${move_op}" "$2" "${move_apply}"; exit $? ;;
esac
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--yes|--archived)
printf '%s\n' "Error: $1 is only valid with --archive, --restore, or --list." >&2
exit 1 ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list [--archived]|--verify-root|PLAN_ID]' \
' set-active-plan.sh --archive <id> [--yes] | --restore <id> [--yes]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--list --json [--archived] [--limit 1..100] [--offset N] emits bounded metadata, including root files.' \
'--verify-root checks the planning root and pointer without listing or selecting.' \
'--archive moves a named plan to .planning/.archive/<id>; --restore moves it back.' \
'Both preview until --yes is given, never copy, and never delete.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |