Compare commits

...
7 Commits
Author SHA1 Message Date
OthmanAdi bb292cba44 release: v3.6.0 (silent hook loss on native-coreutils Windows fixed, /plan-doctor, install matrix)
17-file parity bump (canonical + 5 language + 8 IDE SKILL.md variants,
plugin.json, marketplace.json, CITATION.cff). .continue, .gemini, .pi,
.kiro remain on their own versioning per release scope. CHANGELOG entry,
README release row, version heading, plan-mode handoff FAQ, and the
supported-agents answer refreshed to the 2026 .agents/skills landscape.
2026-07-18 11:54:55 +02:00
OthmanAdi 1a2d95eeb0 fix: set executable bit on plan-doctor.sh (matches resolve-plan-dir.sh) 2026-07-18 11:54:55 +02:00
OthmanAdi 0ec48c1c13 docs: install-route matrix, trust prerequisite, trigger snippet, stale reference cleanup
installation.md now states what each install route actually ships (the
plugin route carries commands/ and reliable hook registration; npx
skills and manual copies do not), documents the project-trust gate that
silently disables project-level skills, and offers a one-line CLAUDE.md
trigger snippet: the July 2026 benchmark measured unforced skill
engagement at 60-67% while always-loaded rules lines engaged 100%.

The last two variant copies still teaching Manus-2025 "one tool call
per turn" (.factory, .mastracode) get the 2026 parallel-host update the
canonical reference.md already carries. kilocode.md notes the Windsurf
to Devin Desktop transition.
2026-07-18 11:54:33 +02:00
OthmanAdi 0d286ac530 feat: add /plan-doctor self-check command
Every failure in the resolution and injection class is silent by design
(hooks always exit 0), so a broken install looks identical to "no plan
yet". plan-doctor.sh answers in one pass: does resolution work here and
which plan wins, does injection emit plan context, what path shape does
the canonicalizer produce, is the plan attested, which install surfaces
exist, and what one hook fire costs in wall-clock.

Dual-shipped in both scripts/ locations and added to the parity test.
From the July 2026 benchmark improvement backlog (P0 trigger and
install-health items).
2026-07-18 11:54:33 +02:00
OthmanAdi 78a526dc60 fix: normalize Windows-native canonical paths in plan containment guards
A native Windows coreutils build on PATH gives sh a realpath that prints
C:\-style backslash paths. The containment prefix match in
resolve-plan-dir.sh and inject-plan.sh is written with forward slashes,
so every canonical pair mismatched: the resolver resolved nothing and
inject-plan.sh emitted nothing, exit 0, no error. Plan resolution and
hook injection were fully and silently disabled on such machines.

Canonical paths are now backslash-normalized (pure shell, no extra
process) before comparison. The resolver also canonicalizes its root via
"." and checks candidates through their cwd-relative form, healing the
8.3 short-path mismatch the v3.2.0 fix only applied to inject-plan.sh.
Per-candidate grep and basename forks are replaced with case patterns
and parameter expansion; the containment root is computed once per run.

Regression tests use a PATH-prepended stub realpath that reproduces the
backslash output shape on every platform, so Linux CI guards this
Windows-only field failure. Also cures the long-standing local
test_ledger.py hang on Windows.
2026-07-18 11:54:22 +02:00
OthmanAdi f90780c92f release: v3.5.1 (Codex WSL bash resolver skip, Windows Python discovery, Pi interactive-tool fix)
Codex on Windows: extend the WSL launcher skip to the Store WindowsApps
alias and add regression tests for both launcher locations. Fold the CI
workflow and test portability work (PRs #198, #199 by @Yigtwxx) into the
release entry.

Pi extension 1.2.1: deliver tool_call recitations and the tamper notice
as nextTurn instead of steer so they can no longer be consumed by
interactive tools blocking the turn (issue #206, diagnosed by @jschmied).

Version bump to 3.5.1 across the 17-file parity set, CHANGELOG,
CONTRIBUTORS, README badge and releases table.
2026-07-14 16:33:15 +02:00
Mahdi Yousefi 59b04ab2a7 fix(codex): skip the WSL bash launcher and harden Windows Python discovery
The Codex shell resolver picked C:\Windows\System32\bash.exe (the WSL
launcher) whenever Git Bash usr\bin was not on PATH, so every shell hook
failed on machines where WSL is present without a distro (the common
Docker Desktop setup). The resolver now skips System32 and continues to
the Git for Windows probe.

pwf-hook.cmd now honors PYTHON_BIN, falls back to py/python on PATH, and
probes standard uv and CPython install locations for the case where Codex
starts hooks with a reduced PATH. The interpreter path is quoted so
installs under paths with spaces work.

Extracted from PR #207. Follow-up to #201 and #204.
2026-07-14 16:20:08 +02:00
44 changed files with 1241 additions and 155 deletions
+1 -1
View File
@@ -9,7 +9,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans that survive context loss, /clear, and crashes, with an opt-in completion gate and multi-agent shared state on disk. Manus-style, installs across 60+ agents via the SKILL.md standard.",
"version": "3.5.0"
"version": "3.6.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.5.0",
"version": "3.6.0",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).",
"author": {
"name": "OthmanAdi",
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+10 -1
View File
@@ -83,10 +83,19 @@ def _windows_git_bash() -> tuple[str | None, list[str]]:
and probe for sh.exe and its sibling bin dirs. This is exactly issue #201:
the reporter had git bash installed but its usr\\bin was not on PATH.
"""
system32 = (Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32").resolve()
for exe in ("sh", "bash"):
found = shutil.which(exe)
if found:
return found, [str(Path(found).parent)]
candidate = Path(found).resolve()
parent = candidate.parent
# Windows' bash.exe is a WSL launcher, not a POSIX shell. Selecting
# it before Git Bash makes every shell hook fail when WSL has no
# installed distro (the common Git-for-Windows-only setup), and even
# a working WSL bash cannot run C:\ script paths. The Store alias
# under WindowsApps is the same launcher.
if parent != system32 and parent.name.lower() != "windowsapps":
return str(candidate), [str(parent)]
roots: list[Path] = []
git = shutil.which("git")
+12 -7
View File
@@ -8,11 +8,16 @@ rem via cmd.exe, PowerShell, or direct CreateProcess, and it lets us fall back
rem from the py launcher to python.exe. The Microsoft Store python3.exe alias is
rem deliberately never selected. Always exits 0 so an advisory hook cannot
rem report "hook exited with code 1".
set "PY="
where py >nul 2>nul && set "PY=py -3"
if not defined PY (
where python >nul 2>nul && set "PY=python"
)
if not defined PY exit /b 0
%PY% "%~dp0%~1" %2 %3 %4 %5
set "PY_EXE="
set "PY_ARGS="
if defined PYTHON_BIN if exist "%PYTHON_BIN%" set "PY_EXE=%PYTHON_BIN%"
if not defined PY_EXE where py >nul 2>nul && set "PY_EXE=py" && set "PY_ARGS=-3"
if not defined PY_EXE where python >nul 2>nul && set "PY_EXE=python"
rem Codex can start hooks with a reduced PATH. Probe the normal uv and CPython
rem install locations so a valid user installation still works in that case.
if not defined PY_EXE for /d %%D in ("%APPDATA%\uv\python\*") do if exist "%%~fD\python.exe" if not defined PY_EXE set "PY_EXE=%%~fD\python.exe"
if not defined PY_EXE for /d %%D in ("%LOCALAPPDATA%\uv\python\*") do if exist "%%~fD\python.exe" if not defined PY_EXE set "PY_EXE=%%~fD\python.exe"
if not defined PY_EXE for /d %%D in ("%LOCALAPPDATA%\Programs\Python\Python*") do if exist "%%~fD\python.exe" if not defined PY_EXE set "PY_EXE=%%~fD\python.exe"
if not defined PY_EXE exit /b 0
"%PY_EXE%" %PY_ARGS% "%~dp0%~1" %2 %3 %4 %5
exit /b 0
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
# Planning with Files
@@ -178,7 +178,7 @@ Manus operates in a continuous 7-step loop:
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Single-Action Execution (Manus 2025 original constraint):** ONE tool call per turn, no parallel execution. This documents Manus's 2025 sandbox practice. **2026 update:** modern hosts (Claude Code, Codex CLI) support parallel tool calls and subagents, so this constraint no longer applies as written. The plan file, not the one-call-per-turn rule, remains the coordination point: parallel calls and subagents share state through the durable markdown plan on disk.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes."
metadata:
version: "3.5.0"
version: "3.6.0"
---
> Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
@@ -178,7 +178,7 @@ Manus operates in a continuous 7-step loop:
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Single-Action Execution (Manus 2025 original constraint):** ONE tool call per turn, no parallel execution. This documents Manus's 2025 sandbox practice. **2026 update:** modern hosts (Claude Code, Codex CLI) support parallel tool calls and subagents, so this constraint no longer applies as written. The plan file, not the one-call-per-turn rule, remains the coordination point: parallel calls and subagents share state through the durable markdown plan on disk.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
@@ -271,7 +271,7 @@ describe("Pi extension runtime handlers", () => {
content: expect.stringContaining("PreToolUse recitation"),
display: false,
}),
{ deliverAs: "steer", triggerTurn: false },
{ deliverAs: "nextTurn", triggerTurn: false },
);
});
@@ -1,6 +1,6 @@
{
"name": "@tomxprime/planning-with-files-pi-extension",
"version": "1.2.0",
"version": "1.2.1",
"private": true,
"type": "module",
"scripts": {
@@ -543,7 +543,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
content: buildTamperMessage(status),
display: true,
},
{ deliverAs: "steer", triggerTurn: false },
{ deliverAs: "nextTurn", triggerTurn: false },
);
} else if (mode === "parity") {
pi.sendMessage(
@@ -552,7 +552,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
content: buildPreToolParityRecitation(status),
display: false,
},
{ deliverAs: "steer", triggerTurn: false },
{ deliverAs: "nextTurn", triggerTurn: false },
);
} else if (mode === "cache-safe") {
pi.sendMessage(
@@ -561,7 +561,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
content: PRE_TOOL_CACHE_SAFE_REMINDER,
display: false,
},
{ deliverAs: "steer", triggerTurn: false },
{ deliverAs: "nextTurn", triggerTurn: false },
);
}
}
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+47 -11
View File
@@ -2,26 +2,62 @@
All notable changes to this project will be documented in this file.
## [Unreleased]
Infrastructure only. Nothing in the distributed skill changed, so no version bump: these changes touch `.github/` and `tests/`, not any of the 19 version-bump targets.
### Added
- **CI test workflow** (`.github/workflows/tests.yml`, PR #199 by @Yigtwxx, closes #197). Runs the pytest suite on `ubuntu-latest` and `windows-latest` (Python 3.12) plus the Pi extension vitest suite on `ubuntu-latest` (Node 22), on every pull request and push to master. Until now the only CI was the Tessl skill-prose review, so nothing ran the 200+ pytest tests or the 21 Pi vitest tests that CONTRIBUTING.md asks contributors to run before opening a PR. The `windows-latest` leg targets the recurring Windows regression class (the v3.2.0 audit found `session-catchup.py` silently non-functional on Windows). Workflow permissions are `contents: read` only, `fail-fast: false` keeps a Windows-only failure visible instead of masked by a cancel, and an explicit step asserts `sh` is on PATH so the roughly ten hook tests that skip without it cannot silently drop coverage. The workflow lives in `.github/` and is not part of the distributed skill.
## [3.6.0] - 2026-07-18
### Fixed
- **Two test-portability failures surfaced by the first hosted-runner run** (PR #198 by @Yigtwxx, test files only, no production script changes). `tests/test_containment.py` canonicalized the resolver's Git Bash POSIX path with `os.path.realpath`, which read `/tmp/...` as `C:\tmp` and failed the escaping-symlink containment assertion on symlink-capable `windows-latest`; a `host_realpath()` helper now maps the path back with `cygpath` before comparing. `tests/test_path_fix.py` ran two Windows-shaped path vectors on `ubuntu-latest`, where `Path.resolve()` treats `C:/...` as relative and prepends the CWD; both now skip unless `os.name == "nt"`, the only platform where that input shape is meaningful. In both cases the resolver rejected the escape correctly and only the test comparison was wrong.
- **Plan resolution and hook injection went silently dark on machines with Windows-native coreutils on PATH.** A native coreutils build (for example `C:\Program Files\coreutils`, increasingly common via winget or uutils) shadows Git Bash's tools inside `sh`, and its `realpath` canonicalizes MSYS `/c/...` input to `C:\`-style backslash output. The containment guard in `resolve-plan-dir.sh` and `inject-plan.sh` compares canonical paths with a forward-slash prefix pattern, so every comparison failed: the resolver resolved nothing, `inject-plan.sh` emitted nothing, and every hook fire exited 0 with no error. The plan mechanisms this skill is built on were fully disabled on such machines with no visible symptom, and Linux CI could never reproduce it. Canonical paths are now backslash-normalized (pure-shell, no extra process) before comparison. Found live during a repo audit on a machine where 33 local tests failed while CI stayed green.
- **The resolver's containment root still canonicalized `$PWD` instead of `.`.** The v3.2.0 fix for 8.3 short-name and `/tmp`-alias mismatches landed in `inject-plan.sh` only; `resolve-plan-dir.sh` kept the old form and additionally canonicalized absolute candidates built from the `$PWD` string, which a Windows-native `realpath` does not spell the same way as a short-form process cwd. The resolver now canonicalizes the root via `.` and checks candidates through their cwd-relative form, so both sides resolve through the same physical-cwd base. Emitted output is unchanged.
- **The local `test_ledger.py` hang on Windows is gone.** Known since v3.4.1 as "hangs locally, green on CI"; it stopped reproducing once the containment comparison was fixed. The ledger suite (12 tests) now passes locally in under 15 seconds.
### Added
- **`/plan-doctor` self-check command** (`commands/plan-doctor.md`, `scripts/plan-doctor.sh`, dual-shipped and parity-tested). Every failure in this class is silent by design (hooks always exit 0), so a broken install looks identical to "no plan yet". The doctor answers, in one pass: does resolution work here and which plan wins, does injection actually emit plan context, what path shape does the canonicalizer produce (warns about the pre-v3.6.0 dark condition), is the plan attested, which install surfaces exist on this machine, and what one hook fire costs in wall-clock. From the July 2026 benchmark improvement backlog.
- **Install-route matrix and trust prerequisite in `docs/installation.md`.** The plugin route ships `commands/` and registers hooks reliably; `npx skills add` and manual skill copies ship no slash commands, and SKILL.md frontmatter hooks have been observed unregistered on project-level installs (headless Claude Code 2.1.201, July 2026 benchmark). Project trust (`hasTrustDialogAccepted`) silently gates project-level skills. Both conditions are now documented with the doctor as the verification step.
- **Belt-and-suspenders trigger line for CLAUDE.md.** The July 2026 benchmark measured unforced skill engagement at 60-67% while always-loaded rules-file instructions engaged 100%. Install docs now offer a one-line CLAUDE.md snippet that makes engagement deterministic while the skill description keeps handling discovery.
- **Regression tests for the backslash-canonicalizer class** (`tests/test_containment.py`): a PATH-prepended stub `realpath` reproduces the Windows-native output shape on every platform, so ubuntu CI now guards a Windows-only field failure.
### Changed
- **Hook fire cost dropped.** Per-candidate `grep -Eq` slug checks and `basename` calls in `resolve-plan-dir.sh` and `inject-plan.sh` were replaced with equivalent shell builtins (case patterns and parameter expansion), and the resolver computes its containment root once per run instead of once per candidate. One `inject-plan.sh` fire measures 289ms wall-clock on the same machine that measured 2.0-2.4s at v3.4.0 (July 2026 benchmark, F4). Output is byte-identical; the legacy invariant holds.
- README documents v3.6.0, adds a plan-mode handoff FAQ (how an accepted plan-mode plan becomes `task_plan.md` phases, answering the open question in #19), and updates the supported-agents answer to the current `.agents/skills/` standard landscape. The stale Manus-2025 "one tool call per turn" guidance was replaced with the 2026 parallel-host update in the last two variant copies that still carried it (`.factory`, `.mastracode`).
### Verification
- Python suite green on master before merge (200 passed, 5 skipped on a non-symlink-capable Windows host). Contributor's hosted-runner run green on all three jobs: 202 passed / 3 skipped on ubuntu (symlink containment tests running), the equivalent profile on windows, and 21 vitest. The workflow's first run on the merge commit (master) is green across all three jobs.
- Supply-chain review: no new runtime dependencies, no install scripts, no bin shims. The workflow installs `pytest` and `pyyaml` for the pytest job and runs `npm install` against the Pi extension's existing devDependencies (vitest, typescript, @types/node). It uses `pull_request` (not `pull_request_target`), so fork PRs run with a read-only token and no secret access.
- Full suite green locally on the machine that reproduced the bug: 205 passed plus 12 ledger tests, 5 skipped, 0 failed (was 33 failed before the fix). Live smoke: `sh scripts/inject-plan.sh` emits plan context in a repo with an active plan, `scripts/plan-doctor.sh` reports PASS on resolution and injection with the Windows-native canonicalizer present.
## [3.5.1] - 2026-07-14
### Fixed
- **Codex Windows hook resolver defaulted to the WSL bash launcher** (extracted from PR #207 by @mahdiit). The shell resolver in `codex_hook_adapter` preferred `C:\Windows\System32\bash.exe`, the WSL launcher, whenever Git Bash's `usr\bin` was not on PATH, the default Git for Windows install layout. On machines where WSL is present but no distro is installed, a common Docker Desktop setup, that launcher exists on disk but fails immediately, so every shell hook silently failed. This is why #201 and #204 kept resurfacing on some Windows machines even after those releases shipped. The resolver now skips WSL launchers, both the System32 binary and the Microsoft Store WindowsApps alias, and continues on to the Git for Windows probe.
- **`pwf-hook.cmd` lost the Python interpreter under Codex's reduced PATH** (also from PR #207). Codex starts hooks with a trimmed environment, so the launcher's plain `py -3` / `python` lookup often found nothing. `pwf-hook.cmd` now honors a `PYTHON_BIN` override, probes the standard `uv` and CPython install locations, and quotes the interpreter path so installs under a path containing spaces still resolve.
- **Pi extension 1.2.1: pre-tool recitations and the tamper notice were consumed by interactive tool dialogs** (#206, diagnosed with the exact mechanism by @jschmied). The `tool_call` hook delivered queued planning text as steer, but when an interactive tool such as AskUserQuestion blocked the turn on its own custom UI, the steer text was read as the dialog's answer instead of reaching the model. Recitations and the tamper notice are now delivered as `nextTurn`, landing after the interactive tool releases the turn instead of being swallowed by it. Bundled Pi extension bumped to 1.2.1.
- **Two test-portability failures surfaced by the first hosted-runner run** (PR #198 by @Yigtwxx, test files only, no production script changes). `tests/test_containment.py` canonicalized the resolver's Git Bash POSIX path with `os.path.realpath`, which read `/tmp/...` as `C:\tmp` and failed the escaping-symlink containment assertion on symlink-capable `windows-latest`; a `host_realpath()` helper now maps the path back with `cygpath` before comparing. `tests/test_path_fix.py` ran two Windows-shaped path vectors on `ubuntu-latest`, where `Path.resolve()` treats `C:/...` as relative and prepends the CWD; both now skip unless `os.name == "nt"`, the only platform where that input shape is meaningful. In both cases the resolver rejected the escape correctly and only the test comparison was wrong.
### Added
- **CI test workflow** (`.github/workflows/tests.yml`, PR #199 by @Yigtwxx, closes #197). Runs the pytest suite on `ubuntu-latest` and `windows-latest` (Python 3.12) plus the Pi extension vitest suite on `ubuntu-latest` (Node 22), on every pull request and push to master. Until now the only CI was the Tessl skill-prose review, so nothing ran the 200+ pytest tests or the 21 Pi vitest tests that CONTRIBUTING.md asks contributors to run before opening a PR. The `windows-latest` leg targets the recurring Windows regression class (the v3.2.0 audit found `session-catchup.py` silently non-functional on Windows). Workflow permissions are `contents: read` only, `fail-fast: false` keeps a Windows-only failure visible instead of masked by a cancel, and an explicit step asserts `sh` is on PATH so the roughly ten hook tests that skip without it cannot silently drop coverage.
### Verification
- Python suite green on master before merge (200 passed, 5 skipped on a non-symlink-capable Windows host). Contributor's hosted-runner run on PR #199 green on all three jobs: pytest on ubuntu with symlink containment tests running, the equivalent profile on windows, and 21 vitest.
- Supply-chain review on PR #198 and #199: no new runtime dependencies, no install scripts, no bin shims. The workflow installs `pytest` and `pyyaml` for the pytest job and runs `npm install` against the Pi extension's existing devDependencies (vitest, typescript, @types/node). It uses `pull_request` (not `pull_request_target`), so fork PRs run with a read-only token and no secret access.
### Thanks
- @Yigtwxx (Yiğit) for filing the CI gap (#197) and landing both the test-portability fixes (#198) and the pytest plus vitest workflow (#199).
- Mahdi (@mahdiit) for producing the Codex Windows WSL bash launcher fix and the Windows Python discovery hardening (PR #207), using Codex Terra after v3.4.1 still failed to clear the hook errors on his own machine.
- jschmied for diagnosing #206 down to the exact runtime location, steer delivered recitations consumed by AskUserQuestion's interactive dialog, and for the `nextTurn` delivery fix that shipped.
- Yigtwxx (Yiğit) for filing the CI gap (#197) and landing both the test-portability fixes (#198) and the pytest plus vitest workflow (#199).
## [3.5.0] - 2026-07-13
+1 -1
View File
@@ -7,7 +7,7 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.5.0"
version: "3.6.0"
date-released: "2026-06-16"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
+8 -3
View File
@@ -106,6 +106,10 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[@jschmied](https://github.com/jschmied)** - [Issue #206](https://github.com/OthmanAdi/planning-with-files/issues/206)
- Diagnosed that pre-tool recitations and the tamper notice queued by the Pi extension's `tool_call` hook were delivered as steer, and that an interactive tool such as AskUserQuestion blocking the turn on its own custom UI consumed that steer text as the dialog's answer instead of letting it reach the model, pinning down the precise runtime location of the collision and the `nextTurn` delivery fix that shipped
- **Impact:** v3.5.1 delivers Pi extension recitations and the tamper notice as `nextTurn` instead of steer, so interactive tool dialogs no longer swallow injected planning text; bundled Pi extension bumped to 1.2.1
- **[@yolo0731](https://github.com/yolo0731)** (yoloyq) - [PR #205](https://github.com/OthmanAdi/planning-with-files/pull/205), closes [Issue #204](https://github.com/OthmanAdi/planning-with-files/issues/204)
- Fixed the Codex hooks on Windows emitting invalid JSON and failing on Unicode: plain `[planning-with-files]` stdout where Codex expects `hookSpecificOutput.additionalContext` or a common-fields object, UTF-8 shell output decoded through the Windows code page, and `ensure_ascii=False` JSON written through cmd.exe
- Serialized each event in its supported Codex JSON shape with ASCII-safe output, decoded shell output as UTF-8, routed PreToolUse plan text through model-visible `additionalContext`, resolved scoped plans in PermissionRequest, added `clear|compact` SessionStart sources, wrote the `.active_plan` pointer without a BOM, and hardened the containment resolver to fail closed
@@ -119,9 +123,10 @@ These amazing people have contributed code, documentation, or significant improv
- Asked for a direct statement of the plan-file lifecycle and why there is no archiving step, noting the earlier #14 had no visible resolution
- **Impact:** v3.5.0 documents the ephemeral-working-memory lifecycle in `docs/workflow.md`, with pointers from `quickstart.md` and the README FAQ
- **[@mahdiit](https://github.com/mahdiit)** (Mahdi) - [Issue #201](https://github.com/OthmanAdi/planning-with-files/issues/201)
- **[@mahdiit](https://github.com/mahdiit)** (Mahdi) - [Issue #201](https://github.com/OthmanAdi/planning-with-files/issues/201), [PR #207](https://github.com/OthmanAdi/planning-with-files/pull/207)
- Reported that Codex hooks failed on Windows with `hook exited with code 1`: the `.codex/hooks.json` commands were POSIX only, so the Windows command interpreter choked on `python3` (the Store alias), `2>/dev/null`, and the `|| true` success guard whose `true` is not a Windows command
- **Impact:** v3.4.1 adds per-hook `commandWindows` overrides, a `pwf-hook.cmd` launcher, a `run_sh.py` front door, and a git-bash resolver so all seven Codex hooks run on Windows
- PR #207: after v3.4.1 still did not clear the hook errors on his machine, traced the remaining failure to the shell resolver preferring the WSL bash launcher over Git Bash whenever `usr\bin` was off PATH, and to `pwf-hook.cmd` losing the Python interpreter under Codex's reduced PATH; produced the fix with Codex Terra, having the resolver skip WSL launchers and adding a `PYTHON_BIN` override plus standard install-location probing to the launcher
- **Impact:** v3.4.1 adds per-hook `commandWindows` overrides, a `pwf-hook.cmd` launcher, a `run_sh.py` front door, and a git-bash resolver so all seven Codex hooks run on Windows; v3.5.1 closes the remaining WSL-launcher and Python-discovery gaps that PR #207 found
- **[@Dikshj](https://github.com/Dikshj)** (diksha) - [PR #193](https://github.com/OthmanAdi/planning-with-files/pull/193), closes [Issue #190](https://github.com/OthmanAdi/planning-with-files/issues/190)
- Added the `/plan-execute` approval command to the Pi extension: hooks previously activated the moment `task_plan.md` existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan
@@ -371,4 +376,4 @@ If you've contributed and don't see your name here, please open an issue! We wan
**Total Contributors:** 50+ and growing!
*Last updated: July 13, 2026*
*Last updated: July 14, 2026*
+9 -3
View File
@@ -18,7 +18,7 @@
[![Skills Playground](https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg)](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)
[![Downloads](https://skill-history.com/badge/othmanadi/planning-with-files.svg)](https://skill-history.com/othmanadi/planning-with-files)
[![Version](https://img.shields.io/badge/version-3.5.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![Version](https://img.shields.io/badge/version-3.5.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
[![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
@@ -74,10 +74,12 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v3.4.1
### Current Version: v3.6.0
| Version | Highlights |
|---------|------------|
| **v3.6.0** | **Plan resolution and hook injection survive Windows-native coreutils, new `/plan-doctor` self-check.** A machine with a native Windows coreutils build on PATH (its `realpath` prints `C:\` backslash paths) failed the containment prefix match in `resolve-plan-dir.sh` and `inject-plan.sh`, so plan resolution and every hook injection went silently dark: no error, no plan context, 33 local test failures that Linux CI could never see. Canonical paths are now slash-normalized before comparison, the resolver canonicalizes root and candidate through the same cwd base (healing the 8.3 short-path mismatch the v3.2.0 fix left in the resolver), and per-candidate `grep` and `basename` forks were replaced with shell builtins: one hook fire measures 289ms on the machine that measured 2.0s at v3.4.0. New `/plan-doctor` command (`scripts/plan-doctor.sh`) reports resolution, injection, canonicalizer path shape, attestation state, install surfaces, and per-fire latency in one pass, because every failure in this class is silent by design. The long-standing local `test_ledger.py` hang on Windows resolved with the same fix; the full suite (217 tests) is green on Windows again. Install docs gained the route matrix (plugin vs npx, which surfaces each ships), the project-trust prerequisite, and a belt-and-suspenders CLAUDE.md trigger line from the July 2026 benchmark backlog. |
| **v3.5.1** | Codex Windows shell resolver skips WSL bash launchers, `pwf-hook.cmd` hardens Python discovery, and Pi recitations are delivered as `nextTurn` so interactive tools are not broken. |
| **v3.5.0** | **Codex Windows hooks emit valid JSON and survive Unicode (PR #205 by @yolo0731, closes #204), the Pi extension stops re-nagging closed and complete plans (#203 by @ziyu4huang), and the plan lifecycle is documented (#202 by @kcinzgg).** On Windows the Codex front door forwarded plain stdout where Codex expects `hookSpecificOutput.additionalContext` or PreCompact JSON, and UTF-8 broke on both decode and encode; the fix serializes each event in its supported shape with ASCII-safe output, decodes shell output as UTF-8, and writes the `.active_plan` pointer without a BOM, with the containment resolver hardened to fail closed (audited clean before merge). The Pi `resolveNewestPlanDir` now ranks by `task_plan.md` file mtime instead of directory mtime and honors the close marker, so a finished plan no longer loses to an incomplete sibling. Four language commands that referenced a non-existent skill namespace were corrected, a Traditional Chinese `/plan-zht` command was added, and the README now documents the full v3 command, hook, and mode surface that had shipped but was never listed. |
| **v3.4.1** | **Codex hooks now run on Windows (closes #201, reported by @mahdiit).** The `.codex/hooks.json` commands were POSIX only, so on Windows the native command interpreter choked on `python3` (the Store alias), `2>/dev/null`, and the `\|\| true` success guard whose `true` is not a Windows command, and every hook reported `hook exited with code 1`. Each hook now carries a per-hook `commandWindows` override (the POSIX `command` is untouched, so macOS and Linux are unchanged) that routes through a new `pwf-hook.cmd` launcher (real Python via `py -3`, falling back to `python`, never the Store `python3` alias) and, for the three shell hooks, a new `run_sh.py` front door. `codex_hook_adapter` resolves the Git for Windows `sh.exe` by anchoring on `git.exe`, so the shell scripts run even when Git's `usr\bin` is off PATH. Codex hook suites green (17 tests) plus new cross-platform and Windows-only coverage. |
| **v3.4.0** | **`PLANNING_DISABLED=1` per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon).** One-shot `codex exec` runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplete plan were hijacked: plan context injected, the actual output redirected into `progress.md`, a fabricated completed phase appended to `task_plan.md`. All Codex hook entry points, the Python adapter route, and the canonical dispatchers (`inject-plan.sh`, `gate-stop.sh`, `check-complete.sh`/`.ps1`) now exit before reading the plan when `PLANNING_DISABLED=1` is set; PreToolUse keeps emitting its allow decision so tool calls proceed. The guard ships in every distributed copy including the five language variants. Also corrected `docs/codex.md`'s stale claim that the Stop hook blocks (non-blocking since v3.1.0). Suite at 200 passed. |
@@ -571,7 +573,11 @@ Context rot is the drift that sets in as the context window fills and earlier in
### Which coding agents does this work with?
Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, CodeBuddy, Factory, Mastra, and 60+ others via the SKILL.md open standard. Installation is one command; see [Quick Install](#quick-install) above.
Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, CodeBuddy, Factory, Mastra, and 70+ others via the SKILL.md open standard (the `npx skills` installer alone targets 71 agents, and tools like Zed, Amp, Warp, and Devin read the standard `.agents/skills/` layout natively). Installation is one command; see [Quick Install](#quick-install) above.
### How does this work with Claude Code's plan mode?
They are complementary stages, not alternatives. Plan mode designs the approach before execution and leaves an approved strategy in the transcript. planning-with-files persists execution state on disk while the work runs. The handoff is one step: after accepting a plan-mode plan, tell the agent to write the accepted plan into `task_plan.md` as phases (or invoke `/plan` and let the skill create the files from it), then execute in normal mode. From that point the hooks keep the phases in the attention window, and the files survive `/clear`, compaction, and session death, which transcript-bound plan-mode output does not.
### What happens to the plan files after a task is complete?
+20
View File
@@ -0,0 +1,20 @@
---
description: "Self-check for the planning-with-files mechanisms that fail silently: plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, and per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. Available since v3.6.0."
disable-model-invocation: true
allowed-tools: "Bash"
---
Run the planning-with-files self-check against the current project directory.
Steps:
1. Run the doctor script from the project root:
- Linux/macOS/Git Bash: `sh ${CLAUDE_PLUGIN_ROOT}/scripts/plan-doctor.sh`
- Windows without Git Bash on PATH: locate Git Bash via `git.exe` (its `usr\bin\sh.exe` sibling) and run the same script with it.
2. Report the PASS/WARN/FAIL lines to the user verbatim — they are designed to be read as-is.
3. If any line reports FAIL, explain the matching remediation:
- resolver FAIL → inspect `.planning/.active_plan` content and plan dir names.
- injection FAIL with a resolving plan → the hooks are silently dark; upgrading past v3.6.0 fixes the Windows-native-coreutils realpath cause. Also check `PLANNING_DISABLED`.
- tamper WARN → re-approve with `/plan-attest` if the plan edit was intentional.
4. Do not attempt automatic fixes; this command is diagnostic only.
Why this exists: the mechanisms this skill relies on (hook injection, plan resolution) exit 0 and stay silent by design when something is off, so a broken install looks identical to "no plan yet". The doctor makes the difference visible in one pass.
+35
View File
@@ -13,6 +13,41 @@ That's it! The skill is now active.
---
## What Each Install Route Actually Ships
Not every route delivers every surface. This matrix is the difference between "installed" and "fully working":
| Route | SKILL.md + scripts + templates | Slash commands (`/plan-goal`, `/plan-loop`, `/plan-attest`, `/plan-doctor`) | Hooks (plan injection, Stop check, PreCompact) |
|---|---|---|---|
| Plugin: `/plugin marketplace add` + `/plugin install` | Yes | **Yes** | **Yes** |
| `npx skills add OthmanAdi/planning-with-files` | Yes | No (`commands/` is not copied) | Frontmatter hooks; see the two silent killers below |
| ClawHub / manual skill copy to `~/.claude/skills/` | Yes | No | Frontmatter hooks; see below |
Two conditions can leave a skill-route install **silently hook-less** — everything looks installed, but no plan context is ever injected:
1. **Project trust.** A project-level install (`.claude/skills/` inside the repo) only activates after the project's trust dialog is accepted (`hasTrustDialogAccepted`). Headless or scripted sessions that never accepted trust load no project skills, and nothing prints an error.
2. **Hook registration.** SKILL.md frontmatter hooks have been observed not to register on some project-level skill installs (observed on headless Claude Code 2.1.201 during the July 2026 benchmark). The plugin route registers hooks reliably.
If hooks matter to you (they are the differentiating mechanism of this skill), install via the plugin route. Either way, verify with the doctor:
```bash
sh scripts/plan-doctor.sh # from your project root; reports resolution, injection, latency
```
---
## Reliability Tip: Belt-and-Suspenders Trigger
Skill descriptions trigger probabilistically — in our July 2026 benchmark, unforced engagement was 60-67%, while an always-loaded rules-file instruction engaged 100% of the time. If you want the skill to fire every time a task is complex, add one line to your project's `CLAUDE.md` (or global `~/.claude/CLAUDE.md`):
```markdown
When a task needs 3+ steps or 5+ tool calls, invoke the planning-with-files skill first and keep task_plan.md current.
```
The skill description still handles discovery; the rules line makes engagement deterministic. Both together cost nothing when no complex task is running.
---
## Installation Methods
### 1. Claude Code Plugin (Recommended)
+1 -1
View File
@@ -166,7 +166,7 @@ $env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
## Migrating from Cursor/Windsurf
## Migrating from Cursor/Windsurf (Windsurf became Devin Desktop in June 2026)
Planning files are fully compatible. Simply copy your `task_plan.md`, `findings.md`, and `progress.md` files to your new project.
+49 -5
View File
@@ -32,9 +32,46 @@ for arg in "$@"; do
esac
done
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
# Plan-id safe-identifier check. Pure-sh case patterns; semantics match the
# previous grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep
# fork per candidate. (Shared shape with 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
}
# 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
# injection silently goes dark. 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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then python3/python os.path.realpath. Prints
# the canonical absolute path on success; prints nothing and returns 1 on a
@@ -79,8 +116,15 @@ is_within_root() {
# different code paths and land on differently-spelled-but-equal targets,
# so the prefix match below fails and injection silently goes dark. "."
# resolves through the same physical-cwd path candidates already use.
# Both sides are backslash-normalized before comparison: Windows-native
# canonicalizers emit C:\-style paths that a forward-slash prefix pattern
# can never match.
root_real="$(canonicalize ".")" || root_real=""
norm_slashes "${root_real}"
root_real="${NORM_OUT}"
cand_real="$(canonicalize "${candidate}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
return 0
fi
@@ -94,20 +138,20 @@ is_within_root() {
# dispatch needs only one script on disk to function). ---
RESOLVED=""
SCOPE=""
if [ -n "${PLAN_ID:-}" ] && printf "%s" "$PLAN_ID" | grep -Eq "$SLUG_RE" && [ -d ".planning/${PLAN_ID}" ]; then
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d ".planning/${PLAN_ID}" ]; then
RESOLVED=".planning/${PLAN_ID}"; SCOPE="scoped"
elif [ -f .planning/.active_plan ]; then
AP=$(tr -d '\r\n[:space:]' < .planning/.active_plan 2>/dev/null)
if [ -n "$AP" ] && printf "%s" "$AP" | grep -Eq "$SLUG_RE" && [ -d ".planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d ".planning/${AP}" ]; then
RESOLVED=".planning/${AP}"; SCOPE="scoped"
fi
fi
if [ -z "$RESOLVED" ] && [ -d .planning ]; then
NEWEST=""; NEWEST_MT=0
for d in .planning/*/; do
d="${d%/}"; n=$(basename "$d")
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
printf "%s" "$n" | grep -Eq "$SLUG_RE" || continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
if [ "$m" -gt "$NEWEST_MT" ] 2>/dev/null; then NEWEST_MT="$m"; NEWEST="$d"; fi
+137
View File
@@ -0,0 +1,137 @@
#!/bin/sh
# planning-with-files: plan-doctor — one-pass self-check for the mechanisms
# that fail silently. Run from the project root:
#
# sh scripts/plan-doctor.sh
#
# Answers:
# - does plan resolution work here, and which plan wins?
# - does hook injection actually emit plan context?
# - is the canonicalizer producing comparable paths? (Windows-native
# coreutils emit C:\-style output; pwf versions before v3.6.0 went
# silently dark on such machines)
# - is the plan attested, and is the attestation file where hooks look?
# - which install surfaces exist on this machine?
# - what does one hook fire cost in wall-clock?
#
# Diagnostic only. Writes nothing except inject-plan.sh's own SHA cache.
# Always exits 0.
set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
ok() { printf 'PASS %s\n' "$1"; }
warn() { printf 'WARN %s\n' "$1"; }
fail() { printf 'FAIL %s\n' "$1"; }
info() { printf 'info %s\n' "$1"; }
echo '=== planning-with-files plan-doctor ==='
info "cwd: ${PWD}"
info "uname: $(uname -s 2>/dev/null || echo unknown)"
[ "${PLANNING_DISABLED:-}" = "1" ] && warn "PLANNING_DISABLED=1 is set — every hook exits immediately in this environment"
# --- [1] canonicalizer probe -------------------------------------------------
CANON="$(realpath . 2>/dev/null)" || CANON=""
[ -z "${CANON}" ] && { CANON="$(readlink -f . 2>/dev/null)" || CANON=""; }
case "${CANON}" in
'')
warn "no realpath/readlink canonicalizer answered — containment falls back to a python spawn per check"
;;
*\\*)
info "canonicalizer emits Windows-style paths (${CANON}) — handled since v3.6.0; OLDER pwf versions resolve nothing on this machine"
;;
*)
info "canonicalizer: ${CANON}"
;;
esac
# --- [2] plan resolution -----------------------------------------------------
RES=""
if [ -f "${SCRIPT_DIR}/resolve-plan-dir.sh" ]; then
RES="$(sh "${SCRIPT_DIR}/resolve-plan-dir.sh" 2>/dev/null)" || RES=""
if [ -n "${RES}" ]; then
ok "resolver: active plan dir = ${RES}"
elif [ -f task_plan.md ]; then
ok "resolver: legacy root plan (./task_plan.md)"
elif [ -d .planning ]; then
fail "resolver: .planning/ exists but nothing resolves — check .planning/.active_plan content and that plan dirs contain task_plan.md"
else
info "resolver: no plan in this directory (run init-session.sh to create one)"
fi
else
warn "resolve-plan-dir.sh not found next to plan-doctor — unexpected install layout"
fi
# --- [3] hook injection ------------------------------------------------------
INJ="${SCRIPT_DIR}/inject-plan.sh"
if [ -f "${INJ}" ]; then
OUT="$(sh "${INJ}" --context=userprompt 2>/dev/null)" || OUT=""
if [ -z "${OUT}" ]; then
if [ -n "${RES}" ] || [ -f task_plan.md ]; then
fail "injection: a plan resolves but inject-plan.sh emitted NOTHING — hooks are dark. Known silent causes: pre-v3.6.0 with a Windows-native realpath on PATH; PLANNING_DISABLED=1; a plan dir outside the project root."
else
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
case "${OUT}" in
*'PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
esac
fi
else
warn "inject-plan.sh not found next to plan-doctor — this install route ships no hook payload (see the install matrix in docs/installation.md)"
fi
# --- [4] attestation ---------------------------------------------------------
ATT=""
if [ -n "${RES}" ] && [ -f "${RES}/.attestation" ]; then
ATT="${RES}/.attestation"
elif [ -f .plan-attestation ]; then
ATT=".plan-attestation"
fi
if [ -n "${ATT}" ]; then
info "attestation present: ${ATT}"
else
info "attestation: none (opt-in in legacy mode; default-on in v3 modes; run /plan-attest after approving the plan)"
fi
# --- [5] install surfaces ----------------------------------------------------
FOUND_SURFACE=0
for s in \
".claude/skills/planning-with-files" \
"${HOME:-}/.claude/skills/planning-with-files" \
".agents/skills/planning-with-files" \
"${HOME:-}/.agents/skills/planning-with-files"
do
[ -n "${s}" ] && [ -d "${s}" ] && { info "install surface present: ${s}"; FOUND_SURFACE=1; }
done
[ "${FOUND_SURFACE}" = "0" ] && info "no skill-dir install surface in project or home (plugin-route installs live under the plugin cache instead)"
info "route reminder: the plugin route ships commands/ + hooks; npx-skills ships the skill only. Hooks silent after a project-level skill install? Check project trust (hasTrustDialogAccepted) and the install matrix in docs/installation.md."
# --- [6] hook latency --------------------------------------------------------
if [ -f "${INJ}" ]; then
T0="$(date +%s%N 2>/dev/null)" || T0=""
sh "${INJ}" --context=userprompt >/dev/null 2>&1
T1="$(date +%s%N 2>/dev/null)" || T1=""
case "${T0}${T1}" in
''|*[!0-9]*)
info "hook latency: skipped (no nanosecond clock on this date binary)"
;;
*)
MS=$(( (T1 - T0) / 1000000 ))
info "one inject-plan.sh fire: ${MS}ms wall-clock"
;;
esac
fi
echo '=== plan-doctor done ==='
exit 0
+70 -12
View File
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
# نظام تخطيط الملفات
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
# Dateiplanungssystem
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
# Sistema de Planificación con Archivos
+1 -1
View File
@@ -29,7 +29,7 @@ hooks:
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
+1 -1
View File
@@ -29,7 +29,7 @@ hooks:
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
+2 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.5.0"
version: "3.6.0"
---
# Planning with Files
@@ -220,6 +220,7 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
- `scripts/session-catchup.py` — Recover context from a previous session after `/clear` (v2.2.0).
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
- `scripts/plan-doctor.sh` — One-pass self-check for the mechanisms that fail silently (v3.6.0): plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. See `/plan-doctor` command.
### Parallel task workflow
@@ -32,9 +32,46 @@ for arg in "$@"; do
esac
done
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
# Plan-id safe-identifier check. Pure-sh case patterns; semantics match the
# previous grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep
# fork per candidate. (Shared shape with 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
}
# 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
# injection silently goes dark. 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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then python3/python os.path.realpath. Prints
# the canonical absolute path on success; prints nothing and returns 1 on a
@@ -79,8 +116,15 @@ is_within_root() {
# different code paths and land on differently-spelled-but-equal targets,
# so the prefix match below fails and injection silently goes dark. "."
# resolves through the same physical-cwd path candidates already use.
# Both sides are backslash-normalized before comparison: Windows-native
# canonicalizers emit C:\-style paths that a forward-slash prefix pattern
# can never match.
root_real="$(canonicalize ".")" || root_real=""
norm_slashes "${root_real}"
root_real="${NORM_OUT}"
cand_real="$(canonicalize "${candidate}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
return 0
fi
@@ -94,20 +138,20 @@ is_within_root() {
# dispatch needs only one script on disk to function). ---
RESOLVED=""
SCOPE=""
if [ -n "${PLAN_ID:-}" ] && printf "%s" "$PLAN_ID" | grep -Eq "$SLUG_RE" && [ -d ".planning/${PLAN_ID}" ]; then
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d ".planning/${PLAN_ID}" ]; then
RESOLVED=".planning/${PLAN_ID}"; SCOPE="scoped"
elif [ -f .planning/.active_plan ]; then
AP=$(tr -d '\r\n[:space:]' < .planning/.active_plan 2>/dev/null)
if [ -n "$AP" ] && printf "%s" "$AP" | grep -Eq "$SLUG_RE" && [ -d ".planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d ".planning/${AP}" ]; then
RESOLVED=".planning/${AP}"; SCOPE="scoped"
fi
fi
if [ -z "$RESOLVED" ] && [ -d .planning ]; then
NEWEST=""; NEWEST_MT=0
for d in .planning/*/; do
d="${d%/}"; n=$(basename "$d")
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
printf "%s" "$n" | grep -Eq "$SLUG_RE" || continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
if [ "$m" -gt "$NEWEST_MT" ] 2>/dev/null; then NEWEST_MT="$m"; NEWEST="$d"; fi
+137
View File
@@ -0,0 +1,137 @@
#!/bin/sh
# planning-with-files: plan-doctor — one-pass self-check for the mechanisms
# that fail silently. Run from the project root:
#
# sh scripts/plan-doctor.sh
#
# Answers:
# - does plan resolution work here, and which plan wins?
# - does hook injection actually emit plan context?
# - is the canonicalizer producing comparable paths? (Windows-native
# coreutils emit C:\-style output; pwf versions before v3.6.0 went
# silently dark on such machines)
# - is the plan attested, and is the attestation file where hooks look?
# - which install surfaces exist on this machine?
# - what does one hook fire cost in wall-clock?
#
# Diagnostic only. Writes nothing except inject-plan.sh's own SHA cache.
# Always exits 0.
set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
ok() { printf 'PASS %s\n' "$1"; }
warn() { printf 'WARN %s\n' "$1"; }
fail() { printf 'FAIL %s\n' "$1"; }
info() { printf 'info %s\n' "$1"; }
echo '=== planning-with-files plan-doctor ==='
info "cwd: ${PWD}"
info "uname: $(uname -s 2>/dev/null || echo unknown)"
[ "${PLANNING_DISABLED:-}" = "1" ] && warn "PLANNING_DISABLED=1 is set — every hook exits immediately in this environment"
# --- [1] canonicalizer probe -------------------------------------------------
CANON="$(realpath . 2>/dev/null)" || CANON=""
[ -z "${CANON}" ] && { CANON="$(readlink -f . 2>/dev/null)" || CANON=""; }
case "${CANON}" in
'')
warn "no realpath/readlink canonicalizer answered — containment falls back to a python spawn per check"
;;
*\\*)
info "canonicalizer emits Windows-style paths (${CANON}) — handled since v3.6.0; OLDER pwf versions resolve nothing on this machine"
;;
*)
info "canonicalizer: ${CANON}"
;;
esac
# --- [2] plan resolution -----------------------------------------------------
RES=""
if [ -f "${SCRIPT_DIR}/resolve-plan-dir.sh" ]; then
RES="$(sh "${SCRIPT_DIR}/resolve-plan-dir.sh" 2>/dev/null)" || RES=""
if [ -n "${RES}" ]; then
ok "resolver: active plan dir = ${RES}"
elif [ -f task_plan.md ]; then
ok "resolver: legacy root plan (./task_plan.md)"
elif [ -d .planning ]; then
fail "resolver: .planning/ exists but nothing resolves — check .planning/.active_plan content and that plan dirs contain task_plan.md"
else
info "resolver: no plan in this directory (run init-session.sh to create one)"
fi
else
warn "resolve-plan-dir.sh not found next to plan-doctor — unexpected install layout"
fi
# --- [3] hook injection ------------------------------------------------------
INJ="${SCRIPT_DIR}/inject-plan.sh"
if [ -f "${INJ}" ]; then
OUT="$(sh "${INJ}" --context=userprompt 2>/dev/null)" || OUT=""
if [ -z "${OUT}" ]; then
if [ -n "${RES}" ] || [ -f task_plan.md ]; then
fail "injection: a plan resolves but inject-plan.sh emitted NOTHING — hooks are dark. Known silent causes: pre-v3.6.0 with a Windows-native realpath on PATH; PLANNING_DISABLED=1; a plan dir outside the project root."
else
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
case "${OUT}" in
*'PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
esac
fi
else
warn "inject-plan.sh not found next to plan-doctor — this install route ships no hook payload (see the install matrix in docs/installation.md)"
fi
# --- [4] attestation ---------------------------------------------------------
ATT=""
if [ -n "${RES}" ] && [ -f "${RES}/.attestation" ]; then
ATT="${RES}/.attestation"
elif [ -f .plan-attestation ]; then
ATT=".plan-attestation"
fi
if [ -n "${ATT}" ]; then
info "attestation present: ${ATT}"
else
info "attestation: none (opt-in in legacy mode; default-on in v3 modes; run /plan-attest after approving the plan)"
fi
# --- [5] install surfaces ----------------------------------------------------
FOUND_SURFACE=0
for s in \
".claude/skills/planning-with-files" \
"${HOME:-}/.claude/skills/planning-with-files" \
".agents/skills/planning-with-files" \
"${HOME:-}/.agents/skills/planning-with-files"
do
[ -n "${s}" ] && [ -d "${s}" ] && { info "install surface present: ${s}"; FOUND_SURFACE=1; }
done
[ "${FOUND_SURFACE}" = "0" ] && info "no skill-dir install surface in project or home (plugin-route installs live under the plugin cache instead)"
info "route reminder: the plugin route ships commands/ + hooks; npx-skills ships the skill only. Hooks silent after a project-level skill install? Check project trust (hasTrustDialogAccepted) and the install matrix in docs/installation.md."
# --- [6] hook latency --------------------------------------------------------
if [ -f "${INJ}" ]; then
T0="$(date +%s%N 2>/dev/null)" || T0=""
sh "${INJ}" --context=userprompt >/dev/null 2>&1
T1="$(date +%s%N 2>/dev/null)" || T1=""
case "${T0}${T1}" in
''|*[!0-9]*)
info "hook latency: skipped (no nanosecond clock on this date binary)"
;;
*)
MS=$(( (T1 - T0) / 1000000 ))
info "one inject-plan.sh fire: ${MS}ms wall-clock"
;;
esac
fi
echo '=== plan-doctor done ==='
exit 0
@@ -24,13 +24,42 @@ ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
# .active_plan file containing only whitespace or random text) without
# enforcing a date prefix that would break backward compatibility.
SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
# Pure-sh case patterns; semantics match the previous
# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
# candidate (the newest-mtime scan calls this once per plan dir).
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
printf "%s" "$1" | grep -Eq "${SLUG_RE}"
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
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
@@ -63,21 +92,50 @@ canonicalize() {
# 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. If
# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
# and python; the SLUG_RE check already blocks traversal in the slug name.
# 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.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
root_real="$(canonicalize "${PWD}")" || root_real=""
cand_real="$(canonicalize "${candidate}")" || cand_real=""
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize ".")" || ROOT_REAL=""
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.
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
cand_real="$(canonicalize "${check_target}")" || cand_real=""
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 ;;
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
@@ -145,7 +203,7 @@ resolve_latest_dir() {
for entry in "${PLAN_ROOT}"/*/; do
[ -d "${entry}" ] || continue
clean="${entry%/}"
name="$(basename "${clean}")"
name="${clean##*/}"
case "${name}" in
.*) continue ;;
esac
+59
View File
@@ -377,6 +377,65 @@ class CodexHooksTests(unittest.TestCase):
self.assertTrue(compact_payload["continue"])
self.assertIn("PreCompact", compact_payload["systemMessage"])
@unittest.skipUnless(
os.name == "nt",
"Windows-shaped path; System32 comparison only meaningful on Windows",
)
def test_windows_git_bash_rejects_wsl_launcher_in_system32(self) -> None:
"""A bare `bash` on PATH resolving into System32 is the WSL launcher.
_windows_git_bash must never hand that path back to callers even when
it is the only `bash` shutil.which can see; it should keep looking
(and return a real Git-for-Windows sh.exe, or None) instead.
"""
sys.path.insert(0, str(HOOKS_DIR))
try:
import codex_hook_adapter as adapter
def fake_which(exe, *args, **kwargs):
if exe == "sh":
return None
if exe == "bash":
return r"C:\windows\system32\bash.EXE"
return None
with mock.patch.object(adapter.shutil, "which", side_effect=fake_which):
sh_path, _ = adapter._windows_git_bash()
finally:
sys.path.pop(0)
if sh_path is not None:
self.assertNotIn("system32", sh_path.lower())
@unittest.skipUnless(
os.name == "nt",
"Windows-shaped path; WindowsApps comparison only meaningful on Windows",
)
def test_windows_git_bash_rejects_wsl_launcher_in_windowsapps(self) -> None:
"""The Microsoft Store WSL alias lives under WindowsApps, not System32.
Even a working WSL bash there cannot execute C:\\ script paths, so
_windows_git_bash must reject it the same way it rejects System32.
"""
sys.path.insert(0, str(HOOKS_DIR))
try:
import codex_hook_adapter as adapter
def fake_which(exe, *args, **kwargs):
if exe == "sh":
return None
if exe == "bash":
return r"C:\Users\x\AppData\Local\Microsoft\WindowsApps\bash.exe"
return None
with mock.patch.object(adapter.shutil, "which", side_effect=fake_which):
sh_path, _ = adapter._windows_git_bash()
finally:
sys.path.pop(0)
if sh_path is not None:
self.assertNotIn("windowsapps", sh_path.lower())
if __name__ == "__main__":
unittest.main()
+83
View File
@@ -177,5 +177,88 @@ class ContainmentTests(unittest.TestCase):
)
INJECT_SH = REPO_ROOT / "skills" / "planning-with-files" / "scripts" / "inject-plan.sh"
@unittest.skipUnless(have_sh(), "sh not available on this platform")
class WindowsNativeCanonicalizerTests(unittest.TestCase):
"""Regression: a Windows-native coreutils realpath (e.g. an installed
C:\\Program Files\\coreutils on PATH ahead of Git's usr/bin) canonicalizes
MSYS-style /c/... input to C:\\-style BACKSLASH output. The containment
prefix match in is_within_root is written with forward slashes, so every
canonical pair mismatched: the resolver (fail-closed) resolved nothing and
inject-plan.sh (guarded exit) emitted nothing — plan resolution and hook
injection silently dark on the whole machine. Found live 2026-07-18.
A PATH-prepended stub realpath reproduces the backslash output shape on
every platform, so this guards the norm_slashes fix on Linux CI too.
"""
def make_backslash_realpath(self, bin_dir: Path) -> None:
stub = bin_dir / "realpath"
stub.write_text(
"#!/bin/sh\n"
"# test stub: Windows-native realpath shape (backslash separators)\n"
'case "$1" in\n'
' "") exit 1 ;;\n'
' /*) abs="$1" ;;\n'
' .) abs="$(pwd -P)" ;;\n'
' *) abs="$(pwd -P)/$1" ;;\n'
"esac\n"
"printf '%s\\n' \"$abs\" | sed 's|/|\\\\|g'\n",
encoding="utf-8",
newline="\n",
)
os.chmod(stub, 0o755)
def run_with_stub(self, script: Path, cwd: Path) -> subprocess.CompletedProcess[str]:
with tempfile.TemporaryDirectory() as stub_tmp:
bin_dir = Path(stub_tmp) / "bin"
bin_dir.mkdir()
self.make_backslash_realpath(bin_dir)
env = os.environ.copy()
env.pop("PLAN_ID", None)
env["PATH"] = str(bin_dir) + os.pathsep + env.get("PATH", "")
return subprocess.run(
["sh", str(script)],
cwd=str(cwd),
text=True,
encoding="utf-8",
capture_output=True,
env=env,
check=False,
)
def test_resolver_survives_backslash_realpath(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
plan = root / ".planning" / "real"
plan.mkdir(parents=True)
(plan / "task_plan.md").write_text("# real\n", encoding="utf-8")
(root / ".planning" / ".active_plan").write_text("real\n", encoding="utf-8")
result = self.run_with_stub(RESOLVE_SH, root)
self.assertEqual(0, result.returncode, result.stderr)
self.assertTrue(
result.stdout.strip().endswith("real"),
f"backslash canonical paths must not kill resolution, got {result.stdout!r}",
)
def test_inject_survives_backslash_realpath(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
plan = root / ".planning" / "real"
plan.mkdir(parents=True)
(plan / "task_plan.md").write_text("# real plan body\n", encoding="utf-8")
(root / ".planning" / ".active_plan").write_text("real\n", encoding="utf-8")
result = self.run_with_stub(INJECT_SH, root)
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn(
"===BEGIN PLAN DATA===",
result.stdout,
f"injection must survive backslash canonical paths, got {result.stdout!r}",
)
self.assertIn("# real plan body", result.stdout)
if __name__ == "__main__":
unittest.main()
+1
View File
@@ -45,6 +45,7 @@ DUAL_SHIPPED = [
"ledger-summary.sh",
"phase-status.ps1",
"phase-status.sh",
"plan-doctor.sh",
"resolve-plan-dir.ps1",
"resolve-plan-dir.sh",
"set-active-plan.ps1",